diff --git a/vue/primitives/docs/intro.vue b/vue/primitives/docs/intro.vue
index 95fdea6..a41f34c 100644
--- a/vue/primitives/docs/intro.vue
+++ b/vue/primitives/docs/intro.vue
@@ -24,35 +24,35 @@
     </p>
 
     <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
-      <div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-5">
-        <h3 class="m-0 text-sm font-semibold text-(--fg)">Unstyled by design</h3>
-        <p class="mt-2 mb-0 text-sm text-(--fg-muted)">
+      <div class="rounded-xl border border-border bg-bg-elevated p-5">
+        <h3 class="m-0 text-sm font-semibold text-fg">Unstyled by design</h3>
+        <p class="mt-2 mb-0 text-sm text-fg-muted">
           No CSS shipped. Primitives render the DOM you ask for and expose state via
           data attributes, so you bring your own styles — Tailwind, vanilla CSS, anything.
         </p>
       </div>
 
-      <div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-5">
-        <h3 class="m-0 text-sm font-semibold text-(--fg)">Accessible out of the box</h3>
-        <p class="mt-2 mb-0 text-sm text-(--fg-muted)">
+      <div class="rounded-xl border border-border bg-bg-elevated p-5">
+        <h3 class="m-0 text-sm font-semibold text-fg">Accessible out of the box</h3>
+        <p class="mt-2 mb-0 text-sm text-fg-muted">
           Focus scopes, roving tabindex, visually-hidden labels and correct ARIA roles
           are handled for you. The suite is tested against
           <code>axe-core</code> in a real browser.
         </p>
       </div>
 
-      <div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-5">
-        <h3 class="m-0 text-sm font-semibold text-(--fg)">Controlled or uncontrolled</h3>
-        <p class="mt-2 mb-0 text-sm text-(--fg-muted)">
+      <div class="rounded-xl border border-border bg-bg-elevated p-5">
+        <h3 class="m-0 text-sm font-semibold text-fg">Controlled or uncontrolled</h3>
+        <p class="mt-2 mb-0 text-sm text-fg-muted">
           Bind state with <code>v-model</code> when you need control, or set a
           <code>defaultValue</code> / <code>defaultOpen</code> and let the primitive
           manage itself.
         </p>
       </div>
 
-      <div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-5">
-        <h3 class="m-0 text-sm font-semibold text-(--fg)">Composable & polymorphic</h3>
-        <p class="mt-2 mb-0 text-sm text-(--fg-muted)">
+      <div class="rounded-xl border border-border bg-bg-elevated p-5">
+        <h3 class="m-0 text-sm font-semibold text-fg">Composable & polymorphic</h3>
+        <p class="mt-2 mb-0 text-sm text-fg-muted">
           Every part takes an <code>as</code> prop, or use <code>as="template"</code>
           to merge behavior onto your own element. Floating UI powers positioning for
           popovers, tooltips and menus.
diff --git a/vue/primitives/eslint.config.ts b/vue/primitives/eslint.config.ts
index 3f17b52..3298689 100644
--- a/vue/primitives/eslint.config.ts
+++ b/vue/primitives/eslint.config.ts
@@ -1,4 +1,4 @@
-import { base, compose, imports, stylistic, typescript, vue } from '@robonen/eslint';
+import { base, compose, imports, stylistic, tests, typescript, vue } from '@robonen/eslint';
 
 export default compose(base, typescript, vue, imports, stylistic, {
   name: 'primitives/overrides',
@@ -6,4 +6,4 @@ export default compose(base, typescript, vue, imports, stylistic, {
   rules: {
     '@stylistic/no-multiple-empty-lines': 'off',
   },
-});
+}, tests);
diff --git a/vue/primitives/playground/src/demos/Accordion.vue b/vue/primitives/playground/src/demos/Accordion.vue
index c5f9156..12075a0 100644
--- a/vue/primitives/playground/src/demos/Accordion.vue
+++ b/vue/primitives/playground/src/demos/Accordion.vue
@@ -5,7 +5,7 @@ import {
   AccordionItem,
   AccordionRoot,
   AccordionTrigger,
-} from '@primitives/accordion';
+} from '@primitives/disclosure/accordion';
 
 const value = ref<string | string[] | undefined>('a');
 const type = ref<'single' | 'multiple'>('single');
diff --git a/vue/primitives/playground/src/demos/Checkbox.vue b/vue/primitives/playground/src/demos/Checkbox.vue
index a7e193e..6fdd066 100644
--- a/vue/primitives/playground/src/demos/Checkbox.vue
+++ b/vue/primitives/playground/src/demos/Checkbox.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { ref } from 'vue';
-import type { CheckedState } from '@primitives/checkbox';
-import { CheckboxIndicator, CheckboxRoot } from '@primitives/checkbox';
+import type { CheckedState } from '@primitives/forms/checkbox';
+import { CheckboxIndicator, CheckboxRoot } from '@primitives/forms/checkbox';
 
 const checked = ref<CheckedState>(false);
 const disabled = ref(false);
diff --git a/vue/primitives/src/__test__/__screenshots__/demos.smoke.test.ts/media-editor-demos-mount-without-error-keyframe-track-demo-vue-mounts-and-renders-1.png b/vue/primitives/src/__test__/__screenshots__/demos.smoke.test.ts/media-editor-demos-mount-without-error-keyframe-track-demo-vue-mounts-and-renders-1.png
new file mode 100644
index 0000000..a7753c7
Binary files /dev/null and b/vue/primitives/src/__test__/__screenshots__/demos.smoke.test.ts/media-editor-demos-mount-without-error-keyframe-track-demo-vue-mounts-and-renders-1.png differ
diff --git a/vue/primitives/src/__test__/__screenshots__/demos.smoke.test.ts/media-editor-demos-mount-without-error-or-Vue-warnings-waveform-demo-vue-mounts-cleanly-1.png b/vue/primitives/src/__test__/__screenshots__/demos.smoke.test.ts/media-editor-demos-mount-without-error-or-Vue-warnings-waveform-demo-vue-mounts-cleanly-1.png
new file mode 100644
index 0000000..b353aee
Binary files /dev/null and b/vue/primitives/src/__test__/__screenshots__/demos.smoke.test.ts/media-editor-demos-mount-without-error-or-Vue-warnings-waveform-demo-vue-mounts-cleanly-1.png differ
diff --git a/vue/primitives/src/__test__/demos.smoke.test.ts b/vue/primitives/src/__test__/demos.smoke.test.ts
new file mode 100644
index 0000000..12a968f
--- /dev/null
+++ b/vue/primitives/src/__test__/demos.smoke.test.ts
@@ -0,0 +1,71 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { nextTick } from 'vue';
+import { afterEach, describe, expect, it } from 'vitest';
+
+// Smoke test: every new media-editor `demo.vue` must MOUNT without throwing
+// (catches context-consumed-outside-its-Root, null-ref api calls at setup, and
+// other runtime breakage that type-checking / SFC-parsing do not surface).
+import AlphaSliderDemo from '../color/alpha-slider/demo.vue';
+import AngleDialDemo from '../canvas/angle-dial/demo.vue';
+import CanvasStageDemo from '../canvas/canvas-stage/demo.vue';
+import ColorAreaDemo from '../color/color-area/demo.vue';
+import ColorFieldDemo from '../color/color-field/demo.vue';
+import CompareSliderDemo from '../canvas/compare-slider/demo.vue';
+import CropDemo from '../canvas/crop/demo.vue';
+import CurveEditorDemo from '../canvas/curve-editor/demo.vue';
+import GradientEditorDemo from '../canvas/gradient-editor/demo.vue';
+import HistogramDemo from '../canvas/histogram/demo.vue';
+import HueSliderDemo from '../color/hue-slider/demo.vue';
+import KeyframeTrackDemo from '../canvas/keyframe-track/demo.vue';
+import LevelsDemo from '../canvas/levels/demo.vue';
+import TimeRulerDemo from '../canvas/time-ruler/demo.vue';
+import TimelineDemo from '../canvas/timeline/demo.vue';
+import TransformBoxDemo from '../canvas/transform-box/demo.vue';
+import WaveformDemo from '../canvas/waveform/demo.vue';
+import ZoomPanDemo from '../canvas/zoom-pan/demo.vue';
+
+const demos: Record<string, unknown> = {
+  'alpha-slider': AlphaSliderDemo,
+  'angle-dial': AngleDialDemo,
+  'canvas-stage': CanvasStageDemo,
+  'color-area': ColorAreaDemo,
+  'color-field': ColorFieldDemo,
+  'compare-slider': CompareSliderDemo,
+  crop: CropDemo,
+  'curve-editor': CurveEditorDemo,
+  'gradient-editor': GradientEditorDemo,
+  histogram: HistogramDemo,
+  'hue-slider': HueSliderDemo,
+  'keyframe-track': KeyframeTrackDemo,
+  levels: LevelsDemo,
+  'time-ruler': TimeRulerDemo,
+  timeline: TimelineDemo,
+  'transform-box': TransformBoxDemo,
+  waveform: WaveformDemo,
+  'zoom-pan': ZoomPanDemo,
+};
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+describe('media-editor demos mount without error or Vue warnings', () => {
+  for (const [name, Comp] of Object.entries(demos)) {
+    it(`${name}/demo.vue mounts cleanly`, async () => {
+      // Collect Vue warnings (e.g. slot-prop-out-of-scope, missing context,
+      // unknown template refs) instead of letting them slip to console.
+      const warnings: string[] = [];
+      const wrapper = mount(Comp as any, {
+        attachTo: document.body,
+        global: { config: { warnHandler: (msg: string) => { warnings.push(msg); } } },
+      });
+      wrappers.push(wrapper);
+      await nextTick();
+      expect(wrapper.html().length).toBeGreaterThan(0);
+      expect(warnings, `Vue warnings in ${name}/demo.vue:\n${warnings.join('\n')}`).toEqual([]);
+    });
+  }
+});
diff --git a/vue/primitives/src/accordion/AccordionContent.vue b/vue/primitives/src/accordion/AccordionContent.vue
deleted file mode 100644
index 563f9f0..0000000
--- a/vue/primitives/src/accordion/AccordionContent.vue
+++ /dev/null
@@ -1,45 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The collapsible panel revealed when its item is open. Rendered as an ARIA
- * `region` labelled by its trigger and mounted/unmounted via `Presence` so
- * enter/leave transitions can run (use `forceMount` to keep it mounted for
- * custom animation).
- */
-export interface AccordionContentProps extends PrimitiveProps {
-  /** Keep content mounted even when closed. */
-  forceMount?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { useAccordionContext, useAccordionItemContext } from './context';
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
-import { useForwardExpose } from '@robonen/vue';
-
-const { as = 'div', forceMount = false } = defineProps<AccordionContentProps>();
-
-const { forwardRef } = useForwardExpose();
-const ctx = useAccordionContext();
-const item = useAccordionItemContext();
-</script>
-
-<template>
-  <Presence :present="forceMount || item.open.value">
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      role="region"
-      :id="item.contentId.value"
-      :aria-labelledby="item.triggerId.value"
-      :data-state="item.open.value ? 'open' : 'closed'"
-      :data-disabled="item.disabled.value ? '' : undefined"
-      :data-orientation="ctx.orientation.value"
-      :hidden="!item.open.value || undefined"
-    >
-      <slot :open="item.open.value" />
-    </Primitive>
-  </Presence>
-</template>
diff --git a/vue/primitives/src/alert-dialog/AlertDialogCancel.vue b/vue/primitives/src/alert-dialog/AlertDialogCancel.vue
deleted file mode 100644
index 594fa50..0000000
--- a/vue/primitives/src/alert-dialog/AlertDialogCancel.vue
+++ /dev/null
@@ -1,22 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The button that dismisses the alert without acting and closes the dialog.
- * Receives focus automatically when the alert opens, making it the safe default
- * choice; always include one so the user has a non-destructive way out.
- */
-export interface AlertDialogCancelProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { DialogClose } from '../dialog';
-
-const { as = 'button' } = defineProps<AlertDialogCancelProps>();
-</script>
-
-<template>
-  <DialogClose :as="as" data-alert-dialog-cancel>
-    <slot />
-  </DialogClose>
-</template>
diff --git a/vue/primitives/src/alert-dialog/__test__/AlertDialog.test.ts b/vue/primitives/src/alert-dialog/__test__/AlertDialog.test.ts
deleted file mode 100644
index a66c4c7..0000000
--- a/vue/primitives/src/alert-dialog/__test__/AlertDialog.test.ts
+++ /dev/null
@@ -1,118 +0,0 @@
-import { mount } from '@vue/test-utils';
-import type { VueWrapper } from '@vue/test-utils';
-import { afterEach, describe, expect, it } from 'vitest';
-import { defineComponent, h, nextTick, ref } from 'vue';
-import {
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogOverlay,
-  AlertDialogPortal,
-  AlertDialogRoot,
-  AlertDialogTitle,
-  AlertDialogTrigger,
-} from '../index';
-
-const wrappers: Array<VueWrapper<any>> = [];
-
-afterEach(() => {
-  while (wrappers.length) wrappers.pop()!.unmount();
-  document.body.innerHTML = '';
-  document.body.removeAttribute('style');
-  delete document.body.dataset['dismissableBlocking'];
-});
-
-function track<T extends VueWrapper<any>>(w: T): T {
-  wrappers.push(w);
-  return w;
-}
-
-function mountAlert(initialOpen = true) {
-  const open = ref(initialOpen);
-  const Harness = defineComponent({
-    setup() {
-      return () => h(
-        AlertDialogRoot,
-        {
-          open: open.value,
-          'onUpdate:open': (v: boolean | undefined) => { open.value = v!; },
-        },
-        {
-          default: () => [
-            h(AlertDialogTrigger, null, { default: () => 'Open' }),
-            h(AlertDialogPortal, null, {
-              default: () => [
-                h(AlertDialogOverlay),
-                h(AlertDialogContent, null, {
-                  default: () => [
-                    h(AlertDialogTitle, null, { default: () => 'Are you sure?' }),
-                    h(AlertDialogDescription, null, { default: () => 'This cannot be undone.' }),
-                    h(AlertDialogCancel, null, { default: () => 'Cancel' }),
-                    h(AlertDialogAction, null, { default: () => 'OK' }),
-                  ],
-                }),
-              ],
-            }),
-          ],
-        },
-      );
-    },
-  });
-  const w = track(mount(Harness, { attachTo: document.body }));
-  return { wrapper: w, open };
-}
-
-describe('AlertDialog', () => {
-  it('renders content with role="alertdialog"', async () => {
-    mountAlert(true);
-    await nextTick();
-    await nextTick();
-    const content = document.querySelector('[data-alert-dialog-content]');
-    expect(content).toBeTruthy();
-    expect(content!.getAttribute('role')).toBe('alertdialog');
-  });
-
-  it('labels content via Title and describes via Description', async () => {
-    mountAlert(true);
-    await nextTick();
-    await nextTick();
-    const content = document.querySelector<HTMLElement>('[data-alert-dialog-content]')!;
-    const labelledby = content.getAttribute('aria-labelledby');
-    const describedby = content.getAttribute('aria-describedby');
-    expect(labelledby).toMatch(/dialog-title/);
-    expect(describedby).toMatch(/dialog-description/);
-    expect(document.getElementById(labelledby!)?.textContent).toBe('Are you sure?');
-    expect(document.getElementById(describedby!)?.textContent).toBe('This cannot be undone.');
-  });
-
-  it('Cancel button closes the dialog', async () => {
-    const { open } = mountAlert(true);
-    await nextTick();
-    await nextTick();
-    const cancel = document.querySelector<HTMLButtonElement>('[data-alert-dialog-cancel]')!;
-    cancel.click();
-    await nextTick();
-    await nextTick();
-    expect(open.value).toBe(false);
-  });
-
-  it('Action button closes the dialog', async () => {
-    const { open } = mountAlert(true);
-    await nextTick();
-    await nextTick();
-    const action = document.querySelector<HTMLButtonElement>('[data-alert-dialog-action]')!;
-    action.click();
-    await nextTick();
-    await nextTick();
-    expect(open.value).toBe(false);
-  });
-
-  it('Cancel and Action carry data attributes', async () => {
-    mountAlert(true);
-    await nextTick();
-    await nextTick();
-    expect(document.querySelector('[data-alert-dialog-cancel]')).toBeTruthy();
-    expect(document.querySelector('[data-alert-dialog-action]')).toBeTruthy();
-  });
-});
diff --git a/vue/primitives/src/aspect-ratio/__test__/AspectRatio.test.ts b/vue/primitives/src/aspect-ratio/__test__/AspectRatio.test.ts
deleted file mode 100644
index 136b94c..0000000
--- a/vue/primitives/src/aspect-ratio/__test__/AspectRatio.test.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { AspectRatio } from '../index';
-
-describe('AspectRatio', () => {
-  it('renders with default 1:1 ratio', () => {
-    const wrapper = mount(AspectRatio);
-    const outer = wrapper.element as HTMLElement;
-    expect(outer.style.paddingBottom).toBe('100%');
-  });
-
-  it('computes padding-bottom from ratio', () => {
-    const wrapper = mount(AspectRatio, { props: { ratio: 16 / 9 } });
-    const outer = wrapper.element as HTMLElement;
-    expect(outer.style.paddingBottom).toMatch(/^56\.25%$/);
-  });
-
-  it('updates padding-bottom when ratio prop changes', async () => {
-    const wrapper = mount(AspectRatio, { props: { ratio: 16 / 9 } });
-    const outer = wrapper.element as HTMLElement;
-    expect(outer.style.paddingBottom).toBe('56.25%');
-
-    await wrapper.setProps({ ratio: 1 });
-    expect(outer.style.paddingBottom).toBe('100%');
-
-    await wrapper.setProps({ ratio: 4 / 3 });
-    expect(outer.style.paddingBottom).toBe('75%');
-  });
-
-  it('places inner element absolutely covering the wrapper', () => {
-    const wrapper = mount(AspectRatio, { props: { ratio: 4 / 3 }, slots: { default: '<img />' } });
-    const inner = wrapper.element.firstElementChild as HTMLElement;
-    expect(inner.style.position).toBe('absolute');
-    expect(inner.getAttribute('data-aspect-ratio')).toBe('true');
-  });
-});
diff --git a/vue/primitives/src/avatar/AvatarImage.vue b/vue/primitives/src/avatar/AvatarImage.vue
deleted file mode 100644
index 83e5564..0000000
--- a/vue/primitives/src/avatar/AvatarImage.vue
+++ /dev/null
@@ -1,89 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { AvatarImageLoadingStatus } from './context';
-
-/**
- * The image to display. It loads the `src` out of band and only renders once
- * the image has successfully loaded, reporting its loading status to the root
- * so the fallback can take over while loading or on error.
- */
-export interface AvatarImageProps extends PrimitiveProps {
-  /** Image source URL — loaded out of band before the image is shown. */
-  src?: string;
-  /** Alternative text describing the image. */
-  alt?: string;
-  /** Called whenever the image's loading status changes (`idle`/`loading`/`loaded`/`error`). */
-  onLoadingStatusChange?: (status: AvatarImageLoadingStatus) => void;
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed, onBeforeUnmount, ref, watch } from 'vue';
-import { useAvatarContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
-
-const { as = 'img', src, alt, onLoadingStatusChange } = defineProps<AvatarImageProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const ctx = useAvatarContext();
-
-const status = ref<AvatarImageLoadingStatus>('idle');
-
-function setStatus(next: AvatarImageLoadingStatus) {
-  status.value = next;
-  ctx.onImageLoadingStatusChange(next);
-  onLoadingStatusChange?.(next);
-}
-
-let currentImage: HTMLImageElement | null = null;
-
-function load(nextSrc: string | undefined) {
-  if (currentImage) {
-    currentImage.onload = null;
-    currentImage.onerror = null;
-    currentImage = null;
-  }
-  if (!nextSrc) {
-    setStatus('error');
-    return;
-  }
-  if (globalThis.window === undefined) {
-    setStatus('loading');
-    return;
-  }
-  setStatus('loading');
-  const img = new globalThis.Image();
-  currentImage = img;
-  img.onload = () => {
-    if (currentImage === img) setStatus('loaded');
-  };
-  img.onerror = () => {
-    if (currentImage === img) setStatus('error');
-  };
-  img.src = nextSrc;
-}
-
-watch(() => src, load, { immediate: true });
-
-onBeforeUnmount(() => {
-  if (currentImage) {
-    currentImage.onload = null;
-    currentImage.onerror = null;
-    currentImage = null;
-  }
-});
-
-const shouldRender = computed(() => status.value === 'loaded');
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    v-if="shouldRender"
-    :src="src"
-    :alt="alt"
-  />
-</template>
diff --git a/vue/primitives/src/avatar/__test__/Avatar.test.ts b/vue/primitives/src/avatar/__test__/Avatar.test.ts
deleted file mode 100644
index f2a15a8..0000000
--- a/vue/primitives/src/avatar/__test__/Avatar.test.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { defineComponent, h, nextTick } from 'vue';
-import { AvatarFallback, AvatarImage, AvatarRoot } from '../index';
-
-class MockImage {
-  onload: (() => void) | null = null;
-  onerror: (() => void) | null = null;
-  private _src = '';
-  set src(value: string) {
-    this._src = value;
-    queueMicrotask(() => {
-      if (value.includes('broken')) this.onerror?.();
-      else this.onload?.();
-    });
-  }
-
-  get src() { return this._src; }
-}
-
-describe('Avatar', () => {
-  beforeEach(() => {
-    vi.stubGlobal('Image', MockImage as unknown as typeof Image);
-  });
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  it('renders fallback until image loads', async () => {
-    const w = mount(defineComponent({
-      setup: () => () => h(AvatarRoot, null, {
-        default: () => [
-          h(AvatarImage, { src: '/ok.png', alt: 'user' }),
-          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
-        ],
-      }),
-    }));
-    expect(w.find('.fb').exists()).toBe(true);
-    expect(w.find('img').exists()).toBe(false);
-    await new Promise(r => queueMicrotask(() => r(null)));
-    await nextTick();
-    expect(w.find('img').exists()).toBe(true);
-    expect(w.find('img').attributes('src')).toBe('/ok.png');
-    expect(w.find('.fb').exists()).toBe(false);
-  });
-
-  it('keeps fallback visible on error', async () => {
-    const w = mount(defineComponent({
-      setup: () => () => h(AvatarRoot, null, {
-        default: () => [
-          h(AvatarImage, { src: '/broken.png' }),
-          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
-        ],
-      }),
-    }));
-    await new Promise(r => queueMicrotask(() => r(null)));
-    await nextTick();
-    expect(w.find('img').exists()).toBe(false);
-    expect(w.find('.fb').exists()).toBe(true);
-  });
-
-  it('delays fallback rendering when delayMs is set', async () => {
-    vi.useFakeTimers();
-    const w = mount(defineComponent({
-      setup: () => () => h(AvatarRoot, null, {
-        default: () => [
-          h(AvatarFallback, { class: 'fb', delayMs: 500 }, { default: () => 'AB' }),
-        ],
-      }),
-    }));
-    expect(w.find('.fb').exists()).toBe(false);
-    vi.advanceTimersByTime(500);
-    await nextTick();
-    expect(w.find('.fb').exists()).toBe(true);
-    vi.useRealTimers();
-  });
-
-  it('sets data-status on the root element', async () => {
-    const w = mount(defineComponent({
-      setup: () => () => h(AvatarRoot, null, {
-        default: () => [
-          h(AvatarImage, { src: '/ok.png' }),
-          h(AvatarFallback, null, { default: () => '?' }),
-        ],
-      }),
-    }));
-    await nextTick();
-    expect(w.element.getAttribute('data-status')).toBe('loading');
-    await new Promise(r => queueMicrotask(() => r(null)));
-    await nextTick();
-    expect(w.element.getAttribute('data-status')).toBe('loaded');
-  });
-});
diff --git a/vue/primitives/src/calendar/CalendarCellTrigger.vue b/vue/primitives/src/calendar/CalendarCellTrigger.vue
deleted file mode 100644
index 2c20ea3..0000000
--- a/vue/primitives/src/calendar/CalendarCellTrigger.vue
+++ /dev/null
@@ -1,202 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The focusable, clickable day button inside a `CalendarCell`. Selects its
- * `day` on click/Enter/Space, drives roving focus and full arrow-key /
- * Home-End / PageUp-Down keyboard navigation (paging the month when focus
- * crosses the visible range), and exposes day state through its slot.
- */
-export interface CalendarCellTriggerProps extends PrimitiveProps {
-  /** The day this trigger represents. */
-  day: Date;
-  /** The month this trigger's cell belongs to. Defaults to grid context. */
-  month?: Date;
-}
-
-export interface CalendarCellTriggerSlotProps {
-  dayValue: string;
-  disabled: boolean;
-  selected: boolean;
-  today: boolean;
-  outsideView: boolean;
-  unavailable: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { useForwardExpose } from '@robonen/vue';
-import { computed, nextTick } from 'vue';
-import { Primitive } from '../primitive';
-import { useCalendarGridContext, useCalendarRootContext } from './context';
-import { addDays, addMonths, addYears, formatFullDate, isAfter, isBefore, isSameDay, isSameMonth, toIsoDate } from './utils';
-
-const { as = 'div', day, month } = defineProps<CalendarCellTriggerProps>();
-
-defineSlots<{
-  default?: (props: CalendarCellTriggerSlotProps) => unknown;
-}>();
-
-const ctx = useCalendarRootContext();
-const gridCtx = useCalendarGridContext();
-const { forwardRef } = useForwardExpose();
-
-const monthValue = computed(() => month ?? gridCtx.month.value);
-
-const isOutsideView = computed(() => !isSameMonth(day, monthValue.value));
-const isDisabled = computed(() => ctx.isDateDisabled(day));
-const isUnavailable = computed(() => ctx.isDateUnavailable(day));
-const isSelected = computed(() => ctx.isDateSelected(day));
-const isToday = computed(() => isSameDay(day, new Date()));
-
-const dayValue = computed(() => day.getDate().toLocaleString(ctx.locale.value));
-const labelText = computed(() => formatFullDate(day, ctx.locale.value));
-
-const isFocusedDate = computed(() => {
-  if (isOutsideView.value || isDisabled.value) return false;
-  if (ctx.focusedDate.value) return isSameDay(day, ctx.focusedDate.value);
-  // Fallback focusable: selected, else today (if in view), else first day of month.
-  if (ctx.modelValue.value && isSameMonth(ctx.modelValue.value, monthValue.value))
-    return isSameDay(day, ctx.modelValue.value);
-  const today = new Date();
-  if (isSameMonth(today, monthValue.value))
-    return isSameDay(day, today);
-  return day.getDate() === 1 && isSameMonth(day, monthValue.value);
-});
-
-function selectIfAllowed() {
-  if (ctx.readonly.value) return;
-  if (isDisabled.value || isUnavailable.value) return;
-  ctx.setDate(day);
-  ctx.focusedDate.value = day;
-}
-
-function handleClick() {
-  selectIfAllowed();
-}
-
-function focusByDataValue(target: Date) {
-  const parent = ctx.parentElement.value;
-  if (!parent) return false;
-  const el = parent.querySelector<HTMLElement>(
-    `[data-primitives-calendar-cell-trigger][data-value="${toIsoDate(target)}"]:not([data-outside-view])`,
-  );
-  if (el) {
-    el.focus();
-    return true;
-  }
-  return false;
-}
-
-function shiftFocus(target: Date) {
-  if (ctx.minValue.value && isBefore(target, ctx.minValue.value)) return;
-  if (ctx.maxValue.value && isAfter(target, ctx.maxValue.value)) return;
-  ctx.focusedDate.value = target;
-  if (focusByDataValue(target)) return;
-  // Crossed visible range — page placeholder and retry.
-  if (target > ctx.placeholder.value) {
-    if (ctx.isNextButtonDisabled()) return;
-    ctx.nextPage();
-  }
-  else {
-    if (ctx.isPrevButtonDisabled()) return;
-    ctx.prevPage();
-  }
-  nextTick(() => focusByDataValue(target));
-}
-
-function handleKeyDown(e: KeyboardEvent) {
-  if (isDisabled.value) return;
-  const rtl = ctx.dir.value === 'rtl' ? -1 : 1;
-  switch (e.key) {
-    case 'ArrowRight':
-      e.preventDefault();
-      shiftFocus(addDays(day, rtl));
-      break;
-    case 'ArrowLeft':
-      e.preventDefault();
-      shiftFocus(addDays(day, -rtl));
-      break;
-    case 'ArrowUp':
-      e.preventDefault();
-      shiftFocus(addDays(day, -7));
-      break;
-    case 'ArrowDown':
-      e.preventDefault();
-      shiftFocus(addDays(day, 7));
-      break;
-    case 'Home': {
-      e.preventDefault();
-      const dow = day.getDay();
-      const offset = (dow - ctx.weekStartsOn.value + 7) % 7;
-      shiftFocus(addDays(day, -offset));
-      break;
-    }
-    case 'End': {
-      e.preventDefault();
-      const dow = day.getDay();
-      const offset = (dow - ctx.weekStartsOn.value + 7) % 7;
-      shiftFocus(addDays(day, 6 - offset));
-      break;
-    }
-    case 'PageUp':
-      e.preventDefault();
-      shiftFocus(e.shiftKey ? addYears(day, -1) : addMonths(day, -1));
-      break;
-    case 'PageDown':
-      e.preventDefault();
-      shiftFocus(e.shiftKey ? addYears(day, 1) : addMonths(day, 1));
-      break;
-    case 'Enter':
-    case ' ':
-      e.preventDefault();
-      selectIfAllowed();
-      break;
-  }
-}
-
-function handleFocus() {
-  ctx.focusedDate.value = day;
-}
-
-const dataValue = computed(() => toIsoDate(day));
-const tabindex = computed(() => {
-  if (isFocusedDate.value) return 0;
-  if (isOutsideView.value || isDisabled.value) return undefined;
-  return -1;
-});
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    role="button"
-    :aria-label="labelText"
-    :aria-disabled="(isDisabled || isUnavailable) ? true : undefined"
-    :aria-selected="isSelected ? true : undefined"
-    :tabindex="tabindex"
-    :data-primitives-calendar-cell-trigger="''"
-    :data-value="dataValue"
-    :data-selected="isSelected ? '' : undefined"
-    :data-disabled="isDisabled ? '' : undefined"
-    :data-unavailable="isUnavailable ? '' : undefined"
-    :data-outside-view="isOutsideView ? '' : undefined"
-    :data-today="isToday ? '' : undefined"
-    :data-focused="isFocusedDate ? '' : undefined"
-    @click="handleClick"
-    @focus="handleFocus"
-    @keydown="handleKeyDown"
-  >
-    <slot
-      :day-value="dayValue"
-      :disabled="isDisabled"
-      :selected="isSelected"
-      :today="isToday"
-      :outside-view="isOutsideView"
-      :unavailable="isUnavailable"
-    >
-      {{ dayValue }}
-    </slot>
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/calendar/CalendarGridHead.vue b/vue/primitives/src/calendar/CalendarGridHead.vue
deleted file mode 100644
index ce273f7..0000000
--- a/vue/primitives/src/calendar/CalendarGridHead.vue
+++ /dev/null
@@ -1,21 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The grid's `<thead>` wrapper holding the row of weekday `CalendarHeadCell`
- * labels.
- */
-export interface CalendarGridHeadProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-
-const { as = 'thead' } = defineProps<CalendarGridHeadProps>();
-</script>
-
-<template>
-  <Primitive :as="as" :data-primitives-calendar-grid-head="''">
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/canvas/angle-dial/AngleDialRoot.vue b/vue/primitives/src/canvas/angle-dial/AngleDialRoot.vue
new file mode 100644
index 0000000..0d22f5f
--- /dev/null
+++ b/vue/primitives/src/canvas/angle-dial/AngleDialRoot.vue
@@ -0,0 +1,335 @@
+<script lang="ts">
+import type { AngleDialDirection, AngleDialSnap, AngleDialWrap } from './context';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * An accessible circular angle / rotation picker. The root owns the angle value
+ * in DEGREES (controlled via `v-model:value` or uncontrolled via
+ * `defaultValue`), converts pointer presses anywhere on the dial into an angle,
+ * snaps to `snap` / `step`, and handles the `0` / `360` seam either by wrapping
+ * continuously (`wrap`) or bounding to an arc (`clamp`). It provides context to
+ * `AngleDialThumb`, which renders the `role="slider"` handle on the ring and
+ * owns keyboard interaction.
+ *
+ * The angle convention is fixed: `0°` points UP (12 o'clock) and increases
+ * CLOCKWISE (right = 90°, down = 180°, left = 270°). Reach for it for rotation,
+ * heading, or hue (a hue ring is `min: 0, max: 360, wrap: 'wrap'`).
+ */
+export interface AngleDialRootProps extends PrimitiveProps {
+  /** Min angle in degrees. @default 0 */
+  min?: number;
+  /** Max angle in degrees. @default 360 */
+  max?: number;
+  /** Step granularity in degrees. @default 1 */
+  step?: number;
+  /** Increment for Page keys / Shift+Arrow, in degrees. @default 15 */
+  largeStep?: number;
+  /**
+   * Seam behavior at the bounds. `'wrap'` lets the value cross `0` / `360`
+   * continuously; `'clamp'` bounds it to the arc `[min, max]`.
+   * @default 'wrap'
+   */
+  wrap?: AngleDialWrap;
+  /**
+   * Snap increments in degrees — a scalar (e.g. `15`) or an explicit list
+   * (e.g. `[0, 45, 90, 135, 180, 225, 270, 315]`). `undefined` disables
+   * snapping (only `step` rounding applies).
+   * @default undefined
+   */
+  snap?: AngleDialSnap;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
+  dir?: AngleDialDirection;
+  /** Uncontrolled initial angle in degrees. @default 0 */
+  defaultValue?: number;
+}
+
+export interface AngleDialRootEmits {
+  /** Emitted when a drag settles (pointerup), with the final angle in degrees. */
+  valueCommit: [value: number];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideAngleDialContext } from './context';
+import { useDirection } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { clamp } from '@robonen/stdlib';
+import {
+  applySnap,
+  getStepDecimals,
+  pointToAngle,
+  roundToStep,
+  shortestDelta,
+} from './utils';
+
+const {
+  min = 0,
+  max = 360,
+  step = 1,
+  largeStep = 15,
+  wrap = 'wrap',
+  snap,
+  disabled = false,
+  dir,
+  defaultValue = 0,
+  as = 'div',
+} = defineProps<AngleDialRootProps>();
+
+const emit = defineEmits<AngleDialRootEmits>();
+
+const direction = useDirection(() => dir);
+
+// `defineModel('value')` drives controlled (`v-model:value`) and uncontrolled
+// modes; in uncontrolled mode it is `undefined` until first write, so the
+// internal `localValue` seeds from `defaultValue`. `null` is tolerated and
+// treated like "no value" for parity with controllers that reset by binding it.
+const model = defineModel<number | null>('value');
+
+const seed = typeof model.value === 'number' ? model.value : defaultValue;
+const localValue = shallowRef<number>(seed);
+
+// Cache decimals per `step` out of the pointermove hot path.
+let stepDecimals = getStepDecimals(step);
+watch(() => step, (s) => {
+  stepDecimals = getStepDecimals(s);
+});
+
+watch(model, (v) => {
+  if (v === null || v === undefined) return;
+  if (v === localValue.value) return;
+  localValue.value = v;
+});
+
+const value = computed<number>({
+  get: () => localValue.value,
+  set: (v) => {
+    if (v === localValue.value) return;
+    localValue.value = v;
+    // `defineModel` emits `update:value` on write — no manual emit needed.
+    model.value = v;
+  },
+});
+
+/**
+ * Normalize a raw angle (degrees) into the committed value, applying snap then
+ * step rounding then the wrap/clamp seam policy.
+ *
+ * In `wrap` mode the result is folded back into `[min, max)` (a full turn); in
+ * `clamp` mode it is bounded to `[min, max]`.
+ */
+function resolve(raw: number): number {
+  const isWrap = wrap === 'wrap';
+  let v = applySnap(raw, snap, isWrap);
+  v = roundToStep(v, step, min, stepDecimals);
+  if (isWrap) {
+    const span = max - min;
+    if (span <= 0) return min;
+    // Fold into [min, max): a 360-span dial returns [0, 360).
+    const folded = ((v - min) % span + span) % span + min;
+    return folded;
+  }
+  return clamp(v, min, max);
+}
+
+function commit(): void {
+  emit('valueCommit', localValue.value);
+}
+
+// ── pointer → angle ───────────────────────────────────────────────────────
+const rootRef = shallowRef<HTMLElement | null>(null);
+
+/** Center + radius of the dial from its current rect; `radius === 0` when unlaid-out. */
+function geometry(): { cx: number; cy: number; radius: number } | null {
+  const el = rootRef.value;
+  if (!el) return null;
+  const rect = el.getBoundingClientRect();
+  // Guard size===0 (mirror SliderRoot's `if (size===0) return min`): an
+  // unlaid-out dial has no meaningful center, so the caller keeps the value.
+  const size = Math.min(rect.width, rect.height);
+  if (size === 0) return null;
+  return {
+    cx: rect.left + rect.width / 2,
+    cy: rect.top + rect.height / 2,
+    radius: size / 2,
+  };
+}
+
+// Accumulator state for `wrap`-mode seam continuity. `lastRaw` is the previous
+// frame's raw pointer angle; `accum` is the unwrapped running angle. Tracking
+// the signed shortest delta per frame means dragging across the seam (e.g.
+// 350° → 10°) accumulates +20° rather than snapping −340°.
+let lastRaw = 0;
+let accum = 0;
+
+/**
+ * Convert a client point to an angle and commit it. In `wrap` mode the value is
+ * accumulated via the shortest per-frame delta so the seam is crossed smoothly;
+ * a pointer exactly at the center (radius 0 from the center) is ignored.
+ */
+function applyPointer(
+  point: { x: number; y: number },
+  first: boolean,
+  geo?: { cx: number; cy: number; radius: number } | null,
+): void {
+  if (disabled) return;
+  // Use the gesture-cached geometry when given (the dial cannot move/resize
+  // mid-drag), else measure live. Caching avoids a getBoundingClientRect reflow
+  // on every onMove frame.
+  const g = geo ?? geometry();
+  if (!g) return;
+  const dx = point.x - g.cx;
+  const dy = point.y - g.cy;
+  // Pointer exactly at center → no defined angle; ignore (keep current value).
+  if (dx === 0 && dy === 0) return;
+
+  const raw = pointToAngle(point, { x: g.cx, y: g.cy });
+
+  if (wrap === 'wrap') {
+    if (first) {
+      // Seed the accumulator from the current value, re-based so the first
+      // frame's raw angle maps to it without a jump.
+      accum = raw;
+      lastRaw = raw;
+    }
+    else {
+      accum += shortestDelta(lastRaw, raw);
+      lastRaw = raw;
+    }
+    value.value = resolve(accum);
+  }
+  else {
+    // Clamp mode: the raw angle is a linear coordinate; snapping/rounding then
+    // clamp to the arc. No accumulation — pushing past an end simply clamps.
+    value.value = resolve(raw);
+  }
+}
+
+// Center + radius snapshotted at gesture start and reused each frame.
+let gestureGeo: { cx: number; cy: number; radius: number } | null = null;
+
+usePointerDrag(rootRef, {
+  threshold: 0,
+  disabled: () => disabled,
+  // Engage immediately on press: position the value to the press point.
+  onStart: (state) => {
+    gestureGeo = geometry();
+    applyPointer(state.point, true, gestureGeo);
+  },
+  onMove: (state) => {
+    applyPointer(state.point, false, gestureGeo);
+  },
+  onCommit: () => {
+    commit();
+  },
+  onEnd: () => {
+    gestureGeo = null;
+  },
+});
+
+// ── keyboard nudge (delegated from the thumb) ──────────────────────────────
+function nudge(delta: number): void {
+  if (disabled) return;
+  const current = localValue.value;
+  // Walk from the current value; `resolve` re-folds (wrap) or clamps (clamp).
+  // Near the seam, wrap mode keeps moving in one direction before re-folding.
+  let next = resolve(current + delta);
+  // When `snap` is coarser than `step`, a single `delta` can resolve back to the
+  // current snap point — which would freeze the keyboard. Keep advancing in the
+  // delta direction until the resolved value actually changes (or we cover a
+  // full turn and conclude there's nowhere else to land, e.g. a clamped end).
+  if (next === current && delta !== 0) {
+    const span = max - min || 360;
+    const maxSteps = Math.ceil(span / Math.max(Math.abs(delta), 1)) + 2;
+    let probe = current;
+    for (let i = 0; i < maxSteps; i++) {
+      probe += delta;
+      const candidate = resolve(probe);
+      if (candidate !== current) {
+        next = candidate;
+        break;
+      }
+    }
+  }
+  if (next === current) return;
+  value.value = next;
+  commit();
+}
+
+function setValue(deg: number): void {
+  if (disabled) return;
+  value.value = resolve(deg);
+  commit();
+}
+
+function toStart(): void {
+  if (disabled) return;
+  value.value = resolve(min);
+  commit();
+}
+
+function toEnd(): void {
+  if (disabled) return;
+  // In wrap mode `max` folds back to `min`; land just before the seam so End is
+  // distinguishable from Home. In clamp mode End is exactly `max`.
+  if (wrap === 'wrap') {
+    const span = max - min;
+    const justBefore = span <= 0 ? min : max - step;
+    value.value = resolve(justBefore);
+  }
+  else {
+    value.value = clamp(roundToStep(max, step, min, stepDecimals), min, max);
+  }
+  commit();
+}
+
+// Keep the value valid if bounds change.
+watch([() => min, () => max, () => wrap], () => {
+  const next = resolve(localValue.value);
+  if (next !== localValue.value) value.value = next;
+});
+
+provideAngleDialContext({
+  value,
+  min: toRef(() => min),
+  max: toRef(() => max),
+  step: toRef(() => step),
+  largeStep: toRef(() => largeStep),
+  wrap: toRef(() => wrap),
+  snap: toRef(() => snap),
+  disabled: toRef(() => disabled),
+  direction,
+  setValue,
+  nudge,
+  toStart,
+  toEnd,
+});
+
+defineExpose({ value });
+
+// `useForwardExpose` runs AFTER `defineExpose` so the composable merges the
+// prior expose bindings (plus props + `$el`) instead of clobbering them.
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (el) => {
+  rootRef.value = el ?? null;
+}, { immediate: true });
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :dir="direction"
+  >
+    <slot :value="value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/angle-dial/AngleDialThumb.vue b/vue/primitives/src/canvas/angle-dial/AngleDialThumb.vue
new file mode 100644
index 0000000..b697b6a
--- /dev/null
+++ b/vue/primitives/src/canvas/angle-dial/AngleDialThumb.vue
@@ -0,0 +1,132 @@
+<script lang="ts">
+import type { AngleDialValueText } from './context';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The draggable handle of an `AngleDialRoot`, rendered as `role="slider"` and
+ * positioned on the ring by the current angle. It owns keyboard interaction
+ * (Arrow keys step by `step`, Shift+Arrow / Page keys by `largeStep`, Home / End
+ * jump to the bounds) and carries the ARIA value attributes.
+ *
+ * It INTENTIONALLY omits `aria-orientation`: a radial control has no single
+ * axis, so claiming `horizontal` / `vertical` would be misleading. Because a
+ * bare number is ambiguous on a circle, `aria-valuetext` strongly defaults to
+ * `` `${Math.round(deg)}°` `` (override via `valueText`). Give the thumb an
+ * `aria-label` (defaults to `'Angle'`). Exposes `value` and `point` (its
+ * fractional `{ x, y }` position on a unit circle, with `0.5,0.5` at center) as
+ * slot props for positioning.
+ */
+export interface AngleDialThumbProps extends PrimitiveProps {
+  /**
+   * Formatter producing a human-friendly `aria-valuetext` from the angle in
+   * degrees. Defaults to `` (deg) => `${Math.round(deg)}°` `` — a degree suffix
+   * disambiguates the bare number on a circular control. Return `undefined` to
+   * omit `aria-valuetext`.
+   * @default (deg) => `${Math.round(deg)}°`
+   */
+  valueText?: AngleDialValueText;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useAttrs } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useAngleDialContext } from './context';
+import { angleToPoint } from './utils';
+
+// Module-shareable unit-circle center; `angleToPoint` only reads `center.x` /
+// `center.y`, so a single frozen const avoids re-allocating the literal on every
+// drag-frame recompute of `point`.
+const CENTER = Object.freeze({ x: 0.5, y: 0.5 });
+
+const { as = 'span', valueText = (deg: number) => `${Math.round(deg)}°` } = defineProps<AngleDialThumbProps>();
+const ctx = useAngleDialContext();
+const attrs = useAttrs();
+
+const value = computed(() => ctx.value.value);
+
+// Fractional position on a unit circle for CSS placement: x/y in [0, 1] with the
+// center at (0.5, 0.5). Consumers typically render `left: x*100%, top: y*100%`
+// on a thumb sized so its center lands on the ring.
+const point = computed<{ x: number; y: number }>(() => angleToPoint(value.value, 0.5, CENTER));
+
+const positionStyle = computed<{ left: string; top: string }>(() => ({
+  left: `${point.value.x * 100}%`,
+  top: `${point.value.y * 100}%`,
+}));
+
+// Fall back to 'Angle' only when the consumer has not supplied an explicit
+// `aria-label` / `aria-labelledby`.
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return 'Angle';
+});
+
+// Humanised `aria-valuetext`; a consumer-supplied `aria-valuetext` attr wins
+// (it falls through via `$attrs`).
+const valueTextAttr = computed<string | undefined>(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  return valueText(value.value);
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const step = ctx.step.value;
+  const big = ctx.largeStep.value;
+  const unit = event.shiftKey ? big : step;
+  switch (event.key) {
+    case 'ArrowRight':
+    case 'ArrowUp':
+      event.preventDefault();
+      ctx.nudge(unit);
+      return;
+    case 'ArrowLeft':
+    case 'ArrowDown':
+      event.preventDefault();
+      ctx.nudge(-unit);
+      return;
+    case 'PageUp':
+      event.preventDefault();
+      ctx.nudge(big);
+      return;
+    case 'PageDown':
+      event.preventDefault();
+      ctx.nudge(-big);
+      return;
+    case 'Home':
+      event.preventDefault();
+      ctx.toStart();
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.toEnd();
+      break;
+    default:
+  }
+}
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :as="as"
+    :ref="forwardRef"
+    role="slider"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
+    :aria-valuemin="ctx.min.value"
+    :aria-valuemax="ctx.max.value"
+    :aria-valuenow="value"
+    :aria-valuetext="valueTextAttr"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :value="value" :point="point" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/angle-dial/__test__/AngleDial.test.ts b/vue/primitives/src/canvas/angle-dial/__test__/AngleDial.test.ts
new file mode 100644
index 0000000..4142761
--- /dev/null
+++ b/vue/primitives/src/canvas/angle-dial/__test__/AngleDial.test.ts
@@ -0,0 +1,423 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { AngleDialRoot, AngleDialThumb } from '../index';
+import {
+  angleToHue,
+  angleToPoint,
+  circularDistance,
+  normalizeDeg,
+  pointToAngle,
+  shortestDelta,
+} from '../utils';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+type RootOpts = Partial<{
+  min: number;
+  max: number;
+  step: number;
+  largeStep: number;
+  wrap: 'wrap' | 'clamp';
+  snap: number | number[];
+  disabled: boolean;
+  defaultValue: number;
+}>;
+
+function mountDial(opts: RootOpts = {}, thumbProps: Record<string, unknown> = {}) {
+  const model = ref<number | undefined>(undefined);
+  const Harness = defineComponent({
+    setup() {
+      return () => h(AngleDialRoot, {
+        value: model.value,
+        'onUpdate:value': (v: number | null | undefined) => { model.value = v ?? undefined; },
+        ...opts,
+      }, {
+        default: () => h(AngleDialThumb, thumbProps),
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false });
+  el.dispatchEvent(event);
+}
+
+function thumbEl(): HTMLElement {
+  return document.querySelector<HTMLElement>('[role="slider"]')!;
+}
+
+describe('AngleDialThumb — ARIA', () => {
+  it('role="slider" with aria-valuemin/max/now and NO aria-orientation', async () => {
+    mountDial({ defaultValue: 45, min: 0, max: 360 });
+    await nextTick();
+    const thumb = thumbEl();
+    expect(thumb).toBeTruthy();
+    expect(thumb.getAttribute('role')).toBe('slider');
+    expect(thumb.getAttribute('aria-valuemin')).toBe('0');
+    expect(thumb.getAttribute('aria-valuemax')).toBe('360');
+    expect(thumb.getAttribute('aria-valuenow')).toBe('45');
+    // A radial control has no axis — aria-orientation must be absent.
+    expect(thumb.getAttribute('aria-orientation')).toBeNull();
+    expect(thumb.tabIndex).toBe(0);
+  });
+
+  it('aria-valuetext defaults to "<n>°"', async () => {
+    mountDial({ defaultValue: 45 });
+    await nextTick();
+    expect(thumbEl().getAttribute('aria-valuetext')).toBe('45°');
+  });
+
+  it('rounds the default valuetext degrees', async () => {
+    mountDial({ defaultValue: 33.6, step: 0.1 });
+    await nextTick();
+    expect(thumbEl().getAttribute('aria-valuetext')).toBe('34°');
+  });
+
+  it('a custom valueText formatter overrides the default', async () => {
+    mountDial({ defaultValue: 90 }, { valueText: (deg: number) => `${deg} degrees` });
+    await nextTick();
+    expect(thumbEl().getAttribute('aria-valuetext')).toBe('90 degrees');
+  });
+
+  it('an explicit aria-valuetext attr wins over the formatter', async () => {
+    mountDial({ defaultValue: 90 }, { 'aria-valuetext': 'east' });
+    await nextTick();
+    expect(thumbEl().getAttribute('aria-valuetext')).toBe('east');
+  });
+
+  it('defaults aria-label to "Angle" and lets an explicit label win', async () => {
+    mountDial({ defaultValue: 0 });
+    await nextTick();
+    expect(thumbEl().getAttribute('aria-label')).toBe('Angle');
+    document.body.innerHTML = '';
+    while (wrappers.length) wrappers.pop()!.unmount();
+    mountDial({ defaultValue: 0 }, { 'aria-label': 'Hue' });
+    await nextTick();
+    expect(thumbEl().getAttribute('aria-label')).toBe('Hue');
+  });
+});
+
+describe('AngleDialThumb — keyboard', () => {
+  it('ArrowRight increments by step, ArrowLeft decrements', async () => {
+    const { model } = mountDial({ defaultValue: 50, step: 5, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(55);
+    keydown(thumb, 'ArrowLeft');
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toBe(45);
+  });
+
+  it('ArrowUp increments, ArrowDown decrements', async () => {
+    const { model } = mountDial({ defaultValue: 50, step: 5, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'ArrowUp');
+    await nextTick();
+    expect(model.value).toBe(55);
+    keydown(thumb, 'ArrowDown');
+    await nextTick();
+    expect(model.value).toBe(50);
+  });
+
+  it('Shift+Arrow jumps by largeStep', async () => {
+    const { model } = mountDial({ defaultValue: 100, step: 1, largeStep: 15, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(model.value).toBe(115);
+    keydown(thumb, 'ArrowLeft', { shiftKey: true });
+    await nextTick();
+    expect(model.value).toBe(100);
+  });
+
+  it('PageUp / PageDown jump by largeStep', async () => {
+    const { model } = mountDial({ defaultValue: 100, step: 1, largeStep: 15, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'PageUp');
+    await nextTick();
+    expect(model.value).toBe(115);
+    keydown(thumb, 'PageDown');
+    keydown(thumb, 'PageDown');
+    await nextTick();
+    expect(model.value).toBe(85);
+  });
+
+  it('Home/End jump to the bounds (clamp mode)', async () => {
+    const { model } = mountDial({ defaultValue: 90, min: 0, max: 270, step: 1, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value).toBe(0);
+    keydown(thumb, 'End');
+    await nextTick();
+    expect(model.value).toBe(270);
+  });
+
+  it('Home goes to the seam start and End just before the seam (wrap mode)', async () => {
+    const { model } = mountDial({ defaultValue: 90, min: 0, max: 360, step: 1, wrap: 'wrap' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value).toBe(0);
+    keydown(thumb, 'End');
+    await nextTick();
+    // max (360) folds back to 0 in wrap mode, so End lands just before the seam.
+    expect(model.value).toBe(359);
+  });
+
+  it('disabled: tabindex=-1, aria-disabled, keys do nothing', async () => {
+    const { model } = mountDial({ defaultValue: 50, disabled: true });
+    await nextTick();
+    const thumb = thumbEl();
+    expect(thumb.tabIndex).toBe(-1);
+    expect(thumb.getAttribute('aria-disabled')).toBe('true');
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+
+  it('preventDefault is called on handled keys', async () => {
+    mountDial({ defaultValue: 50, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    const ev = new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true, cancelable: true });
+    thumb.dispatchEvent(ev);
+    expect(ev.defaultPrevented).toBe(true);
+  });
+});
+
+describe('AngleDialRoot — seam handling', () => {
+  it('wrap mode crosses the 0/360 seam forward without jumping backwards', async () => {
+    const { model } = mountDial({ defaultValue: 359, min: 0, max: 360, step: 1, largeStep: 5, wrap: 'wrap' });
+    await nextTick();
+    const thumb = thumbEl();
+    // 359 + 5 (large) should land at 4 (wrapped through 0), not 354.
+    keydown(thumb, 'PageUp');
+    await nextTick();
+    expect(model.value).toBe(4);
+  });
+
+  it('wrap mode crosses the seam backward (0 → 355)', async () => {
+    const { model } = mountDial({ defaultValue: 0, min: 0, max: 360, step: 1, largeStep: 5, wrap: 'wrap' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'PageDown');
+    await nextTick();
+    expect(model.value).toBe(355);
+  });
+
+  it('clamp mode bounds at the arc ends instead of wrapping', async () => {
+    const { model } = mountDial({ defaultValue: 355, min: 0, max: 360, step: 1, largeStep: 15, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'PageUp');
+    await nextTick();
+    expect(model.value).toBe(360);
+    // Pushing further stays clamped.
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(360);
+  });
+
+  it('clamp mode bounds at the low end', async () => {
+    const { model } = mountDial({ defaultValue: 5, min: 0, max: 360, step: 1, largeStep: 15, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    keydown(thumb, 'PageDown');
+    await nextTick();
+    expect(model.value).toBe(0);
+  });
+});
+
+describe('AngleDialRoot — snap', () => {
+  it('a snapped keyboard nudge advances to the next snap target', async () => {
+    const { model } = mountDial({ defaultValue: 0, step: 1, snap: 15, wrap: 'clamp' });
+    await nextTick();
+    const thumb = thumbEl();
+    // From a snap point, one ArrowRight steps to the next reachable snap target
+    // (15) instead of freezing at 0 (snap is coarser than step).
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(15);
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(30);
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toBe(15);
+  });
+});
+
+describe('AngleDialRoot — pointer drag', () => {
+  function rootEl(): HTMLElement {
+    // The root is the AngleDialRoot's rendered element (the dial container).
+    return document.querySelector<HTMLElement>('[role="slider"]')!.parentElement!;
+  }
+
+  function sizeRoot(el: HTMLElement): { cx: number; cy: number } {
+    el.style.position = 'fixed';
+    el.style.left = '0px';
+    el.style.top = '0px';
+    el.style.width = '200px';
+    el.style.height = '200px';
+    const rect = el.getBoundingClientRect();
+    return { cx: rect.left + rect.width / 2, cy: rect.top + rect.height / 2 };
+  }
+
+  function pointer(el: HTMLElement, type: string, x: number, y: number): void {
+    const ev = new PointerEvent(type, {
+      pointerId: 1,
+      button: 0,
+      clientX: x,
+      clientY: y,
+      bubbles: true,
+      cancelable: true,
+    });
+    el.dispatchEvent(ev);
+  }
+
+  it('pressing to the right of center sets the value to ~90° (0=up, clockwise)', async () => {
+    const { model } = mountDial({ defaultValue: 0, min: 0, max: 360, step: 1, wrap: 'wrap' });
+    await nextTick();
+    const root = rootEl();
+    const { cx, cy } = sizeRoot(root);
+    // A point straight to the right of center.
+    pointer(root, 'pointerdown', cx + 50, cy);
+    pointer(root, 'pointerup', cx + 50, cy);
+    await nextTick();
+    expect(model.value).toBe(90);
+  });
+
+  it('pressing below center sets the value to ~180°', async () => {
+    const { model } = mountDial({ defaultValue: 0, min: 0, max: 360, step: 1, wrap: 'wrap' });
+    await nextTick();
+    const root = rootEl();
+    const { cx, cy } = sizeRoot(root);
+    pointer(root, 'pointerdown', cx, cy + 50);
+    pointer(root, 'pointerup', cx, cy + 50);
+    await nextTick();
+    expect(model.value).toBe(180);
+  });
+
+  it('a press exactly at center is ignored (no angle)', async () => {
+    const { model } = mountDial({ defaultValue: 42, min: 0, max: 360, step: 1, wrap: 'wrap' });
+    await nextTick();
+    const root = rootEl();
+    const { cx, cy } = sizeRoot(root);
+    pointer(root, 'pointerdown', cx, cy);
+    pointer(root, 'pointerup', cx, cy);
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+
+  it('emits valueCommit on pointerup', async () => {
+    const committed: number[] = [];
+    const model = ref<number | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(AngleDialRoot, {
+        value: model.value,
+        wrap: 'wrap',
+        'onUpdate:value': (v: number | null | undefined) => { model.value = v ?? undefined; },
+        onValueCommit: (v: number) => committed.push(v),
+      }, { default: () => h(AngleDialThumb) }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[role="slider"]')!.parentElement!;
+    const { cx, cy } = sizeRoot(root);
+    pointer(root, 'pointerdown', cx + 50, cy);
+    pointer(root, 'pointerup', cx + 50, cy);
+    await nextTick();
+    expect(committed).toContain(90);
+  });
+});
+
+describe('utils — polar math', () => {
+  const center = { x: 0, y: 0 };
+
+  it('pointToAngle: up = 0°', () => {
+    // Screen y grows downward, so "up" is negative y.
+    expect(pointToAngle({ x: 0, y: -10 }, center)).toBeCloseTo(0);
+  });
+
+  it('pointToAngle: right = 90°', () => {
+    expect(pointToAngle({ x: 10, y: 0 }, center)).toBeCloseTo(90);
+  });
+
+  it('pointToAngle: down = 180°', () => {
+    expect(pointToAngle({ x: 0, y: 10 }, center)).toBeCloseTo(180);
+  });
+
+  it('pointToAngle: left = 270°', () => {
+    expect(pointToAngle({ x: -10, y: 0 }, center)).toBeCloseTo(270);
+  });
+
+  it('angleToPoint is the inverse of pointToAngle for cardinals', () => {
+    for (const deg of [0, 90, 180, 270]) {
+      const p = angleToPoint(deg, 10, center);
+      expect(pointToAngle(p, center)).toBeCloseTo(deg);
+    }
+  });
+
+  it('angleToPoint: 0° is straight up (negative y)', () => {
+    const p = angleToPoint(0, 10, center);
+    expect(p.x).toBeCloseTo(0);
+    expect(p.y).toBeCloseTo(-10);
+  });
+
+  it('angleToPoint: 90° is to the right (positive x)', () => {
+    const p = angleToPoint(90, 10, center);
+    expect(p.x).toBeCloseTo(10);
+    expect(p.y).toBeCloseTo(0);
+  });
+
+  it('normalizeDeg folds into [0, 360)', () => {
+    expect(normalizeDeg(370)).toBe(10);
+    expect(normalizeDeg(-10)).toBe(350);
+    expect(normalizeDeg(0)).toBe(0);
+    expect(normalizeDeg(360)).toBe(0);
+  });
+
+  it('shortestDelta picks the seam-crossing direction', () => {
+    expect(shortestDelta(350, 10)).toBeCloseTo(20);
+    expect(shortestDelta(10, 350)).toBeCloseTo(-20);
+    expect(shortestDelta(0, 90)).toBeCloseTo(90);
+    expect(shortestDelta(0, 180)).toBeCloseTo(180);
+  });
+
+  it('circularDistance is the shortest arc', () => {
+    expect(circularDistance(350, 10)).toBeCloseTo(20);
+    expect(circularDistance(0, 180)).toBeCloseTo(180);
+    expect(circularDistance(10, 350)).toBeCloseTo(20);
+  });
+
+  it('angleToHue produces an hsl string from the wrapped angle', () => {
+    expect(angleToHue(0)).toBe('hsl(0, 100%, 50%)');
+    expect(angleToHue(120)).toBe('hsl(120, 100%, 50%)');
+    expect(angleToHue(370)).toBe('hsl(10, 100%, 50%)');
+    expect(angleToHue(120, 80, 40)).toBe('hsl(120, 80%, 40%)');
+  });
+});
diff --git a/vue/primitives/src/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-computes-padding-bottom-from-ratio-1.png b/vue/primitives/src/canvas/angle-dial/__test__/__screenshots__/AngleDial.test.ts/AngleDialRoot---snap-snaps-to-a-scalar-increment-via-keyboard-1.png
similarity index 100%
rename from vue/primitives/src/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-computes-padding-bottom-from-ratio-1.png
rename to vue/primitives/src/canvas/angle-dial/__test__/__screenshots__/AngleDial.test.ts/AngleDialRoot---snap-snaps-to-a-scalar-increment-via-keyboard-1.png
diff --git a/vue/primitives/src/canvas/angle-dial/context.ts b/vue/primitives/src/canvas/angle-dial/context.ts
new file mode 100644
index 0000000..abef3d6
--- /dev/null
+++ b/vue/primitives/src/canvas/angle-dial/context.ts
@@ -0,0 +1,72 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+export type AngleDialDirection = 'ltr' | 'rtl';
+
+/**
+ * How the value behaves at the bounds.
+ * - `'wrap'` — the value lives on a continuous circle; crossing the `0` / `360`
+ *   seam (e.g. dragging from `359°` forward) flows through to `0°`+ without
+ *   jumping backwards. `min` / `max` are treated as the seam (a full turn).
+ * - `'clamp'` — the value is bounded to the arc `[min, max]`; pushing past an
+ *   end stops at that end instead of jumping to the far side.
+ */
+export type AngleDialWrap = 'wrap' | 'clamp';
+
+/**
+ * Snap increments for the angle, in degrees.
+ * - A `number` snaps to every multiple of that increment (e.g. `15` → every 15°).
+ * - A `number[]` snaps to the nearest of an explicit list of angles
+ *   (e.g. `[0, 45, 90, 135, 180, 225, 270, 315]`).
+ * - `undefined` disables snapping (only `step` rounding applies).
+ */
+export type AngleDialSnap = number | number[] | undefined;
+
+/**
+ * Formatter turning the raw angle (degrees) into a human-friendly string for
+ * `aria-valuetext`. A bare number on a circular control is ambiguous, so the
+ * thumb strongly defaults this to `` `${Math.round(deg)}°` ``. Return
+ * `undefined` to omit `aria-valuetext`.
+ */
+export type AngleDialValueText = (deg: number) => string | undefined;
+
+/**
+ * Context shared between `AngleDialRoot` and `AngleDialThumb`.
+ *
+ * Scalar props are exposed as plain `Ref<T>` values, but `AngleDialRoot` builds
+ * them with `toRef(() => prop)` — a `GetterRefImpl` that is reactive without
+ * allocating a `ReactiveEffect` / cache (unlike `computed`), mirroring the
+ * slider's identity-passthrough convention.
+ */
+export interface AngleDialContext {
+  /** Current angle in degrees. */
+  value: Ref<number>;
+  min: Ref<number>;
+  max: Ref<number>;
+  step: Ref<number>;
+  /** Large-step increment (Page keys / Shift+Arrow), in degrees. */
+  largeStep: Ref<number>;
+  wrap: Ref<AngleDialWrap>;
+  snap: Ref<AngleDialSnap>;
+  disabled: Ref<boolean>;
+  direction: Ref<AngleDialDirection>;
+  /**
+   * Commit a new raw angle (degrees). The root applies snap, step rounding, and
+   * wrap/clamp handling before writing the model.
+   */
+  setValue: (deg: number) => void;
+  /**
+   * Nudge the value by a signed delta (degrees) from the keyboard. Honors
+   * wrap/clamp semantics (a wrap dial crosses the seam; a clamp dial stops).
+   */
+  nudge: (delta: number) => void;
+  /** Jump to the canonical low end (Home). */
+  toStart: () => void;
+  /** Jump to the canonical high end (End). */
+  toEnd: () => void;
+}
+
+const ctx = useContextFactory<AngleDialContext>('AngleDialContext');
+
+export const provideAngleDialContext = ctx.provide;
+export const useAngleDialContext = ctx.inject;
diff --git a/vue/primitives/src/canvas/angle-dial/demo.vue b/vue/primitives/src/canvas/angle-dial/demo.vue
new file mode 100644
index 0000000..68dfad5
--- /dev/null
+++ b/vue/primitives/src/canvas/angle-dial/demo.vue
@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { AngleDialRoot, AngleDialThumb } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const angle = ref(45);
+</script>
+
+<template>
+  <div class="demo-card flex w-full max-w-sm flex-col items-center gap-6 p-6 text-fg">
+    <div class="flex w-full items-baseline justify-between text-sm">
+      <span class="font-medium">Rotation</span>
+      <span class="font-mono text-fg-muted">{{ Math.round(angle) }}°</span>
+    </div>
+
+    <!-- The dial: a round track with the thumb on the ring (the box edge), angle
+         in the center. The thumb auto-positions at radius 0.5 of the box, so its
+         center lands exactly on the root's border ring. -->
+    <AngleDialRoot
+      v-model:value="angle"
+      :snap="15"
+      class="relative size-44 touch-none select-none rounded-full border-2 border-border-strong bg-bg-inset shadow-(--shadow-card)"
+    >
+      <!-- tick at 0° (top edge) -->
+      <div class="pointer-events-none absolute left-1/2 top-2 h-2.5 w-0.5 -translate-x-1/2 rounded-full bg-fg-subtle" />
+
+      <!-- center readout -->
+      <div class="pointer-events-none absolute inset-0 flex flex-col items-center justify-center">
+        <span class="font-mono text-2xl font-semibold tabular-nums text-fg">{{ Math.round(angle) }}°</span>
+        <span class="text-xs text-fg-subtle">drag the dial</span>
+      </div>
+
+      <AngleDialThumb
+        aria-label="Rotation angle"
+        class="absolute z-10 size-5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-accent bg-bg shadow-md outline-none transition-[transform] focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+      />
+    </AngleDialRoot>
+
+    <!-- a small element rotated by the live angle -->
+    <div class="flex items-center gap-3 text-sm text-fg-muted">
+      <span>preview</span>
+      <span
+        class="grid size-12 place-items-center rounded-card border border-border-strong bg-accent text-accent-text shadow-sm transition-transform duration-75"
+        :style="{ transform: `rotate(${angle}deg)` }"
+      >
+        <span class="text-lg leading-none">↑</span>
+      </span>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/angle-dial/index.ts b/vue/primitives/src/canvas/angle-dial/index.ts
new file mode 100644
index 0000000..5577d2b
--- /dev/null
+++ b/vue/primitives/src/canvas/angle-dial/index.ts
@@ -0,0 +1,21 @@
+export { default as AngleDialRoot } from './AngleDialRoot.vue';
+export { default as AngleDialThumb } from './AngleDialThumb.vue';
+export type { AngleDialRootEmits, AngleDialRootProps } from './AngleDialRoot.vue';
+export type { AngleDialThumbProps } from './AngleDialThumb.vue';
+export type {
+  AngleDialContext,
+  AngleDialDirection,
+  AngleDialSnap,
+  AngleDialValueText,
+  AngleDialWrap,
+} from './context';
+export {
+  angleToHue,
+  angleToPoint,
+  applySnap,
+  circularDistance,
+  normalizeDeg,
+  pointToAngle,
+  shortestDelta,
+  type Point,
+} from './utils';
diff --git a/vue/primitives/src/canvas/angle-dial/utils.ts b/vue/primitives/src/canvas/angle-dial/utils.ts
new file mode 100644
index 0000000..220c2cd
--- /dev/null
+++ b/vue/primitives/src/canvas/angle-dial/utils.ts
@@ -0,0 +1,142 @@
+import type { Point } from '../../internal/utils/geometry';
+import type { AngleDialSnap } from './context';
+
+// Reuse the package-canonical 2D point (internal `utils/geometry`, not in the
+// root barrel) so angle-dial's `Point` is the SAME symbol as spline/pointer-drag/
+// snapping re-export — keeps the root barrel free of a TS2308 `Point` clash.
+/** A 2D point in client (screen) pixels. */
+export type { Point };
+
+/**
+ * ANGLE CONVENTION (load-bearing — every consumer assumes it):
+ *
+ *   0° points UP (12 o'clock) and the angle increases CLOCKWISE.
+ *
+ *   up = 0°, right = 90°, down = 180°, left = 270°.
+ *
+ * This matches how rotation/heading dials are read by humans (a compass-style
+ * "12 o'clock is zero, turn right to increase"), not the mathematical
+ * convention (0° = +x, counter-clockwise). All conversions below honor it.
+ */
+
+const TAU = Math.PI * 2;
+const RAD_TO_DEG = 360 / TAU;
+const DEG_TO_RAD = TAU / 360;
+
+/** Wrap an angle (degrees) into the `[0, 360)` range. */
+export function normalizeDeg(deg: number): number {
+  const r = deg % 360;
+  return r < 0 ? r + 360 : r;
+}
+
+/**
+ * Convert a screen-space point into an angle (degrees) about `center`, using
+ * the documented convention (0° = up, clockwise-positive). Returns a value in
+ * `[0, 360)`.
+ *
+ * Screen y grows downward, so a point directly below the center (`dy > 0`)
+ * reads as 180° (down), and a point to the right (`dx > 0`) reads as 90°.
+ */
+export function pointToAngle(point: Point, center: Point): number {
+  const dx = point.x - center.x;
+  const dy = point.y - center.y;
+  // atan2(dx, -dy): rotate the standard math frame so 0° is up and the angle
+  // increases clockwise. `-dy` flips the down-positive screen axis to up.
+  const rad = Math.atan2(dx, -dy);
+  return normalizeDeg(rad * RAD_TO_DEG);
+}
+
+/**
+ * Convert an angle (degrees) into a point on a circle of `radius` about
+ * `center`, using the documented convention (0° = up, clockwise-positive).
+ * The inverse of {@link pointToAngle}.
+ */
+export function angleToPoint(deg: number, radius: number, center: Point): Point {
+  const rad = deg * DEG_TO_RAD;
+  return {
+    x: center.x + Math.sin(rad) * radius,
+    y: center.y - Math.cos(rad) * radius,
+  };
+}
+
+/**
+ * Number of decimal digits in a numeric `step`, mirroring the slider's helper.
+ * Used to compensate floating-point drift after step rounding.
+ */
+export function getStepDecimals(step: number): number {
+  if (!Number.isFinite(step)) return 0;
+  const str = String(step);
+  const dot = str.indexOf('.');
+  if (dot === -1) return 0;
+  return str.length - dot - 1;
+}
+
+/** Snap `value` to the nearest multiple of `step` anchored at `min`. */
+export function roundToStep(value: number, step: number, min: number, decimals: number): number {
+  if (step <= 0) return value;
+  const nearest = Math.round((value - min) / step) * step + min;
+  return decimals > 0 ? Number(nearest.toFixed(decimals)) : nearest;
+}
+
+/**
+ * Snap an angle to the nearest configured snap target.
+ *
+ * - scalar `snap` → nearest multiple of that increment (anchored at 0).
+ * - `snap` array → nearest of the explicit angles. In `wrap` mode the distance
+ *   is measured around the circle so a value near 350° can snap to a `0`
+ *   target; in clamp/linear mode it is a plain numeric distance.
+ *
+ * Returns `value` unchanged when `snap` is `undefined` or empty.
+ */
+export function applySnap(value: number, snap: AngleDialSnap, wrap: boolean): number {
+  if (snap === undefined) return value;
+  if (typeof snap === 'number') {
+    if (snap <= 0) return value;
+    return Math.round(value / snap) * snap;
+  }
+  if (snap.length === 0) return value;
+  let best = snap[0]!;
+  let bestDist = wrap ? circularDistance(value, best) : Math.abs(value - best);
+  for (let i = 1; i < snap.length; i++) {
+    const target = snap[i]!;
+    const dist = wrap ? circularDistance(value, target) : Math.abs(value - target);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = target;
+    }
+  }
+  return best;
+}
+
+/** Shortest absolute angular distance (degrees) between two angles on a circle. */
+export function circularDistance(a: number, b: number): number {
+  const d = Math.abs(normalizeDeg(a) - normalizeDeg(b)) % 360;
+  return d > 180 ? 360 - d : d;
+}
+
+/**
+ * Map an angle (degrees) onto the HSL hue wheel, returning a fully-saturated
+ * CSS color string for that hue. Handy when the dial doubles as a hue ring
+ * (`min: 0, max: 360, wrap: 'wrap'`): feed the angle straight in to color the
+ * thumb or a swatch. `saturation` and `lightness` are percentages.
+ *
+ * @param deg The angle in degrees (any range; wrapped to `[0, 360)`).
+ * @param saturation Saturation percentage. @default 100
+ * @param lightness Lightness percentage. @default 50
+ */
+export function angleToHue(deg: number, saturation = 100, lightness = 50): string {
+  return `hsl(${normalizeDeg(deg)}, ${saturation}%, ${lightness}%)`;
+}
+
+/**
+ * Signed shortest angular step (degrees) from `from` to `to` on a circle,
+ * in `(-180, 180]`. Positive is clockwise (increasing angle). Used to track the
+ * frame-to-frame delta in `wrap` mode so crossing the `0` / `360` seam
+ * accumulates smoothly instead of jumping `359 → 0 → 359`.
+ */
+export function shortestDelta(from: number, to: number): number {
+  let d = (normalizeDeg(to) - normalizeDeg(from)) % 360;
+  if (d > 180) d -= 360;
+  else if (d <= -180) d += 360;
+  return d;
+}
diff --git a/vue/primitives/src/canvas/canvas-stage/CanvasStageContent.vue b/vue/primitives/src/canvas/canvas-stage/CanvasStageContent.vue
new file mode 100644
index 0000000..0f3a23f
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/CanvasStageContent.vue
@@ -0,0 +1,57 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The transformed content layer of a `CanvasStage`. Wraps the zoom-pan
+ * `ViewportContent` (one GPU-composited `transform`, `transform-origin: 0 0`) and
+ * renders the consumer's `<img>` / `<video>` / `<canvas>` via the default slot.
+ *
+ * When the `CanvasStageRoot` has no explicit `contentWidth`/`contentHeight`, this
+ * part measures its own intrinsic content size with a `ResizeObserver`
+ * (`useElementSize`) and reports it to the context so `fitView` / `zoomToActual`
+ * / `fitFill` can compute. `ResizeObserver` reports the *layout* (content-box)
+ * size, which is immune to the CSS `transform` the viewport applies — so the
+ * measured size is the true unscaled content size at any zoom, never the
+ * `getBoundingClientRect` post-scale geometry.
+ */
+export interface CanvasStageContentProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { shallowRef, watch } from 'vue';
+import { useElementSize, useForwardExpose } from '@robonen/vue';
+import { ViewportContent } from '../zoom-pan';
+import { useCanvasStageContext } from './context';
+
+const { as = 'div' } = defineProps<CanvasStageContentProps>();
+
+const ctx = useCanvasStageContext();
+const { forwardRef } = useForwardExpose();
+
+// The `ViewportContent` layer is forced to the pane size (`inset: 0`), so it is
+// NOT a meaningful content measurement. Instead we measure a tight inner wrapper
+// (`position: absolute; top/left: 0` — it shrinks to its content) so the
+// intrinsic `<img>` / `<video>` size is what's observed. `useElementSize` reads
+// the content-box, which is immune to the viewport's CSS `transform`.
+const measureEl = shallowRef<HTMLElement | null>(null);
+const { width, height } = useElementSize(measureEl);
+watch([width, height], ([w, h]) => {
+  if (ctx.autoMeasure.value) ctx.setMeasuredContentSize({ width: w, height: h });
+}, { immediate: true });
+</script>
+
+<template>
+  <ViewportContent
+    :ref="forwardRef"
+    :as="as"
+    v-bind="{ 'data-canvas-stage-content': '' }"
+  >
+    <div
+      ref="measureEl"
+      :style="{ position: 'absolute', top: '0', left: '0' }"
+      v-bind="{ 'data-canvas-stage-content-box': '' }"
+    >
+      <slot />
+    </div>
+  </ViewportContent>
+</template>
diff --git a/vue/primitives/src/canvas/canvas-stage/CanvasStagePane.vue b/vue/primitives/src/canvas/canvas-stage/CanvasStagePane.vue
new file mode 100644
index 0000000..198af4f
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/CanvasStagePane.vue
@@ -0,0 +1,48 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The inner clipping / measurement box of a `CanvasStage` (mirrors flow's
+ * `FlowPane`). It renders the zoom-pan `ViewportSurface`, so it already clips the
+ * content (`overflow: hidden`), positions relatively, disables native touch
+ * gestures (`touch-action: none`), and reports its live bounding rect into the
+ * zoom-pan context as the coordinate origin. Kept a *real* element (never
+ * `as="template"`) so `getBoundingClientRect` measures the actual clip box that
+ * the fit / 1:1 / fill maths key off — the `CanvasStageRoot` may itself be
+ * `as="template"`, which is exactly why measurement lives here and not on the
+ * Root. Rendered by `CanvasStageRoot`; not usually placed directly.
+ */
+export interface CanvasStagePaneProps extends PrimitiveProps {}
+
+export interface CanvasStagePaneEmits {
+  /** Fires with the resolved pane element (or `null` on teardown) for measurement. */
+  pane: [el: HTMLElement | null];
+}
+</script>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { ViewportSurface } from '../zoom-pan';
+
+const { as = 'div' } = defineProps<CanvasStagePaneProps>();
+const emit = defineEmits<CanvasStagePaneEmits>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Surface the rendered pane element to `CanvasStageRoot` so it can drive the
+// fit/actual/fill maths off the real clip box.
+watch(currentElement, (el) => {
+  emit('pane', (el as HTMLElement | undefined) ?? null);
+}, { immediate: true });
+</script>
+
+<template>
+  <ViewportSurface
+    :ref="forwardRef"
+    :as="as"
+    v-bind="{ 'data-canvas-stage-pane': '' }"
+  >
+    <slot />
+  </ViewportSurface>
+</template>
diff --git a/vue/primitives/src/canvas/canvas-stage/CanvasStageRoot.vue b/vue/primitives/src/canvas/canvas-stage/CanvasStageRoot.vue
new file mode 100644
index 0000000..4e7ec67
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/CanvasStageRoot.vue
@@ -0,0 +1,351 @@
+<script lang="ts">
+import type { Dimensions, Rect, Viewport, ViewportApi, XYPosition } from '../zoom-pan';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Root of a headless pan/zoom **canvas stage** — a thin photo-editing shell over
+ * the `zoom-pan` viewport that adds the three classic fit modes (**fit** /
+ * **1:1** / **fill**) on top of pan + zoom, plus automatic content-size
+ * measurement so those modes work without the consumer hand-feeding dimensions.
+ *
+ * It owns the master `Viewport` (two-way via `v-model:viewport`, or uncontrolled
+ * via `defaultViewport`), renders an internal `ViewportRoot` wired with the same
+ * model + zoom constraints + the resolved content extent, and builds the
+ * {@link CanvasStageContext} that wraps the zoom-pan {@link ViewportApi} and adds
+ * `fitView()` / `zoomToActual()` / `fitFill()` + the reactive content size. The
+ * combined api is `defineExpose`d so consumers can drive it (and wire their own
+ * zoom buttons) via a template ref.
+ *
+ * Carries `role="application"` (downgraded to `'group'` when keyboard a11y is
+ * disabled), `aria-roledescription="zoomable canvas"`, and `tabindex 0`; pass an
+ * `aria-label` via `$attrs`. Mount your `<img>` / `<video>` / `<canvas>` in the
+ * default slot — it renders inside the single transformed layer.
+ */
+export interface CanvasStageRootProps extends PrimitiveProps {
+  /** Uncontrolled initial viewport (ignored when `v-model:viewport` is bound). @default { x: 0, y: 0, zoom: 1 } */
+  defaultViewport?: Viewport;
+  /** Minimum zoom level. @default 0.1 */
+  minZoom?: number;
+  /** Maximum zoom level. @default 8 */
+  maxZoom?: number;
+  /**
+   * Intrinsic content width in content-space px. When omitted (with
+   * `contentHeight`) the content element is auto-measured. @default undefined
+   */
+  contentWidth?: number;
+  /**
+   * Intrinsic content height in content-space px. When omitted (with
+   * `contentWidth`) the content element is auto-measured. @default undefined
+   */
+  contentHeight?: number;
+  /** Fractional inset on each side when fitting, 0–1. @default 0.1 */
+  fitPadding?: number;
+  /** Fit the content into view once the pane + content are measured. @default true */
+  fitOnReady?: boolean;
+  /** Multiplicative zoom factor per keyboard zoom-in/out step. @default 1.2 */
+  zoomStep?: number;
+  /** Pixel step for arrow-key panning (Shift = ×5). @default 40 */
+  panStep?: number;
+  /** Master interactivity switch (lock). @default false */
+  disabled?: boolean;
+  /** Disable the keyboard a11y layer (downgrades `role` to `'group'`). @default false */
+  disableKeyboardA11y?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { useElementBounding, useEventListener, useForwardExpose } from '@robonen/vue';
+import { ViewportRoot } from '../zoom-pan';
+import CanvasStagePane from './CanvasStagePane.vue';
+import CanvasStageContent from './CanvasStageContent.vue';
+import { provideCanvasStageContext } from './context';
+import type { CanvasStageApi, CanvasStageContext } from './context';
+
+const {
+  defaultViewport = { x: 0, y: 0, zoom: 1 },
+  minZoom = 0.1,
+  maxZoom = 8,
+  contentWidth = undefined,
+  contentHeight = undefined,
+  fitPadding = 0.1,
+  fitOnReady = true,
+  zoomStep = 1.2,
+  panStep = 40,
+  disabled = false,
+  disableKeyboardA11y = false,
+  as = 'div',
+} = defineProps<CanvasStageRootProps>();
+
+// ── viewport model (controlled + uncontrolled), delegated to ViewportRoot ─────
+// `ViewportRoot` already runs the controlled/uncontrolled `shallowRef` + watch
+// dance internally; we simply pass the model straight through so a single
+// canonical `Viewport` lives in the zoom-pan layer.
+const model = defineModel<Viewport | undefined>('viewport');
+
+// ── content size: explicit props win, else the measured intrinsic size ────────
+const autoMeasure = computed(() => contentWidth === undefined || contentHeight === undefined);
+const measuredContentSize = shallowRef<Dimensions>({ width: 0, height: 0 });
+function setMeasuredContentSize(size: Dimensions): void {
+  measuredContentSize.value = size;
+}
+
+const contentSize = computed<Dimensions>(() => {
+  if (!autoMeasure.value) return { width: contentWidth!, height: contentHeight! };
+  return measuredContentSize.value;
+});
+
+// The fit target in content space, anchored at the origin.
+const contentExtent = computed<Rect>(() => ({
+  x: 0,
+  y: 0,
+  width: contentSize.value.width,
+  height: contentSize.value.height,
+}));
+
+// ── inner ViewportRoot api + pane measurement ─────────────────────────────────
+// `ViewportRoot` exposes the imperative `ViewportApi`; we capture it via a
+// template ref and build the canvas fit modes on top of it. The pane element is
+// the `ViewportSurface` (= `CanvasStagePane`) — its bounding rect is the screen
+// origin and the source for the fit/actual/fill maths.
+const viewportRef = shallowRef<(ViewportApi & { viewport: Viewport }) | null>(null);
+const rootEl = shallowRef<HTMLElement | null>(null);
+const paneEl = shallowRef<HTMLElement | null>(null);
+function setPaneEl(el: HTMLElement | null): void {
+  paneEl.value = el;
+}
+
+const { width: paneWidth, height: paneHeight } = useElementBounding(paneEl);
+const measured = shallowRef(false);
+watch([paneWidth, paneHeight, contentSize], () => {
+  if (!measured.value && paneWidth.value > 0 && paneHeight.value > 0)
+    measured.value = true;
+}, { immediate: true });
+
+/** True once the pane has a non-zero rect — fit maths are meaningful. */
+function paneReady(): boolean {
+  return paneWidth.value > 0 && paneHeight.value > 0;
+}
+
+/** The content-space point currently centred in the pane (content centre fallback). */
+function contentCentre(): XYPosition {
+  const ext = contentExtent.value;
+  return { x: ext.x + ext.width / 2, y: ext.y + ext.height / 2 };
+}
+
+/** Centre `target` (content space) at zoom `zoom`, clamped via the zoom-pan api. */
+function applyCentred(zoom: number, target: XYPosition): void {
+  const vp = viewportRef.value;
+  if (!vp) return;
+  vp.setViewport({
+    zoom,
+    x: paneWidth.value / 2 - target.x * zoom,
+    y: paneHeight.value / 2 - target.y * zoom,
+  });
+}
+
+// ── canvas fit modes ──────────────────────────────────────────────────────────
+function fitView(): void {
+  const vp = viewportRef.value;
+  if (!vp || !paneReady()) return;
+  const ext = contentExtent.value;
+  if (ext.width === 0 || ext.height === 0) return;
+  // The zoom-pan `fit` is exactly the "contain" mode (min of the two ratios).
+  vp.fit(ext, { padding: fitPadding });
+}
+
+function zoomToActual(): void {
+  if (!viewportRef.value || !paneReady()) return;
+  // 1:1 — one content px per screen px — centred on the content centre.
+  applyCentred(1, contentCentre());
+}
+
+function fitFill(): void {
+  const ext = contentExtent.value;
+  if (!viewportRef.value || !paneReady() || ext.width === 0 || ext.height === 0) return;
+  // "Cover": the LARGER of the two ratios, so the content fills the pane with no
+  // letterboxing (the opposite choice to `fitView`'s `min`). Padding does not
+  // apply to a cover.
+  const zoom = Math.max(paneWidth.value / ext.width, paneHeight.value / ext.height);
+  applyCentred(zoom, contentCentre());
+}
+
+// ── combined api ──────────────────────────────────────────────────────────────
+const api: CanvasStageApi = {
+  getViewport: () => viewportRef.value?.getViewport() ?? { x: 0, y: 0, zoom: 1 },
+  setViewport: vp => viewportRef.value?.setViewport(vp),
+  zoomIn: (factor = zoomStep) => viewportRef.value?.zoomIn(factor),
+  zoomOut: (factor = zoomStep) => viewportRef.value?.zoomOut(factor),
+  zoomTo: zoom => viewportRef.value?.zoomTo(zoom),
+  fitView,
+  zoomToActual,
+  fitFill,
+  center: point => viewportRef.value?.center(point),
+  reset: () => viewportRef.value?.reset(),
+};
+
+// Reactive viewport mirror: read straight off the inner `ViewportRoot`'s exposed
+// `viewport` computed (reactive through the component instance), falling back to
+// the model / default before it resolves.
+const viewport = computed<Viewport>(
+  () => viewportRef.value?.viewport ?? model.value ?? defaultViewport,
+);
+
+const context: CanvasStageContext = {
+  api,
+  viewport,
+  contentSize,
+  contentExtent,
+  measured,
+  autoMeasure: toRef(() => autoMeasure.value),
+  setMeasuredContentSize,
+};
+provideCanvasStageContext(context);
+
+// ── fit once on ready ─────────────────────────────────────────────────────────
+// Wait until both the pane is measured AND the content extent is non-zero (auto
+// mode resolves it asynchronously after the first ResizeObserver tick). Runs
+// once; focus stays on the Root.
+if (fitOnReady) {
+  const stop = watch(
+    [measured, contentExtent],
+    ([m, ext]) => {
+      if (m && ext.width > 0 && ext.height > 0) {
+        fitView();
+        stop();
+      }
+    },
+    { immediate: true },
+  );
+}
+
+// ── keyboard layer (canvas-specific shortcuts) ────────────────────────────────
+// Bound on the focusable Root element. zoom-pan's own keyboard layer is disabled
+// (`:disable-keyboard`), so CanvasStage is the single source of truth: this lets
+// us honour `panStep`/`zoomStep` and map `0`/`1`/`2`/`Home` onto the canvas fit
+// modes (zoom-pan's `0`/`Home` would do `zoomTo(1)` / `reset`, not
+// `zoomToActual` / `fitView`). Skipped entirely when disabled or when keyboard
+// a11y is off. Focus stays on the Root after a programmatic fit (we never move
+// it), so the next keypress lands here.
+const EDITABLE = /^(?:input|textarea|select)$/i;
+function isTyping(): boolean {
+  const el = document.activeElement as HTMLElement | null;
+  return !!el && (EDITABLE.test(el.tagName) || el.isContentEditable);
+}
+
+function onKeydown(event: KeyboardEvent): void {
+  if (disabled || disableKeyboardA11y || isTyping()) return;
+
+  const step = event.shiftKey ? panStep * 5 : panStep;
+  const arrows: Record<string, [number, number]> = {
+    ArrowUp: [0, step],
+    ArrowDown: [0, -step],
+    ArrowLeft: [step, 0],
+    ArrowRight: [-step, 0],
+  };
+
+  const pan = arrows[event.key];
+  if (pan) {
+    const vp = api.getViewport();
+    api.setViewport({ zoom: vp.zoom, x: vp.x + pan[0], y: vp.y + pan[1] });
+  }
+  else if (event.key === '+' || event.key === '=') {
+    api.zoomIn();
+  }
+  else if (event.key === '-' || event.key === '_') {
+    api.zoomOut();
+  }
+  else if (event.key === '0') {
+    zoomToActual();
+  }
+  else if (event.key === '1') {
+    fitView();
+  }
+  else if (event.key === '2') {
+    fitFill();
+  }
+  else if (event.key === 'Home') {
+    api.reset();
+  }
+  else {
+    return; // not ours — let it bubble (e.g. to the page).
+  }
+
+  event.preventDefault();
+}
+
+// ── focus-visible reflection ──────────────────────────────────────────────────
+const focusVisible = shallowRef(false);
+function onFocus(event: FocusEvent): void {
+  // `:focus-visible` semantics — only reflect keyboard focus, not a pointer grab
+  // (which would flash a focus ring on every drag-to-pan).
+  const el = event.currentTarget as HTMLElement | null;
+  focusVisible.value = !!el?.matches?.(':focus-visible');
+}
+function onBlur(): void {
+  focusVisible.value = false;
+}
+
+// Bind the a11y listeners on the Root element once it resolves. `currentElement`
+// (from `useForwardExpose`) is the rendered Root, which carries `tabindex 0`.
+useEventListener(rootEl, 'keydown', onKeydown);
+useEventListener(rootEl, 'focus', onFocus);
+useEventListener(rootEl, 'blur', onBlur);
+
+// `defineExpose` runs BEFORE `useForwardExpose` so the composable merges these
+// bindings (plus props + `$el`) instead of `defineExpose`'s `expose()`
+// clobbering them and warning "expose() should be called only once". ORDER IS
+// LOAD-BEARING.
+defineExpose({
+  getViewport: api.getViewport,
+  setViewport: api.setViewport,
+  zoomIn: api.zoomIn,
+  zoomOut: api.zoomOut,
+  zoomTo: api.zoomTo,
+  fitView: api.fitView,
+  zoomToActual: api.zoomToActual,
+  fitFill: api.fitFill,
+  center: api.center,
+  reset: api.reset,
+  contentSize,
+});
+
+const { forwardRef } = useForwardExpose();
+
+// Pass-through attrs (`role` / `aria-*` / `data-*` / `tabindex`) the inner
+// `ViewportRoot` doesn't declare as typed props are bound as one object via
+// `v-bind` so they ride through `$attrs` to the DOM without tripping the strict
+// per-prop type check (the codebase convention for forwarding non-prop attrs to
+// a typed SFC child).
+const rootAttrs = computed<Record<string, unknown>>(() => ({
+  role: disableKeyboardA11y ? 'group' : 'application',
+  'aria-roledescription': 'zoomable canvas',
+  tabindex: 0,
+  'data-canvas-stage-root': '',
+  'data-focus-visible': focusVisible.value ? '' : undefined,
+}));
+</script>
+
+<template>
+  <ViewportRoot
+    :ref="(r: any) => { forwardRef(r); viewportRef = r; rootEl = (r?.$el ?? null) as HTMLElement | null; }"
+    v-model:viewport="model"
+    :as="as"
+    :default-viewport="defaultViewport"
+    :min-zoom="minZoom"
+    :max-zoom="maxZoom"
+    :content-extent="contentExtent"
+    :fit-padding="fitPadding"
+    :disabled="disabled"
+    :disable-keyboard="true"
+    v-bind="rootAttrs"
+  >
+    <template #surface>
+      <CanvasStagePane @pane="setPaneEl">
+        <CanvasStageContent>
+          <slot />
+        </CanvasStageContent>
+      </CanvasStagePane>
+    </template>
+  </ViewportRoot>
+</template>
diff --git a/vue/primitives/src/canvas/canvas-stage/CanvasStageZoomIndicator.vue b/vue/primitives/src/canvas/canvas-stage/CanvasStageZoomIndicator.vue
new file mode 100644
index 0000000..50b7ef3
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/CanvasStageZoomIndicator.vue
@@ -0,0 +1,77 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * An accessible zoom-level announcer for a `CanvasStage`. Renders a
+ * `VisuallyHidden` `aria-live="polite"` / `aria-atomic` region that announces the
+ * current zoom percentage to screen readers. To avoid flooding the live region
+ * during a pinch / wheel gesture it announces on *settle* — the value is
+ * debounced, so a burst of per-frame zoom changes collapses into a single
+ * announcement once motion stops.
+ *
+ * The default slot receives the live `{ zoom, percent }` so consumers can ALSO
+ * render a visible indicator (e.g. a "120 %" badge) with the same value.
+ */
+export interface CanvasStageZoomIndicatorProps extends PrimitiveProps {
+  /**
+   * Build the announced/visible string from the rounded zoom percentage.
+   * @default (percent) => `${percent}%`
+   */
+  format?: (percent: number) => string;
+  /** Debounce before announcing, in ms (the "settle" window). @default 200 */
+  settleDelay?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { shallowRef, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+import { useCanvasStageContext } from './context';
+
+const {
+  as = 'div',
+  format = (percent: number) => `${percent}%`,
+  settleDelay = 200,
+} = defineProps<CanvasStageZoomIndicatorProps>();
+
+const ctx = useCanvasStageContext();
+const { forwardRef } = useForwardExpose();
+
+/** Live zoom percentage (rounded), updated every frame for the visible slot. */
+const percent = shallowRef(Math.round(ctx.viewport.value.zoom * 100));
+
+/** Debounced announcement — only written once zoom settles. */
+const announced = shallowRef('');
+
+let timer: ReturnType<typeof setTimeout> | null = null;
+watch(
+  () => ctx.viewport.value.zoom,
+  (zoom) => {
+    percent.value = Math.round(zoom * 100);
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      announced.value = format(percent.value);
+      timer = null;
+    }, settleDelay);
+  },
+  { immediate: true },
+);
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    data-canvas-stage-zoom-indicator=""
+  >
+    <slot
+      :zoom="ctx.viewport.value.zoom"
+      :percent="percent"
+    />
+    <VisuallyHidden v-bind="{ 'aria-live': 'polite', 'aria-atomic': 'true' }">
+      {{ announced }}
+    </VisuallyHidden>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/canvas-stage/__test__/CanvasStage.test.ts b/vue/primitives/src/canvas/canvas-stage/__test__/CanvasStage.test.ts
new file mode 100644
index 0000000..2fd640a
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/__test__/CanvasStage.test.ts
@@ -0,0 +1,208 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { CanvasStageContent, CanvasStagePane, CanvasStageRoot } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+/** Wait for `n` real animation frames so layout + ResizeObserver settle. */
+function raf(n = 1): Promise<void> {
+  return new Promise((resolve) => {
+    let i = 0;
+    const step = (): void => {
+      if (++i >= n) resolve();
+      else requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+  });
+}
+
+function mountStage(props: Record<string, unknown> = {}) {
+  const exposed = ref<any>(null);
+  const Harness = defineComponent({
+    setup() {
+      return () => h(CanvasStageRoot, {
+        ref: (r: any) => { exposed.value = r; },
+        style: 'width: 400px; height: 300px;',
+        contentWidth: 800,
+        contentHeight: 600,
+        'aria-label': 'Photo',
+        ...props,
+      }, {
+        default: () => h('img', { 'data-child': '', src: '', width: 800, height: 600 }),
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, exposed };
+}
+
+describe('CanvasStageRoot (mount)', () => {
+  it('renders role=application + roledescription + tabindex 0', async () => {
+    mountStage();
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-canvas-stage-root]')!;
+    expect(root).toBeTruthy();
+    expect(root.getAttribute('role')).toBe('application');
+    expect(root.getAttribute('aria-roledescription')).toBe('zoomable canvas');
+    expect(root.tabIndex).toBe(0);
+    // Consumer aria-label rides through $attrs.
+    expect(root.getAttribute('aria-label')).toBe('Photo');
+  });
+
+  it('composes ViewportRoot/Surface/Content and renders the child in the transformed layer', async () => {
+    mountStage();
+    await nextTick();
+    expect(document.querySelector('[data-viewport-root]')).toBeTruthy();
+    expect(document.querySelector('[data-canvas-stage-pane][data-viewport-surface]')).toBeTruthy();
+    const content = document.querySelector<HTMLElement>('[data-canvas-stage-content][data-viewport-content]');
+    expect(content).toBeTruthy();
+    // The child renders INSIDE the transformed content layer.
+    const child = content!.querySelector('[data-child]');
+    expect(child).toBeTruthy();
+    expect(content!.style.transformOrigin).toBe('0px 0px');
+  });
+
+  it('keeps the pane a real clipping box (overflow hidden + touch-action none)', async () => {
+    mountStage();
+    await nextTick();
+    const pane = document.querySelector<HTMLElement>('[data-canvas-stage-pane]')!;
+    expect(pane.style.overflow).toBe('hidden');
+    expect(pane.style.touchAction).toBe('none');
+  });
+
+  it('exposes the combined api (fitView/zoomToActual/fitFill/reset/...)', async () => {
+    const { exposed } = mountStage();
+    await nextTick();
+    for (const fn of ['getViewport', 'setViewport', 'zoomIn', 'zoomOut', 'zoomTo', 'fitView', 'zoomToActual', 'fitFill', 'center', 'reset']) {
+      expect(typeof exposed.value[fn]).toBe('function');
+    }
+  });
+
+  it('zoomToActual sets zoom to 1 (1:1)', async () => {
+    const { exposed } = mountStage({ defaultViewport: { x: 0, y: 0, zoom: 0.3 } });
+    await raf(2);
+    await nextTick();
+    exposed.value.zoomToActual();
+    await nextTick();
+    expect(exposed.value.getViewport().zoom).toBeCloseTo(1, 5);
+  });
+
+  it('fitFill covers the pane (zoom = max ratio), fitView contains it (smaller)', async () => {
+    // pane 400x300, content 800x600 → contain = 0.5, cover = 0.5 here (same aspect).
+    // Use a non-matching aspect so contain != cover.
+    const { exposed } = mountStage({ contentWidth: 800, contentHeight: 200 });
+    await raf(2);
+    await nextTick();
+
+    exposed.value.fitView();
+    await nextTick();
+    const fitZoom = exposed.value.getViewport().zoom;
+
+    exposed.value.fitFill();
+    await nextTick();
+    const fillZoom = exposed.value.getViewport().zoom;
+
+    // contain uses min ratio (with padding) → smaller; cover uses max ratio → larger.
+    expect(fillZoom).toBeGreaterThan(fitZoom);
+  });
+
+  it('pressing \'0\' calls zoomToActual and \'1\' calls fitView', async () => {
+    const { exposed } = mountStage({ defaultViewport: { x: 0, y: 0, zoom: 4 } });
+    await raf(2);
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-canvas-stage-root]')!;
+    root.focus();
+
+    root.dispatchEvent(new KeyboardEvent('keydown', { key: '0', bubbles: true }));
+    await nextTick();
+    expect(exposed.value.getViewport().zoom).toBeCloseTo(1, 5);
+
+    root.dispatchEvent(new KeyboardEvent('keydown', { key: '1', bubbles: true }));
+    await nextTick();
+    // fitView (contain, 800x600 into 400x300 with padding) → ~0.45.
+    expect(exposed.value.getViewport().zoom).toBeLessThan(1);
+  });
+
+  it('arrow keys pan by panStep; Shift multiplies it', async () => {
+    const { exposed } = mountStage({ panStep: 40, fitOnReady: false, defaultViewport: { x: 0, y: 0, zoom: 1 } });
+    await raf(2);
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-canvas-stage-root]')!;
+    root.focus();
+
+    root.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    await nextTick();
+    expect(exposed.value.getViewport().x).toBe(-40);
+
+    root.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', shiftKey: true, bubbles: true }));
+    await nextTick();
+    expect(exposed.value.getViewport().x).toBe(-40 - 200);
+  });
+
+  it('disableKeyboardA11y downgrades role to group', async () => {
+    mountStage({ disableKeyboardA11y: true });
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-canvas-stage-root]')!;
+    expect(root.getAttribute('role')).toBe('group');
+  });
+
+  it('auto-measures the content element when no size props are given', async () => {
+    const exposed = ref<any>(null);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(CanvasStageRoot, {
+          ref: (r: any) => { exposed.value = r; },
+          style: 'width: 400px; height: 300px;',
+        }, {
+          default: () => h('div', { 'data-child': '', style: 'width: 250px; height: 120px;' }, 'x'),
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await raf(3);
+    await nextTick();
+    expect(exposed.value.contentSize.width).toBeCloseTo(250, 0);
+    expect(exposed.value.contentSize.height).toBeCloseTo(120, 0);
+  });
+
+  it('drives a controlled v-model:viewport', async () => {
+    const vp = ref({ x: 0, y: 0, zoom: 1 });
+    const Harness = defineComponent({
+      setup() {
+        return () => h(CanvasStageRoot, {
+          viewport: vp.value,
+          'onUpdate:viewport': (v: any) => { vp.value = v; },
+          style: 'width: 400px; height: 300px;',
+          contentWidth: 800,
+          contentHeight: 600,
+          fitOnReady: false,
+        }, { default: () => h('div', { 'data-child': '' }, 'x') });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    vp.value = { x: 10, y: 20, zoom: 1.5 };
+    await nextTick();
+    const content = document.querySelector<HTMLElement>('[data-canvas-stage-content]')!;
+    expect(content.style.transform).toContain('translate(10px, 20px)');
+    expect(content.style.transform).toContain('scale(1.5)');
+  });
+
+  it('the parts can be composed manually under a custom subtree', async () => {
+    // Sanity: Pane + Content are exported and mountable inside the Root surface.
+    expect(CanvasStagePane).toBeTruthy();
+    expect(CanvasStageContent).toBeTruthy();
+  });
+});
diff --git a/vue/primitives/src/canvas/canvas-stage/__test__/__screenshots__/CanvasStage.test.ts/CanvasStageRoot--mount--auto-measures-the-content-element-when-no-size-props-are-given-1.png b/vue/primitives/src/canvas/canvas-stage/__test__/__screenshots__/CanvasStage.test.ts/CanvasStageRoot--mount--auto-measures-the-content-element-when-no-size-props-are-given-1.png
new file mode 100644
index 0000000..52c754d
Binary files /dev/null and b/vue/primitives/src/canvas/canvas-stage/__test__/__screenshots__/CanvasStage.test.ts/CanvasStageRoot--mount--auto-measures-the-content-element-when-no-size-props-are-given-1.png differ
diff --git a/vue/primitives/src/canvas/canvas-stage/context.ts b/vue/primitives/src/canvas/canvas-stage/context.ts
new file mode 100644
index 0000000..64ae599
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/context.ts
@@ -0,0 +1,78 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { Dimensions, Rect, Viewport, XYPosition } from '../zoom-pan';
+
+/**
+ * The imperative control surface of a {@link CanvasStageRoot}. Wraps the
+ * underlying zoom-pan `ViewportApi` and adds the photo-editing fit modes
+ * (`fitView` / `zoomToActual` / `fitFill`) that depend on the content size. Every
+ * write funnels through the zoom-pan api's `clampViewport`, so the result always
+ * honours `minZoom`/`maxZoom`.
+ */
+export interface CanvasStageApi {
+  /** Current viewport `{x,y,zoom}`. */
+  getViewport: () => Viewport;
+  /** Replace the viewport (clamped). */
+  setViewport: (viewport: Viewport) => void;
+  /** Zoom in, anchored at the pane centre. */
+  zoomIn: (factor?: number) => void;
+  /** Zoom out, anchored at the pane centre. */
+  zoomOut: (factor?: number) => void;
+  /** Zoom to an absolute level, anchored at the pane centre. */
+  zoomTo: (zoom: number) => void;
+  /**
+   * Fit the whole content into the pane, centred with `fitPadding`. The
+   * "contain" mode — the entire image/video is visible. No-op until both the
+   * pane and the content have been measured.
+   */
+  fitView: () => void;
+  /**
+   * Zoom to 1:1 (zoom 1, one content px per screen px), centred on the content
+   * centre. No-op until the pane has been measured.
+   */
+  zoomToActual: () => void;
+  /**
+   * Scale the content to *cover* the pane (the larger of the two fit ratios),
+   * centred — the "fill" mode, no letterboxing. No-op until measured.
+   */
+  fitFill: () => void;
+  /** Centre a content-space point in the pane, keeping the current zoom. */
+  center: (point?: XYPosition) => void;
+  /** Reset to `{ x: 0, y: 0, zoom: 1 }` (clamped). */
+  reset: () => void;
+}
+
+/**
+ * Context shared by every `CanvasStage` part. Exposes the wrapped
+ * {@link CanvasStageApi}, the reactive content size, and the resolved content
+ * extent (a content-space {@link Rect} starting at the origin), plus the surface
+ * measurement flag so descendants can gate behaviour until the pane is ready.
+ */
+export interface CanvasStageContext {
+  /** The combined imperative api (zoom-pan + canvas fit modes). */
+  api: CanvasStageApi;
+  /** Live viewport `{x,y,zoom}` (read-only mirror of the zoom-pan master). */
+  viewport: Ref<Viewport>;
+  /**
+   * The intrinsic content size in content-space px — either the explicit
+   * `contentWidth`/`contentHeight` props or the measured size of the content
+   * element. `{ width: 0, height: 0 }` until known.
+   */
+  contentSize: Ref<Dimensions>;
+  /** The content extent `{ x: 0, y: 0, width, height }` used by the fit modes. */
+  contentExtent: Ref<Rect>;
+  /** False until the pane has reported its first non-zero rect. */
+  measured: Ref<boolean>;
+  /** Whether the content element should be auto-measured (no explicit size props). */
+  autoMeasure: Ref<boolean>;
+  /** `CanvasStageContent` reports its measured intrinsic size here. */
+  setMeasuredContentSize: (size: Dimensions) => void;
+}
+
+const context = useContextFactory<CanvasStageContext>('CanvasStageContext');
+
+/** Provide the {@link CanvasStageContext} to descendants of `CanvasStageRoot`. */
+export const provideCanvasStageContext = context.provide;
+
+/** Inject the {@link CanvasStageContext}. Throws when no `CanvasStageRoot` ancestor. */
+export const useCanvasStageContext = context.inject;
diff --git a/vue/primitives/src/canvas/canvas-stage/demo.vue b/vue/primitives/src/canvas/canvas-stage/demo.vue
new file mode 100644
index 0000000..f972d27
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/demo.vue
@@ -0,0 +1,140 @@
+<script setup lang="ts">
+import {
+  CanvasStageContent,
+  CanvasStagePane,
+  CanvasStageRoot,
+  CanvasStageZoomIndicator,
+} from '@robonen/primitives';
+import { useTemplateRef } from 'vue';
+
+const stage = useTemplateRef<InstanceType<typeof CanvasStageRoot>>('stage');
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-2xl space-y-4 p-6 text-fg">
+    <div class="flex items-center justify-between">
+      <span class="text-sm font-medium">Canvas stage</span>
+    </div>
+
+    <CanvasStageRoot
+      ref="stage"
+      aria-label="Zoomable photo"
+      :min-zoom="0.2"
+      :max-zoom="6"
+      class="stage relative h-80 w-full overflow-hidden rounded-card border border-border bg-bg-inset shadow-(--shadow-card) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <CanvasStagePane class="size-full">
+        <CanvasStageContent>
+          <!-- A CSS-gradient "photo" with an intrinsic size so fit modes work. -->
+          <div class="stage-photo">
+            <div class="stage-photo__sun" />
+            <div class="stage-photo__grid" />
+            <span class="stage-photo__caption">1200 × 800</span>
+          </div>
+        </CanvasStageContent>
+      </CanvasStagePane>
+
+      <!-- Visible zoom badge driven by the same indicator value. -->
+      <CanvasStageZoomIndicator class="stage-badge">
+        <template #default="{ percent }">{{ percent }}%</template>
+      </CanvasStageZoomIndicator>
+    </CanvasStageRoot>
+
+    <div class="flex flex-wrap items-center gap-2">
+      <button type="button" class="stage-btn" @click="stage?.zoomIn()">Zoom in</button>
+      <button type="button" class="stage-btn" @click="stage?.zoomOut()">Zoom out</button>
+      <button type="button" class="stage-btn" @click="stage?.fitView()">Fit</button>
+      <button type="button" class="stage-btn" @click="stage?.fitFill()">Fill</button>
+      <button type="button" class="stage-btn" @click="stage?.zoomToActual()">1:1</button>
+      <button type="button" class="stage-btn" @click="stage?.reset()">Reset</button>
+    </div>
+
+    <p class="text-xs text-fg-subtle">
+      Drag to pan, scroll to zoom, or focus the stage and use Arrow keys, +/-, and 0 / 1 / 2 for 1:1 / fit / fill.
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.stage {
+  cursor: grab;
+  touch-action: none;
+}
+.stage:active {
+  cursor: grabbing;
+}
+
+/* Intrinsic-sized gradient "photo". */
+.stage-photo {
+  position: relative;
+  width: 1200px;
+  height: 800px;
+  overflow: hidden;
+  background:
+    radial-gradient(circle at 28% 26%, #fde68a 0%, transparent 30%),
+    linear-gradient(160deg, #6d28d9 0%, #db2777 45%, #f97316 100%);
+}
+.stage-photo__sun {
+  position: absolute;
+  top: 120px;
+  left: 240px;
+  width: 220px;
+  height: 220px;
+  border-radius: 9999px;
+  background: radial-gradient(circle, #fffbeb 0%, #fde047 55%, transparent 72%);
+  filter: blur(2px);
+}
+.stage-photo__grid {
+  position: absolute;
+  inset: 0;
+  background-image:
+    linear-gradient(to right, rgb(255 255 255 / 0.08) 1px, transparent 1px),
+    linear-gradient(to bottom, rgb(255 255 255 / 0.08) 1px, transparent 1px);
+  background-size: 80px 80px;
+}
+.stage-photo__caption {
+  position: absolute;
+  bottom: 24px;
+  right: 28px;
+  font-family: var(--font-mono);
+  font-size: 28px;
+  font-weight: 600;
+  color: rgb(255 255 255 / 0.85);
+  letter-spacing: 0.05em;
+}
+
+.stage-badge {
+  position: absolute;
+  bottom: 0.5rem;
+  right: 0.5rem;
+  padding: 2px 8px;
+  border-radius: 9999px;
+  font-family: var(--font-mono);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  color: var(--fg);
+  background: color-mix(in oklch, var(--bg) 80%, transparent);
+  border: 1px solid var(--border);
+  backdrop-filter: blur(4px);
+}
+
+.stage-btn {
+  padding: 0.375rem 0.75rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  border-radius: 0.5rem;
+  color: var(--fg);
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  cursor: pointer;
+  transition: background 0.12s ease, border-color 0.12s ease;
+}
+.stage-btn:hover {
+  background: var(--bg-inset);
+  border-color: var(--border-strong);
+}
+.stage-btn:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--ring);
+}
+</style>
diff --git a/vue/primitives/src/canvas/canvas-stage/index.ts b/vue/primitives/src/canvas/canvas-stage/index.ts
new file mode 100644
index 0000000..7fa98fc
--- /dev/null
+++ b/vue/primitives/src/canvas/canvas-stage/index.ts
@@ -0,0 +1,12 @@
+export { default as CanvasStageRoot } from './CanvasStageRoot.vue';
+export { default as CanvasStagePane } from './CanvasStagePane.vue';
+export { default as CanvasStageContent } from './CanvasStageContent.vue';
+export { default as CanvasStageZoomIndicator } from './CanvasStageZoomIndicator.vue';
+
+export { provideCanvasStageContext, useCanvasStageContext } from './context';
+export type { CanvasStageApi, CanvasStageContext } from './context';
+
+export type { CanvasStageRootProps } from './CanvasStageRoot.vue';
+export type { CanvasStagePaneEmits, CanvasStagePaneProps } from './CanvasStagePane.vue';
+export type { CanvasStageContentProps } from './CanvasStageContent.vue';
+export type { CanvasStageZoomIndicatorProps } from './CanvasStageZoomIndicator.vue';
diff --git a/vue/primitives/src/canvas/compare-slider/CompareSliderAfter.vue b/vue/primitives/src/canvas/compare-slider/CompareSliderAfter.vue
new file mode 100644
index 0000000..d79880b
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/CompareSliderAfter.vue
@@ -0,0 +1,78 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The revealed ("after") layer, drawn on top of `CompareSliderBefore` and
+ * clipped via `clip-path: inset(...)` so that exactly `position`% of it is
+ * shown. The clip side is driven by the root's combined `flip` flag (so the
+ * revealed region always sits on the same side as the divider). At `0` / `100`
+ * the layer is fully hidden / shown with no sub-pixel sliver. Rendered inside
+ * `CompareSliderRoot` and absolutely positioned to fill it (`inset: 0`); put the
+ * comparison image / view here.
+ */
+export interface CompareSliderAfterProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useCompareSliderContext } from './context';
+import { clamp } from '@robonen/stdlib';
+
+const { as = 'div' } = defineProps<CompareSliderAfterProps>();
+const ctx = useCompareSliderContext();
+const { forwardRef } = useForwardExpose();
+
+// `clip-path: inset(top right bottom left)`. Reveal exactly `position`% measured
+// from the start edge; the OTHER edge is clipped by `100 - position`%. The
+// `flip` flag selects which edge is the start, matching the divider side. Clamp
+// to [0, 100] so 0/100 hide/show fully with no 0.5px sliver.
+const clipPath = computed<string>(() => {
+  const p = clamp(ctx.position.value, 0, 100);
+  const hidden = 100 - p;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const flip = ctx.flip.value;
+  if (horizontal) {
+    // No flip → reveal the left portion (clip the right edge).
+    // Flip → reveal the right portion (clip the left edge).
+    return flip
+      ? `inset(0% 0% 0% ${hidden}%)`
+      : `inset(0% ${hidden}% 0% 0%)`;
+  }
+  // No flip → reveal the top portion (clip the bottom edge).
+  // Flip → reveal the bottom portion (clip the top edge).
+  return flip
+    ? `inset(${hidden}% 0% 0% 0%)`
+    : `inset(0% 0% ${hidden}% 0%)`;
+});
+
+// Stable shape: same keys in the same order for a monomorphic style object.
+const style = computed<{
+  position: string;
+  top: string;
+  right: string;
+  bottom: string;
+  left: string;
+  clipPath: string;
+}>(() => ({
+  position: 'absolute',
+  top: '0',
+  right: '0',
+  bottom: '0',
+  left: '0',
+  clipPath: clipPath.value,
+}));
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :style="style"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+  >
+    <slot :position="ctx.position.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/compare-slider/CompareSliderBefore.vue b/vue/primitives/src/canvas/compare-slider/CompareSliderBefore.vue
new file mode 100644
index 0000000..b40e32f
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/CompareSliderBefore.vue
@@ -0,0 +1,42 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The base ("before") layer of the comparison — the full, unclipped content
+ * that sits underneath. Rendered inside `CompareSliderRoot` and absolutely
+ * positioned to fill it (`inset: 0`). Put the original image / view here; the
+ * `CompareSliderAfter` layer is drawn on top and clipped to reveal it.
+ */
+export interface CompareSliderBeforeProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useCompareSliderContext } from './context';
+
+const { as = 'div' } = defineProps<CompareSliderBeforeProps>();
+const ctx = useCompareSliderContext();
+const { forwardRef } = useForwardExpose();
+
+// Stable shape: same keys in the same order for a monomorphic style object.
+const style = {
+  position: 'absolute',
+  top: '0',
+  right: '0',
+  bottom: '0',
+  left: '0',
+} as const;
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :style="style"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/compare-slider/CompareSliderDivider.vue b/vue/primitives/src/canvas/compare-slider/CompareSliderDivider.vue
new file mode 100644
index 0000000..c146e82
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/CompareSliderDivider.vue
@@ -0,0 +1,70 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A thin presentational line marking the split between the before and after
+ * layers, positioned at the current reveal position. It is purely decorative
+ * (no role, no keyboard) — the focusable, screen-reader-accessible target is
+ * `CompareSliderHandle`.
+ *
+ * The recommended two-element pattern is a thin `CompareSliderDivider` line for
+ * the visible seam plus a larger `CompareSliderHandle` "puck" for the grab /
+ * focus target sitting on top of it (give the handle a wider hit-area via CSS).
+ * Render the divider as a sibling or wrapper of the handle inside the root.
+ */
+export interface CompareSliderDividerProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useCompareSliderContext } from './context';
+
+const { as = 'span' } = defineProps<CompareSliderDividerProps>();
+const ctx = useCompareSliderContext();
+const { forwardRef } = useForwardExpose();
+
+// Sit on the divider. Stable shape: same keys in the same order; the `flip` flag
+// selects the positioning edge so the line tracks the after-layer clip side.
+const style = computed<{
+  position: string;
+  left: string | undefined;
+  right: string | undefined;
+  top: string | undefined;
+  bottom: string | undefined;
+}>(() => {
+  const pct = `${ctx.position.value}%`;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const flip = ctx.flip.value;
+  if (horizontal) {
+    return {
+      position: 'absolute',
+      left: flip ? undefined : pct,
+      right: flip ? pct : undefined,
+      top: undefined,
+      bottom: undefined,
+    };
+  }
+  return {
+    position: 'absolute',
+    left: undefined,
+    right: undefined,
+    top: flip ? undefined : pct,
+    bottom: flip ? pct : undefined,
+  };
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    :style="style"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+  >
+    <slot :position="ctx.position.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/compare-slider/CompareSliderHandle.vue b/vue/primitives/src/canvas/compare-slider/CompareSliderHandle.vue
new file mode 100644
index 0000000..f7df1bf
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/CompareSliderHandle.vue
@@ -0,0 +1,153 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The keyboard- and screen-reader-accessible divider handle, rendered as
+ * `role="slider"` with full ARIA value attributes (`aria-valuemin=0`,
+ * `aria-valuemax=100`, `aria-valuenow=position`). It positions itself at the
+ * divider and handles keyboard interaction: Arrow keys move the divider toward
+ * the after/before layer by `keyboardStep` (orientation- and direction-aware),
+ * Shift+Arrow and Page keys by `keyboardLargeStep`, and Home/End jump to 0/100.
+ * This is the hit-target / focus element; pair it with a thin presentational
+ * `CompareSliderDivider` for the visible line. Exposes `position` as a slot prop.
+ */
+export interface CompareSliderHandleProps extends PrimitiveProps {
+  /**
+   * Optional formatter producing this handle's `aria-valuetext`. Overrides the
+   * root-level `valueText` for this handle when provided. Receives the reveal
+   * position (0–100).
+   */
+  valueText?: (position: number) => string | undefined;
+  // `aria-label` (and other ARIA attributes) fall through to the rendered
+  // `role="slider"` element; a default of 'Comparison position' is applied when
+  // none is supplied.
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed, useAttrs } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useCompareSliderContext } from './context';
+
+const { as = 'span', valueText } = defineProps<CompareSliderHandleProps>();
+const ctx = useCompareSliderContext();
+const attrs = useAttrs();
+const { forwardRef } = useForwardExpose();
+
+// Position the handle at the divider. Stable shape: same keys in the same order
+// for a monomorphic style object; unused sides are explicit `undefined`. The
+// `flip` flag selects the positioning edge, matching the after-layer clip side.
+const style = computed<{
+  position: string;
+  left: string | undefined;
+  right: string | undefined;
+  top: string | undefined;
+  bottom: string | undefined;
+}>(() => {
+  const pct = `${ctx.position.value}%`;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const flip = ctx.flip.value;
+  if (horizontal) {
+    return {
+      position: 'absolute',
+      left: flip ? undefined : pct,
+      right: flip ? pct : undefined,
+      top: undefined,
+      bottom: undefined,
+    };
+  }
+  return {
+    position: 'absolute',
+    left: undefined,
+    right: undefined,
+    top: flip ? undefined : pct,
+    bottom: flip ? pct : undefined,
+  };
+});
+
+// Fall back to a generic accessible name when the consumer supplies none.
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return 'Comparison position';
+});
+
+// Humanised `aria-valuetext`: the per-handle `valueText` prop wins, then the
+// root-level formatter; a consumer-supplied `aria-valuetext` attr wins over both.
+const valueTextStr = computed<string | undefined>(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  const fmt = valueText ?? ctx.valueText.value;
+  return fmt ? fmt(ctx.position.value) : undefined;
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const flip = ctx.flip.value;
+  const big = event.shiftKey ? ctx.keyboardLargeStep.value : ctx.keyboardStep.value;
+  let delta: number;
+  switch (event.key) {
+    case 'ArrowRight':
+      // Toward the after layer (increase) unless flipped.
+      delta = horizontal ? (flip ? -big : big) : 0;
+      break;
+    case 'ArrowLeft':
+      delta = horizontal ? (flip ? big : -big) : 0;
+      break;
+    case 'ArrowUp':
+      // Vertical no-flip reveals the top region; ArrowUp shrinks it (decrease).
+      delta = horizontal ? 0 : (flip ? big : -big);
+      break;
+    case 'ArrowDown':
+      delta = horizontal ? 0 : (flip ? -big : big);
+      break;
+    case 'PageUp':
+      delta = horizontal
+        ? ctx.keyboardLargeStep.value
+        : (flip ? ctx.keyboardLargeStep.value : -ctx.keyboardLargeStep.value);
+      break;
+    case 'PageDown':
+      delta = horizontal
+        ? -ctx.keyboardLargeStep.value
+        : (flip ? -ctx.keyboardLargeStep.value : ctx.keyboardLargeStep.value);
+      break;
+    case 'Home':
+      event.preventDefault();
+      ctx.setPosition(0);
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.setPosition(100);
+      return;
+    default:
+      return;
+  }
+  if (delta === 0) return;
+  event.preventDefault();
+  ctx.step(delta);
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
+    :aria-valuemin="0"
+    :aria-valuemax="100"
+    :aria-valuenow="ctx.position.value"
+    :aria-valuetext="valueTextStr"
+    :aria-orientation="ctx.orientation.value"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+    :style="style"
+    @keydown="onKeyDown"
+  >
+    <slot :position="ctx.position.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/compare-slider/CompareSliderRoot.vue b/vue/primitives/src/canvas/compare-slider/CompareSliderRoot.vue
new file mode 100644
index 0000000..f38cc03
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/CompareSliderRoot.vue
@@ -0,0 +1,214 @@
+<script lang="ts">
+import type { CompareSliderDirection, CompareSliderOrientation, CompareSliderValueText } from './context';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A before/after split-reveal slider: two stacked layers (a base
+ * `CompareSliderBefore` and a clipped `CompareSliderAfter`) with a draggable
+ * divider that reveals exactly `position`% of the after-layer. The root owns the
+ * reveal position (controlled via `v-model:position` or uncontrolled via
+ * `defaultPosition`), clamps it to 0–100, and starts a pointer drag on press —
+ * mapping the pointer's position over the root's box onto the reveal
+ * percentage. When `hover` is set the divider follows the pointer on hover
+ * (no press needed). It provides context to `CompareSliderBefore`,
+ * `CompareSliderAfter`, `CompareSliderHandle`, and `CompareSliderDivider`, and
+ * supports horizontal/vertical `orientation` plus `dir`/`inverted` direction.
+ * Reach for it to compare two images, designs, or any two overlaid views.
+ */
+export interface CompareSliderRootProps extends PrimitiveProps {
+  /** Orientation. @default 'horizontal' */
+  orientation?: CompareSliderOrientation;
+  /** Uncontrolled initial reveal position (0–100). @default 50 */
+  defaultPosition?: number;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /** Invert the direction of interaction (and the revealed side). @default false */
+  inverted?: boolean;
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
+  dir?: CompareSliderDirection;
+  /** Position change per Arrow key press. @default 1 */
+  keyboardStep?: number;
+  /** Position change per Shift+Arrow / Page key press. @default 10 */
+  keyboardLargeStep?: number;
+  /** When true the divider follows the pointer on hover, without a press. @default false */
+  hover?: boolean;
+  /**
+   * Optional formatter producing a human-friendly `aria-valuetext` for the
+   * handle. Receives the reveal position (0–100).
+   */
+  valueText?: CompareSliderValueText;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideCompareSliderContext } from './context';
+import { useDirection } from '../../utilities/config-provider';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+import { clamp } from '@robonen/stdlib';
+
+const {
+  orientation = 'horizontal',
+  defaultPosition = 50,
+  disabled = false,
+  inverted = false,
+  dir,
+  keyboardStep = 1,
+  keyboardLargeStep = 10,
+  hover = false,
+  valueText,
+  as = 'div',
+} = defineProps<CompareSliderRootProps>();
+
+// Resolve direction: explicit `dir` prop wins, otherwise inherit from the
+// nearest `ConfigProvider` (falls back to `'ltr'`).
+const direction = useDirection(() => dir);
+
+// `defineModel` drives both controlled (`v-model:position`) and uncontrolled
+// modes; in uncontrolled mode `model.value` is `undefined` until first write,
+// so `localPosition` below seeds from `defaultPosition`.
+const model = defineModel<number>('position');
+
+const localPosition = ref<number>(clamp(model.value ?? defaultPosition, 0, 100));
+
+watch(model, (v) => {
+  if (v === undefined || v === null) return;
+  const next = clamp(v, 0, 100);
+  if (next !== localPosition.value) localPosition.value = next;
+});
+
+const position = computed<number>({
+  get: () => localPosition.value,
+  set: (v) => {
+    const next = clamp(v, 0, 100);
+    if (next === localPosition.value) return;
+    localPosition.value = next;
+    // `defineModel` emits `update:position` on write — no manual emit needed.
+    model.value = next;
+  },
+});
+
+// Combined flip flag — the SAME flag drives BOTH the pointer-offset mapping and
+// the after-layer clip side (see context.ts). For horizontal, rtl and inverted
+// each flip the start edge; for vertical only `inverted` flips.
+const flip = computed<boolean>(() =>
+  orientation === 'horizontal'
+    ? (direction.value === 'rtl') !== inverted
+    : inverted,
+);
+
+// `defineExpose` MUST precede `useForwardExpose` (else Vue warns "expose()
+// called only once" and clobbers the forwarded `$el`/props). `currentElement`
+// is consumed at top-level setup below (drag/hover/context), so `defineExpose`
+// is hoisted up to here — its dep `position` is already declared above.
+defineExpose({ position });
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Map a client point over the root's box onto the reveal percentage (0–100).
+// Guard size === 0 → return 0 (mirror SliderRoot's `getValueFromPointer`).
+function positionFromClient(clientX: number, clientY: number, rect?: DOMRect): number {
+  // During a drag the caller passes the rect snapshotted at onStart (the box
+  // cannot change mid-drag); hover passes nothing and measures live.
+  const r = rect ?? currentElement.value?.getBoundingClientRect();
+  if (!r) return 0;
+  const horizontal = orientation === 'horizontal';
+  const size = horizontal ? r.width : r.height;
+  if (size === 0) return 0;
+  let offset = horizontal ? clientX - r.left : clientY - r.top;
+  // The SAME flip flag drives the after-layer clip side, so the divider and the
+  // revealed region stay in sync.
+  if (flip.value) offset = size - offset;
+  return clamp((offset / size) * 100, 0, 100);
+}
+
+// Rect snapshotted for the duration of a drag — removes a getBoundingClientRect
+// reflow on every onMove frame.
+let gestureRect: DOMRect | undefined;
+
+// Drag the divider. `threshold: 0` so a single press jumps to the pointer and
+// drags from there (no dead zone). `state.point` is the live client point.
+const drag = usePointerDrag(currentElement, {
+  threshold: 0,
+  disabled: () => disabled,
+  preventDefault: true,
+  onStart: (state) => {
+    gestureRect = currentElement.value?.getBoundingClientRect();
+    position.value = positionFromClient(state.point.x, state.point.y, gestureRect);
+  },
+  onMove: (state) => {
+    position.value = positionFromClient(state.point.x, state.point.y, gestureRect);
+  },
+  onEnd: () => {
+    gestureRect = undefined;
+  },
+});
+
+const hovering = ref(false);
+
+// Hover-move: when `hover` is set, the divider follows the pointer over the root
+// without a press. A live drag takes precedence (its own pointermove drives the
+// position), so skip while dragging.
+useEventListener(currentElement, 'pointermove', (event: PointerEvent) => {
+  if (disabled || !hover || drag.isDragging.value) return;
+  position.value = positionFromClient(event.clientX, event.clientY);
+});
+useEventListener(currentElement, 'pointerenter', () => {
+  if (disabled || !hover) return;
+  hovering.value = true;
+});
+useEventListener(currentElement, 'pointerleave', () => {
+  hovering.value = false;
+});
+
+function setPosition(next: number): void {
+  if (disabled) return;
+  position.value = next;
+}
+function stepBy(delta: number): void {
+  if (disabled) return;
+  position.value = localPosition.value + delta;
+}
+
+// Stable shape: always the same keys in the same order so V8 (and Vue's style
+// patcher) sees a monomorphic object.
+const rootStyle = computed<{ position: string }>(() => ({ position: 'relative' }));
+
+provideCompareSliderContext({
+  position,
+  // `toRef(() => prop)` → `GetterRefImpl`: reactive `Ref` without a
+  // `ReactiveEffect` / cache, since these are identity passthroughs.
+  orientation: toRef(() => orientation),
+  // `direction` is already a `ComputedRef` from `useDirection`; `flip` a `computed`.
+  direction,
+  disabled: toRef(() => disabled),
+  inverted: toRef(() => inverted),
+  flip,
+  keyboardStep: toRef(() => keyboardStep),
+  keyboardLargeStep: toRef(() => keyboardLargeStep),
+  valueText: toRef(() => valueText),
+  step: stepBy,
+  setPosition,
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :style="rootStyle"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-orientation="orientation"
+    :data-dragging="drag.isDragging.value ? '' : undefined"
+    :data-hovering="hovering ? '' : undefined"
+    :dir="direction"
+  >
+    <slot :position="position" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/compare-slider/__test__/CompareSlider.test.ts b/vue/primitives/src/canvas/compare-slider/__test__/CompareSlider.test.ts
new file mode 100644
index 0000000..cab32fb
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/__test__/CompareSlider.test.ts
@@ -0,0 +1,333 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { provideConfig } from '../../../utilities/config-provider';
+import {
+  CompareSliderAfter,
+  CompareSliderBefore,
+  CompareSliderDivider,
+  CompareSliderHandle,
+  CompareSliderRoot,
+} from '../index';
+
+// Minimal declarative config wrapper (the package ships no ConfigProvider
+// component; config is provided via `provideConfig` inside a setup).
+const ConfigProvider = defineComponent({
+  props: { dir: { type: String, default: undefined } },
+  setup(props, { slots }) {
+    provideConfig({ dir: () => props.dir as 'ltr' | 'rtl' | undefined });
+    return () => slots.default?.();
+  },
+});
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+type RootOpts = Partial<{
+  defaultPosition: number;
+  disabled: boolean;
+  inverted: boolean;
+  orientation: 'horizontal' | 'vertical';
+  dir: 'ltr' | 'rtl';
+  keyboardStep: number;
+  keyboardLargeStep: number;
+}>;
+
+function mountSlider(opts: RootOpts = {}, wrapInConfig?: { dir?: 'ltr' | 'rtl' }) {
+  const model = ref<number | undefined>(undefined);
+  const Harness = defineComponent({
+    setup() {
+      const tree = () => h(CompareSliderRoot, {
+        position: model.value,
+        'onUpdate:position': (v: number | undefined) => { model.value = v; },
+        ...opts,
+      }, {
+        default: () => [
+          h(CompareSliderBefore),
+          h(CompareSliderAfter, { id: 'after' }),
+          h(CompareSliderDivider),
+          h(CompareSliderHandle, { id: 'handle' }),
+        ],
+      });
+      return () => wrapInConfig
+        ? h(ConfigProvider, { dir: wrapInConfig.dir }, { default: tree })
+        : tree();
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false });
+  el.dispatchEvent(event);
+}
+
+describe('CompareSlider — rendering & ARIA', () => {
+  it('renders the handle as role="slider" with correct aria-value*', async () => {
+    mountSlider({ defaultPosition: 40 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(handle).toBeTruthy();
+    expect(handle.getAttribute('aria-valuemin')).toBe('0');
+    expect(handle.getAttribute('aria-valuemax')).toBe('100');
+    expect(handle.getAttribute('aria-valuenow')).toBe('40');
+    expect(handle.getAttribute('aria-orientation')).toBe('horizontal');
+    expect(handle.tabIndex).toBe(0);
+  });
+
+  it('applies the default aria-label "Comparison position"', async () => {
+    mountSlider({ defaultPosition: 50 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(handle.getAttribute('aria-label')).toBe('Comparison position');
+  });
+
+  it('an explicit aria-label wins over the default', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(CompareSliderRoot, { defaultPosition: 50 }, {
+        default: () => [
+          h(CompareSliderBefore),
+          h(CompareSliderAfter),
+          h(CompareSliderHandle, { 'aria-label': 'Reveal' }),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(handle.getAttribute('aria-label')).toBe('Reveal');
+  });
+
+  it('sets data-orientation as a literal on the root and handle', async () => {
+    mountSlider({ defaultPosition: 50, orientation: 'vertical' });
+    await nextTick();
+    const handle = document.getElementById('handle')!;
+    expect(handle.getAttribute('data-orientation')).toBe('vertical');
+    expect(handle.getAttribute('aria-orientation')).toBe('vertical');
+  });
+});
+
+describe('CompareSlider — keyboard', () => {
+  it('ArrowRight increments and ArrowLeft decrements the position', async () => {
+    const { model } = mountSlider({ defaultPosition: 50, keyboardStep: 5 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(handle, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(55);
+    keydown(handle, 'ArrowLeft');
+    keydown(handle, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toBe(45);
+  });
+
+  it('ArrowRight is reversed under dir="rtl"', async () => {
+    const { model } = mountSlider({ defaultPosition: 50, keyboardStep: 5, dir: 'rtl' });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(handle, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(45);
+    keydown(handle, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toBe(50);
+  });
+
+  it('Shift+Arrow and Page keys use the large step', async () => {
+    const { model } = mountSlider({ defaultPosition: 50, keyboardStep: 1, keyboardLargeStep: 10 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(handle, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(model.value).toBe(60);
+    keydown(handle, 'PageDown');
+    keydown(handle, 'PageDown');
+    await nextTick();
+    expect(model.value).toBe(40);
+  });
+
+  it('Home/End jump to 0/100', async () => {
+    const { model } = mountSlider({ defaultPosition: 50 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(handle, 'Home');
+    await nextTick();
+    expect(model.value).toBe(0);
+    keydown(handle, 'End');
+    await nextTick();
+    expect(model.value).toBe(100);
+  });
+
+  it('clamps at 0 and 100', async () => {
+    const { model } = mountSlider({ defaultPosition: 95, keyboardStep: 10 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(handle, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(100);
+    keydown(handle, 'Home');
+    keydown(handle, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toBe(0);
+  });
+
+  it('vertical: ArrowDown increases, ArrowUp decreases (no-flip reveals the top)', async () => {
+    const { model } = mountSlider({ defaultPosition: 50, orientation: 'vertical', keyboardStep: 5 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(handle, 'ArrowDown');
+    await nextTick();
+    expect(model.value).toBe(55);
+    keydown(handle, 'ArrowUp');
+    keydown(handle, 'ArrowUp');
+    await nextTick();
+    expect(model.value).toBe(45);
+  });
+
+  it('disabled: tabindex=-1, aria-disabled, and keys do nothing', async () => {
+    const { model } = mountSlider({ defaultPosition: 50, disabled: true });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(handle.tabIndex).toBe(-1);
+    expect(handle.getAttribute('aria-disabled')).toBe('true');
+    keydown(handle, 'ArrowRight');
+    keydown(handle, 'Home');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+    expect(handle.getAttribute('aria-valuenow')).toBe('50');
+  });
+});
+
+describe('CompareSlider — after-layer clip-path', () => {
+  it('clip-path inset reflects position (horizontal, no flip → clips the right)', async () => {
+    mountSlider({ defaultPosition: 30 });
+    await nextTick();
+    const after = document.getElementById('after')!;
+    // 30% revealed from the left → right edge clipped by 70%.
+    expect(after.style.clipPath).toBe('inset(0% 70% 0% 0%)');
+  });
+
+  it('updates the clip-path when the position changes', async () => {
+    const { model } = mountSlider({ defaultPosition: 50, keyboardStep: 10 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    const after = document.getElementById('after')!;
+    keydown(handle, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBe(60);
+    expect(after.style.clipPath).toBe('inset(0% 40% 0% 0%)');
+  });
+
+  it('inverted flips the clipped side (horizontal → clips the left)', async () => {
+    mountSlider({ defaultPosition: 30, inverted: true });
+    await nextTick();
+    const after = document.getElementById('after')!;
+    expect(after.style.clipPath).toBe('inset(0% 0% 0% 70%)');
+  });
+
+  it('vertical (no flip) clips the bottom edge', async () => {
+    mountSlider({ defaultPosition: 30, orientation: 'vertical' });
+    await nextTick();
+    const after = document.getElementById('after')!;
+    // The browser collapses the trailing `0%` (CSSOM `inset()` serialization,
+    // like `margin`): `inset(0% 0% 70% 0%)` → `inset(0% 0% 70%)`.
+    expect(after.style.clipPath).toBe('inset(0% 0% 70%)');
+  });
+
+  it('0 and 100 produce no sliver (full hide / full show)', async () => {
+    const { model } = mountSlider({ defaultPosition: 50 });
+    await nextTick();
+    const handle = document.querySelector<HTMLElement>('[role="slider"]')!;
+    const after = document.getElementById('after')!;
+    keydown(handle, 'Home');
+    await nextTick();
+    expect(model.value).toBe(0);
+    // 0% revealed → right edge clipped by the full 100% (nothing shown).
+    expect(after.style.clipPath).toBe('inset(0% 100% 0% 0%)');
+    keydown(handle, 'End');
+    await nextTick();
+    // 100% revealed → no clipping; the browser collapses `inset(0% 0% 0% 0%)`
+    // to the single-value shorthand `inset(0%)`.
+    expect(after.style.clipPath).toBe('inset(0%)');
+  });
+});
+
+describe('CompareSlider — pointer drag', () => {
+  it('maps a pointerdown on the root onto the reveal position', async () => {
+    const { model } = mountSlider({ defaultPosition: 50 });
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-orientation]')!;
+    // Give the root a deterministic box.
+    root.style.width = '200px';
+    root.style.height = '100px';
+    await nextTick();
+    const rect = root.getBoundingClientRect();
+    const down = new PointerEvent('pointerdown', {
+      bubbles: true,
+      cancelable: true,
+      button: 0,
+      pointerId: 1,
+      clientX: rect.left + rect.width * 0.25,
+      clientY: rect.top + rect.height / 2,
+    });
+    root.dispatchEvent(down);
+    await nextTick();
+    expect(model.value).toBeCloseTo(25, 0);
+  });
+
+  it('disabled blocks pointer drag', async () => {
+    const { model } = mountSlider({ defaultPosition: 50, disabled: true });
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-orientation]')!;
+    root.style.width = '200px';
+    const rect = root.getBoundingClientRect();
+    const down = new PointerEvent('pointerdown', {
+      bubbles: true,
+      cancelable: true,
+      button: 0,
+      pointerId: 1,
+      clientX: rect.left + rect.width * 0.75,
+      clientY: rect.top + 10,
+    });
+    root.dispatchEvent(down);
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+});
+
+describe('CompareSlider — controlled position model', () => {
+  it('reflects an external position update onto aria-valuenow and clip-path', async () => {
+    const model = ref<number | undefined>(20);
+    const Harness = defineComponent({
+      setup: () => () => h(CompareSliderRoot, {
+        position: model.value,
+        'onUpdate:position': (v: number | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(CompareSliderBefore),
+          h(CompareSliderAfter, { id: 'after2' }),
+          h(CompareSliderHandle, { id: 'handle2' }),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const handle = document.getElementById('handle2')!;
+    expect(handle.getAttribute('aria-valuenow')).toBe('20');
+    model.value = 75;
+    await nextTick();
+    expect(handle.getAttribute('aria-valuenow')).toBe('75');
+    expect(document.getElementById('after2')!.style.clipPath).toBe('inset(0% 25% 0% 0%)');
+  });
+});
diff --git a/vue/primitives/src/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-places-inner-element-absolutely-covering-the-wrapper-1.png b/vue/primitives/src/canvas/compare-slider/__test__/__screenshots__/CompareSlider.test.ts/CompareSlider---after-layer-clip-path-0-and-100-produce-no-sliver--full-hide---full-show--1.png
similarity index 100%
rename from vue/primitives/src/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-places-inner-element-absolutely-covering-the-wrapper-1.png
rename to vue/primitives/src/canvas/compare-slider/__test__/__screenshots__/CompareSlider.test.ts/CompareSlider---after-layer-clip-path-0-and-100-produce-no-sliver--full-hide---full-show--1.png
diff --git a/vue/primitives/src/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-renders-with-default-1-1-ratio-1.png b/vue/primitives/src/canvas/compare-slider/__test__/__screenshots__/CompareSlider.test.ts/CompareSlider---after-layer-clip-path-vertical--no-flip--clips-the-bottom-edge-1.png
similarity index 100%
rename from vue/primitives/src/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-renders-with-default-1-1-ratio-1.png
rename to vue/primitives/src/canvas/compare-slider/__test__/__screenshots__/CompareSlider.test.ts/CompareSlider---after-layer-clip-path-vertical--no-flip--clips-the-bottom-edge-1.png
diff --git a/vue/primitives/src/canvas/compare-slider/context.ts b/vue/primitives/src/canvas/compare-slider/context.ts
new file mode 100644
index 0000000..dea28de
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/context.ts
@@ -0,0 +1,54 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+export type CompareSliderOrientation = 'horizontal' | 'vertical';
+export type CompareSliderDirection = 'ltr' | 'rtl';
+
+/**
+ * Formatter turning the raw reveal position (0–100) into a human-friendly
+ * string for the handle's `aria-valuetext`. Return `undefined` to omit
+ * `aria-valuetext`.
+ */
+export type CompareSliderValueText = (position: number) => string | undefined;
+
+/**
+ * Context shared between `CompareSliderRoot` and its descendants
+ * (`CompareSliderBefore`, `CompareSliderAfter`, `CompareSliderHandle`,
+ * `CompareSliderDivider`).
+ *
+ * Scalar props are exposed as plain `Ref<T>`, but `CompareSliderRoot` builds
+ * them with `toRef(() => prop)` — a `GetterRefImpl` that is reactive without
+ * allocating a `ReactiveEffect` / cache (unlike `computed`). For identity
+ * passthrough of scalar props this avoids redundant effects per instance while
+ * keeping template auto-unwrap and `.value` ergonomics.
+ */
+export interface CompareSliderContext {
+  /** Reveal position, 0–100 (percentage of the after-layer shown). */
+  position: Ref<number>;
+  orientation: Ref<CompareSliderOrientation>;
+  direction: Ref<CompareSliderDirection>;
+  disabled: Ref<boolean>;
+  inverted: Ref<boolean>;
+  /**
+   * Combined flip flag driving BOTH the pointer-offset mapping and the
+   * after-layer clip side. For horizontal: `(dir === 'rtl') !== inverted`; for
+   * vertical: `inverted`. Keeping a single source of truth prevents the divider
+   * and the revealed region from desyncing.
+   */
+  flip: Ref<boolean>;
+  /** Single keyboard step (Arrow). */
+  keyboardStep: Ref<number>;
+  /** Large keyboard step (Shift+Arrow / Page keys). */
+  keyboardLargeStep: Ref<number>;
+  /** Optional formatter for the handle's `aria-valuetext`; `undefined` when unset. */
+  valueText: Ref<CompareSliderValueText | undefined>;
+  /** Move the reveal position by `delta` (clamped to 0–100). */
+  step: (delta: number) => void;
+  /** Set the reveal position to an absolute value (clamped to 0–100). */
+  setPosition: (next: number) => void;
+}
+
+const ctx = useContextFactory<CompareSliderContext>('CompareSliderContext');
+
+export const provideCompareSliderContext = ctx.provide;
+export const useCompareSliderContext = ctx.inject;
diff --git a/vue/primitives/src/canvas/compare-slider/demo.vue b/vue/primitives/src/canvas/compare-slider/demo.vue
new file mode 100644
index 0000000..00927e3
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/demo.vue
@@ -0,0 +1,123 @@
+<script setup lang="ts">
+import {
+  CompareSliderAfter,
+  CompareSliderBefore,
+  CompareSliderDivider,
+  CompareSliderHandle,
+  CompareSliderRoot,
+} from '@robonen/primitives';
+import { ref } from 'vue';
+
+const position = ref(50);
+const valueText = (p: number) => `${Math.round(p)}% revealed`;
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-md space-y-4 p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <span class="font-medium">Before / After</span>
+      <span class="font-mono text-fg-muted">{{ Math.round(position) }}% after</span>
+    </div>
+
+    <CompareSliderRoot
+      v-model:position="position"
+      :value-text="valueText"
+      class="compare-root group relative aspect-video w-full select-none overflow-hidden rounded-card border border-border shadow-(--shadow-card)"
+    >
+      <!-- "Before" layer: cool graded photo -->
+      <CompareSliderBefore class="compare-before">
+        <span class="absolute left-3 top-3 rounded-md bg-bg/80 px-2 py-0.5 text-xs font-medium text-fg backdrop-blur">
+          Before
+        </span>
+      </CompareSliderBefore>
+
+      <!-- "After" layer: warm graded photo, clipped to the reveal % -->
+      <CompareSliderAfter class="compare-after">
+        <span class="absolute right-3 top-3 rounded-md bg-bg/80 px-2 py-0.5 text-xs font-medium text-fg backdrop-blur">
+          After
+        </span>
+      </CompareSliderAfter>
+
+      <!-- Seam line -->
+      <CompareSliderDivider class="compare-divider" />
+
+      <!-- Grab / focus target -->
+      <CompareSliderHandle
+        aria-label="Comparison position"
+        class="compare-handle"
+      >
+        <span class="compare-handle__grip" aria-hidden="true">
+          <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <polyline points="15 18 9 12 15 6" />
+            <polyline points="9 18 3 12 9 6" transform="translate(12 0)" />
+          </svg>
+        </span>
+      </CompareSliderHandle>
+    </CompareSliderRoot>
+
+    <p class="text-xs text-fg-subtle">
+      Drag the handle (or focus it and use Arrow / Home / End keys) to reveal the after image.
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.compare-root {
+  cursor: ew-resize;
+  touch-action: none;
+}
+
+/* Two contrasting CSS-gradient "photos" stand in for real images. */
+.compare-before :deep(*),
+.compare-before {
+  background: linear-gradient(135deg, #1e3a8a 0%, #0ea5e9 50%, #22d3ee 100%);
+}
+.compare-before {
+  background:
+    radial-gradient(circle at 70% 30%, rgb(255 255 255 / 0.25), transparent 45%),
+    linear-gradient(135deg, #1e3a8a 0%, #0ea5e9 55%, #22d3ee 100%);
+}
+.compare-after {
+  background:
+    radial-gradient(circle at 30% 70%, rgb(255 255 255 / 0.3), transparent 45%),
+    linear-gradient(135deg, #b45309 0%, #f97316 55%, #facc15 100%);
+}
+
+/* Thin seam line at the split. */
+.compare-divider {
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  margin-left: -1px;
+  background: rgb(255 255 255 / 0.9);
+  box-shadow: 0 0 0 1px rgb(0 0 0 / 0.12);
+}
+
+/* Round grab puck centred on the seam. */
+.compare-handle {
+  top: 50%;
+  display: grid;
+  place-items: center;
+  width: 0;
+  height: 0;
+  outline: none;
+}
+.compare-handle__grip {
+  display: grid;
+  place-items: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  color: var(--fg);
+  background: var(--bg);
+  border-radius: 9999px;
+  box-shadow: 0 1px 3px rgb(0 0 0 / 0.3);
+  transform: translate(-50%, -50%);
+  transition: transform 0.12s ease;
+}
+.compare-handle:hover .compare-handle__grip {
+  transform: translate(-50%, -50%) scale(1.08);
+}
+.compare-handle:focus-visible .compare-handle__grip {
+  box-shadow: 0 0 0 3px var(--ring), 0 1px 3px rgb(0 0 0 / 0.3);
+}
+</style>
diff --git a/vue/primitives/src/canvas/compare-slider/index.ts b/vue/primitives/src/canvas/compare-slider/index.ts
new file mode 100644
index 0000000..3e822d5
--- /dev/null
+++ b/vue/primitives/src/canvas/compare-slider/index.ts
@@ -0,0 +1,15 @@
+export { default as CompareSliderRoot } from './CompareSliderRoot.vue';
+export { default as CompareSliderAfter } from './CompareSliderAfter.vue';
+export { default as CompareSliderBefore } from './CompareSliderBefore.vue';
+export { default as CompareSliderDivider } from './CompareSliderDivider.vue';
+export { default as CompareSliderHandle } from './CompareSliderHandle.vue';
+export type {
+  CompareSliderDirection,
+  CompareSliderOrientation,
+  CompareSliderValueText,
+} from './context';
+export type { CompareSliderAfterProps } from './CompareSliderAfter.vue';
+export type { CompareSliderBeforeProps } from './CompareSliderBefore.vue';
+export type { CompareSliderDividerProps } from './CompareSliderDivider.vue';
+export type { CompareSliderHandleProps } from './CompareSliderHandle.vue';
+export type { CompareSliderRootProps } from './CompareSliderRoot.vue';
diff --git a/vue/primitives/src/canvas/crop/CropArea.vue b/vue/primitives/src/canvas/crop/CropArea.vue
new file mode 100644
index 0000000..e2b9d35
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/CropArea.vue
@@ -0,0 +1,107 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The crop rectangle surface — the draggable, focusable body of the selection.
+ * It sizes and positions itself from the Root's rect (× media size in pixel
+ * units), moves the whole rect on pointer drag (constrained to the media
+ * bounds), and moves it with the arrow keys when focused. Carries
+ * `role="group"`, `tabindex 0`, and an overridable `aria-label`. Place
+ * `CropHandle`s and `CropGrid` inside it. Hidden (renders nothing) while the
+ * selection is empty.
+ */
+export interface CropAreaProps extends PrimitiveProps {
+  /** Accessible label for the crop region. @default 'Crop region' */
+  label?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useCropContext } from './context';
+
+const { label = 'Crop region', as = 'div' } = defineProps<CropAreaProps>();
+
+const ctx = useCropContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Position/size from the rect. In normalized units the rect is already 0..1 so
+// we emit percentages; in pixel units we map rect × media-pixel ratio so the
+// surface sits over the media regardless of its on-screen scale.
+const positionStyle = computed<{
+  position: string;
+  left: string;
+  top: string;
+  width: string;
+  height: string;
+}>(() => {
+  const r = ctx.rect.value;
+  if (r === null) return { position: 'absolute', left: '0', top: '0', width: '0', height: '0' };
+  const denomW = ctx.units.value === 'normalized' ? 1 : Math.max(ctx.mediaPixels.value.width, 1e-9);
+  const denomH = ctx.units.value === 'normalized' ? 1 : Math.max(ctx.mediaPixels.value.height, 1e-9);
+  const rtl = ctx.direction.value === 'rtl';
+  const leftPct = (rtl ? (denomW - r.x - r.width) : r.x) / denomW * 100;
+  return {
+    position: 'absolute',
+    left: `${leftPct}%`,
+    top: `${(r.y / denomH) * 100}%`,
+    width: `${(r.width / denomW) * 100}%`,
+    height: `${(r.height / denomH) * 100}%`,
+  };
+});
+
+function onPointerDown(event: PointerEvent): void {
+  if (ctx.disabled.value) return;
+  // The CropArea element is the media-aligned surface for the move projection.
+  ctx.beginMove(event, currentElement.value ?? null);
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value || ctx.rect.value === null) return;
+  const rtl = ctx.direction.value === 'rtl';
+  const stepX = event.shiftKey ? ctx.keyboardLargeStepX.value : ctx.keyboardStepX.value;
+  const stepY = event.shiftKey ? ctx.keyboardLargeStepY.value : ctx.keyboardStepY.value;
+  let dx = 0;
+  let dy = 0;
+  switch (event.key) {
+    case 'ArrowLeft':
+      dx = rtl ? stepX : -stepX;
+      break;
+    case 'ArrowRight':
+      dx = rtl ? -stepX : stepX;
+      break;
+    case 'ArrowUp':
+      dy = -stepY;
+      break;
+    case 'ArrowDown':
+      dy = stepY;
+      break;
+    default:
+      return;
+  }
+  event.preventDefault();
+  ctx.nudgeMove(dx, dy);
+}
+</script>
+
+<template>
+  <Primitive
+    v-if="ctx.rect.value !== null"
+    :ref="forwardRef"
+    :as="as"
+    role="group"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="label"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-cropping="ctx.isCropping.value ? '' : undefined"
+    :data-dir="ctx.direction.value"
+    :style="positionStyle"
+    @pointerdown="onPointerDown"
+    @keydown="onKeyDown"
+  >
+    <slot :rect="ctx.rect.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/crop/CropGrid.vue b/vue/primitives/src/canvas/crop/CropGrid.vue
new file mode 100644
index 0000000..41a4eda
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/CropGrid.vue
@@ -0,0 +1,67 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The rule-of-thirds overlay: two vertical and two horizontal guide lines drawn
+ * across the crop box at the ⅓ and ⅔ marks. Purely presentational
+ * (`aria-hidden`), it renders only when the Root's `grid` prop is enabled and a
+ * selection exists. Place it inside `CropArea`. Each line is exposed as a slot
+ * entry so the consumer can style or replace the lines; the default slot renders
+ * four absolutely-positioned `<span>`s.
+ */
+export interface CropGridProps extends PrimitiveProps {
+  /** Number of columns/rows the grid divides the box into. @default 3 */
+  divisions?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useCropContext } from './context';
+
+const { divisions = 3, as = 'div' } = defineProps<CropGridProps>();
+
+const ctx = useCropContext();
+const { forwardRef } = useForwardExpose();
+
+const visible = computed(() => ctx.grid.value && ctx.rect.value !== null);
+
+// Interior line positions as percentages of the box (e.g. 33.33%, 66.66% for
+// thirds). Endpoints (0/100) are the box edges and are omitted.
+const lines = computed(() => {
+  const out: number[] = [];
+  const n = Math.max(2, Math.round(divisions));
+  for (let i = 1; i < n; i++) out.push((i / n) * 100);
+  return out;
+});
+</script>
+
+<template>
+  <Primitive
+    v-if="visible"
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    data-crop-grid=""
+    :style="{ position: 'absolute', inset: '0', pointerEvents: 'none' }"
+  >
+    <slot :lines="lines">
+      <Primitive
+        v-for="(pct, i) in lines"
+        :key="`v-${i}`"
+        as="span"
+        data-orientation="vertical"
+        :style="{ position: 'absolute', top: '0', bottom: '0', left: `${pct}%`, width: '0' }"
+      />
+      <Primitive
+        v-for="(pct, i) in lines"
+        :key="`h-${i}`"
+        as="span"
+        data-orientation="horizontal"
+        :style="{ position: 'absolute', left: '0', right: '0', top: `${pct}%`, height: '0' }"
+      />
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/crop/CropHandle.vue b/vue/primitives/src/canvas/crop/CropHandle.vue
new file mode 100644
index 0000000..cfb346f
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/CropHandle.vue
@@ -0,0 +1,109 @@
+<script lang="ts">
+import type { CropHandlePosition } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * One of the eight resize handles — four corners and four edge midpoints. Render
+ * eight of these inside `CropArea`, one per `position`. Each is a native
+ * `<button type="button">` with an `aria-label` ("Resize top-left", etc.) and
+ * keyboard edge-resize: arrow keys move that edge/corner with the opposite edge
+ * fixed (Shift = large step), honouring aspect-ratio, min size, and bounds.
+ * Dragging resizes the same way. Positioned at its anchor on the crop box edge.
+ */
+export interface CropHandleProps extends PrimitiveProps {
+  /** Which of the eight handles this is. */
+  position: CropHandlePosition;
+  /** Accessible label override (defaults to "Resize <position>"). */
+  label?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useCropContext } from './context';
+
+const { position, label = undefined, as = 'button' } = defineProps<CropHandleProps>();
+
+const ctx = useCropContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const DEFAULT_LABELS: Record<CropHandlePosition, string> = {
+  'top-left': 'Resize top-left',
+  top: 'Resize top',
+  'top-right': 'Resize top-right',
+  right: 'Resize right',
+  'bottom-right': 'Resize bottom-right',
+  bottom: 'Resize bottom',
+  'bottom-left': 'Resize bottom-left',
+  left: 'Resize left',
+};
+
+const accessibleLabel = computed(() => label ?? DEFAULT_LABELS[position]);
+
+// Anchor the handle on the crop box edge in percentages of the box (the box is
+// the CropArea, whose 0%..100% spans the crop rect). RTL mirrors the x anchor.
+const anchorStyle = computed<{ position: string; left: string; top: string }>(() => {
+  const rtl = ctx.direction.value === 'rtl';
+  let xPct = position.includes('left') ? 0 : position.includes('right') ? 100 : 50;
+  if (rtl) xPct = 100 - xPct;
+  const yPct = position.includes('top') ? 0 : position.includes('bottom') ? 100 : 50;
+  return { position: 'absolute', left: `${xPct}%`, top: `${yPct}%` };
+});
+
+function onPointerDown(event: PointerEvent): void {
+  if (ctx.disabled.value) return;
+  ctx.beginResize(position, event, currentElement.value ?? null);
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value || ctx.rect.value === null) return;
+  const rtl = ctx.direction.value === 'rtl';
+  const stepX = event.shiftKey ? ctx.keyboardLargeStepX.value : ctx.keyboardStepX.value;
+  const stepY = event.shiftKey ? ctx.keyboardLargeStepY.value : ctx.keyboardStepY.value;
+  let dx = 0;
+  let dy = 0;
+  switch (event.key) {
+    case 'ArrowLeft':
+      dx = rtl ? stepX : -stepX;
+      break;
+    case 'ArrowRight':
+      dx = rtl ? -stepX : stepX;
+      break;
+    case 'ArrowUp':
+      dy = -stepY;
+      break;
+    case 'ArrowDown':
+      dy = stepY;
+      break;
+    default:
+      return;
+  }
+  event.preventDefault();
+  // Keep the keypress from also reaching CropArea's move handler (handles are
+  // nested inside the area, so the event would otherwise bubble and move the
+  // whole rect on top of the resize).
+  event.stopPropagation();
+  ctx.nudgeResize(position, dx, dy);
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    :aria-label="accessibleLabel"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :disabled="as === 'button' && ctx.disabled.value ? true : undefined"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-position="position"
+    :style="anchorStyle"
+    @pointerdown="onPointerDown"
+    @keydown="onKeyDown"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/crop/CropOverlay.vue b/vue/primitives/src/canvas/crop/CropOverlay.vue
new file mode 100644
index 0000000..a48dd12
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/CropOverlay.vue
@@ -0,0 +1,87 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The dimmed scrim over the media OUTSIDE the crop rectangle. Renders four
+ * absolutely-positioned rects (top / bottom / left / right of the selection) so
+ * the consumer can tint the excluded region with a single `background`.
+ * Presentational (`aria-hidden`, `pointer-events: none`). Place it as a sibling
+ * of `CropArea`, spanning the media surface. Hidden while the selection is empty.
+ * The four rects are exposed via the default slot for full styling control.
+ */
+export interface CropOverlayProps extends PrimitiveProps {}
+
+/** One scrim rect exposed via the default slot: a stable-shape inline style. */
+export interface ScrimRect {
+  key: string;
+  style: {
+    position: string;
+    left: string | undefined;
+    right: string | undefined;
+    top: string | undefined;
+    bottom: string | undefined;
+    width: string | undefined;
+    height: string | undefined;
+  };
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useCropContext } from './context';
+
+const { as = 'div' } = defineProps<CropOverlayProps>();
+
+const ctx = useCropContext();
+const { forwardRef } = useForwardExpose();
+
+// The crop rect as fractions of the media (0..1) regardless of `units`, with the
+// x axis mirrored under RTL so the scrim lines up with the visual selection.
+const frac = computed(() => {
+  const r = ctx.rect.value;
+  if (r === null) return null;
+  const denomW = ctx.units.value === 'normalized' ? 1 : Math.max(ctx.mediaPixels.value.width, 1e-9);
+  const denomH = ctx.units.value === 'normalized' ? 1 : Math.max(ctx.mediaPixels.value.height, 1e-9);
+  let left = r.x / denomW;
+  if (ctx.direction.value === 'rtl') left = (denomW - r.x - r.width) / denomW;
+  return {
+    left: left * 100,
+    top: (r.y / denomH) * 100,
+    width: (r.width / denomW) * 100,
+    height: (r.height / denomH) * 100,
+  };
+});
+
+// The four scrim rects (top, bottom, left, right of the selection). Every rect
+// emits the same key set (unused sides explicit `undefined`) so the style type
+// stays monomorphic.
+const rects = computed<ScrimRect[]>(() => {
+  const f = frac.value;
+  if (f === null) return [];
+  const right = f.left + f.width;
+  const bottom = f.top + f.height;
+  return [
+    { key: 'top', style: { position: 'absolute', left: '0', right: '0', top: '0', bottom: undefined, width: undefined, height: `${f.top}%` } },
+    { key: 'bottom', style: { position: 'absolute', left: '0', right: '0', top: `${bottom}%`, bottom: '0', width: undefined, height: undefined } },
+    { key: 'left', style: { position: 'absolute', left: '0', right: undefined, top: `${f.top}%`, bottom: undefined, width: `${f.left}%`, height: `${f.height}%` } },
+    { key: 'right', style: { position: 'absolute', left: `${right}%`, right: '0', top: `${f.top}%`, bottom: undefined, width: undefined, height: `${f.height}%` } },
+  ];
+});
+</script>
+
+<template>
+  <Primitive
+    v-if="frac !== null"
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    data-crop-overlay=""
+    :style="{ position: 'absolute', inset: '0', pointerEvents: 'none' }"
+  >
+    <slot :rects="rects">
+      <Primitive v-for="rect in rects" :key="rect.key" as="span" :data-side="rect.key" :style="rect.style" />
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/crop/CropRoot.vue b/vue/primitives/src/canvas/crop/CropRoot.vue
new file mode 100644
index 0000000..1a50834
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/CropRoot.vue
@@ -0,0 +1,392 @@
+<script lang="ts">
+import type { CropDirection, CropUnits } from './context';
+import type { CropBounds, CropHandlePosition, CropRect } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Headless crop selector rendered **over** a media element (`<img>`, `<video>`,
+ * `<canvas>`). It owns a single crop rectangle — controlled via `v-model` or
+ * uncontrolled via `defaultValue` — and drives moving, eight-handle resizing,
+ * aspect-ratio locking, a rule-of-thirds grid, and a draw-from-empty create
+ * gesture. The rect lives in NORMALIZED `0..1` fractions of the media by default
+ * (resolution-independent) or in media pixels via `units: 'pixels'`.
+ *
+ * Supply the media size with `mediaWidth`/`mediaHeight` for standalone use, or
+ * mount inside a `CanvasStageRoot` and the Root reads the stage's content size
+ * automatically (props still win when given). It provides {@link CropContext} to
+ * `CropArea`, `CropHandle`, `CropGrid`, and `CropOverlay`, and emits `cropCommit`
+ * when a gesture or keypress settles. Reach for it to let a user pick a sub-rect
+ * of an image or video (avatar crop, thumbnail framing, redaction region).
+ */
+export interface CropRootProps extends PrimitiveProps {
+  /**
+   * The crop rectangle (two-way via `v-model`). `null` means "no selection
+   * yet" — the Root falls back to the full frame or stays empty depending on
+   * `createOnEmpty`.
+   */
+  modelValue?: CropRect | null;
+  /** Uncontrolled initial rect. @default null */
+  defaultValue?: CropRect | null;
+  /** Coordinate space for the rect and the size props. @default 'normalized' */
+  units?: CropUnits;
+  /** Locked `width / height` of the crop box (visual ratio), or `null` to resize freely. @default null */
+  aspectRatio?: number | null;
+  /** Minimum crop width, in the chosen `units`. @default 0 */
+  minWidth?: number;
+  /** Minimum crop height, in the chosen `units`. @default 0 */
+  minHeight?: number;
+  /** Media width in pixels. Read from a `CanvasStage` ancestor when omitted. @default undefined */
+  mediaWidth?: number;
+  /** Media height in pixels. Read from a `CanvasStage` ancestor when omitted. @default undefined */
+  mediaHeight?: number;
+  /** Keep the rect within the media bounds. @default true */
+  constrain?: boolean;
+  /** Render the rule-of-thirds grid. @default true */
+  grid?: boolean;
+  /** Pointerdown on empty media draws a new rect from zero. @default true */
+  createOnEmpty?: boolean;
+  /** Keyboard nudge step, in normalized units (scaled to px when `units: 'pixels'`). @default 0.01 */
+  keyboardStep?: number;
+  /** Large keyboard step (Shift+Arrow). @default keyboardStep * 10 */
+  keyboardLargeStep?: number;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /** Writing direction (inherited from `ConfigProvider` when omitted). */
+  dir?: CropDirection;
+}
+
+export interface CropRootEmits {
+  /** Fired when a pointer gesture or keypress settles, with the committed rect (or `null`). */
+  cropCommit: [rect: CropRect | null];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onScopeDispose, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideCropContext } from './context';
+import { useDirection } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+import { useCanvasStageContext } from '../canvas-stage/context';
+import type { CanvasStageContext } from '../canvas-stage/context';
+import { createRect, moveRect, normalizeRect, resizeRect, resolveAspectRatio } from './utils';
+
+const {
+  defaultValue = null,
+  units = 'normalized',
+  aspectRatio = null,
+  minWidth = 0,
+  minHeight = 0,
+  mediaWidth = undefined,
+  mediaHeight = undefined,
+  constrain = true,
+  grid = true,
+  createOnEmpty = true,
+  keyboardStep = 0.01,
+  keyboardLargeStep = undefined,
+  disabled = false,
+  dir,
+  as = 'div',
+} = defineProps<CropRootProps>();
+
+const emit = defineEmits<CropRootEmits>();
+const direction = useDirection(() => dir);
+
+// Optional CanvasStage ancestor — `null` when standalone. The canvas-stage
+// factory `inject` throws when no provider exists *and* no fallback is given;
+// passing an explicit `null` fallback makes it return `null` so Crop works
+// standalone (media size then comes from the `mediaWidth`/`mediaHeight` props).
+const stage = useCanvasStageContext(null as unknown as CanvasStageContext);
+
+// Media pixel size: explicit props win; otherwise read the stage content size.
+const mediaPixels = computed<CropBounds>(() => {
+  const w = mediaWidth ?? stage?.contentSize.value.width ?? 0;
+  const h = mediaHeight ?? stage?.contentSize.value.height ?? 0;
+  return { width: w, height: h };
+});
+
+// Bounds in the rect's units: `{1,1}` normalized, real px otherwise.
+const mediaSize = computed<CropBounds>(() => {
+  if (units === 'normalized') return { width: 1, height: 1 };
+  return mediaPixels.value;
+});
+
+// Resolve the visual aspect ratio into the rect's units (normalized needs the
+// media-pixel-aspect correction so the box stays visually square/16:9/etc.).
+const resolvedRatio = computed<number | null>(() =>
+  resolveAspectRatio(aspectRatio, units, mediaPixels.value.width, mediaPixels.value.height),
+);
+
+// Scale keyboard steps into the rect's units. In pixel mode the normalized step
+// is multiplied by the media dimension on each axis.
+const largeBase = computed(() => keyboardLargeStep ?? keyboardStep * 10);
+const stepX = computed(() => (units === 'normalized' ? keyboardStep : keyboardStep * mediaPixels.value.width));
+const stepY = computed(() => (units === 'normalized' ? keyboardStep : keyboardStep * mediaPixels.value.height));
+const largeStepX = computed(() => (units === 'normalized' ? largeBase.value : largeBase.value * mediaPixels.value.width));
+const largeStepY = computed(() => (units === 'normalized' ? largeBase.value : largeBase.value * mediaPixels.value.height));
+
+function resizeOptions() {
+  return {
+    aspectRatio: resolvedRatio.value,
+    minWidth,
+    minHeight,
+    bounds: mediaSize.value,
+    constrain,
+  };
+}
+
+// ── model (controlled + uncontrolled) ─────────────────────────────────────────
+const model = defineModel<CropRect | null>();
+const seed = model.value ?? defaultValue;
+const localRect = shallowRef<CropRect | null>(
+  seed ? normalizeRect(seed, resizeOptions()) : null,
+);
+
+watch(model, (v) => {
+  if (v === undefined) return;
+  if (v === localRect.value) return;
+  localRect.value = v === null ? null : normalizeRect(v, resizeOptions());
+});
+
+// Re-settle the rect when ratio / units / bounds change (e.g. ratio set on a
+// free rect → re-fit; media measured later → clamp into the new bounds).
+watch([resolvedRatio, mediaSize, () => constrain, () => minWidth, () => minHeight], () => {
+  const r = localRect.value;
+  if (r === null) return;
+  const next = normalizeRect(r, resizeOptions());
+  if (next.x !== r.x || next.y !== r.y || next.width !== r.width || next.height !== r.height)
+    writeRect(next, false);
+});
+
+function writeRect(next: CropRect | null, commit: boolean): void {
+  localRect.value = next;
+  model.value = next;
+  if (commit) emit('cropCommit', next);
+}
+
+function setRect(next: CropRect | null): void {
+  if (disabled) return;
+  writeRect(next === null ? null : normalizeRect(next, resizeOptions()), false);
+}
+
+const isEmpty = computed(() => localRect.value === null);
+
+// ── pointer-to-units mapping ──────────────────────────────────────────────────
+// The crop surface element (a media-sized container) is the projection origin: a
+// client point maps to media-space units via the surface's rect. The stage's own
+// zoom/pan is already baked into the surface's on-screen rect, so reading
+// `getBoundingClientRect()` is correct standalone AND inside a CanvasStage — no
+// extra viewport math needed.
+let surfaceRect: DOMRect | null = null;
+
+function clientToUnits(clientX: number, clientY: number): { x: number; y: number } {
+  const r = surfaceRect;
+  if (!r || r.width === 0 || r.height === 0) return { x: 0, y: 0 };
+  let fx = (clientX - r.left) / r.width;
+  if (direction.value === 'rtl') fx = 1 - fx;
+  const fy = (clientY - r.top) / r.height;
+  if (units === 'normalized') return { x: fx, y: fy };
+  return { x: fx * mediaPixels.value.width, y: fy * mediaPixels.value.height };
+}
+
+// ── pointer gesture pipeline ──────────────────────────────────────────────────
+// A single capture pipeline handles move / resize / create. Each part calls the
+// matching `begin*` on pointerdown; the part passes the media surface element so
+// the Root can cache its rect for the client→units projection and capture the
+// pointer on it for the gesture's lifetime.
+const isCropping = shallowRef(false);
+let pointerId = -1;
+let mode: 'move' | 'resize' | 'create' | null = null;
+let activeHandle: CropHandlePosition | null = null;
+let gestureStartRect: CropRect | null = null;
+let createOrigin: { x: number; y: number } | null = null;
+let downClientX = 0;
+let downClientY = 0;
+let captureEl: HTMLElement | null = null;
+
+function setLive(next: CropRect): void {
+  localRect.value = next;
+  model.value = next;
+}
+
+function onPointerMove(event: PointerEvent): void {
+  if (event.pointerId !== pointerId) return;
+  if (!isCropping.value) isCropping.value = true;
+  if (mode === 'move' && gestureStartRect) {
+    const start = clientToUnits(downClientX, downClientY);
+    const now = clientToUnits(event.clientX, event.clientY);
+    setLive(moveRect(gestureStartRect, now.x - start.x, now.y - start.y, mediaSize.value, constrain));
+  }
+  else if (mode === 'resize' && gestureStartRect && activeHandle) {
+    const now = clientToUnits(event.clientX, event.clientY);
+    setLive(resizeRect(gestureStartRect, activeHandle, now.x, now.y, resizeOptions()));
+  }
+  else if (mode === 'create' && createOrigin) {
+    const now = clientToUnits(event.clientX, event.clientY);
+    setLive(createRect(createOrigin, now, resizeOptions()));
+  }
+}
+
+function endGesture(commit: boolean): void {
+  globalThis.removeEventListener('pointermove', onPointerMove);
+  globalThis.removeEventListener('pointerup', onPointerUp);
+  globalThis.removeEventListener('pointercancel', onPointerCancel);
+  captureEl?.releasePointerCapture?.(pointerId);
+  pointerId = -1;
+  isCropping.value = false;
+  const wasCreate = mode === 'create';
+  mode = null;
+  activeHandle = null;
+  gestureStartRect = null;
+  createOrigin = null;
+  captureEl = null;
+  // A create gesture that never grew past zero leaves no selection.
+  if (wasCreate && localRect.value && localRect.value.width === 0 && localRect.value.height === 0)
+    localRect.value = model.value = null;
+  if (commit) emit('cropCommit', localRect.value);
+}
+
+function onPointerUp(event: PointerEvent): void {
+  if (event.pointerId !== pointerId) return;
+  endGesture(true);
+}
+function onPointerCancel(event: PointerEvent): void {
+  if (event.pointerId !== pointerId) return;
+  endGesture(false);
+}
+
+// The three window listeners + pointer capture opened by `startGesture` are torn
+// down only on the pointerup/cancel that ends the gesture. If the Root unmounts
+// while a gesture is in flight (parent v-if toggles crop off, route change,
+// editor panel teardown), that end event never arrives for this scope and the
+// listeners leak — their closures retain this (now-dead) instance, its reactive
+// state and the detached capture element. Run the same teardown on scope dispose.
+onScopeDispose(() => {
+  if (pointerId !== -1) endGesture(false);
+});
+
+function startGesture(event: PointerEvent, surface: HTMLElement | null): void {
+  // The media-sized surface is the projection origin. A part may pass its own
+  // element, but the Root element (which wraps the media) is the canonical
+  // surface, so prefer it when available.
+  const projection = rootEl.value ?? surface;
+  surfaceRect = projection ? projection.getBoundingClientRect() : null;
+  pointerId = event.pointerId;
+  downClientX = event.clientX;
+  downClientY = event.clientY;
+  isCropping.value = true;
+  captureEl = (event.currentTarget as HTMLElement | null) ?? surface;
+  captureEl?.setPointerCapture?.(event.pointerId);
+  globalThis.addEventListener('pointermove', onPointerMove);
+  globalThis.addEventListener('pointerup', onPointerUp);
+  globalThis.addEventListener('pointercancel', onPointerCancel);
+}
+
+function beginMove(event: PointerEvent, surface: HTMLElement | null): void {
+  if (disabled || event.button !== 0 || localRect.value === null) return;
+  event.preventDefault();
+  mode = 'move';
+  gestureStartRect = localRect.value;
+  startGesture(event, surface);
+}
+
+function beginResize(handle: CropHandlePosition, event: PointerEvent, surface: HTMLElement | null): void {
+  if (disabled || event.button !== 0 || localRect.value === null) return;
+  event.preventDefault();
+  event.stopPropagation();
+  mode = 'resize';
+  activeHandle = handle;
+  gestureStartRect = localRect.value;
+  startGesture(event, surface);
+}
+
+function beginCreate(event: PointerEvent, surface: HTMLElement | null): void {
+  if (disabled || event.button !== 0 || !createOnEmpty || localRect.value !== null) return;
+  event.preventDefault();
+  mode = 'create';
+  const projection = rootEl.value ?? surface;
+  surfaceRect = projection ? projection.getBoundingClientRect() : null;
+  createOrigin = clientToUnits(event.clientX, event.clientY);
+  setLive({ x: createOrigin.x, y: createOrigin.y, width: 0, height: 0 });
+  startGesture(event, surface);
+}
+
+// Pointerdown landing on the Root itself (the media surface) starts a
+// draw-from-empty create when there is no selection yet. CropArea / CropHandle
+// stop propagation on their own presses, so this only fires on bare media.
+function onRootPointerDown(event: PointerEvent): void {
+  if (localRect.value !== null) return;
+  beginCreate(event, rootEl.value ?? null);
+}
+
+// ── keyboard nudges ───────────────────────────────────────────────────────────
+function nudgeMove(dx: number, dy: number): void {
+  if (disabled || localRect.value === null) return;
+  writeRect(moveRect(localRect.value, dx, dy, mediaSize.value, constrain), true);
+}
+
+function nudgeResize(handle: CropHandlePosition, dx: number, dy: number): void {
+  if (disabled || localRect.value === null) return;
+  const r = localRect.value;
+  const left = r.x;
+  const right = r.x + r.width;
+  const top = r.y;
+  const bottom = r.y + r.height;
+  const isLeft = handle === 'top-left' || handle === 'left' || handle === 'bottom-left';
+  const isRight = handle === 'top-right' || handle === 'right' || handle === 'bottom-right';
+  const isTop = handle === 'top-left' || handle === 'top' || handle === 'top-right';
+  const isBottom = handle === 'bottom-left' || handle === 'bottom' || handle === 'bottom-right';
+  // Target = the dragged handle's current position + the delta.
+  const px = isLeft ? left + dx : isRight ? right + dx : (left + right) / 2;
+  const py = isTop ? top + dy : isBottom ? bottom + dy : (top + bottom) / 2;
+  writeRect(resizeRect(r, handle, px, py, resizeOptions()), true);
+}
+
+provideCropContext({
+  rect: localRect,
+  isEmpty,
+  units: toRef(() => units),
+  direction,
+  mediaSize,
+  mediaPixels,
+  constrain: toRef(() => constrain),
+  grid: toRef(() => grid),
+  disabled: toRef(() => disabled),
+  aspectRatio: resolvedRatio,
+  minWidth: toRef(() => minWidth),
+  minHeight: toRef(() => minHeight),
+  keyboardStepX: stepX,
+  keyboardStepY: stepY,
+  keyboardLargeStepX: largeStepX,
+  keyboardLargeStepY: largeStepY,
+  isCropping,
+  setRect,
+  nudgeMove,
+  nudgeResize,
+  beginMove,
+  beginResize,
+  beginCreate,
+});
+
+defineExpose({ rect: localRect, isEmpty, setRect });
+
+// `defineExpose` precedes `useForwardExpose` so the composable merges the prior
+// bindings instead of clobbering them. `currentElement` is the rendered Root —
+// the media-sized surface every gesture projects against.
+const { forwardRef, currentElement: rootEl } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :dir="direction"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-empty="isEmpty ? '' : undefined"
+    :data-cropping="isCropping ? '' : undefined"
+    @pointerdown="onRootPointerDown"
+  >
+    <slot :rect="localRect" :is-empty="isEmpty" :is-cropping="isCropping" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/crop/__test__/Crop.test.ts b/vue/primitives/src/canvas/crop/__test__/Crop.test.ts
new file mode 100644
index 0000000..982ee7a
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/__test__/Crop.test.ts
@@ -0,0 +1,253 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { CropRect } from '../utils';
+import { CROP_HANDLE_POSITIONS } from '../utils';
+import { CropArea, CropGrid, CropHandle, CropOverlay, CropRoot } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+/** Mount a full crop with all parts. The Root is sized so its rect is well-defined. */
+function mountCrop(opts: Record<string, unknown> = {}, initial: CropRect | null = { x: 0.2, y: 0.2, width: 0.4, height: 0.4 }) {
+  const model = ref<CropRect | null>(initial);
+  const committed = ref<CropRect | null | undefined>(undefined);
+  const Harness = defineComponent({
+    setup() {
+      const props: Record<string, unknown> = {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: CropRect | null) => { model.value = v; },
+        onCropCommit: (v: CropRect | null) => { committed.value = v; },
+        style: { position: 'relative', width: '400px', height: '300px' },
+        ...opts,
+      };
+      return () => h(CropRoot, props, {
+        default: () => [
+          h(CropOverlay),
+          h(CropArea, null, {
+            default: () => [
+              h(CropGrid),
+              ...CROP_HANDLE_POSITIONS.map(position => h(CropHandle, { position, key: position })),
+            ],
+          }),
+        ],
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model, committed };
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false }));
+}
+
+function pointer(type: string, el: Element, x: number, y: number, id = 1): void {
+  el.dispatchEvent(new PointerEvent(type, { pointerId: id, clientX: x, clientY: y, button: 0, bubbles: true, cancelable: true }));
+}
+
+describe('CropArea', () => {
+  it('has role="group", is focusable, and carries an aria-label', async () => {
+    mountCrop();
+    await nextTick();
+    const area = document.querySelector<HTMLElement>('[role="group"]')!;
+    expect(area).toBeTruthy();
+    expect(area.tabIndex).toBe(0);
+    expect(area.getAttribute('aria-label')).toBe('Crop region');
+  });
+
+  it('renders nothing while the selection is empty', async () => {
+    mountCrop({}, null);
+    await nextTick();
+    expect(document.querySelector('[role="group"]')).toBeNull();
+  });
+});
+
+describe('CropHandle', () => {
+  it('renders 8 handle buttons each with an aria-label', async () => {
+    mountCrop();
+    await nextTick();
+    const handles = Array.from(document.querySelectorAll<HTMLElement>('[data-position]'));
+    expect(handles).toHaveLength(8);
+    for (const h of handles) {
+      expect(h.tagName.toLowerCase()).toBe('button');
+      expect(h.getAttribute('type')).toBe('button');
+      expect(h.getAttribute('aria-label')).toMatch(/^Resize /);
+    }
+  });
+});
+
+describe('keyboard — CropArea moves the rect', () => {
+  it('ArrowRight/ArrowDown nudge the whole rect by keyboardStep', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.05 });
+    await nextTick();
+    const area = document.querySelector<HTMLElement>('[role="group"]')!;
+    keydown(area, 'ArrowRight');
+    await nextTick();
+    expect(model.value!.x).toBeCloseTo(0.25, 6);
+    keydown(area, 'ArrowDown');
+    await nextTick();
+    expect(model.value!.y).toBeCloseTo(0.25, 6);
+    // Size is unchanged by a move.
+    expect(model.value!.width).toBeCloseTo(0.4, 6);
+  });
+
+  it('clamps to [0,1] at the media edge', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.5 });
+    await nextTick();
+    const area = document.querySelector<HTMLElement>('[role="group"]')!;
+    keydown(area, 'ArrowRight');
+    keydown(area, 'ArrowRight');
+    keydown(area, 'ArrowRight');
+    await nextTick();
+    expect(model.value!.x + model.value!.width).toBeLessThanOrEqual(1 + 1e-9);
+  });
+
+  it('Shift+Arrow uses the large step', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.01, keyboardLargeStep: 0.1 });
+    await nextTick();
+    const area = document.querySelector<HTMLElement>('[role="group"]')!;
+    keydown(area, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(model.value!.x).toBeCloseTo(0.3, 6);
+  });
+});
+
+describe('keyboard — CropHandle resizes with the opposite edge fixed', () => {
+  it('ArrowRight on the right handle widens, left edge stays put', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.05 });
+    await nextTick();
+    const right = document.querySelector<HTMLElement>('[data-position="right"]')!;
+    const before = { ...model.value! };
+    keydown(right, 'ArrowRight');
+    await nextTick();
+    expect(model.value!.x).toBeCloseTo(before.x, 6); // left fixed
+    expect(model.value!.width).toBeCloseTo(before.width + 0.05, 6);
+  });
+
+  it('ArrowLeft on the left handle keeps the right edge fixed', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.05 });
+    await nextTick();
+    const left = document.querySelector<HTMLElement>('[data-position="left"]')!;
+    const rightEdge = model.value!.x + model.value!.width;
+    keydown(left, 'ArrowLeft');
+    await nextTick();
+    expect(model.value!.x + model.value!.width).toBeCloseTo(rightEdge, 6);
+    expect(model.value!.x).toBeLessThan(0.2);
+  });
+});
+
+describe('aspectRatio keeps the ratio on keyboard resize', () => {
+  it('a corner nudge preserves width/height', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.05, aspectRatio: 1, units: 'pixels', mediaWidth: 400, mediaHeight: 400 }, { x: 100, y: 100, width: 100, height: 100 });
+    await nextTick();
+    const corner = document.querySelector<HTMLElement>('[data-position="bottom-right"]')!;
+    keydown(corner, 'ArrowRight');
+    await nextTick();
+    expect(model.value!.width / model.value!.height).toBeCloseTo(1, 6);
+  });
+});
+
+describe('constrain clamps the rect within bounds', () => {
+  it('a handle drag past the edge keeps the rect inside the media', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.5 });
+    await nextTick();
+    const corner = document.querySelector<HTMLElement>('[data-position="bottom-right"]')!;
+    keydown(corner, 'ArrowRight');
+    keydown(corner, 'ArrowDown');
+    keydown(corner, 'ArrowRight');
+    keydown(corner, 'ArrowDown');
+    await nextTick();
+    expect(model.value!.x + model.value!.width).toBeLessThanOrEqual(1 + 1e-9);
+    expect(model.value!.y + model.value!.height).toBeLessThanOrEqual(1 + 1e-9);
+  });
+});
+
+describe('createOnEmpty draws from null', () => {
+  it('a pointer drag on empty media creates a rect', async () => {
+    const { model } = mountCrop({ keyboardStep: 0.05 }, null);
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-empty]')!;
+    const rect = root.getBoundingClientRect();
+    expect(model.value).toBeNull();
+    // Press near the top-left quarter, drag toward the centre.
+    pointer('pointerdown', root, rect.left + rect.width * 0.25, rect.top + rect.height * 0.25);
+    pointer('pointermove', document.body, rect.left + rect.width * 0.75, rect.top + rect.height * 0.75);
+    pointer('pointerup', document.body, rect.left + rect.width * 0.75, rect.top + rect.height * 0.75);
+    await nextTick();
+    expect(model.value).not.toBeNull();
+    expect(model.value!.width).toBeGreaterThan(0.3);
+    expect(model.value!.height).toBeGreaterThan(0.3);
+  });
+
+  it('does not create when createOnEmpty is false', async () => {
+    const { model } = mountCrop({ createOnEmpty: false }, null);
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-empty]')!;
+    const rect = root.getBoundingClientRect();
+    pointer('pointerdown', root, rect.left + 10, rect.top + 10);
+    pointer('pointermove', document.body, rect.left + 100, rect.top + 100);
+    pointer('pointerup', document.body, rect.left + 100, rect.top + 100);
+    await nextTick();
+    expect(model.value).toBeNull();
+  });
+});
+
+describe('disabled blocks interaction', () => {
+  it('arrow keys do nothing when disabled', async () => {
+    const { model } = mountCrop({ disabled: true, keyboardStep: 0.05 });
+    await nextTick();
+    const area = document.querySelector<HTMLElement>('[role="group"]')!;
+    expect(area.getAttribute('aria-disabled')).toBe('true');
+    const before = { ...model.value! };
+    keydown(area, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toEqual(before);
+  });
+
+  it('handle buttons are disabled', async () => {
+    mountCrop({ disabled: true });
+    await nextTick();
+    const handle = document.querySelector<HTMLButtonElement>('[data-position="right"]')!;
+    expect(handle.disabled).toBe(true);
+  });
+});
+
+describe('CropGrid', () => {
+  it('renders the rule-of-thirds lines (2 vertical + 2 horizontal) when grid is on', async () => {
+    mountCrop();
+    await nextTick();
+    const grid = document.querySelector<HTMLElement>('[data-crop-grid]')!;
+    expect(grid).toBeTruthy();
+    expect(grid.getAttribute('aria-hidden')).toBe('true');
+    expect(grid.querySelectorAll('[data-orientation="vertical"]')).toHaveLength(2);
+    expect(grid.querySelectorAll('[data-orientation="horizontal"]')).toHaveLength(2);
+  });
+
+  it('is absent when grid is disabled', async () => {
+    mountCrop({ grid: false });
+    await nextTick();
+    expect(document.querySelector('[data-crop-grid]')).toBeNull();
+  });
+});
+
+describe('CropOverlay', () => {
+  it('renders 4 scrim rects (aria-hidden) when a selection exists', async () => {
+    mountCrop();
+    await nextTick();
+    const overlay = document.querySelector<HTMLElement>('[data-crop-overlay]')!;
+    expect(overlay).toBeTruthy();
+    expect(overlay.getAttribute('aria-hidden')).toBe('true');
+    expect(overlay.querySelectorAll('[data-side]')).toHaveLength(4);
+  });
+});
diff --git a/vue/primitives/src/canvas/crop/__test__/utils.test.ts b/vue/primitives/src/canvas/crop/__test__/utils.test.ts
new file mode 100644
index 0000000..210a961
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/__test__/utils.test.ts
@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest';
+import type { CropBounds, CropRect } from '../utils';
+import {
+  createRect,
+  fitRectToRatio,
+  minBox,
+  moveRect,
+  normalizeRect,
+  resizeRect,
+  resolveAspectRatio,
+} from '../utils';
+
+const UNIT: CropBounds = { width: 1, height: 1 };
+
+function opts(over: Partial<{ aspectRatio: number | null; minWidth: number; minHeight: number; bounds: CropBounds; constrain: boolean }> = {}) {
+  return {
+    aspectRatio: null,
+    minWidth: 0,
+    minHeight: 0,
+    bounds: UNIT,
+    constrain: true,
+    ...over,
+  };
+}
+
+describe('minBox — min + ratio conflict', () => {
+  it('returns the raw mins with no ratio', () => {
+    expect(minBox(0.2, 0.3, null)).toEqual({ width: 0.2, height: 0.3 });
+  });
+
+  it('grows the binding dimension so BOTH mins are satisfied (ratio > mins imply width grows)', () => {
+    // ratio 2 (w = 2h). minWidth 0.2, minHeight 0.3 → height-min forces w >= 0.6.
+    const box = minBox(0.2, 0.3, 2);
+    expect(box.width).toBeCloseTo(0.6, 6);
+    expect(box.height).toBeCloseTo(0.3, 6);
+    // Ratio is exactly held.
+    expect(box.width / box.height).toBeCloseTo(2, 6);
+  });
+
+  it('picks width-min as binding when it forces the larger box', () => {
+    // ratio 2. minWidth 0.8 dominates (0.8 > 2*0.3=0.6).
+    const box = minBox(0.8, 0.3, 2);
+    expect(box.width).toBeCloseTo(0.8, 6);
+    expect(box.height).toBeCloseTo(0.4, 6);
+    expect(box.width / box.height).toBeCloseTo(2, 6);
+  });
+});
+
+describe('moveRect', () => {
+  const rect: CropRect = { x: 0.2, y: 0.2, width: 0.4, height: 0.4 };
+
+  it('translates without changing size', () => {
+    const out = moveRect(rect, 0.1, -0.05, UNIT, false);
+    expect(out.x).toBeCloseTo(0.3, 6);
+    expect(out.y).toBeCloseTo(0.15, 6);
+    expect(out.width).toBeCloseTo(0.4, 6);
+    expect(out.height).toBeCloseTo(0.4, 6);
+  });
+
+  it('clamps within bounds when constrained', () => {
+    const out = moveRect(rect, 1, 1, UNIT, true);
+    // Can't go past 1 - width.
+    expect(out.x).toBeCloseTo(0.6, 6);
+    expect(out.y).toBeCloseTo(0.6, 6);
+    expect(out.width).toBeCloseTo(0.4, 6);
+  });
+});
+
+describe('resizeRect — free resize keeps the opposite edge fixed', () => {
+  const rect: CropRect = { x: 0.2, y: 0.2, width: 0.4, height: 0.4 }; // right=0.6, bottom=0.6
+
+  it('drags the left edge, right edge stays put', () => {
+    const out = resizeRect(rect, 'left', 0.1, 0.2, opts());
+    expect(out.x).toBeCloseTo(0.1, 6);
+    expect(out.x + out.width).toBeCloseTo(0.6, 6); // right fixed
+  });
+
+  it('drags the bottom-right corner, top-left stays put', () => {
+    const out = resizeRect(rect, 'bottom-right', 0.9, 0.8, opts());
+    expect(out.x).toBeCloseTo(0.2, 6); // left fixed
+    expect(out.y).toBeCloseTo(0.2, 6); // top fixed
+    expect(out.x + out.width).toBeCloseTo(0.9, 6);
+    expect(out.y + out.height).toBeCloseTo(0.8, 6);
+  });
+});
+
+describe('resizeRect — aspect ratio', () => {
+  const rect: CropRect = { x: 0.2, y: 0.2, width: 0.2, height: 0.2 };
+
+  it('keeps the ratio on a corner drag', () => {
+    const out = resizeRect(rect, 'bottom-right', 0.8, 0.5, opts({ aspectRatio: 1 }));
+    expect(out.width / out.height).toBeCloseTo(1, 6);
+  });
+
+  it('adjusts the paired dimension on an edge drag (right → height follows)', () => {
+    const out = resizeRect(rect, 'right', 0.6, 0.3, opts({ aspectRatio: 2 }));
+    expect(out.width / out.height).toBeCloseTo(2, 6);
+  });
+});
+
+describe('resizeRect — constrain clamps into bounds while holding ratio', () => {
+  it('a corner drag past the media edge clamps and preserves the ratio', () => {
+    const rect: CropRect = { x: 0.5, y: 0.5, width: 0.2, height: 0.2 };
+    const out = resizeRect(rect, 'bottom-right', 2, 2, opts({ aspectRatio: 1, constrain: true }));
+    expect(out.x + out.width).toBeLessThanOrEqual(1 + 1e-9);
+    expect(out.y + out.height).toBeLessThanOrEqual(1 + 1e-9);
+    expect(out.width / out.height).toBeCloseTo(1, 6);
+  });
+
+  it('free corner drag past the edge clamps the dimension', () => {
+    const rect: CropRect = { x: 0.2, y: 0.2, width: 0.2, height: 0.2 };
+    const out = resizeRect(rect, 'bottom-right', 2, 2, opts({ constrain: true }));
+    expect(out.x + out.width).toBeLessThanOrEqual(1 + 1e-9);
+    expect(out.y + out.height).toBeLessThanOrEqual(1 + 1e-9);
+  });
+
+  it('never shrinks below the combined min box', () => {
+    const rect: CropRect = { x: 0.4, y: 0.4, width: 0.2, height: 0.2 };
+    const out = resizeRect(rect, 'top-left', 0.59, 0.59, opts({ minWidth: 0.1, minHeight: 0.1 }));
+    expect(out.width).toBeGreaterThanOrEqual(0.1 - 1e-9);
+    expect(out.height).toBeGreaterThanOrEqual(0.1 - 1e-9);
+  });
+});
+
+describe('fitRectToRatio', () => {
+  it('re-fits a free rect to the ratio about its centre and clamps into bounds', () => {
+    const rect: CropRect = { x: 0.1, y: 0.1, width: 0.8, height: 0.4 };
+    const out = fitRectToRatio(rect, 1, UNIT, 0, 0);
+    expect(out.width / out.height).toBeCloseTo(1, 6);
+    expect(out.x).toBeGreaterThanOrEqual(-1e-9);
+    expect(out.y).toBeGreaterThanOrEqual(-1e-9);
+    expect(out.x + out.width).toBeLessThanOrEqual(1 + 1e-9);
+    expect(out.y + out.height).toBeLessThanOrEqual(1 + 1e-9);
+  });
+});
+
+describe('createRect — draw from empty', () => {
+  it('draws a rect from the pointerdown origin to the current point', () => {
+    const out = createRect({ x: 0.2, y: 0.3 }, { x: 0.6, y: 0.7 }, opts());
+    expect(out.x).toBeCloseTo(0.2, 6);
+    expect(out.y).toBeCloseTo(0.3, 6);
+    expect(out.width).toBeCloseTo(0.4, 6);
+    expect(out.height).toBeCloseTo(0.4, 6);
+  });
+
+  it('normalises a backwards drag (point above/left of origin)', () => {
+    const out = createRect({ x: 0.6, y: 0.7 }, { x: 0.2, y: 0.3 }, opts());
+    expect(out.x).toBeCloseTo(0.2, 6);
+    expect(out.y).toBeCloseTo(0.3, 6);
+    expect(out.width).toBeCloseTo(0.4, 6);
+    expect(out.height).toBeCloseTo(0.4, 6);
+  });
+});
+
+describe('normalizeRect', () => {
+  it('clamps an out-of-bounds rect inside the media', () => {
+    const out = normalizeRect({ x: 0.8, y: 0.8, width: 0.5, height: 0.5 }, opts({ constrain: true }));
+    expect(out.x + out.width).toBeLessThanOrEqual(1 + 1e-9);
+    expect(out.y + out.height).toBeLessThanOrEqual(1 + 1e-9);
+  });
+
+  it('enforces the min size', () => {
+    const out = normalizeRect({ x: 0.4, y: 0.4, width: 0.01, height: 0.01 }, opts({ minWidth: 0.1, minHeight: 0.1 }));
+    expect(out.width).toBeGreaterThanOrEqual(0.1 - 1e-9);
+    expect(out.height).toBeGreaterThanOrEqual(0.1 - 1e-9);
+  });
+});
+
+describe('resolveAspectRatio', () => {
+  it('returns the ratio unchanged in pixel units', () => {
+    expect(resolveAspectRatio(2, 'pixels', 800, 600)).toBe(2);
+  });
+
+  it('corrects for the media pixel-aspect in normalized units', () => {
+    // visual 1:1 on a 2:1 media → normalized w/h = 1 * (h/w) = 0.5.
+    expect(resolveAspectRatio(1, 'normalized', 2, 1)).toBeCloseTo(0.5, 6);
+  });
+
+  it('passes through null', () => {
+    expect(resolveAspectRatio(null, 'normalized', 100, 100)).toBeNull();
+  });
+});
diff --git a/vue/primitives/src/canvas/crop/context.ts b/vue/primitives/src/canvas/crop/context.ts
new file mode 100644
index 0000000..77b8c4b
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/context.ts
@@ -0,0 +1,73 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { CropBounds, CropHandlePosition, CropRect } from './utils';
+
+export type CropUnits = 'normalized' | 'pixels';
+export type CropDirection = 'ltr' | 'rtl';
+
+/**
+ * Context shared between `CropRoot` and its parts (`CropArea`, `CropHandle`,
+ * `CropGrid`, `CropOverlay`). The Root owns the rect and the gesture engines;
+ * every part reads the live rect and asks the Root to begin a gesture or nudge
+ * the rect via the keyboard.
+ *
+ * Scalar props are exposed as plain `Ref<T>` built with `toRef(() => prop)` (a
+ * reactive getter ref without a `ReactiveEffect`) for identity passthrough,
+ * mirroring the slider convention.
+ */
+export interface CropContext {
+  /** The live crop rect in the chosen `units`, or `null` when there is no selection. */
+  rect: Ref<CropRect | null>;
+  /** Whether `rect` is `null` (no selection yet). */
+  isEmpty: Ref<boolean>;
+  /** The active coordinate space. */
+  units: Ref<CropUnits>;
+  /** Reading direction (affects arrow-key x sign). */
+  direction: Ref<CropDirection>;
+  /** Media bounds in the rect's units (`{1,1}` normalized, media px otherwise). */
+  mediaSize: Ref<CropBounds>;
+  /** Media size in pixels — always real px regardless of `units` (for layout). */
+  mediaPixels: Ref<CropBounds>;
+  /** Whether the rect is kept within the media bounds. */
+  constrain: Ref<boolean>;
+  /** Whether the rule-of-thirds grid is enabled. */
+  grid: Ref<boolean>;
+  /** Master interactivity switch. */
+  disabled: Ref<boolean>;
+  /** Resolved `width / height` lock in the rect's units, or `null` when free. */
+  aspectRatio: Ref<number | null>;
+  /** Minimum width in the rect's units. */
+  minWidth: Ref<number>;
+  /** Minimum height in the rect's units. */
+  minHeight: Ref<number>;
+  /** Keyboard nudge step on the x axis, in the rect's units. */
+  keyboardStepX: Ref<number>;
+  /** Keyboard nudge step on the y axis, in the rect's units. */
+  keyboardStepY: Ref<number>;
+  /** Large keyboard nudge step (Shift+Arrow) on the x axis, in the rect's units. */
+  keyboardLargeStepX: Ref<number>;
+  /** Large keyboard nudge step (Shift+Arrow) on the y axis, in the rect's units. */
+  keyboardLargeStepY: Ref<number>;
+  /** Whether a pointer gesture is currently in progress. */
+  isCropping: Ref<boolean>;
+  /** Replace the rect wholesale (the value is normalised by the Root). */
+  setRect: (rect: CropRect | null) => void;
+  /** Move the whole rect by a delta in the rect's units, clamped + committed. */
+  nudgeMove: (dx: number, dy: number) => void;
+  /** Resize an edge/corner by a delta in the rect's units, clamped + committed. */
+  nudgeResize: (handle: CropHandlePosition, dx: number, dy: number) => void;
+  /** Begin a pointer move gesture on the crop surface. */
+  beginMove: (event: PointerEvent, surface: HTMLElement | null) => void;
+  /** Begin a pointer resize gesture for `handle`. */
+  beginResize: (handle: CropHandlePosition, event: PointerEvent, el: HTMLElement | null) => void;
+  /** Begin a draw-from-empty create gesture on the media surface. */
+  beginCreate: (event: PointerEvent, surface: HTMLElement | null) => void;
+}
+
+const context = useContextFactory<CropContext>('CropContext');
+
+/** Provide the {@link CropContext} to descendants of `CropRoot`. */
+export const provideCropContext = context.provide;
+
+/** Inject the {@link CropContext}. Throws when used outside a `CropRoot`. */
+export const useCropContext = context.inject;
diff --git a/vue/primitives/src/canvas/crop/demo.vue b/vue/primitives/src/canvas/crop/demo.vue
new file mode 100644
index 0000000..c7be918
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/demo.vue
@@ -0,0 +1,132 @@
+<script setup lang="ts">
+import {
+  CROP_HANDLE_POSITIONS,
+  CropArea,
+  CropGrid,
+  CropHandle,
+  CropOverlay,
+  CropRoot,
+} from '@robonen/primitives';
+import type { CropRect } from '@robonen/primitives';
+import { ref } from 'vue';
+
+// Normalized rect: x / y / width / height are fractions 0..1 of the photo.
+const crop = ref<CropRect>({ x: 0.18, y: 0.16, width: 0.5, height: 0.5 });
+
+// Aspect-ratio lock variants (width / height of the visual box). null = free.
+const ratios = [
+  { label: 'Free', value: null },
+  { label: '1:1', value: 1 },
+  { label: '16:9', value: 16 / 9 },
+  { label: '4:5', value: 4 / 5 },
+] as const;
+const ratio = ref<number | null>(null);
+
+const pct = (n: number) => Math.round(n * 100);
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-xl space-y-4 p-6 text-fg">
+    <div class="flex flex-wrap items-center justify-between gap-3">
+      <div>
+        <h3 class="text-sm font-semibold">Crop</h3>
+        <p class="text-xs text-fg-muted">Drag the region to move, the squares to resize. Rule-of-thirds grid + dimmed surround.</p>
+      </div>
+
+      <!-- Aspect-ratio variant switch -->
+      <div class="flex items-center gap-1 rounded-lg border border-border bg-bg-inset p-0.5">
+        <button
+          v-for="opt in ratios"
+          :key="opt.label"
+          type="button"
+          class="rounded-md px-2 py-1 text-xs font-medium transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          :class="ratio === opt.value ? 'bg-accent text-accent-fg shadow-sm' : 'text-fg-muted hover:text-fg'"
+          @click="ratio = opt.value"
+        >
+          {{ opt.label }}
+        </button>
+      </div>
+    </div>
+
+    <!-- The photo: CropRoot is the media-sized, positioned surface laid over it. -->
+    <CropRoot
+      v-model="crop"
+      :aspect-ratio="ratio"
+      :media-width="640"
+      :media-height="420"
+      :min-width="0.1"
+      :min-height="0.1"
+      class="relative aspect-[640/420] w-full select-none overflow-hidden rounded-card border border-border outline-none"
+      style="background: linear-gradient(115deg, oklch(0.7 0.16 200) 0%, oklch(0.66 0.2 285) 45%, oklch(0.74 0.18 25) 100%);"
+    >
+      <!-- Decorative 'subject' so the crop has something to frame. -->
+      <div
+        class="pointer-events-none absolute left-[42%] top-[34%] h-28 w-28 rounded-full opacity-90 blur-[2px]"
+        style="background: radial-gradient(circle at 35% 30%, oklch(0.96 0.05 95) 0%, oklch(0.82 0.16 80) 55%, transparent 72%);"
+      />
+
+      <!-- Dimmed scrim over everything OUTSIDE the crop rect (four sibling rects). -->
+      <CropOverlay>
+        <template #default="{ rects }">
+          <span
+            v-for="rect in rects"
+            :key="rect.key"
+            :style="rect.style"
+            class="bg-black/55 backdrop-saturate-50"
+          />
+        </template>
+      </CropOverlay>
+
+      <!-- The crop rectangle: draggable body + handles + grid. -->
+      <CropArea class="absolute cursor-move outline-none ring-1 ring-bg/30 focus-visible:ring-2 focus-visible:ring-ring">
+        <!-- Selection border -->
+        <span class="pointer-events-none absolute inset-0 border border-bg/90 shadow-[0_0_0_1px_oklch(0_0_0/0.25)]" />
+
+        <!-- Rule-of-thirds grid lines -->
+        <CropGrid>
+          <template #default="{ lines }">
+            <span
+              v-for="(p, i) in lines"
+              :key="`v-${i}`"
+              class="absolute bottom-0 top-0 w-px bg-bg/50"
+              :style="{ left: `${p}%` }"
+            />
+            <span
+              v-for="(p, i) in lines"
+              :key="`h-${i}`"
+              class="absolute left-0 right-0 h-px bg-bg/50"
+              :style="{ top: `${p}%` }"
+            />
+          </template>
+        </CropGrid>
+
+        <!-- Eight resize handles as small accent squares on the corners + edges. -->
+        <CropHandle
+          v-for="pos in CROP_HANDLE_POSITIONS"
+          :key="pos"
+          :position="pos"
+          class="block h-3 w-3 -translate-x-1/2 -translate-y-1/2 rounded-[2px] border border-bg bg-accent shadow-sm outline-none transition hover:scale-125 focus-visible:ring-2 focus-visible:ring-ring"
+          :class="pos === 'left' || pos === 'right' ? 'cursor-ew-resize' : pos === 'top' || pos === 'bottom' ? 'cursor-ns-resize' : pos === 'top-left' || pos === 'bottom-right' ? 'cursor-nwse-resize' : 'cursor-nesw-resize'"
+        />
+      </CropArea>
+    </CropRoot>
+
+    <!-- Normalized crop rect readout. -->
+    <dl class="grid grid-cols-4 gap-2 text-center">
+      <div v-for="item in [
+        { label: 'X', value: `${pct(crop.x)}%` },
+        { label: 'Y', value: `${pct(crop.y)}%` },
+        { label: 'W', value: `${pct(crop.width)}%` },
+        { label: 'H', value: `${pct(crop.height)}%` },
+      ]" :key="item.label" class="rounded-md border border-border bg-bg-inset py-1.5">
+        <dt class="text-[10px] font-medium uppercase tracking-wide text-fg-subtle">{{ item.label }}</dt>
+        <dd class="font-mono text-sm text-fg">{{ item.value }}</dd>
+      </div>
+    </dl>
+
+    <p class="text-xs text-fg-subtle">
+      Values are normalized fractions of the photo. Focus the region or a handle and use arrow keys
+      (<kbd class="rounded border border-border bg-bg px-1 font-mono">Shift</kbd> for larger steps).
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/crop/index.ts b/vue/primitives/src/canvas/crop/index.ts
new file mode 100644
index 0000000..0b27c90
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/index.ts
@@ -0,0 +1,26 @@
+export { default as CropRoot } from './CropRoot.vue';
+export { default as CropArea } from './CropArea.vue';
+export { default as CropGrid } from './CropGrid.vue';
+export { default as CropHandle } from './CropHandle.vue';
+export { default as CropOverlay } from './CropOverlay.vue';
+
+export { provideCropContext, useCropContext } from './context';
+export type { CropContext, CropDirection, CropUnits } from './context';
+
+export type { CropAreaProps } from './CropArea.vue';
+export type { CropGridProps } from './CropGrid.vue';
+export type { CropHandleProps } from './CropHandle.vue';
+export type { CropOverlayProps } from './CropOverlay.vue';
+export type { CropRootEmits, CropRootProps } from './CropRoot.vue';
+
+export type { CropBounds, CropHandlePosition, CropRect } from './utils';
+export {
+  CROP_HANDLE_POSITIONS,
+  createRect,
+  fitRectToRatio,
+  minBox,
+  moveRect,
+  normalizeRect,
+  resizeRect,
+  resolveAspectRatio,
+} from './utils';
diff --git a/vue/primitives/src/canvas/crop/utils.ts b/vue/primitives/src/canvas/crop/utils.ts
new file mode 100644
index 0000000..da39336
--- /dev/null
+++ b/vue/primitives/src/canvas/crop/utils.ts
@@ -0,0 +1,441 @@
+import type { Point } from '../../internal/utils/geometry';
+
+/**
+ * An axis-aligned crop rectangle. Lives in whatever coordinate space the
+ * consumer chose via the `units` prop on `CropRoot`:
+ * - `'normalized'` (default): `x`/`y`/`width`/`height` are fractions `0..1` of
+ *   the media, so the rect is resolution-independent.
+ * - `'pixels'`: the same fields are media-space pixels.
+ *
+ * The pure helpers in this module operate in a single, consistent space — the
+ * caller picks one and stays in it. They never mix units.
+ */
+export interface CropRect {
+  /** Left edge. */
+  x: number;
+  /** Top edge. */
+  y: number;
+  /** Rectangle width (always `>= 0`). */
+  width: number;
+  /** Rectangle height (always `>= 0`). */
+  height: number;
+}
+
+/**
+ * The eight resize handles of a crop rectangle: four corners and four edge
+ * midpoints. Corner handles move two edges, edge handles move one.
+ */
+export type CropHandlePosition
+  = | 'top-left'
+    | 'top'
+    | 'top-right'
+    | 'right'
+    | 'bottom-right'
+    | 'bottom'
+    | 'bottom-left'
+    | 'left';
+
+/** The media bounds the crop is clamped against, in the rect's own units. */
+export interface CropBounds {
+  /** Media width (`1` in normalized units, media pixels otherwise). */
+  width: number;
+  /** Media height (`1` in normalized units, media pixels otherwise). */
+  height: number;
+}
+
+/** All eight handle positions in a stable, clockwise-from-top-left order. */
+export const CROP_HANDLE_POSITIONS: readonly CropHandlePosition[] = [
+  'top-left',
+  'top',
+  'top-right',
+  'right',
+  'bottom-right',
+  'bottom',
+  'bottom-left',
+  'left',
+] as const;
+
+/** Whether a handle moves the top edge. */
+function movesTop(h: CropHandlePosition): boolean {
+  return h === 'top-left' || h === 'top' || h === 'top-right';
+}
+/** Whether a handle moves the bottom edge. */
+function movesBottom(h: CropHandlePosition): boolean {
+  return h === 'bottom-left' || h === 'bottom' || h === 'bottom-right';
+}
+/** Whether a handle moves the left edge. */
+function movesLeft(h: CropHandlePosition): boolean {
+  return h === 'top-left' || h === 'left' || h === 'bottom-left';
+}
+/** Whether a handle moves the right edge. */
+function movesRight(h: CropHandlePosition): boolean {
+  return h === 'top-right' || h === 'right' || h === 'bottom-right';
+}
+
+/** Clamp `n` into `[lo, hi]`. (Local copy — keeps `utils.ts` dependency-free.) */
+function clamp(n: number, lo: number, hi: number): number {
+  return n < lo ? lo : n > hi ? hi : n;
+}
+
+/**
+ * The smallest box (in the rect's units) that satisfies BOTH `minWidth`/
+ * `minHeight` AND, when `aspectRatio` is set, the ratio. The binding constraint
+ * is whichever forces the larger box — so a tall ratio grows the width to keep
+ * the height-min legal, and vice versa. The crop must never shrink past this.
+ *
+ * @param minWidth Minimum width in the rect's units (`>= 0`).
+ * @param minHeight Minimum height in the rect's units (`>= 0`).
+ * @param aspectRatio Locked `width / height`, or `null` for free resize.
+ */
+export function minBox(
+  minWidth: number,
+  minHeight: number,
+  aspectRatio: number | null,
+): { width: number; height: number } {
+  const mw = Math.max(0, minWidth);
+  const mh = Math.max(0, minHeight);
+  if (aspectRatio === null || !(aspectRatio > 0) || !Number.isFinite(aspectRatio))
+    return { width: mw, height: mh };
+  // Grow whichever dimension is too small to honour the ratio about the other.
+  // width = ratio * height. Pick the larger of (mw, ratio*mh) for the width, then
+  // derive the matching height so both minimums are met.
+  const widthFromHeight = aspectRatio * mh;
+  const width = Math.max(mw, widthFromHeight);
+  const height = width / aspectRatio;
+  return { width, height };
+}
+
+/**
+ * Re-fit an existing rect to `aspectRatio` about its centre (used when the
+ * ratio is set/changed on a free rect), then clamp the result into `bounds`.
+ * The area is preserved as closely as possible: the new box is the
+ * ratio-correct rect whose area matches the old one, centred on the old centre.
+ *
+ * @param rect The current (free) rectangle.
+ * @param aspectRatio Target `width / height` (`> 0`).
+ * @param bounds Media bounds to clamp into.
+ * @param minWidth Minimum width in units.
+ * @param minHeight Minimum height in units.
+ */
+export function fitRectToRatio(
+  rect: CropRect,
+  aspectRatio: number,
+  bounds: CropBounds,
+  minWidth: number,
+  minHeight: number,
+): CropRect {
+  if (!(aspectRatio > 0) || !Number.isFinite(aspectRatio)) return rect;
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  const area = Math.max(rect.width * rect.height, 1e-9);
+  // w * h = area, w / h = ratio  →  h = sqrt(area / ratio), w = ratio * h.
+  let height = Math.sqrt(area / aspectRatio);
+  let width = aspectRatio * height;
+  // Never below the combined min box.
+  const min = minBox(minWidth, minHeight, aspectRatio);
+  if (width < min.width) {
+    width = min.width;
+    height = min.height;
+  }
+  // Never exceed the media in either dimension while holding the ratio.
+  const maxW = bounds.width;
+  const maxH = bounds.height;
+  if (width > maxW) {
+    width = maxW;
+    height = width / aspectRatio;
+  }
+  if (height > maxH) {
+    height = maxH;
+    width = height * aspectRatio;
+  }
+  const x = clamp(cx - width / 2, 0, Math.max(0, bounds.width - width));
+  const y = clamp(cy - height / 2, 0, Math.max(0, bounds.height - height));
+  return { x, y, width, height };
+}
+
+/**
+ * Translate (move) `rect` by `dx`/`dy`, optionally clamped so it stays fully
+ * inside `bounds`. Size is never changed — only the origin.
+ *
+ * @param rect The rectangle to move.
+ * @param dx Delta on x in the rect's units.
+ * @param dy Delta on y in the rect's units.
+ * @param bounds Media bounds.
+ * @param constrain When `true`, the rect is kept within `bounds`.
+ */
+export function moveRect(
+  rect: CropRect,
+  dx: number,
+  dy: number,
+  bounds: CropBounds,
+  constrain: boolean,
+): CropRect {
+  let x = rect.x + dx;
+  let y = rect.y + dy;
+  if (constrain) {
+    x = clamp(x, 0, Math.max(0, bounds.width - rect.width));
+    y = clamp(y, 0, Math.max(0, bounds.height - rect.height));
+  }
+  return { x, y, width: rect.width, height: rect.height };
+}
+
+/**
+ * Resize `rect` by dragging `handle` to a new pointer position, with the
+ * opposite edge(s) held fixed. Honours `aspectRatio` (paired-dimension
+ * adjustment), the combined `minBox`, and — when `constrain` is set — the media
+ * bounds (clamping the limiting dimension while preserving the ratio).
+ *
+ * The whole computation runs in the rect's units. `px`/`py` are the desired new
+ * position of the dragged handle (the anchor edge stays put). This is the core
+ * of every corner/edge drag and of keyboard edge-resize (with a synthetic
+ * target one step away).
+ *
+ * @param rect The rectangle being resized.
+ * @param handle Which handle is being dragged.
+ * @param px Desired new x of the dragged handle, in units.
+ * @param py Desired new y of the dragged handle, in units.
+ * @param options Aspect, mins, bounds and the constrain flag.
+ */
+export function resizeRect(
+  rect: CropRect,
+  handle: CropHandlePosition,
+  px: number,
+  py: number,
+  options: {
+    aspectRatio: number | null;
+    minWidth: number;
+    minHeight: number;
+    bounds: CropBounds;
+    constrain: boolean;
+  },
+): CropRect {
+  const { aspectRatio, minWidth, minHeight, bounds, constrain } = options;
+  const ratio = aspectRatio !== null && aspectRatio > 0 && Number.isFinite(aspectRatio)
+    ? aspectRatio
+    : null;
+  const min = minBox(minWidth, minHeight, ratio);
+
+  // Fixed (anchor) edges — the opposite edge of whatever the handle moves.
+  const left = rect.x;
+  const right = rect.x + rect.width;
+  const top = rect.y;
+  const bottom = rect.y + rect.height;
+
+  const ml = movesLeft(handle);
+  const mr = movesRight(handle);
+  const mt = movesTop(handle);
+  const mb = movesBottom(handle);
+
+  // 1) Free resize: move the active edges to the pointer, clamp each so the box
+  //    keeps a non-negative size at least `min` and (when constrain) stays in
+  //    bounds. Anchor edges are the opposite, untouched edges.
+  let newLeft = left;
+  let newRight = right;
+  let newTop = top;
+  let newBottom = bottom;
+
+  if (ml) newLeft = constrain ? clamp(px, 0, right - min.width) : Math.min(px, right - min.width);
+  if (mr) newRight = constrain ? clamp(px, left + min.width, bounds.width) : Math.max(px, left + min.width);
+  if (mt) newTop = constrain ? clamp(py, 0, bottom - min.height) : Math.min(py, bottom - min.height);
+  if (mb) newBottom = constrain ? clamp(py, top + min.height, bounds.height) : Math.max(py, top + min.height);
+
+  let width = newRight - newLeft;
+  let height = newBottom - newTop;
+
+  if (ratio !== null) {
+    // 2) Aspect-locked: the dragged edge(s) drive the PRIMARY dimension; the
+    //    paired dimension is derived and grown about the appropriate anchor.
+    const isCorner = (ml || mr) && (mt || mb);
+    if (isCorner) {
+      // Corner: let width lead, derive height (pick the larger so the pointer
+      // is always "inside" the box — feels natural on a corner drag).
+      const hFromW = width / ratio;
+      if (hFromW >= height) {
+        height = hFromW;
+      }
+      else {
+        width = height * ratio;
+      }
+    }
+    else if (ml || mr) {
+      // Horizontal edge handle: width leads, height follows about the centre.
+      height = width / ratio;
+    }
+    else {
+      // Vertical edge handle: height leads, width follows about the centre.
+      width = height * ratio;
+    }
+
+    // Never below the combined min.
+    if (width < min.width) {
+      width = min.width;
+      height = min.height;
+    }
+
+    // 3) Constrain + ratio: if the derived box would exit the media, clamp the
+    //    LIMITING dimension and re-derive the other to preserve the ratio.
+    if (constrain) {
+      // Determine the anchor corner the box grows from.
+      const anchorX = ml ? right : left; // fixed x edge
+      const anchorY = mt ? bottom : top; // fixed y edge
+      // Max width/height available from the anchor toward the drag direction.
+      const availW = ml ? anchorX : bounds.width - anchorX;
+      const availH = mt ? anchorY : bounds.height - anchorY;
+      if (width > availW) {
+        width = availW;
+        height = width / ratio;
+      }
+      if (height > availH) {
+        height = availH;
+        width = height * ratio;
+      }
+      // Re-apply the min after clamping (clamp may have pushed below min when
+      // the media is smaller than the min box — min wins, bounds are honoured
+      // by the final position clamp).
+      if (width < min.width) {
+        width = min.width;
+        height = min.height;
+      }
+    }
+
+    // Recompute the moving edges from the fixed anchors + the (possibly
+    // ratio-adjusted) dimensions. For a centre-anchored edge handle the paired
+    // dimension grows symmetrically about the box centre.
+    if (ml) newLeft = right - width;
+    else if (mr) newRight = left + width;
+    else {
+      // vertical-only handle: centre the width about the existing centre x.
+      const cx = (left + right) / 2;
+      newLeft = cx - width / 2;
+      newRight = cx + width / 2;
+    }
+    if (mt) newTop = bottom - height;
+    else if (mb) newBottom = top + height;
+    else {
+      // horizontal-only handle: centre the height about the existing centre y.
+      const cy = (top + bottom) / 2;
+      newTop = cy - height / 2;
+      newBottom = cy + height / 2;
+    }
+  }
+
+  let outX = newLeft;
+  let outY = newTop;
+  let outW = newRight - newLeft;
+  let outH = newBottom - newTop;
+
+  // Final safety clamp: keep the box inside the media when constrained. Shift
+  // (not shrink) so the ratio/size survive; only shrink if the box is wider/
+  // taller than the media itself.
+  if (constrain) {
+    if (outW > bounds.width) outW = bounds.width;
+    if (outH > bounds.height) outH = bounds.height;
+    outX = clamp(outX, 0, Math.max(0, bounds.width - outW));
+    outY = clamp(outY, 0, Math.max(0, bounds.height - outH));
+  }
+
+  return { x: outX, y: outY, width: outW, height: outH };
+}
+
+/**
+ * Build a fresh rect from a draw-from-empty create gesture: the press `origin`
+ * and the current pointer `point` define opposite corners. Normalised so width
+ * and height are non-negative, then aspect-fitted (anchored at `origin`) and
+ * clamped into bounds. Used by the `createOnEmpty` path.
+ *
+ * @param origin The pointerdown corner, in units.
+ * @param point The current pointer corner, in units.
+ * @param options Aspect, mins, bounds and the constrain flag.
+ */
+export function createRect(
+  origin: Point,
+  point: Point,
+  options: {
+    aspectRatio: number | null;
+    minWidth: number;
+    minHeight: number;
+    bounds: CropBounds;
+    constrain: boolean;
+  },
+): CropRect {
+  // Which handle the pointer is dragging is decided by the sign of the drag, so
+  // we drive `resizeRect` from a zero-area rect anchored at `origin` and let it
+  // do all the ratio/bounds/min work.
+  const dirX = point.x >= origin.x ? 'right' : 'left';
+  const dirY = point.y >= origin.y ? 'bottom' : 'top';
+  const handle = `${dirY === 'bottom' ? 'bottom' : 'top'}-${dirX === 'right' ? 'right' : 'left'}` as CropHandlePosition;
+  const seed: CropRect = { x: origin.x, y: origin.y, width: 0, height: 0 };
+  return resizeRect(seed, handle, point.x, point.y, options);
+}
+
+/**
+ * Clamp/normalise an arbitrary rect into a legal crop: non-negative size, at
+ * least the combined `minBox`, optionally ratio-fitted, and (when `constrain`)
+ * within `bounds`. Used to sanitise an incoming `modelValue` and to settle a
+ * rect after a units / aspectRatio / bounds change.
+ *
+ * @param rect The candidate rectangle.
+ * @param options Aspect, mins, bounds and the constrain flag.
+ */
+export function normalizeRect(
+  rect: CropRect,
+  options: {
+    aspectRatio: number | null;
+    minWidth: number;
+    minHeight: number;
+    bounds: CropBounds;
+    constrain: boolean;
+  },
+): CropRect {
+  const { aspectRatio, minWidth, minHeight, bounds, constrain } = options;
+  const ratio = aspectRatio !== null && aspectRatio > 0 && Number.isFinite(aspectRatio)
+    ? aspectRatio
+    : null;
+  let width = Math.max(0, rect.width);
+  let height = Math.max(0, rect.height);
+  let x = rect.x;
+  let y = rect.y;
+
+  if (ratio !== null) {
+    const fitted = fitRectToRatio({ x, y, width, height }, ratio, bounds, minWidth, minHeight);
+    return fitted;
+  }
+
+  const min = minBox(minWidth, minHeight, ratio);
+  if (width < min.width) width = min.width;
+  if (height < min.height) height = min.height;
+
+  if (constrain) {
+    if (width > bounds.width) width = bounds.width;
+    if (height > bounds.height) height = bounds.height;
+    x = clamp(x, 0, Math.max(0, bounds.width - width));
+    y = clamp(y, 0, Math.max(0, bounds.height - height));
+  }
+  return { x, y, width, height };
+}
+
+/**
+ * Convert between coordinate spaces for an aspect-ratio supplied in display
+ * (pixel) terms. The `aspectRatio` prop is unit-agnostic (`width / height` of
+ * the *crop box*), so in normalized space it must be divided by the media's own
+ * pixel aspect to stay visually correct. Returns the ratio expressed in the
+ * rect's units.
+ *
+ * @param aspectRatio The visual `width / height` the consumer asked for.
+ * @param units The active coordinate space.
+ * @param mediaWidth Media width in pixels (for the normalized correction).
+ * @param mediaHeight Media height in pixels.
+ */
+export function resolveAspectRatio(
+  aspectRatio: number | null,
+  units: 'normalized' | 'pixels',
+  mediaWidth: number,
+  mediaHeight: number,
+): number | null {
+  if (aspectRatio === null || !(aspectRatio > 0) || !Number.isFinite(aspectRatio)) return null;
+  if (units === 'pixels') return aspectRatio;
+  // Normalized: a visual ratio of R means width_px/height_px = R, i.e.
+  // (wx*mediaW)/(hy*mediaH) = R  →  wx/hy = R * mediaH / mediaW.
+  if (mediaWidth <= 0 || mediaHeight <= 0) return aspectRatio;
+  return aspectRatio * (mediaHeight / mediaWidth);
+}
diff --git a/vue/primitives/src/canvas/curve-editor/CurveEditorCurve.vue b/vue/primitives/src/canvas/curve-editor/CurveEditorCurve.vue
new file mode 100644
index 0000000..c5476f1
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/CurveEditorCurve.vue
@@ -0,0 +1,84 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The rendered curve of a `CurveEditorRoot`, an SVG `<path>` whose `d` is built
+ * by sampling `f(x)` across `domainX` (or the per-anchor bezier path in
+ * `'bezier'` mode) and projecting each sample to pixels. It is decorative
+ * (`role="presentation"` / `aria-hidden`) — the accessible controls are the
+ * `CurveEditorPoint` thumbs. The path `d` is also exposed as a slot prop for
+ * custom rendering (fills, glows).
+ */
+export interface CurveEditorCurveProps extends PrimitiveProps {
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useCurveEditorContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+import { buildBezierPath, buildPolylinePath, sampleFnToPolyline } from '../../internal/spline';
+
+const { as = 'path' } = defineProps<CurveEditorCurveProps>();
+const ctx = useCurveEditorContext();
+
+/** Project a domain point to pixel space via the axis scales. */
+function project(x: number, y: number): { x: number; y: number } {
+  return { x: ctx.scaleX.scale(x), y: ctx.scaleY.scale(y) };
+}
+
+const SAMPLES = 256;
+
+const pathD = computed<string>(() => {
+  const [x0, x1] = ctx.domainX.value;
+
+  if (ctx.interpolation.value === 'bezier') {
+    // Per-segment cubic: chain `M … C … C …` through projected anchors/handles.
+    const list = ctx.anchors.value;
+    if (list.length < 2) return '';
+    let d = '';
+    for (let i = 0; i < list.length - 1; i++) {
+      const a = list[i]!;
+      const b = list[i + 1]!;
+      const dx = b.x - a.x;
+      const c1x = a.outHandle ? a.x + a.outHandle.x : a.x + dx / 3;
+      const c1y = a.outHandle ? a.y + a.outHandle.y : a.y + (b.y - a.y) / 3;
+      const c2x = b.inHandle ? b.x + b.inHandle.x : b.x - dx / 3;
+      const c2y = b.inHandle ? b.y + b.inHandle.y : b.y - (b.y - a.y) / 3;
+      const p0 = project(a.x, a.y);
+      const pc1 = project(c1x, c1y);
+      const pc2 = project(c2x, c2y);
+      const p3 = project(b.x, b.y);
+      const seg = buildBezierPath(p0, pc1, pc2, p3);
+      // Drop the leading `M` on subsequent segments (they continue the path).
+      d += i === 0 ? seg : seg.replace(/^M[^C]*/, '');
+    }
+    return d;
+  }
+
+  // Sampled `y = f(x)` polyline projected to pixels.
+  const samples = sampleFnToPolyline(x => ctx.sample(x), x0, x1, SAMPLES);
+  for (let i = 0; i < samples.length; i++) {
+    const p = samples[i]!;
+    samples[i] = project(p.x, p.y);
+  }
+  return buildPolylinePath(samples);
+});
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :d="as === 'path' ? pathD : undefined"
+    role="presentation"
+    aria-hidden="true"
+    fill="none"
+    data-curve-editor-curve=""
+  >
+    <slot :d="pathD" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/curve-editor/CurveEditorGrid.vue b/vue/primitives/src/canvas/curve-editor/CurveEditorGrid.vue
new file mode 100644
index 0000000..748aff3
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/CurveEditorGrid.vue
@@ -0,0 +1,42 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The background gridlines of a `CurveEditorRoot`, drawn from `niceTicks` on
+ * both axes. Rendered as an SVG `<g>` by default (override via `as`) and marked
+ * `aria-hidden` — it is decorative. Exposes the projected `xTicks` / `yTicks` as
+ * slot props so the consumer draws their own lines / labels, and provides a
+ * `#histogram` slot region behind the curve for tone-curve histograms.
+ */
+export interface CurveEditorGridProps extends PrimitiveProps {
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useCurveEditorContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'g' } = defineProps<CurveEditorGridProps>();
+const ctx = useCurveEditorContext();
+
+// `useScale` already projects ticks to pixels (`tick.px`); the x ticks run along
+// the horizontal axis, the y ticks along the vertical (value-up) axis.
+const xTicks = computed(() => ctx.scaleX.ticks.value);
+const yTicks = computed(() => ctx.scaleY.ticks.value);
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    data-curve-editor-grid=""
+  >
+    <slot :x-ticks="xTicks" :y-ticks="yTicks" />
+    <slot name="histogram" :x-ticks="xTicks" :y-ticks="yTicks" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/curve-editor/CurveEditorHandle.vue b/vue/primitives/src/canvas/curve-editor/CurveEditorHandle.vue
new file mode 100644
index 0000000..0908879
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/CurveEditorHandle.vue
@@ -0,0 +1,102 @@
+<script lang="ts">
+import type { CurveEditorAnchor, CurveEditorHandleSide } from './context';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A bezier tangent handle for an anchor, rendered only in `'bezier'`
+ * interpolation. Dragging it adjusts the anchor's `inHandle` / `outHandle`
+ * tangent (relative deltas), clamped (in easing / `monotonicX` mode) so the
+ * cubic segment stays single-valued in x — the handle's x-component can't reach
+ * past the neighbouring anchor (`dx >= 0`), preventing an S-fold. It is exposed
+ * as `role="slider"` with a descriptive `aria-label`; pass `aria-hidden` to make
+ * it purely decorative. Positions itself at the tangent endpoint in pixel space.
+ */
+export interface CurveEditorHandleProps extends PrimitiveProps {
+  /** The anchor whose tangent this handle controls. */
+  anchor: CurveEditorAnchor;
+  /** Which tangent (`'in'` = incoming, `'out'` = outgoing). */
+  side: CurveEditorHandleSide;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useCurveEditorContext } from './context';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useForwardExpose } from '@robonen/vue';
+
+const { anchor, side, as = 'div' } = defineProps<CurveEditorHandleProps>();
+const ctx = useCurveEditorContext();
+
+const isBezier = computed(() => ctx.interpolation.value === 'bezier');
+
+// Default tangent (one-third toward the neighbour) when no handle is set yet, so
+// the handle is grabbable before the consumer first drags it.
+const handle = computed(() => {
+  const stored = side === 'in' ? anchor.inHandle : anchor.outHandle;
+  if (stored) return stored;
+  const list = ctx.anchors.value;
+  const i = ctx.indexOf(anchor.id);
+  const neighbour = side === 'out' ? list[i + 1] : list[i - 1];
+  if (!neighbour) return { x: 0, y: 0 };
+  return { x: (neighbour.x - anchor.x) / 3, y: (neighbour.y - anchor.y) / 3 };
+});
+
+// Tangent endpoint in domain space → pixels.
+const tip = computed(() => {
+  const h = handle.value;
+  return {
+    x: ctx.scaleX.scale(anchor.x + h.x),
+    y: ctx.scaleY.scale(anchor.y + h.y),
+  };
+});
+
+const positionStyle = computed<{ left: string; top: string }>(() => ({
+  left: `${tip.value.x}px`,
+  top: `${tip.value.y}px`,
+}));
+
+const ariaLabel = computed(() => side === 'in' ? 'Incoming tangent handle' : 'Outgoing tangent handle');
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+let originX = 0;
+let originY = 0;
+usePointerDrag(currentElement, {
+  axis: 'both',
+  threshold: 0,
+  disabled: () => ctx.disabled.value || !isBezier.value,
+  onStart: () => {
+    originX = tip.value.x;
+    originY = tip.value.y;
+  },
+  onMove: (state) => {
+    // Invert the dragged tip to domain space, then store the tangent relative to
+    // the anchor. `updateHandle` clamps for monotonic-x safety. Live update only;
+    // `anchorsCommit` is emitted once on settle (onCommit), not per rAF frame.
+    const tipX = ctx.scaleX.invert(originX + state.total.x);
+    const tipY = ctx.scaleY.invert(originY + state.total.y);
+    ctx.updateHandle(anchor.id, side, { x: tipX - anchor.x, y: tipY - anchor.y });
+  },
+  // Successful pointerup only (never on cancel/abort): emit the settled anchors.
+  onCommit: () => ctx.commit(),
+});
+</script>
+
+<template>
+  <Primitive
+    v-if="isBezier"
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :aria-label="ariaLabel"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-side="side"
+    :style="positionStyle"
+    @keydown.stop
+  >
+    <slot :handle="handle" :x="tip.x" :y="tip.y" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/curve-editor/CurveEditorPoint.vue b/vue/primitives/src/canvas/curve-editor/CurveEditorPoint.vue
new file mode 100644
index 0000000..d6377da
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/CurveEditorPoint.vue
@@ -0,0 +1,227 @@
+<script lang="ts">
+import type { CurveEditorAnchor } from './context';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * One anchor handle of a `CurveEditorRoot`, rendered as `role="slider"`. A 2D
+ * control whose single `aria-valuenow` (the output `y`) can't carry both axes,
+ * so `aria-valuetext` announces the pair as `"input {x}, output {y}"`.
+ * `aria-valuemin`/`max` describe the output (`y`) domain.
+ *
+ * Anchors share one tab-stop (roving focus): Tab moves focus between them, the
+ * arrow keys nudge the focused anchor. Left/Right nudge `x` by `step`
+ * (neighbour- and domain-clamped; no-op for fixed endpoints), Up/Down nudge `y`
+ * (Up = +y), Shift+Arrow uses the large step, PageUp/PageDown jump `y`, Home/End
+ * move `x` to the domain min/max. Enter adds an anchor at the midpoint to the
+ * next anchor; Delete/Backspace removes the focused anchor (never an endpoint).
+ * Double-click also adds, drag moves the anchor (2D, clamped). Exposes the
+ * anchor and its pixel position as slot props.
+ */
+export interface CurveEditorPointProps extends PrimitiveProps {
+  /** The anchor this point renders. */
+  anchor: CurveEditorAnchor;
+  /**
+   * Override the announced `aria-valuetext`. Receives the anchor's `x` and `y`
+   * in domain space.
+   */
+  valueText?: (x: number, y: number) => string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, useAttrs, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useCurveEditorContext } from './context';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useForwardExpose } from '@robonen/vue';
+import { formatAnchorValueText } from './utils';
+
+const { anchor, valueText, as = 'div' } = defineProps<CurveEditorPointProps>();
+const ctx = useCurveEditorContext();
+const attrs = useAttrs();
+
+const index = computed(() => ctx.indexOf(anchor.id));
+const isEndpoint = computed(() => ctx.isEndpoint(anchor.id));
+const isActive = computed(() => ctx.activeIndex.value === index.value);
+
+// Pixel position from the axis projections (x horizontal, y value-up vertical).
+const pxX = computed(() => ctx.scaleX.scale(anchor.x));
+const pxY = computed(() => ctx.scaleY.scale(anchor.y));
+
+const positionStyle = computed<{ left: string; top: string }>(() => ({
+  left: `${pxX.value}px`,
+  top: `${pxY.value}px`,
+}));
+
+// `aria-valuemin`/`max`/`now` describe the OUTPUT (y) domain — the single axis a
+// slider can express; `aria-valuetext` conveys both coordinates.
+const domainY = computed(() => ctx.domainY.value);
+const ariaValueMin = computed(() => Math.min(domainY.value[0], domainY.value[1]));
+const ariaValueMax = computed(() => Math.max(domainY.value[0], domainY.value[1]));
+
+const ariaValueText = computed<string | undefined>(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  if (valueText) return valueText(anchor.x, anchor.y);
+  return formatAnchorValueText(anchor.x, anchor.y);
+});
+
+// Roving focus: only the active anchor is in the tab order.
+const tabindex = computed(() => {
+  if (ctx.disabled.value) return -1;
+  return isActive.value ? 0 : -1;
+});
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+watch(currentElement, (node) => {
+  ctx.registerAnchorEl(anchor.id, node ?? null);
+});
+onBeforeUnmount(() => ctx.registerAnchorEl(anchor.id, null));
+
+// ── pointer drag (2D) ─────────────────────────────────────────────────────
+// Map the element-relative pointer to domain x/y via inverse projection. The
+// drag tracks the ROOT element's rect (the projections measure that box).
+// Capture the anchor's pixel origin at drag start so cumulative drag totals
+// (client px, which equal plot px 1:1) project back through the scales without
+// needing the plot rect.
+let dragOriginX = 0;
+let dragOriginY = 0;
+usePointerDrag(currentElement, {
+  axis: 'both',
+  threshold: 0,
+  disabled: () => ctx.disabled.value,
+  onStart: () => {
+    ctx.setActiveIndex(index.value);
+    dragOriginX = pxX.value;
+    dragOriginY = pxY.value;
+  },
+  onMove: (state) => {
+    const x = ctx.scaleX.invert(dragOriginX + state.total.x);
+    const y = ctx.scaleY.invert(dragOriginY + state.total.y);
+    // Live update only — the drag commits once on settle (onCommit), so
+    // `anchorsCommit` fires per the documented "after a drag settles" contract
+    // rather than once per rAF frame.
+    ctx.updateAnchor(anchor.id, { x, y });
+  },
+  // Successful pointerup only (never on cancel/abort): emit the settled anchors.
+  onCommit: () => ctx.commit(),
+});
+
+// ── keyboard ──────────────────────────────────────────────────────────────
+// A keyboard nudge is a discrete settle: emit `anchorsCommit` once, only when
+// the anchor actually moved (a clamped no-op at a domain edge does not commit,
+// matching the original updateAnchor-only-on-change behaviour).
+function nudge(dx: number, dy: number): void {
+  let changed = false;
+  if (dx !== 0) changed = ctx.updateAnchor(anchor.id, { x: anchor.x + dx }) || changed;
+  if (dy !== 0) changed = ctx.updateAnchor(anchor.id, { y: anchor.y + dy }) || changed;
+  if (changed) ctx.commit();
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const rtl = ctx.direction.value === 'rtl';
+  const step = ctx.step.value;
+  const big = ctx.largeStep.value;
+  const unit = event.shiftKey ? big : step;
+  const [dyMin, dyMax] = ctx.domainY.value;
+  const ySpan = Math.abs(dyMax - dyMin);
+  const xLocked = ctx.fixedEndpoints.value && isEndpoint.value;
+
+  switch (event.key) {
+    case 'ArrowRight':
+      event.preventDefault();
+      if (!xLocked) nudge(rtl ? -unit : unit, 0);
+      return;
+    case 'ArrowLeft':
+      event.preventDefault();
+      if (!xLocked) nudge(rtl ? unit : -unit, 0);
+      return;
+    case 'ArrowUp':
+      event.preventDefault();
+      nudge(0, unit);
+      return;
+    case 'ArrowDown':
+      event.preventDefault();
+      nudge(0, -unit);
+      return;
+    case 'PageUp':
+      event.preventDefault();
+      if (ctx.updateAnchor(anchor.id, { y: anchor.y + ySpan * 0.1 })) ctx.commit();
+      return;
+    case 'PageDown':
+      event.preventDefault();
+      if (ctx.updateAnchor(anchor.id, { y: anchor.y - ySpan * 0.1 })) ctx.commit();
+      return;
+    case 'Home':
+      event.preventDefault();
+      if (!xLocked && ctx.updateAnchor(anchor.id, { x: ctx.domainX.value[0] })) ctx.commit();
+      return;
+    case 'End':
+      event.preventDefault();
+      if (!xLocked && ctx.updateAnchor(anchor.id, { x: ctx.domainX.value[1] })) ctx.commit();
+      return;
+    case 'Enter': {
+      event.preventDefault();
+      // Add an anchor between this one and the next (or before, at the last).
+      const list = ctx.anchors.value;
+      const i = index.value;
+      const next = list[i + 1] ?? list[i - 1];
+      if (!next) return;
+      const midX = (anchor.x + next.x) / 2;
+      ctx.addAnchor(midX);
+      return;
+    }
+    case 'Delete':
+    case 'Backspace':
+      event.preventDefault();
+      ctx.removeAnchor(anchor.id);
+      break;
+    default:
+      break;
+  }
+}
+
+function onDblClick(event: MouseEvent): void {
+  if (ctx.disabled.value) return;
+  event.preventDefault();
+  // Double-click on an interior anchor removes it; on an endpoint adds a midpoint.
+  if (!isEndpoint.value) {
+    ctx.removeAnchor(anchor.id);
+    return;
+  }
+  const list = ctx.anchors.value;
+  const i = index.value;
+  const neighbour = list[i + 1] ?? list[i - 1];
+  if (neighbour) ctx.addAnchor((anchor.x + neighbour.x) / 2);
+}
+
+function onFocus(): void {
+  if (index.value !== -1) ctx.setActiveIndex(index.value);
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="tabindex"
+    :aria-valuemin="ariaValueMin"
+    :aria-valuemax="ariaValueMax"
+    :aria-valuenow="anchor.y"
+    :aria-valuetext="ariaValueText"
+    :aria-orientation="undefined"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-endpoint="isEndpoint ? '' : undefined"
+    :data-active="isActive ? '' : undefined"
+    :data-channel="ctx.channel.value"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+    @dblclick="onDblClick"
+    @focus="onFocus"
+  >
+    <slot :anchor="anchor" :x="pxX" :y="pxY" :active="isActive" :endpoint="isEndpoint" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/curve-editor/CurveEditorRoot.vue b/vue/primitives/src/canvas/curve-editor/CurveEditorRoot.vue
new file mode 100644
index 0000000..1c7d985
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/CurveEditorRoot.vue
@@ -0,0 +1,428 @@
+<script lang="ts">
+import type { CurveEditorAnchor, CurveEditorChannel, CurveEditorDirection, CurveEditorHandleSide, CurveEditorInterpolation } from './context';
+import type { Point } from '../../internal/utils/geometry';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A headless control-point curve editor: a draggable set of anchors defining a
+ * single-valued `y = f(x)` curve. It backs both **animation easing curves** (an
+ * ease over normalized time) and **photo tone curves** (per-RGB-channel output
+ * remapping), and is the shared engine reused by Levels (gamma) and the future
+ * KeyframeTrack.
+ *
+ * The root owns the anchor array (controlled via `v-model`, uncontrolled via
+ * `defaultValue`), builds value↔pixel projections for both axes (`useScale`,
+ * y-axis value-up), and exposes the live evaluator: `sample(x) → y` and
+ * `toLUT(size)` for applying the curve to pixels. With `monotonicX` (the
+ * default) anchors are neighbour-clamped so they can never cross in x — easing
+ * and tone curves both require a function of x. `fixedEndpoints` locks the first
+ * and last anchor in x. The `interpolation` mode selects monotone (default),
+ * linear, catmull-rom, or per-anchor bezier handles.
+ *
+ * Provides context to `CurveEditorGrid`, `CurveEditorCurve`, `CurveEditorPoint`,
+ * and `CurveEditorHandle`. The `channel` prop only tags which curve is being
+ * edited (for styling / the `#channel` slot); consumers render their own RGB
+ * tabs.
+ */
+export interface CurveEditorRootProps extends PrimitiveProps {
+  /** Uncontrolled initial anchors. Seeds the curve when `v-model` is absent. */
+  defaultValue?: CurveEditorAnchor[];
+  /**
+   * How the curve is interpolated between anchors.
+   * @default 'monotone'
+   */
+  interpolation?: CurveEditorInterpolation;
+  /** Input (x) domain `[min, max]`. @default [0, 1] */
+  domainX?: readonly [number, number];
+  /** Output (y) domain `[min, max]`. @default [0, 1] */
+  domainY?: readonly [number, number];
+  /**
+   * Keep x single-valued: neighbour-clamp anchors so they can't cross in x.
+   * Easing / tone curves require a function of x. @default true
+   */
+  monotonicX?: boolean;
+  /** Lock the first and last anchor in x (only y is editable). @default true */
+  fixedEndpoints?: boolean;
+  /**
+   * Tags which curve is being edited (composite `'value'` or per-channel
+   * `'r'`/`'g'`/`'b'`). Purely cosmetic — exposed for styling / the `#channel`
+   * slot; consumers render their own channel tabs. @default 'value'
+   */
+  channel?: CurveEditorChannel;
+  /** Keyboard step for x/y nudges. @default 0.01 */
+  step?: number;
+  /** Large keyboard step (Shift+Arrow / Page keys). @default 0.1 */
+  largeStep?: number;
+  /** Sample count for the rendered polyline / LUT. @default 256 */
+  samples?: number;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /** Writing direction (inherited from `ConfigProvider` when omitted). */
+  dir?: CurveEditorDirection;
+}
+
+export interface CurveEditorRootEmits {
+  /** Fired after a drag or keypress settles (anchor added / removed / moved). */
+  anchorsCommit: [anchors: CurveEditorAnchor[]];
+  /** Fired when an anchor is added. */
+  anchorAdd: [anchor: CurveEditorAnchor];
+  /** Fired when an anchor is removed. */
+  anchorRemove: [anchor: CurveEditorAnchor];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideCurveEditorContext } from './context';
+import { useScale } from '../../internal/scale';
+import { useDirection, useId } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+import { buildEvaluator, clampAnchorX, clampAnchorY, sortAnchors } from './utils';
+import { toLUT as splineToLUT } from '../../internal/spline';
+
+const {
+  defaultValue,
+  interpolation = 'monotone',
+  domainX = [0, 1] as readonly [number, number],
+  domainY = [0, 1] as readonly [number, number],
+  monotonicX = true,
+  fixedEndpoints = true,
+  channel = 'value',
+  step = 0.01,
+  largeStep = 0.1,
+  samples = 256,
+  disabled = false,
+  dir,
+  as = 'div',
+} = defineProps<CurveEditorRootProps>();
+
+const direction = useDirection(() => dir);
+const emit = defineEmits<CurveEditorRootEmits>();
+const idBase = useId();
+
+const model = defineModel<CurveEditorAnchor[] | null>();
+
+/** Default curve: a straight identity line across the domain (two endpoints). */
+function defaultAnchors(): CurveEditorAnchor[] {
+  const [x0, x1] = domainX;
+  const [y0, y1] = domainY;
+  return [
+    { id: `${idBase.value}-0`, x: x0, y: y0 },
+    { id: `${idBase.value}-1`, x: x1, y: y1 },
+  ];
+}
+
+function seedAnchors(): CurveEditorAnchor[] {
+  const seed = Array.isArray(model.value) && model.value.length > 0
+    ? model.value
+    : Array.isArray(defaultValue) && defaultValue.length > 0
+      ? defaultValue
+      : defaultAnchors();
+  return sortAnchors(seed);
+}
+
+// `shallowRef` — the array is replaced wholesale on every mutation; items are
+// plain (non-proxied) so the evaluator/render path reads them cheaply.
+const localAnchors = shallowRef<CurveEditorAnchor[]>(seedAnchors());
+
+watch(model, (v) => {
+  if (v === null || v === undefined) return;
+  if (v === localAnchors.value) return;
+  localAnchors.value = sortAnchors(v);
+});
+
+const anchors = computed<CurveEditorAnchor[]>({
+  get: () => localAnchors.value,
+  set: (v) => {
+    const sorted = sortAnchors(v);
+    localAnchors.value = sorted;
+    model.value = sorted;
+  },
+});
+
+// Auto-incrementing id seed for inserted anchors (stable across the session).
+let idCounter = localAnchors.value.length;
+function nextId(): string {
+  return `${idBase.value}-${idCounter++}`;
+}
+
+// ── geometry / projections ────────────────────────────────────────────────
+// Plot size in pixels; measured from the root element after mount. Degenerate
+// `[n, n]` ranges (zero-size pre-mount) are guarded by `scaleLinear` (returns
+// range start), so projections never NaN.
+const plotWidth = shallowRef(0);
+const plotHeight = shallowRef(0);
+
+const scaleX = useScale({
+  domain: () => domainX,
+  range: () => [0, plotWidth.value] as const,
+  orientation: 'horizontal',
+  clamp: true,
+});
+
+// y-axis is value-UP: domain start maps to the bottom (range end).
+const scaleY = useScale({
+  domain: () => domainY,
+  range: () => [0, plotHeight.value] as const,
+  orientation: 'vertical',
+  clamp: true,
+});
+
+// ── evaluator ─────────────────────────────────────────────────────────────
+const evaluator = computed(() => buildEvaluator(localAnchors.value, interpolation));
+
+function sample(x: number): number {
+  return evaluator.value(x);
+}
+
+function toLUT(size: number = samples): number[] {
+  const [x0, x1] = domainX;
+  return splineToLUT(evaluator.value, size, x0, x1);
+}
+
+// ── roving focus ──────────────────────────────────────────────────────────
+const activeIndex = ref(0);
+const anchorEls = new Map<string, HTMLElement | null>();
+
+function registerAnchorEl(id: string, el: HTMLElement | null): void {
+  if (el) anchorEls.set(id, el);
+  else anchorEls.delete(id);
+}
+
+// id → index map, rebuilt once per `localAnchors` replacement. Parts derive
+// their `index`/`isEndpoint` from this O(1) lookup instead of each re-scanning
+// the wholesale-replaced array every drag frame (was O(n) per part → O(n^2)
+// across the list per committed frame).
+const indexById = computed(() => {
+  const list = localAnchors.value;
+  const map = new Map<string, number>();
+  for (let i = 0; i < list.length; i++) map.set(list[i]!.id, i);
+  return map;
+});
+
+function indexOf(id: string): number {
+  return indexById.value.get(id) ?? -1;
+}
+
+function isEndpoint(id: string): boolean {
+  const i = indexById.value.get(id) ?? -1;
+  return i === 0 || i === localAnchors.value.length - 1;
+}
+
+function focusIndex(index: number): void {
+  const anchor = localAnchors.value[index];
+  if (!anchor) return;
+  anchorEls.get(anchor.id)?.focus();
+}
+
+function setActiveIndex(index: number): void {
+  const count = localAnchors.value.length;
+  if (count === 0) return;
+  const clamped = Math.min(Math.max(index, 0), count - 1);
+  activeIndex.value = clamped;
+  focusIndex(clamped);
+}
+
+function moveFocus(delta: number): void {
+  const count = localAnchors.value.length;
+  if (count === 0) return;
+  const next = ((activeIndex.value + delta) % count + count) % count;
+  setActiveIndex(next);
+}
+
+// Keep the active index valid as anchors are added/removed.
+watch(() => localAnchors.value.length, (count) => {
+  if (count === 0) {
+    activeIndex.value = 0;
+    return;
+  }
+  if (activeIndex.value > count - 1) activeIndex.value = count - 1;
+});
+
+// ── mutations ─────────────────────────────────────────────────────────────
+const minGap = computed(() => Math.max(step, (Math.abs(domainX[1] - domainX[0])) * 1e-3));
+
+function commit(): void {
+  emit('anchorsCommit', localAnchors.value.map(a => ({ ...a })));
+}
+
+// Returns whether the anchor actually moved. The live update is decoupled from
+// the `anchorsCommit` emit: callers commit on settle (drag end / keypress), not
+// per frame. Returning the changed-flag lets discrete callers (keyboard) skip
+// committing on a clamped no-op, matching the original "only emit on change".
+function updateAnchor(id: string, next: { x?: number; y?: number }): boolean {
+  if (disabled) return false;
+  const list = localAnchors.value;
+  const index = indexOf(id);
+  if (index === -1) return false;
+  const current = list[index]!;
+
+  let x = current.x;
+  if (next.x !== undefined) {
+    x = clampAnchorX(list, index, next.x, {
+      domainMin: domainX[0],
+      domainMax: domainX[1],
+      monotonicX,
+      fixedEndpoints,
+      minGap: minGap.value,
+    });
+  }
+  let y = current.y;
+  if (next.y !== undefined)
+    y = clampAnchorY(next.y, domainY[0], domainY[1]);
+
+  if (x === current.x && y === current.y) return false;
+
+  const candidate = list.slice();
+  candidate[index] = { ...current, x, y };
+  // x never crosses a neighbour (clampAnchorX guarantees it under monotonicX),
+  // so order is preserved without a re-sort. Re-sort defensively when monotonicX
+  // is off (anchors may legitimately reorder).
+  anchors.value = monotonicX ? candidate : sortAnchors(candidate);
+  // Track the moved anchor's new index for roving focus.
+  activeIndex.value = indexOf(id);
+  return true;
+}
+
+function updateHandle(id: string, side: CurveEditorHandleSide, handle: Point): void {
+  if (disabled || interpolation !== 'bezier') return;
+  const list = localAnchors.value;
+  const index = indexOf(id);
+  if (index === -1) return;
+  const current = list[index]!;
+
+  // Easing requires the segment stay monotone in x: clamp the tangent so its
+  // x-component never points "backwards" past the adjacent anchor (dx >= 0).
+  const clamped = clampHandle(list, index, side, handle);
+
+  const candidate = list.slice();
+  candidate[index] = side === 'in'
+    ? { ...current, inHandle: clamped }
+    : { ...current, outHandle: clamped };
+  anchors.value = candidate;
+  // Live update only; the handle drag commits once on settle (see onCommit).
+}
+
+/**
+ * Clamp a bezier tangent so the cubic segment stays single-valued in x
+ * (`dx >= 0`): the outgoing handle may not reach past the next anchor, the
+ * incoming handle may not reach before the previous anchor. Prevents the
+ * S-fold that would make the easing curve multi-valued.
+ */
+function clampHandle(list: readonly CurveEditorAnchor[], index: number, side: CurveEditorHandleSide, handle: Point): Point {
+  if (!monotonicX) return handle;
+  const current = list[index]!;
+  if (side === 'out') {
+    const next = list[index + 1];
+    const maxDx = next ? next.x - current.x : domainX[1] - current.x;
+    return { x: Math.min(Math.max(handle.x, 0), Math.max(0, maxDx)), y: handle.y };
+  }
+  const prev = list[index - 1];
+  const minDx = prev ? prev.x - current.x : domainX[0] - current.x;
+  return { x: Math.max(Math.min(handle.x, 0), Math.min(0, minDx)), y: handle.y };
+}
+
+function addAnchor(x: number, y?: number): string | undefined {
+  if (disabled) return undefined;
+  const lo = Math.min(domainX[0], domainX[1]);
+  const hi = Math.max(domainX[0], domainX[1]);
+  const cx = Math.min(Math.max(x, lo), hi);
+  const cy = clampAnchorY(y ?? sample(cx), domainY[0], domainY[1]);
+  const id = nextId();
+  const anchor: CurveEditorAnchor = { id, x: cx, y: cy };
+  const candidate = sortAnchors([...localAnchors.value, anchor]);
+  anchors.value = candidate;
+  setActiveIndex(indexOf(id));
+  emit('anchorAdd', { ...anchor });
+  commit();
+  return id;
+}
+
+function removeAnchor(id: string): void {
+  if (disabled) return;
+  if (isEndpoint(id)) return;
+  const index = indexOf(id);
+  if (index === -1) return;
+  const removed = localAnchors.value[index]!;
+  const candidate = localAnchors.value.slice();
+  candidate.splice(index, 1);
+  anchors.value = candidate;
+  setActiveIndex(Math.min(index, candidate.length - 1));
+  emit('anchorRemove', { ...removed });
+  commit();
+}
+
+provideCurveEditorContext({
+  anchors,
+  interpolation: toRef(() => interpolation),
+  domainX: toRef(() => domainX),
+  domainY: toRef(() => domainY),
+  scaleX,
+  scaleY,
+  channel: toRef(() => channel),
+  step: toRef(() => step),
+  largeStep: toRef(() => largeStep),
+  monotonicX: toRef(() => monotonicX),
+  fixedEndpoints: toRef(() => fixedEndpoints),
+  direction,
+  disabled: toRef(() => disabled),
+  activeIndex,
+  sample,
+  toLUT,
+  indexOf,
+  registerAnchorEl,
+  isEndpoint,
+  setActiveIndex,
+  moveFocus,
+  commit,
+  updateAnchor,
+  updateHandle,
+  addAnchor,
+  removeAnchor,
+});
+
+defineExpose({ sample, toLUT, anchors, addAnchor, removeAnchor });
+
+// `useForwardExpose` runs AFTER `defineExpose` so it merges the prior bindings
+// (plus props + `$el`) instead of clobbering them.
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Measure the plot box once the root element resolves, and on resize.
+watch(currentElement, (node, _prev, onCleanup) => {
+  if (!node) return;
+  const measure = (): void => {
+    const rect = node.getBoundingClientRect();
+    plotWidth.value = rect.width;
+    plotHeight.value = rect.height;
+  };
+  measure();
+  if (typeof ResizeObserver !== 'undefined') {
+    const ro = new ResizeObserver(measure);
+    ro.observe(node);
+    // Disconnect on unmount AND before the next run (currentElement change).
+    // Without this each re-run stacks a new observer and the last one leaks,
+    // retaining the root node + the measure closure (+ this component scope).
+    onCleanup(() => ro.disconnect());
+  }
+}, { immediate: false });
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :dir="direction"
+    :data-channel="channel"
+    :data-interpolation="interpolation"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+  >
+    <slot
+      :anchors="anchors"
+      :channel="channel"
+      :interpolation="interpolation"
+      :sample="sample"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/curve-editor/__test__/CurveEditor.test.ts b/vue/primitives/src/canvas/curve-editor/__test__/CurveEditor.test.ts
new file mode 100644
index 0000000..fbcb164
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/__test__/CurveEditor.test.ts
@@ -0,0 +1,285 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { CurveEditorAnchor, CurveEditorInterpolation } from '../index';
+import { CurveEditorCurve, CurveEditorPoint, CurveEditorRoot } from '../index';
+import { buildEvaluator, clampAnchorX } from '../utils';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', {
+    key,
+    bubbles: true,
+    cancelable: true,
+    shiftKey: opts.shiftKey ?? false,
+  }));
+}
+
+function anchorsFromIds(...pts: Array<[number, number]>): CurveEditorAnchor[] {
+  return pts.map(([x, y], i) => ({ id: `a${i}`, x, y }));
+}
+
+function round(n: number, d = 3): number {
+  const f = 10 ** d;
+  return Math.round(n * f) / f;
+}
+
+function mountEditor(
+  opts: Partial<{
+    defaultValue: CurveEditorAnchor[];
+    interpolation: CurveEditorInterpolation;
+    monotonicX: boolean;
+    fixedEndpoints: boolean;
+    step: number;
+    largeStep: number;
+    disabled: boolean;
+  }> = {},
+) {
+  const model = ref<CurveEditorAnchor[] | undefined>(undefined);
+  const Harness = defineComponent({
+    setup: () => () => h(
+      CurveEditorRoot,
+      {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: CurveEditorAnchor[] | null | undefined) => {
+          model.value = v ?? undefined;
+        },
+        ...opts,
+      },
+      {
+        default: ({ anchors }: { anchors: CurveEditorAnchor[] }) => [
+          h(CurveEditorCurve),
+          ...anchors.map(a => h(CurveEditorPoint, { key: a.id, anchor: a })),
+        ],
+      },
+    ),
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+// ── unit tests: evaluator / sample logic ────────────────────────────────────
+
+describe('CurveEditor evaluator (unit)', () => {
+  it('linear interpolates and passes through anchors', () => {
+    const f = buildEvaluator(anchorsFromIds([0, 0], [1, 1]), 'linear');
+    expect(f(0)).toBe(0);
+    expect(f(1)).toBe(1);
+    expect(round(f(0.5))).toBe(0.5);
+  });
+
+  it('monotone passes through anchors and is non-decreasing for a rising set', () => {
+    const f = buildEvaluator(anchorsFromIds([0, 0], [0.5, 0.2], [1, 1]), 'monotone');
+    expect(round(f(0))).toBe(0);
+    expect(round(f(0.5))).toBe(0.2);
+    expect(round(f(1))).toBe(1);
+    // Monotone (no overshoot): sampling forward never decreases.
+    let prev = -Infinity;
+    for (let i = 0; i <= 20; i++) {
+      const y = f(i / 20);
+      expect(y).toBeGreaterThanOrEqual(prev - 1e-9);
+      prev = y;
+    }
+  });
+
+  it('catmull-rom passes through its anchors', () => {
+    const f = buildEvaluator(anchorsFromIds([0, 0], [0.5, 0.7], [1, 1]), 'catmull-rom');
+    expect(round(f(0), 2)).toBe(0);
+    expect(round(f(0.5), 2)).toBe(0.7);
+    expect(round(f(1), 2)).toBe(1);
+  });
+
+  it('bezier with default tangents reproduces a near-linear segment', () => {
+    const f = buildEvaluator(anchorsFromIds([0, 0], [1, 1]), 'bezier');
+    expect(round(f(0))).toBe(0);
+    expect(round(f(1))).toBe(1);
+    expect(round(f(0.5), 2)).toBe(0.5);
+  });
+
+  it('clamps x outside the domain to the endpoint y', () => {
+    const f = buildEvaluator(anchorsFromIds([0, 0.1], [1, 0.9]), 'monotone');
+    expect(f(-1)).toBe(0.1);
+    expect(f(2)).toBe(0.9);
+  });
+
+  it('clampAnchorX keeps an anchor between its neighbours under monotonicX', () => {
+    const list = anchorsFromIds([0, 0], [0.5, 0.5], [1, 1]);
+    // Try to push the middle anchor past the right neighbour.
+    const x = clampAnchorX(list, 1, 5, {
+      domainMin: 0,
+      domainMax: 1,
+      monotonicX: true,
+      fixedEndpoints: true,
+      minGap: 0.01,
+    });
+    expect(x).toBeLessThanOrEqual(1 - 0.01);
+    expect(x).toBeGreaterThan(0);
+  });
+
+  it('clampAnchorX pins endpoints when fixedEndpoints', () => {
+    const list = anchorsFromIds([0, 0], [1, 1]);
+    expect(clampAnchorX(list, 0, 0.4, { domainMin: 0, domainMax: 1, monotonicX: true, fixedEndpoints: true, minGap: 0.01 })).toBe(0);
+    expect(clampAnchorX(list, 1, 0.4, { domainMin: 0, domainMax: 1, monotonicX: true, fixedEndpoints: true, minGap: 0.01 })).toBe(1);
+  });
+});
+
+// ── component tests (browser mode) ──────────────────────────────────────────
+
+describe('CurveEditor component', () => {
+  it('renders anchors as role=slider with aria-valuetext conveying input + output', async () => {
+    mountEditor({ defaultValue: anchorsFromIds([0, 0], [1, 0.5]) });
+    await nextTick();
+    const sliders = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(sliders.length).toBe(2);
+    const last = sliders[1]!;
+    expect(last.getAttribute('aria-valuenow')).toBe('0.5');
+    expect(last.getAttribute('aria-valuetext')).toBe('input 1, output 0.5');
+    expect(last.getAttribute('aria-valuemin')).toBe('0');
+    expect(last.getAttribute('aria-valuemax')).toBe('1');
+  });
+
+  it('exposes sample() and toLUT() that pass through anchors', async () => {
+    const { wrapper } = mountEditor({ defaultValue: anchorsFromIds([0, 0], [0.5, 0.2], [1, 1]), interpolation: 'monotone' });
+    await nextTick();
+    const root = wrapper.findComponent(CurveEditorRoot);
+    const sample = (root.vm as any).sample as (x: number) => number;
+    expect(round(sample(0))).toBe(0);
+    expect(round(sample(0.5))).toBe(0.2);
+    expect(round(sample(1))).toBe(1);
+    const lut = (root.vm as any).toLUT(16) as number[];
+    expect(lut.length).toBe(16);
+    expect(round(lut[0]!)).toBe(0);
+    expect(round(lut[lut.length - 1]!)).toBe(1);
+  });
+
+  it('ArrowUp increases y on the focused anchor', async () => {
+    const { model } = mountEditor({ defaultValue: anchorsFromIds([0, 0], [1, 0.5]), step: 0.1 });
+    await nextTick();
+    const slider = document.querySelectorAll<HTMLElement>('[role="slider"]')[1]!;
+    keydown(slider, 'ArrowUp');
+    await nextTick();
+    expect(round(model.value![1]!.y)).toBe(0.6);
+  });
+
+  it('ArrowRight increases x; endpoints are x-locked when fixedEndpoints', async () => {
+    const { model } = mountEditor({
+      defaultValue: anchorsFromIds([0, 0], [0.5, 0.5], [1, 1]),
+      step: 0.1,
+      fixedEndpoints: true,
+    });
+    await nextTick();
+    const sliders = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    // Interior anchor moves in x.
+    keydown(sliders[1]!, 'ArrowRight');
+    await nextTick();
+    expect(round(model.value![1]!.x)).toBe(0.6);
+    // Endpoint x is locked.
+    keydown(sliders[2]!, 'ArrowRight');
+    await nextTick();
+    expect(round(model.value![2]!.x)).toBe(1);
+  });
+
+  it('monotonicX prevents an anchor from crossing its neighbour', async () => {
+    const { model } = mountEditor({
+      defaultValue: anchorsFromIds([0, 0], [0.5, 0.5], [1, 1]),
+      step: 0.1,
+      monotonicX: true,
+    });
+    await nextTick();
+    const mid = document.querySelectorAll<HTMLElement>('[role="slider"]')[1]!;
+    // Hammer ArrowRight far past the right neighbour at x=1.
+    for (let i = 0; i < 20; i++) keydown(mid, 'ArrowRight');
+    await nextTick();
+    expect(model.value![1]!.x).toBeLessThan(1);
+    // Order is preserved.
+    expect(model.value![0]!.x).toBeLessThan(model.value![1]!.x);
+    expect(model.value![1]!.x).toBeLessThan(model.value![2]!.x);
+  });
+
+  it('Shift+Arrow uses the large step', async () => {
+    const { model } = mountEditor({ defaultValue: anchorsFromIds([0, 0], [1, 0.5]), step: 0.01, largeStep: 0.1 });
+    await nextTick();
+    const slider = document.querySelectorAll<HTMLElement>('[role="slider"]')[1]!;
+    keydown(slider, 'ArrowUp', { shiftKey: true });
+    await nextTick();
+    expect(round(model.value![1]!.y)).toBe(0.6);
+  });
+
+  it('Enter adds an anchor at the midpoint, Delete removes an interior anchor', async () => {
+    const { model } = mountEditor({ defaultValue: anchorsFromIds([0, 0], [1, 1]) });
+    await nextTick();
+    const first = document.querySelectorAll<HTMLElement>('[role="slider"]')[0]!;
+    keydown(first, 'Enter');
+    await nextTick();
+    expect(model.value!.length).toBe(3);
+    expect(round(model.value![1]!.x)).toBe(0.5);
+    // Remove the new interior anchor.
+    const interior = document.querySelectorAll<HTMLElement>('[role="slider"]')[1]!;
+    keydown(interior, 'Delete');
+    await nextTick();
+    expect(model.value!.length).toBe(2);
+  });
+
+  it('Delete does not remove an endpoint', async () => {
+    mountEditor({ defaultValue: anchorsFromIds([0, 0], [1, 1]) });
+    await nextTick();
+    const first = document.querySelectorAll<HTMLElement>('[role="slider"]')[0]!;
+    keydown(first, 'Delete');
+    await nextTick();
+    // The endpoint is never removed: both anchors still render.
+    expect(document.querySelectorAll('[role="slider"]').length).toBe(2);
+  });
+
+  it('roving focus: only the active anchor is tabbable', async () => {
+    mountEditor({ defaultValue: anchorsFromIds([0, 0], [0.5, 0.5], [1, 1]) });
+    await nextTick();
+    const sliders = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    // Active index defaults to 0.
+    expect(sliders[0]!.tabIndex).toBe(0);
+    expect(sliders[1]!.tabIndex).toBe(-1);
+    expect(sliders[2]!.tabIndex).toBe(-1);
+  });
+
+  it('disabled: tabindex=-1 and keys do nothing', async () => {
+    const { model } = mountEditor({ defaultValue: anchorsFromIds([0, 0], [1, 0.5]), disabled: true });
+    await nextTick();
+    const slider = document.querySelectorAll<HTMLElement>('[role="slider"]')[1]!;
+    expect(slider.tabIndex).toBe(-1);
+    keydown(slider, 'ArrowUp');
+    await nextTick();
+    // No mutation occurred (model never written).
+    expect(model.value).toBeUndefined();
+  });
+
+  it('renders the curve as an aria-hidden path with a non-empty d', async () => {
+    mountEditor({ defaultValue: anchorsFromIds([0, 0], [1, 1]) });
+    await nextTick();
+    const path = document.querySelector<SVGPathElement>('[data-curve-editor-curve]')!;
+    expect(path).toBeTruthy();
+    expect(path.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('interpolation modes each produce a curve through the anchors', async () => {
+    for (const interpolation of ['linear', 'monotone', 'catmull-rom', 'bezier'] as const) {
+      const { wrapper } = mountEditor({ defaultValue: anchorsFromIds([0, 0], [0.5, 0.4], [1, 1]), interpolation });
+      await nextTick();
+      const sample = (wrapper.findComponent(CurveEditorRoot).vm as any).sample as (x: number) => number;
+      expect(round(sample(0), 2)).toBe(0);
+      expect(round(sample(0.5), 2)).toBe(0.4);
+      expect(round(sample(1), 2)).toBe(1);
+      wrapper.unmount();
+    }
+  });
+});
diff --git a/vue/primitives/src/calendar/__test__/__screenshots__/Calendar.test.ts/Calendar-mounts-cell-triggers-without--expose---should-be-called-only-once--warnings-1.png b/vue/primitives/src/canvas/curve-editor/__test__/__screenshots__/CurveEditor.test.ts/CurveEditor-component-Delete-does-not-remove-an-endpoint-1.png
similarity index 100%
rename from vue/primitives/src/calendar/__test__/__screenshots__/Calendar.test.ts/Calendar-mounts-cell-triggers-without--expose---should-be-called-only-once--warnings-1.png
rename to vue/primitives/src/canvas/curve-editor/__test__/__screenshots__/CurveEditor.test.ts/CurveEditor-component-Delete-does-not-remove-an-endpoint-1.png
diff --git a/vue/primitives/src/canvas/curve-editor/context.ts b/vue/primitives/src/canvas/curve-editor/context.ts
new file mode 100644
index 0000000..1361169
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/context.ts
@@ -0,0 +1,122 @@
+import type { Ref } from 'vue';
+import type { Point } from '../../internal/utils/geometry';
+import type { UseScaleReturn } from '../../internal/scale';
+import { useContextFactory } from '@robonen/vue';
+
+export type CurveEditorDirection = 'ltr' | 'rtl';
+
+/**
+ * How the curve is interpolated between anchors.
+ * - `'linear'` — straight segments (piecewise-linear).
+ * - `'bezier'` — per-anchor cubic tangents (`inHandle`/`outHandle`), solved for
+ *   `x` so the curve stays a function of `x`.
+ * - `'monotone'` — Fritsch-Carlson monotone cubic (no overshoot; the tone/gamma
+ *   default).
+ * - `'catmull-rom'` — Catmull-Rom spline through the anchors.
+ */
+export type CurveEditorInterpolation = 'linear' | 'bezier' | 'monotone' | 'catmull-rom';
+
+/**
+ * Which curve is being edited. For animation easing this is always `'value'`;
+ * for photo tone curves the consumer switches between the composite `'value'`
+ * curve and the per-channel `'r'`/`'g'`/`'b'` curves. The channel only tags the
+ * curve (for styling / the `#channel` slot) — it does not change the maths.
+ */
+export type CurveEditorChannel = 'value' | 'r' | 'g' | 'b';
+
+/**
+ * A single control point on the curve.
+ *
+ * `x`/`y` are in domain space (`domainX`/`domainY`). `inHandle`/`outHandle` are
+ * bezier tangents **relative** to the anchor (deltas, not absolute points) and
+ * are only consulted in `'bezier'` interpolation.
+ */
+export interface CurveEditorAnchor {
+  /** Stable identity used as the `v-for` key and roving-focus handle. */
+  id: string;
+  /** Input coordinate in `domainX` space. */
+  x: number;
+  /** Output coordinate in `domainY` space. */
+  y: number;
+  /** Incoming bezier tangent, relative to the anchor (`'bezier'` mode only). */
+  inHandle?: Point;
+  /** Outgoing bezier tangent, relative to the anchor (`'bezier'` mode only). */
+  outHandle?: Point;
+}
+
+/**
+ * Which tangent handle of an anchor a `CurveEditorHandle` controls.
+ */
+export type CurveEditorHandleSide = 'in' | 'out';
+
+/**
+ * Context shared between `CurveEditorRoot` and its descendants.
+ *
+ * Scalar props are exposed as plain `Ref<T>` — `CurveEditorRoot` builds them
+ * with `toRef(() => prop)` (a reactive getter ref without an extra effect),
+ * matching the slider / color-area convention.
+ */
+export interface CurveEditorContext {
+  /** The live anchor array (sorted ascending by `x`). */
+  anchors: Ref<CurveEditorAnchor[]>;
+  /** Active interpolation mode. */
+  interpolation: Ref<CurveEditorInterpolation>;
+  /** Input (x) domain `[min, max]`. */
+  domainX: Ref<readonly [number, number]>;
+  /** Output (y) domain `[min, max]`. */
+  domainY: Ref<readonly [number, number]>;
+  /** x-axis value↔pixel projection (horizontal). */
+  scaleX: UseScaleReturn;
+  /** y-axis value↔pixel projection (vertical, value-up). */
+  scaleY: UseScaleReturn;
+  /** Channel tag for styling / the `#channel` slot. */
+  channel: Ref<CurveEditorChannel>;
+  /** Keyboard step for x/y nudges. */
+  step: Ref<number>;
+  /** Large keyboard step (Shift+Arrow / Page keys). */
+  largeStep: Ref<number>;
+  /** Whether x is kept single-valued (neighbour-clamped, anchors can't cross). */
+  monotonicX: Ref<boolean>;
+  /** Whether the first/last anchor are locked in x. */
+  fixedEndpoints: Ref<boolean>;
+  direction: Ref<CurveEditorDirection>;
+  disabled: Ref<boolean>;
+  /** Index of the currently focused anchor (roving focus tab-stop). */
+  activeIndex: Ref<number>;
+  /** Evaluate the curve: input `x` → output `y`. */
+  sample: (x: number) => number;
+  /** Sample the curve into a `size`-length lookup table across `domainX`. */
+  toLUT: (size?: number) => number[];
+  /** Index of an anchor by id (`-1` when absent). */
+  indexOf: (id: string) => number;
+  /** Register an anchor element so roving focus can move between them. */
+  registerAnchorEl: (id: string, el: HTMLElement | null) => void;
+  /** Whether `id` is the first or last anchor (endpoint). */
+  isEndpoint: (id: string) => boolean;
+  /** Move the active anchor to `index` and focus its element. */
+  setActiveIndex: (index: number) => void;
+  /** Move roving focus by `delta` anchors (wraps). */
+  moveFocus: (delta: number) => void;
+  /**
+   * Emit `anchorsCommit` with a snapshot of the current anchors. Called by parts
+   * once a gesture/keypress settles (not per drag frame).
+   */
+  commit: () => void;
+  /**
+   * Update an anchor's `x`/`y` (neighbour + domain clamped, endpoints x-locked).
+   * Returns whether the anchor actually moved (so discrete callers can decide
+   * whether to `commit()`); does not itself emit `anchorsCommit`.
+   */
+  updateAnchor: (id: string, next: { x?: number; y?: number }) => boolean;
+  /** Update an anchor's bezier tangent handle (`'bezier'` mode). */
+  updateHandle: (id: string, side: CurveEditorHandleSide, handle: Point) => void;
+  /** Insert an anchor at `x` (y defaults to the sampled curve value). */
+  addAnchor: (x: number, y?: number) => string | undefined;
+  /** Remove an anchor by id (endpoints are never removed). */
+  removeAnchor: (id: string) => void;
+}
+
+const ctx = useContextFactory<CurveEditorContext>('CurveEditorContext');
+
+export const provideCurveEditorContext = ctx.provide;
+export const useCurveEditorContext = ctx.inject;
diff --git a/vue/primitives/src/canvas/curve-editor/demo.vue b/vue/primitives/src/canvas/curve-editor/demo.vue
new file mode 100644
index 0000000..b71ccb7
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/demo.vue
@@ -0,0 +1,183 @@
+<script setup lang="ts">
+import type { CurveEditorAnchor, CurveEditorChannel } from '@robonen/primitives';
+import {
+  CurveEditorCurve,
+  CurveEditorGrid,
+  CurveEditorPoint,
+  CurveEditorRoot,
+  buildEvaluator,
+} from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+// A tone curve with a gentle S-shape: lifted shadows, pulled highlights.
+const anchors = ref<CurveEditorAnchor[]>([
+  { id: 'a', x: 0, y: 0 },
+  { id: 'b', x: 0.28, y: 0.18 },
+  { id: 'c', x: 0.72, y: 0.86 },
+  { id: 'd', x: 1, y: 1 },
+]);
+
+// Mirror the Root's evaluator with the exported `buildEvaluator` so the readout
+// table below can show the curve's output at a few fixed inputs (same monotone
+// interpolation the Root uses).
+const sampleFn = computed(() => buildEvaluator(anchors.value, 'monotone'));
+const probes = [0, 0.25, 0.5, 0.75, 1];
+const readout = computed(() => probes.map(x => ({ x, y: sampleFn.value(x) })));
+
+// Channel toggle — purely cosmetic here (tags the curve / data-channel), but it
+// drives the accent color of the curve and points.
+const channel = ref<CurveEditorChannel>('value');
+const channels: Array<{ id: CurveEditorChannel; label: string }> = [
+  { id: 'value', label: 'Value' },
+  { id: 'r', label: 'Red' },
+  { id: 'g', label: 'Green' },
+  { id: 'b', label: 'Blue' },
+];
+
+const channelColor = computed(() => {
+  switch (channel.value) {
+    case 'r': return '#ef4444';
+    case 'g': return '#22c55e';
+    case 'b': return '#3b82f6';
+    default: return 'var(--color-accent, #6366f1)';
+  }
+});
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-md space-y-4 bg-bg p-6 text-fg">
+    <!-- Channel tabs -->
+    <div class="flex items-center justify-between">
+      <span class="text-sm font-medium">Tone curve</span>
+      <div class="flex gap-1 rounded-lg bg-bg-inset p-0.5">
+        <button
+          v-for="c in channels"
+          :key="c.id"
+          type="button"
+          class="rounded-md px-2.5 py-1 text-xs font-medium transition outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          :class="channel === c.id
+            ? 'bg-bg-elevated text-fg shadow-(--shadow-card)'
+            : 'text-fg-muted hover:text-fg'"
+          @click="channel = c.id"
+        >
+          {{ c.label }}
+        </button>
+      </div>
+    </div>
+
+    <!-- Plot. The Root measures its OWN box as the plot, so it gets an explicit
+         size + relative positioning; absolutely-positioned SVG (grid + curve)
+         and the draggable Point thumbs all read pixel coords from that box. -->
+    <CurveEditorRoot
+      v-model="anchors"
+      :channel="channel"
+      interpolation="monotone"
+      :domain-x="[0, 1]"
+      :domain-y="[0, 1]"
+      class="relative aspect-square w-full touch-none select-none overflow-hidden rounded-card border border-border bg-bg-inset"
+      :style="{ '--curve-color': channelColor }"
+    >
+      <template #default>
+        <svg
+          class="pointer-events-none absolute inset-0 h-full w-full"
+          aria-hidden="true"
+        >
+          <!-- Gridlines from niceTicks on each axis (decorative). -->
+          <CurveEditorGrid v-slot="{ xTicks, yTicks }">
+            <line
+              v-for="t in xTicks"
+              :key="`x-${t.value}`"
+              :x1="t.px"
+              :y1="0"
+              :x2="t.px"
+              y2="100%"
+              class="stroke-border"
+              stroke-width="1"
+            />
+            <line
+              v-for="t in yTicks"
+              :key="`y-${t.value}`"
+              x1="0"
+              :y1="t.px"
+              x2="100%"
+              :y2="t.px"
+              class="stroke-border"
+              stroke-width="1"
+            />
+          </CurveEditorGrid>
+
+          <!-- Soft fill under the curve + the curve stroke itself. -->
+          <CurveEditorCurve v-slot="{ d }" as="g">
+            <!-- Close the stroked curve down to the bottom for a soft area fill.
+                 `V/H` use unitless user-space px; the huge V is clipped by the
+                 plot's `overflow-hidden`, so it always reaches the bottom edge. -->
+            <path
+              v-if="d"
+              :d="`${d} V 9999 H 0 Z`"
+              :fill="channelColor"
+              fill-opacity="0.10"
+              stroke="none"
+            />
+            <path
+              :d="d"
+              fill="none"
+              :stroke="channelColor"
+              stroke-width="2.5"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+          </CurveEditorCurve>
+        </svg>
+
+        <!-- Draggable anchor thumbs. Each Point sets its own left/top (px).
+             The `active`/`endpoint` slot props are scoped to the slot CHILDREN,
+             so the conditional styling lives on the inner span, not on the
+             CurveEditorPoint element's own `:class`. -->
+        <CurveEditorPoint
+          v-for="a in anchors"
+          :key="a.id"
+          v-slot="{ active, endpoint }"
+          :anchor="a"
+          class="absolute z-10 -translate-x-1/2 -translate-y-1/2 cursor-grab rounded-full outline-none active:cursor-grabbing focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <span
+            class="block h-3.5 w-3.5 rounded-full border-2 bg-bg shadow-sm transition hover:scale-125"
+            :style="{ borderColor: 'var(--curve-color)' }"
+            :class="[
+              active ? 'scale-125 ring-2 ring-ring' : '',
+              endpoint ? 'rounded-sm' : '',
+            ]"
+          />
+          <span class="sr-only">{{ endpoint ? 'Endpoint' : 'Anchor' }}</span>
+        </CurveEditorPoint>
+      </template>
+    </CurveEditorRoot>
+
+    <!-- Sampled readout: f(x) at a few fixed inputs. -->
+    <div class="space-y-1.5 rounded-card bg-bg-inset p-3">
+      <div class="flex items-center justify-between text-xs text-fg-subtle">
+        <span>input x</span>
+        <span>output f(x)</span>
+      </div>
+      <div
+        v-for="p in readout"
+        :key="p.x"
+        class="flex items-center gap-3"
+      >
+        <span class="w-8 font-mono text-xs text-fg-muted">{{ p.x.toFixed(2) }}</span>
+        <div class="relative h-1.5 flex-1 overflow-hidden rounded-full bg-bg-elevated">
+          <div
+            class="absolute inset-y-0 left-0 rounded-full"
+            :style="{ width: `${Math.round(p.y * 100)}%`, backgroundColor: channelColor }"
+          />
+        </div>
+        <span class="w-10 text-right font-mono text-xs tabular-nums text-fg">{{ p.y.toFixed(3) }}</span>
+      </div>
+    </div>
+
+    <p class="text-xs text-fg-subtle">
+      Drag the anchors. Double-click an endpoint to add a point, or an interior
+      point to remove it. Arrow keys nudge the focused anchor.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/curve-editor/index.ts b/vue/primitives/src/canvas/curve-editor/index.ts
new file mode 100644
index 0000000..7273afb
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/index.ts
@@ -0,0 +1,31 @@
+export { default as CurveEditorRoot } from './CurveEditorRoot.vue';
+export { default as CurveEditorCurve } from './CurveEditorCurve.vue';
+export { default as CurveEditorGrid } from './CurveEditorGrid.vue';
+export { default as CurveEditorHandle } from './CurveEditorHandle.vue';
+export { default as CurveEditorPoint } from './CurveEditorPoint.vue';
+
+export type { CurveEditorRootEmits, CurveEditorRootProps } from './CurveEditorRoot.vue';
+export type { CurveEditorCurveProps } from './CurveEditorCurve.vue';
+export type { CurveEditorGridProps } from './CurveEditorGrid.vue';
+export type { CurveEditorHandleProps } from './CurveEditorHandle.vue';
+export type { CurveEditorPointProps } from './CurveEditorPoint.vue';
+
+export {
+  type CurveEditorAnchor,
+  type CurveEditorChannel,
+  type CurveEditorContext,
+  type CurveEditorDirection,
+  type CurveEditorHandleSide,
+  type CurveEditorInterpolation,
+  provideCurveEditorContext,
+  useCurveEditorContext,
+} from './context';
+
+export {
+  anchorsToPoints,
+  buildEvaluator,
+  clampAnchorX,
+  clampAnchorY,
+  formatAnchorValueText,
+  sortAnchors,
+} from './utils';
diff --git a/vue/primitives/src/canvas/curve-editor/utils.ts b/vue/primitives/src/canvas/curve-editor/utils.ts
new file mode 100644
index 0000000..d5ac56f
--- /dev/null
+++ b/vue/primitives/src/canvas/curve-editor/utils.ts
@@ -0,0 +1,257 @@
+import type { Point } from '../../internal/utils/geometry';
+import type { CurveEditorAnchor, CurveEditorInterpolation } from './context';
+import { catmullRom, evalCubicBezier, linearInterpolate, monotoneCubic } from '../../internal/spline';
+
+/**
+ * Sort anchors ascending by `x`, returning a new array (never mutating the
+ * input). Stable for equal `x` (preserves insertion order), so monotonic-x
+ * neighbour-clamping keeps a deterministic order.
+ */
+export function sortAnchors(anchors: readonly CurveEditorAnchor[]): CurveEditorAnchor[] {
+  return anchors
+    .map((a, i) => [a, i] as const)
+    .sort((p, q) => (p[0].x - q[0].x) || (p[1] - q[1]))
+    .map(p => p[0]);
+}
+
+/**
+ * Project anchors onto bare `Point`s (`{ x, y }`), dropping bezier handles. The
+ * shape the spline samplers consume.
+ */
+export function anchorsToPoints(anchors: readonly CurveEditorAnchor[]): Point[] {
+  const out: Point[] = Array.from({ length: anchors.length });
+  for (let i = 0; i < anchors.length; i++) {
+    const a = anchors[i]!;
+    out[i] = { x: a.x, y: a.y };
+  }
+  return out;
+}
+
+/**
+ * Build a `y = f(x)` evaluator from `anchors` for the given `interpolation`
+ * mode. Anchors are assumed sorted ascending by `x`. Out-of-range `x` clamps to
+ * the endpoint y (every mode is range-clamped, matching the spline helpers).
+ *
+ * - `'linear'` → {@link linearInterpolate}.
+ * - `'monotone'` → {@link monotoneCubic} (Fritsch-Carlson, no overshoot — the
+ *   tone/gamma default).
+ * - `'catmull-rom'` → {@link catmullRom} sampled by `x` (resampled to a dense
+ *   monotone-x table so it stays a function of `x`).
+ * - `'bezier'` → per-segment cubic from each anchor's `outHandle`/`inHandle`
+ *   tangents, solved for `x` via a Newton-Raphson search so the curve remains
+ *   single-valued in `x`.
+ *
+ * The returned closure is allocation-free per call (it closes over precomputed
+ * arrays), so it is cheap on the render / LUT hot path.
+ */
+export function buildEvaluator(
+  anchors: readonly CurveEditorAnchor[],
+  interpolation: CurveEditorInterpolation,
+): (x: number) => number {
+  const n = anchors.length;
+  if (n === 0)
+    return () => 0;
+  if (n === 1) {
+    const y = anchors[0]!.y;
+    return () => y;
+  }
+
+  const points = anchorsToPoints(anchors);
+
+  switch (interpolation) {
+    case 'linear':
+      return (x: number) => linearInterpolate(points, x);
+
+    case 'monotone':
+      return monotoneCubic(points);
+
+    case 'catmull-rom':
+      return buildCatmullRomEvaluator(points);
+
+    case 'bezier':
+      return buildBezierEvaluator(anchors);
+
+    default:
+      return monotoneCubic(points);
+  }
+}
+
+/** Default density for resampling a parametric spline into a monotone-x table. */
+const RESAMPLE = 256;
+
+/**
+ * Catmull-Rom is parametric (`t → Point`), so it can fold back on itself in `x`.
+ * For a single-valued `y = f(x)` curve we sample it densely in `t`, then build a
+ * piecewise-linear lookup by `x`. The result passes through every anchor (the
+ * spline interpolates its control points) and is monotone-clamped at the ends.
+ */
+function buildCatmullRomEvaluator(points: Point[]): (x: number) => number {
+  const samples: Point[] = Array.from({ length: RESAMPLE + 1 });
+  for (let i = 0; i <= RESAMPLE; i++)
+    samples[i] = catmullRom(points, i / RESAMPLE);
+  // The sampled x's are not guaranteed strictly increasing, but for a curve that
+  // is monotone in x (the editor enforces this) they are non-decreasing, so a
+  // linear lookup by x is well-defined.
+  return (x: number) => linearInterpolate(samples, x);
+}
+
+/**
+ * Build the per-segment cubic-bezier evaluator. Between anchors `a` and `b` the
+ * control points are `a + a.outHandle` and `b + b.inHandle` (handles are deltas
+ * relative to their anchor); absent handles default to one-third of the segment
+ * (a straight-through tangent), giving a linear segment. Each segment is solved
+ * for `t` from `x` with Newton-Raphson + bisection so the curve stays a function
+ * of `x`.
+ */
+function buildBezierEvaluator(anchors: readonly CurveEditorAnchor[]): (x: number) => number {
+  const n = anchors.length;
+  const xs: number[] = Array.from({ length: n });
+  for (let i = 0; i < n; i++)
+    xs[i] = anchors[i]!.x;
+
+  return (x: number): number => {
+    const first = anchors[0]!;
+    const last = anchors[n - 1]!;
+    if (x <= first.x)
+      return first.y;
+    if (x >= last.x)
+      return last.y;
+
+    // Binary search for the segment [lo, lo+1] containing x.
+    let lo = 0;
+    let hi = n - 1;
+    while (hi - lo > 1) {
+      const mid = (lo + hi) >> 1;
+      if (xs[mid]! <= x)
+        lo = mid;
+      else
+        hi = mid;
+    }
+
+    const a = anchors[lo]!;
+    const b = anchors[lo + 1]!;
+    const dx = b.x - a.x;
+    if (dx === 0)
+      return a.y;
+
+    // Default tangents (one-third along the segment) when a handle is missing.
+    const c1: Point = a.outHandle
+      ? { x: a.x + a.outHandle.x, y: a.y + a.outHandle.y }
+      : { x: a.x + dx / 3, y: a.y + (b.y - a.y) / 3 };
+    const c2: Point = b.inHandle
+      ? { x: b.x + b.inHandle.x, y: b.y + b.inHandle.y }
+      : { x: b.x - dx / 3, y: b.y - (b.y - a.y) / 3 };
+
+    const t = solveSegmentT(a.x, c1.x, c2.x, b.x, x);
+    return evalCubicBezier(a, c1, c2, b, t).y;
+  };
+}
+
+/**
+ * Solve `x(t) = target` on a cubic whose x-components are `x0..x3` (general
+ * endpoints, unlike `solveBezierX` which assumes 0/1). Newton-Raphson from a
+ * normalized initial guess, with a bisection fallback.
+ */
+function solveSegmentT(x0: number, x1: number, x2: number, x3: number, target: number, epsilon = 1e-6): number {
+  const sampleX = (t: number): number => {
+    const u = 1 - t;
+    return u * u * u * x0 + 3 * u * u * t * x1 + 3 * u * t * t * x2 + t * t * t * x3;
+  };
+  const sampleDX = (t: number): number => {
+    const u = 1 - t;
+    return 3 * u * u * (x1 - x0) + 6 * u * t * (x2 - x1) + 3 * t * t * (x3 - x2);
+  };
+
+  const span = x3 - x0;
+  let t = span === 0 ? 0 : (target - x0) / span;
+  t = Math.min(Math.max(t, 0), 1);
+
+  for (let i = 0; i < 8; i++) {
+    const fx = sampleX(t) - target;
+    if (Math.abs(fx) < epsilon)
+      return t;
+    const dx = sampleDX(t);
+    if (Math.abs(dx) < epsilon)
+      break;
+    t -= fx / dx;
+    t = Math.min(Math.max(t, 0), 1);
+  }
+
+  let lo = 0;
+  let hi = 1;
+  t = Math.min(Math.max(span === 0 ? 0 : (target - x0) / span, 0), 1);
+  for (let i = 0; i < 32 && hi - lo > epsilon; i++) {
+    const fx = sampleX(t);
+    if (Math.abs(fx - target) < epsilon)
+      return t;
+    if (target > fx)
+      lo = t;
+    else
+      hi = t;
+    t = (lo + hi) / 2;
+  }
+  return t;
+}
+
+/**
+ * Clamp a candidate `x` for the anchor at `index` so it stays strictly between
+ * its neighbours (when `monotonicX`) by at least `minGap`, and within
+ * `[domainMin, domainMax]`. Endpoints are pinned to the domain edge when
+ * `fixedEndpoints`.
+ */
+export function clampAnchorX(
+  anchors: readonly CurveEditorAnchor[],
+  index: number,
+  x: number,
+  options: {
+    domainMin: number;
+    domainMax: number;
+    monotonicX: boolean;
+    fixedEndpoints: boolean;
+    minGap: number;
+  },
+): number {
+  const { domainMin, domainMax, monotonicX, fixedEndpoints, minGap } = options;
+  const lo = Math.min(domainMin, domainMax);
+  const hi = Math.max(domainMin, domainMax);
+  const isFirst = index === 0;
+  const isLast = index === anchors.length - 1;
+
+  if (fixedEndpoints && isFirst)
+    return lo;
+  if (fixedEndpoints && isLast)
+    return hi;
+
+  let v = Math.min(Math.max(x, lo), hi);
+  if (monotonicX) {
+    const prev = anchors[index - 1];
+    const next = anchors[index + 1];
+    if (prev !== undefined)
+      v = Math.max(v, prev.x + minGap);
+    if (next !== undefined)
+      v = Math.min(v, next.x - minGap);
+  }
+  return v;
+}
+
+/** Clamp a candidate `y` into `[domainMin, domainMax]` (order-agnostic). */
+export function clampAnchorY(y: number, domainMin: number, domainMax: number): number {
+  const lo = Math.min(domainMin, domainMax);
+  const hi = Math.max(domainMin, domainMax);
+  return Math.min(Math.max(y, lo), hi);
+}
+
+/**
+ * Format the default `aria-valuetext` for an anchor: a 2-coordinate control
+ * whose single `aria-valuenow` can't carry both axes, so both the input (x) and
+ * output (y) are announced.
+ */
+export function formatAnchorValueText(x: number, y: number, decimals = 2): string {
+  return `input ${round(x, decimals)}, output ${round(y, decimals)}`;
+}
+
+/** Round to `decimals` places, trimming float noise (no trailing-zero padding). */
+export function round(value: number, decimals: number): number {
+  const f = 10 ** decimals;
+  return Math.round(value * f) / f;
+}
diff --git a/vue/primitives/src/canvas/flow/FlowBackground.vue b/vue/primitives/src/canvas/flow/FlowBackground.vue
new file mode 100644
index 0000000..dd86c77
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowBackground.vue
@@ -0,0 +1,90 @@
+<script lang="ts">
+export type FlowBackgroundVariant = 'dots' | 'lines' | 'cross';
+
+/**
+ * A grid background drawn as an SVG `<pattern>` that pans and zooms with the
+ * viewport (the pattern origin shifts by `viewport % (gap·zoom)` and its cell
+ * scales by `zoom`). Sits behind the viewport layer, ignores pointer events, and
+ * is fully styleable via `[data-flow-background]` / `currentColor`.
+ */
+export interface FlowBackgroundProps {
+  /** Pattern style. @default 'dots' */
+  variant?: FlowBackgroundVariant;
+  /** Grid spacing in flow units (single value or `[x, y]`). @default 20 */
+  gap?: number | [number, number];
+  /** Dot radius / line thickness in px. @default 1 */
+  size?: number;
+  /** Pattern colour. @default 'currentColor' */
+  color?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useFlowContext } from './context';
+
+const { variant = 'dots', gap = 20, size = 1, color = 'currentColor' } = defineProps<FlowBackgroundProps>();
+
+const ctx = useFlowContext();
+const patternId = computed(() => `${ctx.flowId}__bg`);
+
+const gapXY = computed<[number, number]>(() => (Array.isArray(gap) ? gap : [gap, gap]));
+
+const scaled = computed(() => {
+  const vp = ctx.viewport.value;
+  return {
+    w: gapXY.value[0] * vp.zoom,
+    h: gapXY.value[1] * vp.zoom,
+    x: vp.x % (gapXY.value[0] * vp.zoom),
+    y: vp.y % (gapXY.value[1] * vp.zoom),
+    s: size * vp.zoom,
+  };
+});
+
+// Path for line / cross variants, drawn at the cell origin.
+const linePath = computed(() => {
+  const { w, h } = scaled.value;
+  return variant === 'cross'
+    ? `M ${w / 2} ${h / 2 - 3} V ${h / 2 + 3} M ${w / 2 - 3} ${h / 2} H ${w / 2 + 3}`
+    : `M ${w} 0 H 0 V ${h}`;
+});
+</script>
+
+<template>
+  <svg
+    data-flow-background=""
+    :data-variant="variant"
+    :style="{ position: 'absolute', inset: '0', width: '100%', height: '100%', pointerEvents: 'none', color }"
+  >
+    <pattern
+      :id="patternId"
+      :x="scaled.x"
+      :y="scaled.y"
+      :width="scaled.w"
+      :height="scaled.h"
+      patternUnits="userSpaceOnUse"
+    >
+      <circle
+        v-if="variant === 'dots'"
+        :cx="scaled.w / 2"
+        :cy="scaled.h / 2"
+        :r="scaled.s"
+        fill="currentColor"
+      />
+      <path
+        v-else
+        :d="linePath"
+        fill="none"
+        stroke="currentColor"
+        :stroke-width="scaled.s"
+      />
+    </pattern>
+    <rect
+      x="0"
+      y="0"
+      width="100%"
+      height="100%"
+      :fill="`url(#${patternId})`"
+    />
+  </svg>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowConnectionLine.vue b/vue/primitives/src/canvas/flow/FlowConnectionLine.vue
new file mode 100644
index 0000000..380c64c
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowConnectionLine.vue
@@ -0,0 +1,57 @@
+<script lang="ts">
+/**
+ * Live preview path drawn while a connection is being dragged from a handle to
+ * the pointer. Renders nothing when no connection is in progress. Only this
+ * component (and the hovered handle) subscribes to `connection`, so dragging a
+ * connection does not re-render nodes or committed edges. Override the visual via
+ * the default slot.
+ */
+export type FlowConnectionLineProps = Record<string, never>;
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useFlowContext } from './context';
+import { getBezierPath } from './edge-paths';
+
+const ctx = useFlowContext();
+const connection = computed(() => ctx.connection.value);
+
+const path = computed(() => {
+  const c = connection.value;
+  if (!c.inProgress || !c.fromPosition || !c.toPosition) return null;
+  const [d] = getBezierPath({
+    sourceX: c.fromPosition.x,
+    sourceY: c.fromPosition.y,
+    sourcePosition: c.fromHandle?.position ?? 'bottom',
+    targetX: c.toPosition.x,
+    targetY: c.toPosition.y,
+    targetPosition: 'top',
+  });
+  return d;
+});
+</script>
+
+<template>
+  <g
+    v-if="path"
+    data-flow-connection-line=""
+    :data-valid="connection.isValid === true ? '' : undefined"
+    :data-invalid="connection.isValid === false ? '' : undefined"
+  >
+    <slot
+      :from="connection.fromPosition"
+      :to="connection.toPosition"
+      :valid="connection.isValid"
+      :path="path"
+    >
+      <path
+        :d="path"
+        fill="none"
+        stroke="currentColor"
+        :stroke-width="1"
+        :style="{ pointerEvents: 'none' }"
+      />
+    </slot>
+  </g>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowControls.vue b/vue/primitives/src/canvas/flow/FlowControls.vue
new file mode 100644
index 0000000..e338007
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowControls.vue
@@ -0,0 +1,59 @@
+<script lang="ts">
+import type { FlowPanelPosition } from './FlowPanel.vue';
+
+/**
+ * Zoom-in / zoom-out / fit-view button cluster, hosted in a `FlowPanel`. Headless
+ * — every button is unstyled with a `data-flow-control` hook and an overridable
+ * icon slot (`#zoom-in`, `#zoom-out`, `#fit-view`); add more buttons via the
+ * default slot. Drives the canvas through `useFlow`.
+ */
+export interface FlowControlsProps {
+  /** Panel anchor. @default 'bottom-left' */
+  position?: FlowPanelPosition;
+  /** Accessible group label. @default 'Flow controls' */
+  ariaLabel?: string;
+}
+</script>
+
+<script setup lang="ts">
+import FlowPanel from './FlowPanel.vue';
+import { useFlow } from './composables/useFlow';
+
+const { position = 'bottom-left', ariaLabel = 'Flow controls' } = defineProps<FlowControlsProps>();
+const api = useFlow();
+</script>
+
+<template>
+  <FlowPanel
+    :position="position"
+    data-flow-controls=""
+    role="group"
+    :aria-label="ariaLabel"
+  >
+    <button
+      type="button"
+      data-flow-control="zoom-in"
+      aria-label="Zoom in"
+      @click="api.zoomIn()"
+    >
+      <slot name="zoom-in">+</slot>
+    </button>
+    <button
+      type="button"
+      data-flow-control="zoom-out"
+      aria-label="Zoom out"
+      @click="api.zoomOut()"
+    >
+      <slot name="zoom-out">−</slot>
+    </button>
+    <button
+      type="button"
+      data-flow-control="fit-view"
+      aria-label="Fit view"
+      @click="api.fitView()"
+    >
+      <slot name="fit-view">⊡</slot>
+    </button>
+    <slot />
+  </FlowPanel>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowEdge.vue b/vue/primitives/src/canvas/flow/FlowEdge.vue
new file mode 100644
index 0000000..a437f9c
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowEdge.vue
@@ -0,0 +1,181 @@
+<script lang="ts">
+import type { CSSProperties, Component } from 'vue';
+
+/**
+ * One edge. Reads only its own entry from `edgeLookup`, resolves endpoints from
+ * the source/target nodes' measured handle bounds (falling back to side
+ * centres), picks the path builder by `edge.type`, and memoizes the `d` string.
+ * Renders a visible path plus a transparent fat interaction path for hit-testing
+ * (no JS hit math). Customise via `#edge-<type>` slot or the `edgeTypes` map; the
+ * slot receives every path builder for full control.
+ */
+export interface FlowEdgeProps {
+  /** Edge id; matches the render key. */
+  id: string;
+  /** Component map keyed by `edge.type` (forwarded from the renderer). */
+  edgeTypes?: Record<string, Component>;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useSlots } from 'vue';
+import { useFlowContext } from './context';
+import type { EdgeMarkerType } from './types';
+import type { PathResult } from './edge-paths';
+import { getBezierPath, getMarkerId, getSmoothStepPath, getStepPath, getStraightPath } from './edge-paths';
+import { findHandle, getAbsoluteHandlePoint, getDefaultEndpoint } from './utils';
+
+const { id, edgeTypes } = defineProps<FlowEdgeProps>();
+
+const ctx = useFlowContext();
+const slots = useSlots();
+
+const edge = computed(() => ctx.edgeLookup.value.get(id));
+const sourceNode = computed(() => (edge.value ? ctx.nodeLookup.value.get(edge.value.source) : undefined));
+const targetNode = computed(() => (edge.value ? ctx.nodeLookup.value.get(edge.value.target) : undefined));
+const selected = computed(() => ctx.selection.value.edges.has(id));
+const resolvedType = computed(() => edge.value?.type ?? 'default');
+
+const endpoints = computed(() => {
+  const e = edge.value;
+  const s = sourceNode.value;
+  const t = targetNode.value;
+  if (!e || !s || !t) return null;
+
+  const sHandle = findHandle(s, 'source', e.sourceHandle);
+  const tHandle = findHandle(t, 'target', e.targetHandle);
+  const sPos = sHandle?.position ?? s.sourcePosition ?? 'bottom';
+  const tPos = tHandle?.position ?? t.targetPosition ?? 'top';
+  const sp = sHandle ? getAbsoluteHandlePoint(s.positionAbsolute, sHandle) : getDefaultEndpoint(s, sPos);
+  const tp = tHandle ? getAbsoluteHandlePoint(t.positionAbsolute, tHandle) : getDefaultEndpoint(t, tPos);
+  return { sp, tp, sPos, tPos };
+});
+
+const path = computed<PathResult>(() => {
+  const ep = endpoints.value;
+  if (!ep) return ['', 0, 0, 0, 0];
+  const params = {
+    sourceX: ep.sp.x,
+    sourceY: ep.sp.y,
+    sourcePosition: ep.sPos,
+    targetX: ep.tp.x,
+    targetY: ep.tp.y,
+    targetPosition: ep.tPos,
+  };
+  switch (resolvedType.value) {
+    case 'straight': return getStraightPath(params);
+    case 'step': return getStepPath(params);
+    case 'smoothstep': return getSmoothStepPath(params);
+    default: return getBezierPath(params);
+  }
+});
+
+const slotName = computed(() => {
+  const key = `edge-${resolvedType.value}`;
+  if (slots[key]) return key;
+  if (slots['edge']) return 'edge';
+  return null;
+});
+const TypeComponent = computed(() => edgeTypes?.[resolvedType.value]);
+
+const slotProps = computed(() => {
+  const ep = endpoints.value;
+  const e = edge.value;
+  const [d, labelX, labelY] = path.value;
+  return {
+    id,
+    source: e?.source,
+    target: e?.target,
+    sourceX: ep?.sp.x ?? 0,
+    sourceY: ep?.sp.y ?? 0,
+    targetX: ep?.tp.x ?? 0,
+    targetY: ep?.tp.y ?? 0,
+    sourcePosition: ep?.sPos,
+    targetPosition: ep?.tPos,
+    selected: selected.value,
+    animated: e?.animated ?? false,
+    data: e?.data,
+    label: e?.label,
+    markerStart: e?.markerStart,
+    markerEnd: e?.markerEnd,
+    markerStartUrl: markerStartRef.value,
+    markerEndUrl: markerEndRef.value,
+    path: d,
+    labelX,
+    labelY,
+    getBezierPath,
+    getSmoothStepPath,
+    getStraightPath,
+    getStepPath,
+  };
+});
+
+function markerRef(marker: EdgeMarkerType | undefined): string | undefined {
+  if (!marker) return undefined;
+  if (typeof marker === 'string') return marker.startsWith('url(') ? marker : `url(#${marker})`;
+  return `url(#${getMarkerId(marker, ctx.flowId)})`;
+}
+const markerStartRef = computed(() => markerRef(edge.value?.markerStart));
+const markerEndRef = computed(() => markerRef(edge.value?.markerEnd));
+
+// Stable style objects (avoid allocating a fresh object on every edge render,
+// which happens for incident edges on every pan/node-drag frame).
+const visiblePathStyle = { pointerEvents: 'none' } as const;
+// Only two outcomes exist (selectable vs not), so select between two frozen
+// constants instead of allocating a fresh { pointerEvents, cursor } object each
+// time edge.value identity changes (every drag/pan frame for incident edges).
+const INTERACTION_STROKE = { pointerEvents: 'stroke', cursor: 'pointer' } as const;
+const INTERACTION_NONE = { pointerEvents: 'none', cursor: 'pointer' } as const;
+const interactionPathStyle = computed<CSSProperties>(() =>
+  edge.value?.selectable === false ? INTERACTION_NONE : INTERACTION_STROKE,
+);
+
+function onPointerdown(event: PointerEvent): void {
+  if (event.button !== 0 || edge.value?.selectable === false || !ctx.elementsSelectable.value) return;
+  event.stopPropagation();
+  ctx.selectEdge(id, event.shiftKey || event.metaKey || event.ctrlKey);
+}
+</script>
+
+<template>
+  <g
+    v-if="endpoints"
+    v-memo="[path[0], selected, edge?.animated, edge?.selectable, edge?.data, markerStartRef, markerEndRef]"
+    data-flow-edge=""
+    :data-id="id"
+    :data-type="resolvedType"
+    :data-selected="selected ? '' : undefined"
+    :data-animated="edge?.animated ? '' : undefined"
+  >
+    <slot
+      v-if="slotName"
+      :name="slotName"
+      v-bind="slotProps"
+    />
+    <component
+      :is="TypeComponent"
+      v-else-if="TypeComponent"
+      v-bind="slotProps"
+    />
+    <template v-else>
+      <path
+        :d="path[0]"
+        data-flow-edge-path=""
+        fill="none"
+        stroke="currentColor"
+        :stroke-width="1"
+        :marker-start="markerStartRef"
+        :marker-end="markerEndRef"
+        :style="visiblePathStyle"
+      />
+      <path
+        :d="path[0]"
+        fill="none"
+        stroke="transparent"
+        :stroke-width="20"
+        :style="interactionPathStyle"
+        @pointerdown="onPointerdown"
+      />
+    </template>
+  </g>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowEdgeRenderer.vue b/vue/primitives/src/canvas/flow/FlowEdgeRenderer.vue
new file mode 100644
index 0000000..9aa77e9
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowEdgeRenderer.vue
@@ -0,0 +1,107 @@
+<script lang="ts">
+import type { Component } from 'vue';
+
+/**
+ * The single shared `<svg>` for all edges, living inside the viewport transform
+ * so edge coordinates are plain flow-space numbers. `overflow:visible` lets
+ * paths draw outside the nominal box; `pointer-events:none` here, re-enabled per
+ * edge on the fat interaction path. Markers are deduped into one `<defs>`.
+ * Rendered under the nodes (earlier in DOM) so nodes paint on top.
+ */
+export interface FlowEdgeRendererProps {
+  edgeTypes?: Record<string, Component>;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useSlots } from 'vue';
+import { useFlowContext } from './context';
+import type { EdgeMarker } from './types';
+import { getMarkerId } from './edge-paths';
+import FlowEdge from './FlowEdge.vue';
+import FlowConnectionLine from './FlowConnectionLine.vue';
+
+defineProps<FlowEdgeRendererProps>();
+defineOptions({ inheritAttrs: false });
+
+const ctx = useFlowContext();
+const slots = useSlots();
+// Stable name list — avoids new dynamic-slot identities per render.
+const edgeSlotNames = computed(() => Object.keys(slots).filter(n => n !== 'defs' && n !== 'connection-line'));
+
+/** Deduped set of object markers across all edges, rendered once in `<defs>`. */
+const markers = computed(() => {
+  const map = new Map<string, EdgeMarker>();
+  for (const edge of ctx.edgeLookup.value.values()) {
+    for (const marker of [edge.markerStart, edge.markerEnd]) {
+      if (marker && typeof marker === 'object') {
+        const mid = getMarkerId(marker, ctx.flowId);
+        if (!map.has(mid)) map.set(mid, marker);
+      }
+    }
+  }
+  return [...map.entries()].map(([id, marker]) => ({ id, marker }));
+});
+</script>
+
+<template>
+  <svg
+    data-flow-edges=""
+    :style="{ position: 'absolute', top: '0', left: '0', width: '100%', height: '100%', overflow: 'visible', pointerEvents: 'none' }"
+  >
+    <defs>
+      <marker
+        v-for="{ id, marker } in markers"
+        :id="id"
+        :key="id"
+        viewBox="-10 -10 20 20"
+        :markerWidth="marker.width ?? 12"
+        :markerHeight="marker.height ?? 12"
+        :markerUnits="marker.markerUnits ?? 'strokeWidth'"
+        :orient="marker.orient ?? 'auto-start-reverse'"
+        refX="0"
+        refY="0"
+      >
+        <polyline
+          :stroke="marker.color ?? 'currentColor'"
+          :fill="marker.type === 'arrowclosed' ? (marker.color ?? 'currentColor') : 'none'"
+          :stroke-width="marker.strokeWidth ?? 1"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          :points="marker.type === 'arrowclosed' ? '-5,-4 0,0 -5,4 -5,-4' : '-5,-4 0,0 -5,4'"
+        />
+      </marker>
+      <slot name="defs" />
+    </defs>
+
+    <FlowEdge
+      v-for="id in ctx.visibleEdgeIds.value"
+      :id="id"
+      :key="id"
+      :edge-types="edgeTypes"
+    >
+      <template
+        v-for="name in edgeSlotNames"
+        :key="name"
+        #[name]="sp"
+      >
+        <slot
+          :name="name"
+          v-bind="sp ?? {}"
+        />
+      </template>
+    </FlowEdge>
+
+    <FlowConnectionLine>
+      <template
+        v-if="$slots['connection-line']"
+        #default="sp"
+      >
+        <slot
+          name="connection-line"
+          v-bind="sp ?? {}"
+        />
+      </template>
+    </FlowConnectionLine>
+  </svg>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowHandle.vue b/vue/primitives/src/canvas/flow/FlowHandle.vue
new file mode 100644
index 0000000..4f9e841
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowHandle.vue
@@ -0,0 +1,91 @@
+<script lang="ts">
+import type { CSSProperties } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { HandleType, IsValidConnection, Position } from './types';
+
+/**
+ * A connection anchor placed inside a custom node. Registers itself with the
+ * node sub-context (triggering a re-measure of handle geometry), positions
+ * itself on the given side by default, and starts a connection on pointerdown.
+ * The visual (size/colour) is the consumer's via `[data-flow-handle]`; only the
+ * side positioning is applied inline. `data-handleid` / `data-handletype` /
+ * `data-handlepos` drive measurement and styling hooks.
+ */
+export interface FlowHandleProps extends PrimitiveProps {
+  /** Whether this handle starts (`source`) or ends (`target`) connections. */
+  type: HandleType;
+  /** Side of the node the handle sits on. */
+  position: Position;
+  /** Handle id; required when a node has multiple handles of one type. */
+  id?: string | null;
+  /** Per-handle connect enable (defaults to the node's `connectable`). */
+  isConnectable?: boolean;
+  /** Per-handle connection validator (composed with the global one). */
+  isValidConnection?: IsValidConnection;
+}
+
+// Module-level: shared across every handle instance, never mutated (Vue style
+// binding only reads). Avoids rebuilding a style object per render/per drag frame.
+const BASE: CSSProperties = { position: 'absolute', transform: 'translate(-50%, -50%)', pointerEvents: 'all' };
+const POSITION_STYLES: Record<Position, CSSProperties> = {
+  top: { ...BASE, top: '0', left: '50%' },
+  bottom: { ...BASE, top: '100%', left: '50%' },
+  left: { ...BASE, top: '50%', left: '0' },
+  right: { ...BASE, top: '50%', left: '100%' },
+};
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useFlowContext, useFlowNodeContext } from './context';
+
+// `isConnectable` MUST default to `undefined` (not via destructure default):
+// Vue coerces an absent Boolean prop to `false`, which would defeat the
+// `?? nodeCtx.connectable` fallback and make every handle non-connectable.
+const props = withDefaults(defineProps<FlowHandleProps>(), {
+  id: null,
+  isConnectable: undefined,
+  as: 'div',
+});
+
+const ctx = useFlowContext();
+const nodeCtx = useFlowNodeContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const connectable = computed(() => (props.isConnectable ?? nodeCtx.connectable.value) && ctx.nodesConnectable.value);
+
+onMounted(() => {
+  const el = currentElement.value;
+  if (el) nodeCtx.registerHandle({ id: props.id, type: props.type, position: props.position, element: el });
+});
+onBeforeUnmount(() => nodeCtx.unregisterHandle(props.id, props.type));
+
+function onPointerdown(event: PointerEvent): void {
+  if (event.button !== 0 || !connectable.value || !ctx.interactive.value) return;
+  // Don't let the node start dragging / the pane start panning.
+  event.stopPropagation();
+  const el = currentElement.value;
+  if (!el) return;
+  ctx.startConnection({ id: props.id, type: props.type, position: props.position, element: el }, nodeCtx.nodeId);
+}
+
+const positionStyle = computed(() => POSITION_STYLES[props.position]);
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="props.as"
+    data-flow-handle=""
+    :data-handleid="props.id ?? ''"
+    :data-handletype="props.type"
+    :data-handlepos="props.position"
+    :data-connectable="connectable ? '' : undefined"
+    :style="positionStyle"
+    @pointerdown="onPointerdown"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowMiniMap.vue b/vue/primitives/src/canvas/flow/FlowMiniMap.vue
new file mode 100644
index 0000000..b578864
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowMiniMap.vue
@@ -0,0 +1,113 @@
+<script lang="ts">
+import type { FlowPanelPosition } from './FlowPanel.vue';
+
+/**
+ * A scaled overview of the graph with a viewport indicator. Auto-frames all
+ * nodes plus the current viewport, draws a `<rect>` per node, and (when
+ * `pannable`) recenters the viewport on click. Node rects expose `data-id` /
+ * `data-selected` for styling; size and colour are the consumer's.
+ */
+export interface FlowMiniMapProps {
+  /** Panel anchor. @default 'bottom-right' */
+  position?: FlowPanelPosition;
+  /** Map width in px. @default 200 */
+  width?: number;
+  /** Map height in px. @default 150 */
+  height?: number;
+  /** Click the map to recenter the viewport. @default true */
+  pannable?: boolean;
+  /** Accessible label. @default 'Mini map' */
+  ariaLabel?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import FlowPanel from './FlowPanel.vue';
+import { useFlowContext } from './context';
+import { getNodesBounds, visibleFlowRect } from './utils';
+
+const {
+  position = 'bottom-right',
+  width = 200,
+  height = 150,
+  pannable = true,
+  ariaLabel = 'Mini map',
+} = defineProps<FlowMiniMapProps>();
+
+const ctx = useFlowContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const nodes = computed(() => [...ctx.nodeLookup.value.values()].filter(n => !n.hidden));
+const viewRect = computed(() => visibleFlowRect(ctx.viewport.value, ctx.paneRect.value, 0));
+
+const bounds = computed(() => {
+  const b = getNodesBounds(nodes.value);
+  const v = viewRect.value;
+  const x1 = Math.min(b.x, v.x);
+  const y1 = Math.min(b.y, v.y);
+  const x2 = Math.max(b.x + b.width, v.x + v.width);
+  const y2 = Math.max(b.y + b.height, v.y + v.height);
+  const w = x2 - x1 || 1;
+  const h = y2 - y1 || 1;
+  const pad = Math.max(w, h) * 0.1;
+  return { x: x1 - pad, y: y1 - pad, width: w + 2 * pad, height: h + 2 * pad };
+});
+
+const viewBox = computed(() => `${bounds.value.x} ${bounds.value.y} ${bounds.value.width} ${bounds.value.height}`);
+const maskStroke = computed(() => (bounds.value.width / width) * 1.5);
+
+function onPointerdown(event: PointerEvent): void {
+  if (!pannable) return;
+  const el = currentElement.value;
+  if (!el) return;
+  const r = el.getBoundingClientRect();
+  const fx = bounds.value.x + ((event.clientX - r.left) / r.width) * bounds.value.width;
+  const fy = bounds.value.y + ((event.clientY - r.top) / r.height) * bounds.value.height;
+  const vp = ctx.viewport.value;
+  const pane = ctx.paneRect.value;
+  ctx.viewport.value = { zoom: vp.zoom, x: pane.width / 2 - fx * vp.zoom, y: pane.height / 2 - fy * vp.zoom };
+}
+</script>
+
+<template>
+  <FlowPanel :position="position">
+    <svg
+      :ref="forwardRef"
+      data-flow-minimap=""
+      role="img"
+      :aria-label="ariaLabel"
+      :width="width"
+      :height="height"
+      :viewBox="viewBox"
+      preserveAspectRatio="xMidYMid meet"
+      :style="{ cursor: pannable ? 'pointer' : undefined }"
+      @pointerdown="onPointerdown"
+    >
+      <rect
+        v-for="n in nodes"
+        :key="n.id"
+        v-memo="[n.positionAbsolute.x, n.positionAbsolute.y, n.measured.width, n.measured.height, ctx.selection.value.nodes.has(n.id)]"
+        data-flow-minimap-node=""
+        :data-id="n.id"
+        :data-selected="ctx.selection.value.nodes.has(n.id) ? '' : undefined"
+        :x="n.positionAbsolute.x"
+        :y="n.positionAbsolute.y"
+        :width="n.measured.width"
+        :height="n.measured.height"
+        fill="currentColor"
+      />
+      <rect
+        data-flow-minimap-mask=""
+        :x="viewRect.x"
+        :y="viewRect.y"
+        :width="viewRect.width"
+        :height="viewRect.height"
+        fill="none"
+        stroke="currentColor"
+        :stroke-width="maskStroke"
+      />
+    </svg>
+  </FlowPanel>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowNode.vue b/vue/primitives/src/canvas/flow/FlowNode.vue
new file mode 100644
index 0000000..2d7d0c8
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowNode.vue
@@ -0,0 +1,168 @@
+<script lang="ts">
+import type { Component } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * One node. Reads only its own entry from `nodeLookup` (computed by id) so
+ * moving another node never re-renders it; `v-memo` short-circuits patches when
+ * its position/size/selection are unchanged. Positions itself with a plain
+ * `translate` in flow space (the viewport applies zoom), measures itself once
+ * via a ResizeObserver, wires drag, and provides `FlowNodeContext` to handles /
+ * resizer / toolbar. Resolves its renderer from `#node-<type>` slot →
+ * `nodeTypes[type]` → `#node` slot.
+ */
+export interface FlowNodeProps extends PrimitiveProps {
+  /** Node id; matches the render key. */
+  id: string;
+  /** Component map keyed by `node.type` (forwarded from the renderer). */
+  nodeTypes?: Record<string, Component>;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, nextTick, useSlots, watch } from 'vue';
+import { useForwardExpose, useResizeObserver } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { provideFlowNodeContext, useFlowContext } from './context';
+import type { FlowNodeContext, HandleRegistration } from './context';
+import type { HandleType } from './types';
+import { useNodeDrag } from './composables/useNodeDrag';
+import { getHandleBoundsFromDom } from './utils';
+
+const { id, nodeTypes, as = 'div' } = defineProps<FlowNodeProps>();
+
+const ctx = useFlowContext();
+const slots = useSlots();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const node = computed(() => ctx.nodeLookup.value.get(id));
+const selected = computed(() => ctx.selection.value.nodes.has(id));
+const dragging = computed(() => node.value?.dragging ?? false);
+const positionAbsolute = computed(() => node.value?.positionAbsolute ?? { x: 0, y: 0 });
+const measured = computed(() => node.value?.measured ?? { width: 0, height: 0 });
+const connectable = computed(() => ctx.nodesConnectable.value && node.value?.connectable !== false);
+const selectable = computed(() => ctx.elementsSelectable.value && node.value?.selectable !== false);
+
+// Position by the ABSOLUTE flow point (parent chain summed) so subflow children
+// land inside their parent even though all nodes are flat siblings in the DOM.
+const transform = computed(() => `translate(${positionAbsolute.value.x}px, ${positionAbsolute.value.y}px)`);
+const zIndex = computed(() => node.value?.zIndex ?? (selected.value || dragging.value ? 1000 : 0));
+
+const resolvedType = computed(() => node.value?.type ?? 'default');
+const slotName = computed(() => {
+  const key = `node-${resolvedType.value}`;
+  if (slots[key]) return key;
+  if (slots['node']) return 'node';
+  return null;
+});
+const TypeComponent = computed(() => nodeTypes?.[resolvedType.value]);
+
+const slotProps = computed(() => ({
+  id,
+  type: resolvedType.value,
+  data: node.value?.data,
+  selected: selected.value,
+  dragging: dragging.value,
+  connectable: connectable.value,
+  positionAbsolute: positionAbsolute.value,
+  width: measured.value.width,
+  height: measured.value.height,
+  sourcePosition: node.value?.sourcePosition,
+  targetPosition: node.value?.targetPosition,
+}));
+
+// ── measurement ──────────────────────────────────────────────────────────
+function measure(): void {
+  const el = currentElement.value;
+  if (!el) return;
+  const rect = el.getBoundingClientRect();
+  const zoom = ctx.viewport.value.zoom || 1;
+  // getBoundingClientRect returns the *scaled* box under the viewport's CSS
+  // scale; dividing by zoom recovers zoom-independent flow-space geometry.
+  ctx.setNodeMeasured(id, { width: rect.width / zoom, height: rect.height / zoom }, getHandleBoundsFromDom(el, zoom));
+}
+
+useResizeObserver(currentElement, () => measure());
+watch(currentElement, (el) => {
+  if (el) nextTick(measure);
+}, { immediate: true });
+
+// ── drag + selection ──────────────────────────────────────────────────────
+useNodeDrag(currentElement, ctx, () => id);
+
+function onPointerdown(event: PointerEvent): void {
+  if (event.button !== 0 || !selectable.value) return;
+  const additive = event.shiftKey || event.metaKey || event.ctrlKey;
+  if (!selected.value || additive) ctx.selectNode(id, additive);
+}
+
+// ── node sub-context (handles re-trigger measurement when they mount) ───────
+const handleIds = new Set<string>();
+function registerHandle(reg: HandleRegistration): void {
+  handleIds.add(`${reg.type}:${reg.id ?? ''}`);
+  nextTick(measure);
+}
+function unregisterHandle(handleId: string | null, type: HandleType): void {
+  handleIds.delete(`${type}:${handleId ?? ''}`);
+  nextTick(measure);
+}
+
+const nodeContext: FlowNodeContext = {
+  nodeId: id,
+  node,
+  positionAbsolute,
+  measured,
+  selected,
+  dragging,
+  connectable,
+  nodeRef: currentElement,
+  registerHandle,
+  unregisterHandle,
+};
+provideFlowNodeContext(nodeContext);
+</script>
+
+<template>
+  <Primitive
+    v-memo="[positionAbsolute.x, positionAbsolute.y, selected, dragging, connectable, measured.width, measured.height, resolvedType, node?.data, node?.width, node?.height]"
+    :ref="forwardRef"
+    :as="as"
+    data-flow-node=""
+    :data-id="id"
+    :data-selected="selected ? '' : undefined"
+    :data-dragging="dragging ? '' : undefined"
+    :data-selectable="selectable ? '' : undefined"
+    :data-connectable="connectable ? '' : undefined"
+    :data-type="resolvedType"
+    :tabindex="ctx.disableKeyboardA11y.value ? undefined : 0"
+    :aria-label="node?.ariaLabel"
+    :style="{
+      position: 'absolute',
+      top: '0',
+      left: '0',
+      transform,
+      zIndex,
+      width: node?.width ? `${node.width}px` : undefined,
+      height: node?.height ? `${node.height}px` : undefined,
+      willChange: dragging ? 'transform' : undefined,
+      pointerEvents: ctx.interactive.value ? undefined : 'none',
+    }"
+    @pointerdown="onPointerdown"
+  >
+    <slot
+      v-if="slotName"
+      :name="slotName"
+      v-bind="slotProps"
+    />
+    <component
+      :is="TypeComponent"
+      v-else-if="TypeComponent"
+      v-bind="slotProps"
+    />
+    <slot
+      v-else
+      name="node-default"
+      v-bind="slotProps"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowNodeRenderer.vue b/vue/primitives/src/canvas/flow/FlowNodeRenderer.vue
new file mode 100644
index 0000000..9f9c7aa
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowNodeRenderer.vue
@@ -0,0 +1,47 @@
+<script lang="ts">
+import type { Component } from 'vue';
+
+/**
+ * Iterates the visible node ids and renders one `FlowNode` per id, keyed by id
+ * so virtualization re-inclusion patches in place. Forwards the `#node-<type>`
+ * slots and the `nodeTypes` component map down to each node. Renderless (returns
+ * a fragment of nodes directly into the viewport — no wrapper element).
+ */
+export interface FlowNodeRendererProps {
+  nodeTypes?: Record<string, Component>;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useSlots } from 'vue';
+import { useFlowContext } from './context';
+import FlowNode from './FlowNode.vue';
+
+defineProps<FlowNodeRendererProps>();
+defineOptions({ inheritAttrs: false });
+
+const ctx = useFlowContext();
+const slots = useSlots();
+// Stable name list (mirrors FlowRoot) — avoids new dynamic-slot identities per render.
+const slotNames = computed(() => Object.keys(slots));
+</script>
+
+<template>
+  <FlowNode
+    v-for="id in ctx.visibleNodeIds.value"
+    :id="id"
+    :key="id"
+    :node-types="nodeTypes"
+  >
+    <template
+      v-for="name in slotNames"
+      :key="name"
+      #[name]="sp"
+    >
+      <slot
+        :name="name"
+        v-bind="sp ?? {}"
+      />
+    </template>
+  </FlowNode>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowNodeResizer.vue b/vue/primitives/src/canvas/flow/FlowNodeResizer.vue
new file mode 100644
index 0000000..9b96b9b
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowNodeResizer.vue
@@ -0,0 +1,173 @@
+<script lang="ts">
+import type { CSSProperties } from 'vue';
+
+/**
+ * In-node resize handles (8 control points). Placed inside a custom node, it
+ * resizes that node by writing explicit `width`/`height` (and `position` for
+ * top/left edges, so the opposite edge stays fixed). Deltas are converted to
+ * flow space (`/zoom`), clamped to min/max, and committed through `updateNode`.
+ * Handles are unstyled — target `[data-flow-resize-handle][data-position]`.
+ */
+export interface FlowNodeResizerProps {
+  /** Minimum width in flow units. @default 10 */
+  minWidth?: number;
+  /** Maximum width in flow units. @default Infinity */
+  maxWidth?: number;
+  /** Minimum height in flow units. @default 10 */
+  minHeight?: number;
+  /** Maximum height in flow units. @default Infinity */
+  maxHeight?: number;
+  /** Keep the node's aspect ratio while resizing. @default false */
+  keepAspectRatio?: boolean;
+}
+
+interface Control {
+  position: string;
+  cursor: string;
+  style: CSSProperties;
+}
+</script>
+
+<script setup lang="ts">
+import { onScopeDispose } from 'vue';
+import { clamp } from '@robonen/stdlib';
+import { useFlowContext, useFlowNodeContext } from './context';
+import { capturePointer, releasePointer } from './composables/dom';
+
+const {
+  minWidth = 10,
+  maxWidth = Number.POSITIVE_INFINITY,
+  minHeight = 10,
+  maxHeight = Number.POSITIVE_INFINITY,
+  keepAspectRatio = false,
+} = defineProps<FlowNodeResizerProps>();
+
+const ctx = useFlowContext();
+const nodeCtx = useFlowNodeContext();
+
+const CONTROLS: Control[] = [
+  { position: 'top-left', cursor: 'nwse-resize', style: { top: '0', left: '0' } },
+  { position: 'top', cursor: 'ns-resize', style: { top: '0', left: '50%' } },
+  { position: 'top-right', cursor: 'nesw-resize', style: { top: '0', left: '100%' } },
+  { position: 'right', cursor: 'ew-resize', style: { top: '50%', left: '100%' } },
+  { position: 'bottom-right', cursor: 'nwse-resize', style: { top: '100%', left: '100%' } },
+  { position: 'bottom', cursor: 'ns-resize', style: { top: '100%', left: '50%' } },
+  { position: 'bottom-left', cursor: 'nesw-resize', style: { top: '100%', left: '0' } },
+  { position: 'left', cursor: 'ew-resize', style: { top: '50%', left: '0' } },
+];
+
+let pointerId = -1;
+let activeEl: HTMLElement | undefined;
+let control = '';
+let startClientX = 0;
+let startClientY = 0;
+let startW = 0;
+let startH = 0;
+let startX = 0;
+let startY = 0;
+let lastEvent: PointerEvent | null = null;
+let rafId: number | null = null;
+
+function flush(): void {
+  rafId = null;
+  if (!lastEvent) return;
+  const node = nodeCtx.node.value;
+  if (!node) return;
+
+  const zoom = ctx.viewport.value.zoom || 1;
+  const dx = (lastEvent.clientX - startClientX) / zoom;
+  const dy = (lastEvent.clientY - startClientY) / zoom;
+  const ratio = startH === 0 ? 1 : startW / startH;
+
+  let w = startW;
+  let h = startH;
+  if (control.includes('right')) w = startW + dx;
+  if (control.includes('left')) w = startW - dx;
+  if (control.includes('bottom')) h = startH + dy;
+  if (control.includes('top')) h = startH - dy;
+
+  w = clamp(w, minWidth, maxWidth);
+  h = clamp(h, minHeight, maxHeight);
+  if (keepAspectRatio) {
+    if (control === 'left' || control === 'right') h = w / ratio;
+    else if (control === 'top' || control === 'bottom') w = h * ratio;
+    else h = w / ratio;
+  }
+
+  let x = startX;
+  let y = startY;
+  if (control.includes('left')) x = startX + (startW - w);
+  if (control.includes('top')) y = startY + (startH - h);
+
+  ctx.updateNode(node.id, { width: w, height: h, position: { x, y } });
+}
+
+function onMove(event: PointerEvent): void {
+  if (event.pointerId !== pointerId) return;
+  lastEvent = event;
+  if (rafId === null) rafId = requestAnimationFrame(flush);
+}
+
+function onUp(event: PointerEvent): void {
+  if (event.pointerId !== pointerId) return;
+  if (rafId !== null) {
+    cancelAnimationFrame(rafId);
+    rafId = null;
+  }
+  flush();
+  releasePointer(activeEl, event.pointerId);
+  globalThis.removeEventListener?.('pointermove', onMove);
+  globalThis.removeEventListener?.('pointerup', onUp);
+  pointerId = -1;
+  activeEl = undefined;
+}
+
+function onPointerdown(event: PointerEvent, c: Control): void {
+  if (event.button !== 0 || !ctx.interactive.value) return;
+  const node = nodeCtx.node.value;
+  if (!node) return;
+  event.stopPropagation();
+  event.preventDefault();
+
+  control = c.position;
+  pointerId = event.pointerId;
+  activeEl = event.currentTarget as HTMLElement;
+  startClientX = event.clientX;
+  startClientY = event.clientY;
+  startW = node.measured.width;
+  startH = node.measured.height;
+  startX = node.position.x;
+  startY = node.position.y;
+
+  capturePointer(activeEl, event.pointerId);
+  globalThis.addEventListener?.('pointermove', onMove);
+  globalThis.addEventListener?.('pointerup', onUp);
+}
+
+onScopeDispose(() => {
+  globalThis.removeEventListener?.('pointermove', onMove);
+  globalThis.removeEventListener?.('pointerup', onUp);
+});
+</script>
+
+<template>
+  <div
+    v-for="c in CONTROLS"
+    :key="c.position"
+    class="nodrag"
+    data-flow-resize-handle=""
+    :data-position="c.position"
+    :style="{
+      position: 'absolute',
+      transform: 'translate(-50%, -50%)',
+      cursor: c.cursor,
+      touchAction: 'none',
+      ...c.style,
+    }"
+    @pointerdown="onPointerdown($event, c)"
+  >
+    <slot
+      :position="c.position"
+    />
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowNodeToolbar.vue b/vue/primitives/src/canvas/flow/FlowNodeToolbar.vue
new file mode 100644
index 0000000..9c6dbf5
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowNodeToolbar.vue
@@ -0,0 +1,91 @@
+<script lang="ts">
+import type { CSSProperties } from 'vue';
+import { Teleport, computed, defineComponent, h, mergeProps } from 'vue';
+import { useFlowContext, useFlowNodeContext } from './context';
+import type { Position } from './types';
+
+/**
+ * A contextual toolbar anchored to its node, teleported out of the transformed
+ * layer so it renders at a constant 1:1 scale regardless of zoom. Position is
+ * recomputed from the node's absolute rect via `flowToScreen` (fixed
+ * positioning). Visible when the node is selected by default; override with
+ * `isVisible`. Placed inside a custom node component.
+ *
+ * Implemented as a render function: a `<Teleport>` toggled by `v-if` at an SFC
+ * template root does not reliably re-subscribe to its visibility source, so the
+ * conditional teleport is expressed directly here.
+ */
+export interface FlowNodeToolbarProps {
+  /** Force visibility; defaults to "visible while the node is selected". */
+  isVisible?: boolean;
+  /** Side of the node to anchor to. @default 'top' */
+  position?: Position;
+  /** Gap from the node edge in px. @default 8 */
+  offset?: number;
+  /** Teleport target. @default 'body' */
+  to?: string;
+}
+
+const TRANSFORMS = (offset: number): Record<Position, string> => ({
+  top: `translate(-50%, calc(-100% - ${offset}px))`,
+  bottom: `translate(-50%, ${offset}px)`,
+  left: `translate(calc(-100% - ${offset}px), -50%)`,
+  right: `translate(${offset}px, -50%)`,
+});
+
+export default defineComponent({
+  name: 'FlowNodeToolbar',
+  inheritAttrs: false,
+  props: {
+    isVisible: { type: Boolean, default: undefined },
+    position: { type: String as () => Position, default: 'top' },
+    offset: { type: Number, default: 8 },
+    to: { type: String, default: 'body' },
+  },
+  setup(props, { slots, attrs }) {
+    const ctx = useFlowContext();
+    const nodeCtx = useFlowNodeContext();
+
+    const visible = computed(() => (props.isVisible === undefined ? nodeCtx.selected.value : props.isVisible));
+
+    const style = computed<CSSProperties>(() => {
+      const node = nodeCtx.node.value;
+      if (!node) return { display: 'none' };
+      const { x, y } = node.positionAbsolute;
+      const { width, height } = node.measured;
+      let fx = x + width / 2;
+      let fy = y + height / 2;
+      if (props.position === 'top') fy = y;
+      else if (props.position === 'bottom') fy = y + height;
+      else if (props.position === 'left') fx = x;
+      else if (props.position === 'right') fx = x + width;
+      const a = ctx.flowToScreen({ x: fx, y: fy });
+      return {
+        position: 'fixed',
+        left: `${a.x}px`,
+        top: `${a.y}px`,
+        transform: TRANSFORMS(props.offset)[props.position],
+        pointerEvents: 'all',
+        zIndex: '1000',
+      };
+    });
+
+    return () =>
+      visible.value
+        ? h(Teleport, { to: props.to }, [
+            h(
+              'div',
+              mergeProps(attrs, {
+                'data-flow-node-toolbar': '',
+                'data-position': props.position,
+                style: style.value,
+                onPointerdown: (e: Event) => e.stopPropagation(),
+                onWheel: (e: Event) => e.stopPropagation(),
+              }),
+              slots.default?.(),
+            ),
+          ])
+        : null;
+  },
+});
+</script>
diff --git a/vue/primitives/src/canvas/flow/FlowPane.vue b/vue/primitives/src/canvas/flow/FlowPane.vue
new file mode 100644
index 0000000..43f3737
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowPane.vue
@@ -0,0 +1,107 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The interaction surface. Clips the canvas (`overflow:hidden`), disables native
+ * touch gestures (`touch-action:none`), reports its bounding rect into the
+ * context as the screen origin for coordinate math, and hosts the wheel/drag
+ * pan-zoom, marquee-selection, connection and keyboard layers. Background click
+ * clears the selection. Rendered by `FlowRoot`; not usually placed directly.
+ */
+export interface FlowPaneProps extends PrimitiveProps {
+  /** Drag the empty pane to pan. @default true */
+  panOnDrag?: boolean;
+  /** Wheel scroll pans instead of zooms. @default false */
+  panOnScroll?: boolean;
+  /** Wheel scroll zooms toward the pointer. @default true */
+  zoomOnScroll?: boolean;
+  /** Trackpad pinch zooms. @default true */
+  zoomOnPinch?: boolean;
+  /** Double-click zooms in. @default true */
+  zoomOnDoubleClick?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { watchEffect } from 'vue';
+import { useElementBounding, useEventListener, useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+import { useFlowContext } from './context';
+import { usePanZoom } from './composables/usePanZoom';
+import { useConnection } from './composables/useConnection';
+import { useMarquee } from './composables/useMarquee';
+import { useKeyboard } from './composables/useKeyboard';
+import { useViewportApi } from './composables/useViewportApi';
+
+const {
+  as = 'div',
+  panOnDrag = true,
+  panOnScroll = false,
+  zoomOnScroll = true,
+  zoomOnPinch = true,
+  zoomOnDoubleClick = true,
+} = defineProps<FlowPaneProps>();
+
+const ctx = useFlowContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const { left, top, width, height } = useElementBounding(currentElement, { updateTiming: 'next-frame' });
+watchEffect(() => {
+  ctx.setPaneRect({ left: left.value, top: top.value, width: width.value, height: height.value });
+});
+
+const { isPanning } = usePanZoom(currentElement, ctx, {
+  panOnDrag,
+  panOnScroll,
+  zoomOnScroll,
+  zoomOnPinch,
+  zoomOnDoubleClick,
+});
+
+useConnection(ctx);
+const { rect: marquee } = useMarquee(currentElement, ctx);
+useKeyboard(currentElement, ctx, useViewportApi(ctx));
+
+useEventListener(currentElement, 'click', (event: MouseEvent) => {
+  const target = event.target as Element | null;
+  if (target && !target.closest('[data-flow-node],[data-flow-edge]'))
+    ctx.clearSelection();
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    data-flow-pane=""
+    :data-panning="isPanning ? '' : undefined"
+    :data-interactive="ctx.interactive.value ? '' : undefined"
+    :role="ctx.disableKeyboardA11y.value ? undefined : 'application'"
+    :tabindex="ctx.disableKeyboardA11y.value ? undefined : 0"
+    :style="{ position: 'relative', overflow: 'hidden', touchAction: 'none' }"
+  >
+    <slot />
+
+    <div
+      v-if="marquee"
+      data-flow-selection-rect=""
+      :style="{
+        position: 'absolute',
+        top: '0',
+        left: '0',
+        transform: `translate(${marquee.x}px, ${marquee.y}px)`,
+        width: `${marquee.width}px`,
+        height: `${marquee.height}px`,
+        pointerEvents: 'none',
+      }"
+    />
+
+    <VisuallyHidden
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      <slot name="a11y-status" />
+    </VisuallyHidden>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowPanel.vue b/vue/primitives/src/canvas/flow/FlowPanel.vue
new file mode 100644
index 0000000..7e44c53
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowPanel.vue
@@ -0,0 +1,60 @@
+<script lang="ts">
+import type { CSSProperties } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+export type FlowPanelPosition
+  = | 'top-left' | 'top-center' | 'top-right'
+    | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+/**
+ * An absolutely-positioned overlay anchored to a corner/edge of the pane, for
+ * chrome like controls, legends, or toolbars. Stops pointer/wheel events from
+ * reaching the pane, so interacting with the panel never pans or zooms. Place
+ * inside `FlowRoot`'s default slot.
+ */
+export interface FlowPanelProps extends PrimitiveProps {
+  /** Anchor position within the pane. @default 'top-left' */
+  position?: FlowPanelPosition;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+
+const { position = 'top-left', as = 'div' } = defineProps<FlowPanelProps>();
+const { forwardRef } = useForwardExpose();
+
+const style = computed<CSSProperties>(() => {
+  const [v, h] = position.split('-') as ['top' | 'bottom', 'left' | 'center' | 'right'];
+  const s: CSSProperties = { position: 'absolute', pointerEvents: 'all' };
+  s[v] = '0';
+  if (h === 'center') {
+    s.left = '50%';
+    s.transform = 'translateX(-50%)';
+  }
+  else {
+    s[h] = '0';
+  }
+  return s;
+});
+
+function stop(event: Event): void {
+  event.stopPropagation();
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    data-flow-panel=""
+    :data-position="position"
+    :style="style"
+    @pointerdown="stop"
+    @wheel="stop"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowRoot.vue b/vue/primitives/src/canvas/flow/FlowRoot.vue
new file mode 100644
index 0000000..d3057da
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowRoot.vue
@@ -0,0 +1,573 @@
+<script lang="ts">
+import type { Component, Ref } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type {
+  Connection,
+  ConnectionMode,
+  ConnectionState,
+  Dimensions,
+  EdgeChange,
+  FlowEdge,
+  FlowNode,
+  HandleType,
+  InternalNode,
+  IsValidConnection,
+  NodeChange,
+  SelectionMode,
+  Viewport,
+  XYPosition,
+} from './types';
+
+/**
+ * Root of the headless flow canvas. Owns node/edge/viewport state (two-way via
+ * `v-model:nodes` / `v-model:edges` / `v-model:viewport`, or uncontrolled via
+ * `defaultNodes` / `defaultEdges` / `defaultViewport`), reconciles the public
+ * arrays into internal `shallowRef` Maps for O(1) reads, and provides
+ * `FlowContext` to every part. It renders the standard `FlowPane → FlowViewport
+ * → (edges, nodes)` subtree and exposes the default slot for absolutely-
+ * positioned chrome (Background / Controls / MiniMap / Panel). Customise node
+ * and edge rendering with `nodeTypes` / `edgeTypes` component maps or the
+ * `#node-<type>` / `#edge-<type>` scoped slots. Emits granular `@nodes-change` /
+ * `@edges-change` alongside `v-model`, so consumers may own their data.
+ */
+export interface FlowRootProps extends PrimitiveProps {
+  /** Uncontrolled initial nodes (ignored when `v-model:nodes` is bound). */
+  defaultNodes?: FlowNode[];
+  /** Uncontrolled initial edges. */
+  defaultEdges?: FlowEdge[];
+  /** Uncontrolled initial viewport. @default { x:0, y:0, zoom:1 } */
+  defaultViewport?: Viewport;
+  /** Minimum zoom level. @default 0.5 */
+  minZoom?: number;
+  /** Maximum zoom level. @default 2 */
+  maxZoom?: number;
+  /** Global drag enable (per-node `draggable` overrides). @default true */
+  nodesDraggable?: boolean;
+  /** Global connect enable (per-node `connectable` overrides). @default true */
+  nodesConnectable?: boolean;
+  /** Global selection enable. @default true */
+  elementsSelectable?: boolean;
+  /** Snap dragged nodes to a grid. @default false */
+  snapToGrid?: boolean;
+  /** Grid spacing `[x, y]` for `snapToGrid`. @default [15, 15] */
+  snapGrid?: [number, number];
+  /** Connection validity model. @default 'strict' */
+  connectionMode?: ConnectionMode;
+  /** Pixel radius for snapping a connection to a nearby handle. @default 20 */
+  connectionRadius?: number;
+  /** Marquee inclusion rule. @default 'partial' */
+  selectionMode?: SelectionMode;
+  /** Raise z-index of selected nodes. @default true */
+  elevateNodesOnSelect?: boolean;
+  /** Component map keyed by `node.type`. Define module-level, never inline. */
+  nodeTypes?: Record<string, Component>;
+  /** Component map keyed by `edge.type`. */
+  edgeTypes?: Record<string, Component>;
+  /** Default edge type when an edge has none. @default 'default' */
+  defaultEdgeType?: string;
+  /** Master interactivity switch (lock). @default true */
+  interactive?: boolean;
+  /** Disable the keyboard a11y layer + `role=application`. @default false */
+  disableKeyboardA11y?: boolean;
+  /** Global connection validator, overridable per handle. */
+  isValidConnection?: IsValidConnection;
+  /** Cull nodes/edges outside the viewport — for large graphs. @default false */
+  onlyRenderVisibleElements?: boolean;
+  /** Extra px kept rendered around the viewport when virtualizing. @default 200 */
+  virtualizationBuffer?: number;
+}
+
+export interface FlowRootEmits {
+  nodesChange: [changes: NodeChange[]];
+  edgesChange: [changes: EdgeChange[]];
+  connect: [connection: Connection];
+  connectStart: [payload: { nodeId: string; handleId: string | null; handleType: HandleType }];
+  connectEnd: [];
+  nodeDragStop: [ids: string[]];
+  selectionChange: [selection: { nodes: string[]; edges: string[] }];
+  paneClick: [event: PointerEvent];
+  nodeClick: [id: string, event: PointerEvent];
+  edgeClick: [id: string, event: PointerEvent];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, triggerRef, useSlots, watch } from 'vue';
+import { useId } from '@robonen/vue';
+import FlowPane from './FlowPane.vue';
+import FlowViewport from './FlowViewport.vue';
+import FlowNodeRenderer from './FlowNodeRenderer.vue';
+import FlowEdgeRenderer from './FlowEdgeRenderer.vue';
+import { provideFlowContext } from './context';
+import type { FlowContext, FlowSelection, HandleRegistration } from './context';
+import { flowToScreen, getNodePositionAbsolute, screenToFlow, visibleFlowRect } from './utils';
+import { buildConnection, connectionToEdgeId, findClosestHandle, isValidConnection as isValidConnectionGate } from './connection';
+import { getVisibleEdgeIds, getVisibleNodeIds } from './virtualization';
+import { useViewportApi } from './composables/useViewportApi';
+import { useInteractionState } from './composables/useInteractionState';
+
+const {
+  defaultNodes,
+  defaultEdges,
+  defaultViewport,
+  minZoom = 0.5,
+  maxZoom = 2,
+  nodesDraggable = true,
+  nodesConnectable = true,
+  elementsSelectable = true,
+  snapToGrid = false,
+  snapGrid = [15, 15],
+  connectionMode = 'strict',
+  connectionRadius = 20,
+  selectionMode = 'partial',
+  interactive = true,
+  disableKeyboardA11y = false,
+  isValidConnection,
+  onlyRenderVisibleElements = false,
+  virtualizationBuffer = 200,
+  as = 'div',
+} = defineProps<FlowRootProps>();
+
+const emit = defineEmits<FlowRootEmits>();
+const slots = useSlots();
+
+const flowId = useId(undefined, 'flow').value;
+
+// ── models (controlled + uncontrolled) ────────────────────────────────────
+const localNodes = shallowRef<FlowNode[]>(defaultNodes ? defaultNodes.slice() : []);
+const nodes = defineModel<FlowNode[]>('nodes', {
+  get: external => external ?? localNodes.value,
+  set: (value) => {
+    localNodes.value = value;
+    return value;
+  },
+});
+
+const localEdges = shallowRef<FlowEdge[]>(defaultEdges ? defaultEdges.slice() : []);
+const edges = defineModel<FlowEdge[]>('edges', {
+  get: external => external ?? localEdges.value,
+  set: (value) => {
+    localEdges.value = value;
+    return value;
+  },
+});
+
+const localViewport = shallowRef<Viewport>(defaultViewport ?? { x: 0, y: 0, zoom: 1 });
+const viewport = defineModel<Viewport>('viewport', {
+  get: external => external ?? localViewport.value,
+  set: (value) => {
+    localViewport.value = value;
+    return value;
+  },
+});
+
+// ── derived state (shallow Maps; nodes updated IMMUTABLY — a changed node is
+// replaced with a new object so its per-node `computed(()=>lookup.get(id))`
+// sees a new identity and re-renders; untouched nodes keep identity so they
+// don't. In-place mutation would make that computed short-circuit and the node
+// would never visually update). ────────────────────────────────────────────
+const nodeLookup = shallowRef(new Map<string, InternalNode>());
+const edgeLookup = shallowRef(new Map<string, FlowEdge>());
+const selection = shallowRef<FlowSelection>({ nodes: new Set(), edges: new Set() });
+const paneRect = shallowRef({ left: 0, top: 0, width: 0, height: 0 });
+const isDragging = shallowRef(false);
+const draggedIds = new Set<string>();
+const isInteracting = useInteractionState(() => viewport.value);
+let hasParenting = false;
+
+function reconcileNodes(): void {
+  // During an active drag the model array is stale on purpose; don't clobber
+  // the live in-place positions until pointerup commits them.
+  if (isDragging.value) return;
+
+  const arr = nodes.value ?? [];
+  const map = nodeLookup.value;
+  const seen = new Set<string>();
+  hasParenting = false;
+
+  for (const n of arr) {
+    seen.add(n.id);
+    if (n.parentId) hasParenting = true;
+    const existing = map.get(n.id);
+    // Unchanged public node object → keep the existing internal entry (identity
+    // stable so this node won't re-render on unrelated updates).
+    if (existing && existing._source === n) continue;
+    map.set(n.id, {
+      ...n,
+      measured: existing?.measured ?? { width: n.width ?? 0, height: n.height ?? 0 },
+      positionAbsolute: { x: n.position.x, y: n.position.y },
+      handleBounds: existing?.handleBounds ?? null,
+      dragging: existing?.dragging ?? false,
+      _source: n,
+    });
+  }
+
+  for (const id of map.keys()) if (!seen.has(id)) map.delete(id);
+
+  // Recompute absolute positions; clone only the entries whose value changed.
+  for (const node of map.values()) {
+    const abs = getNodePositionAbsolute(node, map);
+    if (abs.x !== node.positionAbsolute.x || abs.y !== node.positionAbsolute.y)
+      map.set(node.id, { ...node, positionAbsolute: abs });
+  }
+
+  triggerRef(nodeLookup);
+}
+
+function reconcileEdges(): void {
+  const arr = edges.value ?? [];
+  const map = edgeLookup.value;
+  const seen = new Set<string>();
+  for (const e of arr) {
+    seen.add(e.id);
+    map.set(e.id, e);
+  }
+  for (const id of map.keys()) if (!seen.has(id)) map.delete(id);
+  triggerRef(edgeLookup);
+}
+
+watch(nodes, reconcileNodes, { immediate: true });
+watch(edges, reconcileEdges, { immediate: true });
+
+const visibleNodeIds = computed(() => {
+  const all = (nodes.value ?? []).filter(n => !n.hidden);
+  if (!onlyRenderVisibleElements) return all.map(n => n.id);
+  const rect = visibleFlowRect(viewport.value!, paneRect.value, virtualizationBuffer);
+  return getVisibleNodeIds(all, nodeLookup.value, rect);
+});
+
+const visibleNodeSet = computed(() => new Set(visibleNodeIds.value));
+
+const visibleEdgeIds = computed(() => {
+  const all = (edges.value ?? []).filter(e => !e.hidden);
+  if (!onlyRenderVisibleElements) return all.map(e => e.id);
+  return getVisibleEdgeIds(all, visibleNodeSet.value);
+});
+
+// ── coordinate actions ──────────────────────────────────────────────────────
+function toFlow(point: XYPosition): XYPosition {
+  return screenToFlow(point, viewport.value!, paneRect.value);
+}
+function toScreen(point: XYPosition): XYPosition {
+  return flowToScreen(point, viewport.value!, paneRect.value);
+}
+function setPaneRect(rect: { left: number; top: number; width: number; height: number }): void {
+  paneRect.value = rect;
+}
+
+// ── node mutation ─────────────────────────────────────────────────────────
+/**
+ * Re-derive absolute positions, cloning only the entries whose value changed.
+ * Hot during a drag of nested nodes (loops every node each frame), so the
+ * parent-chain sum is inlined to avoid a throwaway `{x,y}` per unchanged node
+ * (mirrors `getNodePositionAbsolute`, incl. its cycle-guard).
+ */
+function recomputeAbsolute(map: Map<string, InternalNode>): void {
+  const ids = hasParenting ? map.keys() : draggedIds;
+  for (const id of ids) {
+    const n = map.get(id);
+    if (!n) continue;
+    let x = n.position.x;
+    let y = n.position.y;
+    let parentId = n.parentId;
+    let guard = 0;
+    while (parentId && guard++ < 100) {
+      const parent = map.get(parentId);
+      if (!parent) break;
+      x += parent.position.x;
+      y += parent.position.y;
+      parentId = parent.parentId;
+    }
+    if (x !== n.positionAbsolute.x || y !== n.positionAbsolute.y)
+      map.set(id, { ...n, positionAbsolute: { x, y } });
+  }
+}
+
+function updateNodePositions(positions: Map<string, XYPosition>, dragging: boolean): void {
+  isDragging.value = dragging;
+  const map = nodeLookup.value;
+  for (const [id, pos] of positions) {
+    const n = map.get(id);
+    if (!n) continue;
+    // Replace with a NEW object (immutable) so this node's per-node computed
+    // sees a new identity and re-renders. For root nodes set absolute inline.
+    const next: InternalNode = { ...n, position: pos, dragging };
+    if (!n.parentId) next.positionAbsolute = { x: pos.x, y: pos.y };
+    map.set(id, next);
+    draggedIds.add(id);
+  }
+  if (hasParenting) recomputeAbsolute(map);
+  triggerRef(nodeLookup);
+}
+
+function commitNodeDrag(): void {
+  isDragging.value = false;
+  if (draggedIds.size === 0) return;
+  const ids = [...draggedIds];
+  const map = nodeLookup.value;
+  const changes: NodeChange[] = [];
+  for (const id of ids) {
+    const n = map.get(id);
+    if (!n) continue;
+    map.set(id, { ...n, dragging: false });
+    changes.push({ type: 'position', id, position: { x: n.position.x, y: n.position.y }, dragging: false });
+  }
+  draggedIds.clear();
+  triggerRef(nodeLookup);
+
+  const posById = new Map(changes.map(c => [c.id, (c as Extract<NodeChange, { type: 'position' }>).position!]));
+  nodes.value = (nodes.value ?? []).map(n => (posById.has(n.id) ? { ...n, position: posById.get(n.id)! } : n));
+  emit('nodesChange', changes);
+  emit('nodeDragStop', ids);
+}
+
+function setNodeMeasured(id: string, size: Dimensions, handleBounds: InternalNode['handleBounds']): void {
+  const map = nodeLookup.value;
+  const n = map.get(id);
+  if (!n) return;
+  const sizeChanged = n.measured.width !== size.width || n.measured.height !== size.height;
+  // New object so the node (and its incident edges, via the node computeds)
+  // pick up the fresh measurement / handle geometry.
+  map.set(id, { ...n, measured: sizeChanged ? size : n.measured, handleBounds });
+  triggerRef(nodeLookup);
+}
+
+function updateNode(id: string, patch: Partial<FlowNode>): void {
+  nodes.value = (nodes.value ?? []).map(n => (n.id === id ? { ...n, ...patch } : n));
+  const changes: NodeChange[] = [];
+  if (patch.position) changes.push({ type: 'position', id, position: patch.position });
+  if (patch.width !== undefined || patch.height !== undefined)
+    changes.push({ type: 'dimensions', id, dimensions: { width: patch.width ?? 0, height: patch.height ?? 0 } });
+  if (changes.length) emit('nodesChange', changes);
+}
+
+// ── selection ─────────────────────────────────────────────────────────────
+function emitSelection(): void {
+  emit('selectionChange', { nodes: [...selection.value.nodes], edges: [...selection.value.edges] });
+}
+
+function selectNode(id: string, additive = false): void {
+  if (!elementsSelectable) return;
+  const sel = selection.value;
+  const nextNodes = additive ? new Set(sel.nodes) : new Set<string>();
+  const nextEdges = additive ? new Set(sel.edges) : new Set<string>();
+  if (additive && nextNodes.has(id)) nextNodes.delete(id);
+  else nextNodes.add(id);
+  selection.value = { nodes: nextNodes, edges: nextEdges };
+  emitSelection();
+}
+
+function selectEdge(id: string, additive = false): void {
+  if (!elementsSelectable) return;
+  const sel = selection.value;
+  const nextNodes = additive ? new Set(sel.nodes) : new Set<string>();
+  const nextEdges = additive ? new Set(sel.edges) : new Set<string>();
+  if (additive && nextEdges.has(id)) nextEdges.delete(id);
+  else nextEdges.add(id);
+  selection.value = { nodes: nextNodes, edges: nextEdges };
+  emitSelection();
+}
+
+function setSelection(nodeIds: string[], edgeIds: string[]): void {
+  selection.value = { nodes: new Set(nodeIds), edges: new Set(edgeIds) };
+  emitSelection();
+}
+
+function clearSelection(): void {
+  if (selection.value.nodes.size === 0 && selection.value.edges.size === 0) return;
+  selection.value = { nodes: new Set(), edges: new Set() };
+  emitSelection();
+}
+
+function removeSelected(): void {
+  const sel = selection.value;
+  if (sel.nodes.size === 0 && sel.edges.size === 0) return;
+  const removedNodes = sel.nodes;
+  const nodeChanges: NodeChange[] = [...removedNodes].map(id => ({ type: 'remove', id }));
+  const edgeChanges: EdgeChange[] = [];
+  for (const e of edges.value ?? []) {
+    if (sel.edges.has(e.id) || removedNodes.has(e.source) || removedNodes.has(e.target))
+      edgeChanges.push({ type: 'remove', id: e.id });
+  }
+  const removedEdges = new Set(edgeChanges.map(c => c.id));
+  nodes.value = (nodes.value ?? []).filter(n => !removedNodes.has(n.id));
+  edges.value = (edges.value ?? []).filter(e => !removedEdges.has(e.id));
+  selection.value = { nodes: new Set(), edges: new Set() };
+  if (nodeChanges.length) emit('nodesChange', nodeChanges);
+  if (edgeChanges.length) emit('edgesChange', edgeChanges);
+  emitSelection();
+}
+
+// ── connection (state setters; FSM hit-test wired by useConnection) ─────────
+function idleConnection(): ConnectionState {
+  return {
+    inProgress: false,
+    fromNode: null,
+    fromHandle: null,
+    fromPosition: null,
+    fromType: null,
+    toPosition: null,
+    toHandle: null,
+    toNode: null,
+    isValid: null,
+  };
+}
+const connection = shallowRef<ConnectionState>(idleConnection());
+
+function startConnection(from: HandleRegistration, nodeId: string): void {
+  if (!nodesConnectable || !interactive) return;
+  const node = nodeLookup.value.get(nodeId);
+  const handleBound = node?.handleBounds?.[from.type]?.find(h => h.id === from.id) ?? null;
+  connection.value = {
+    inProgress: true,
+    fromNode: nodeId,
+    fromHandle: handleBound,
+    fromPosition: handleBound && node
+      ? { x: node.positionAbsolute.x + handleBound.x + handleBound.width / 2, y: node.positionAbsolute.y + handleBound.y + handleBound.height / 2 }
+      : null,
+    fromType: from.type,
+    toPosition: null,
+    toHandle: null,
+    toNode: null,
+    isValid: null,
+  };
+  emit('connectStart', { nodeId, handleId: from.id, handleType: from.type });
+}
+
+function updateConnection(flowPoint: XYPosition): void {
+  const c = connection.value;
+  if (!c.inProgress || !c.fromType || !c.fromNode || !c.fromHandle) return;
+
+  const radiusFlow = connectionRadius / (viewport.value!.zoom || 1);
+  const candidate = findClosestHandle(
+    flowPoint, nodeLookup.value, c.fromType, c.fromNode, c.fromHandle.id, connectionMode, radiusFlow,
+  );
+
+  let toHandle = null;
+  let toNode = null;
+  let isValid: boolean | null = null;
+  if (candidate) {
+    toHandle = candidate.handle;
+    toNode = candidate.nodeId;
+    const conn = buildConnection(c.fromType, c.fromNode, c.fromHandle, candidate);
+    isValid = isValidConnectionGate(conn, edges.value ?? [], isValidConnection);
+  }
+
+  connection.value = { ...c, toPosition: flowPoint, toHandle, toNode, isValid };
+}
+
+function endConnection(): void {
+  const c = connection.value;
+  if (!c.inProgress) return;
+
+  if (c.isValid && c.toHandle && c.toNode && c.fromHandle && c.fromNode && c.fromType) {
+    const target = { nodeId: c.toNode, handle: c.toHandle };
+    const conn = buildConnection(c.fromType, c.fromNode, c.fromHandle, target);
+    const newEdge: FlowEdge = { id: connectionToEdgeId(conn), ...conn };
+    edges.value = [...(edges.value ?? []), newEdge];
+    emit('connect', conn);
+    emit('edgesChange', [{ type: 'add', item: newEdge }]);
+  }
+
+  connection.value = idleConnection();
+  emit('connectEnd');
+}
+
+// ── provide ──────────────────────────────────────────────────────────────
+const context: FlowContext = {
+  flowId,
+  viewport: viewport as unknown as Ref<Viewport>,
+  paneRect,
+  minZoom: toRef(() => minZoom),
+  maxZoom: toRef(() => maxZoom),
+  isInteracting,
+  nodesDraggable: toRef(() => nodesDraggable),
+  nodesConnectable: toRef(() => nodesConnectable),
+  elementsSelectable: toRef(() => elementsSelectable),
+  snapToGrid: toRef(() => snapToGrid),
+  snapGrid: toRef(() => snapGrid),
+  connectionMode: toRef(() => connectionMode),
+  connectionRadius: toRef(() => connectionRadius),
+  selectionMode: toRef(() => selectionMode),
+  interactive: toRef(() => interactive),
+  disableKeyboardA11y: toRef(() => disableKeyboardA11y),
+  nodeLookup,
+  edgeLookup,
+  selection,
+  connection,
+  visibleNodeIds,
+  visibleEdgeIds,
+  screenToFlow: toFlow,
+  flowToScreen: toScreen,
+  setPaneRect,
+  updateNodePositions,
+  commitNodeDrag,
+  setNodeMeasured,
+  updateNode,
+  isDragging,
+  selectNode,
+  selectEdge,
+  setSelection,
+  clearSelection,
+  removeSelected,
+  startConnection,
+  updateConnection,
+  endConnection,
+  emitNodesChange: changes => emit('nodesChange', changes),
+  emitEdgesChange: changes => emit('edgesChange', changes),
+};
+provideFlowContext(context);
+
+// Imperative API, also exposed so consumers can drive the flow via a template ref.
+const api = useViewportApi(context);
+
+const nodeSlotNames = computed(() => Object.keys(slots).filter(n => n === 'node' || n.startsWith('node-')));
+const edgeSlotNames = computed(() => Object.keys(slots).filter(n => n === 'edge' || n.startsWith('edge-')));
+
+defineExpose({
+  ...api,
+  viewport,
+  nodes,
+  edges,
+  selection,
+  selectNode,
+  selectEdge,
+  setSelection,
+  clearSelection,
+  removeSelected,
+});
+</script>
+
+<template>
+  <FlowPane :as="as">
+    <FlowViewport>
+      <FlowEdgeRenderer :edge-types="edgeTypes">
+        <template
+          v-for="name in edgeSlotNames"
+          :key="name"
+          #[name]="sp"
+        >
+          <slot
+            :name="name"
+            v-bind="sp ?? {}"
+          />
+        </template>
+      </FlowEdgeRenderer>
+
+      <FlowNodeRenderer :node-types="nodeTypes">
+        <template
+          v-for="name in nodeSlotNames"
+          :key="name"
+          #[name]="sp"
+        >
+          <slot
+            :name="name"
+            v-bind="sp ?? {}"
+          />
+        </template>
+      </FlowNodeRenderer>
+    </FlowViewport>
+
+    <slot />
+  </FlowPane>
+</template>
diff --git a/vue/primitives/src/canvas/flow/FlowViewport.vue b/vue/primitives/src/canvas/flow/FlowViewport.vue
new file mode 100644
index 0000000..e743e21
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/FlowViewport.vue
@@ -0,0 +1,52 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The single transformed layer. Every node and the edge `<svg>` live inside it,
+ * so pan/zoom is one GPU-composited `transform` rather than a per-element
+ * restyle. `transform-origin:0 0` is required — the coordinate formulas assume
+ * top-left scaling. `will-change:transform` is toggled on ONLY while interacting
+ * (never permanently): a pinned hint locks the compositor's raster scale, so the
+ * cached texture is GPU-upscaled and the graph blurs at high zoom — toggling it
+ * lets the layer re-rasterise crisply once motion settles (see
+ * `useInteractionState`). Mirrors `FlowNode`'s per-node drag toggle.
+ */
+export interface FlowViewportProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useFlowContext } from './context';
+
+const { as = 'div' } = defineProps<FlowViewportProps>();
+
+const ctx = useFlowContext();
+const { forwardRef } = useForwardExpose();
+
+const transform = computed(() => {
+  const vp = ctx.viewport.value;
+  return `translate(${vp.x}px, ${vp.y}px) scale(${vp.zoom})`;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    data-flow-viewport=""
+    :style="{
+      position: 'absolute',
+      top: '0',
+      left: '0',
+      width: '100%',
+      height: '100%',
+      transformOrigin: '0 0',
+      transform,
+      willChange: ctx.isInteracting.value ? 'transform' : undefined,
+    }"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/flow/__test__/Advanced.test.ts b/vue/primitives/src/canvas/flow/__test__/Advanced.test.ts
new file mode 100644
index 0000000..ae406fb
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/Advanced.test.ts
@@ -0,0 +1,73 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { FlowNodeResizer, FlowNodeToolbar, FlowRoot, useFlow } from '../index';
+import type { FlowNode, UseFlowReturn } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  delete (globalThis as any).__api;
+});
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+const Capture = defineComponent({
+  setup() {
+    (globalThis as any).__api = useFlow();
+    return () => null;
+  },
+});
+
+describe('subflows', () => {
+  it('computes absolute position as the parent chain sum', async () => {
+    const nodes: FlowNode[] = [
+      { id: 'p', position: { x: 100, y: 100 } },
+      { id: 'c', position: { x: 10, y: 20 }, parentId: 'p' },
+    ];
+    track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes },
+      slots: { 'node-default': () => h('div', 'n'), default: () => h(Capture) },
+    }));
+    await nextTick();
+    const api = (globalThis as any).__api as UseFlowReturn;
+    expect(api.getNode('c')?.positionAbsolute).toEqual({ x: 110, y: 120 });
+  });
+});
+
+describe('FlowNodeResizer', () => {
+  it('renders eight resize handles inside a node', () => {
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: [{ id: 'a', position: { x: 0, y: 0 }, width: 120, height: 60 }] },
+      slots: { 'node-default': () => [h('div', 'n'), h(FlowNodeResizer)] },
+    }));
+    expect(w.findAll('[data-flow-resize-handle]')).toHaveLength(8);
+    expect(w.find('[data-flow-resize-handle][data-position="bottom-right"]').exists()).toBe(true);
+  });
+});
+
+describe('FlowNodeToolbar', () => {
+  it('teleports a toolbar to the body only while the node is selected', async () => {
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: [{ id: 'a', position: { x: 0, y: 0 } }] },
+      slots: {
+        'node-default': () => [h('div', 'n'), h(FlowNodeToolbar, null, { default: () => h('button', 'del') })],
+      },
+    }));
+    await nextTick();
+    expect(document.querySelector('[data-flow-node-toolbar]')).toBeNull();
+
+    w.find('[data-id="a"]').element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    expect(w.find('[data-id="a"]').attributes('data-selected')).toBe('');
+    await nextTick();
+    expect(document.querySelector('[data-flow-node-toolbar]')).not.toBeNull();
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/Chrome.test.ts b/vue/primitives/src/canvas/flow/__test__/Chrome.test.ts
new file mode 100644
index 0000000..5df0b4d
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/Chrome.test.ts
@@ -0,0 +1,74 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { h, nextTick } from 'vue';
+import { FlowBackground, FlowControls, FlowMiniMap, FlowPanel, FlowRoot } from '../index';
+import type { FlowNode } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+const nodes: FlowNode[] = [
+  { id: 'a', position: { x: 0, y: 0 } },
+  { id: 'b', position: { x: 300, y: 200 } },
+];
+
+function mountWithChrome(chrome: () => any) {
+  return track(mount(FlowRoot, {
+    attachTo: document.body,
+    props: { defaultNodes: nodes },
+    slots: { 'node-default': () => h('div', 'n'), default: chrome },
+  }));
+}
+
+describe('FlowPanel', () => {
+  it('renders at the requested corner and stops pane events', () => {
+    const w = mountWithChrome(() => h(FlowPanel, { position: 'top-right' }, () => 'panel'));
+    const panel = w.find('[data-flow-panel]');
+    expect(panel.exists()).toBe(true);
+    expect(panel.attributes('data-position')).toBe('top-right');
+    expect((panel.element as HTMLElement).style.position).toBe('absolute');
+  });
+});
+
+describe('FlowBackground', () => {
+  it('renders an svg pattern that reacts to the variant', () => {
+    const w = mountWithChrome(() => h(FlowBackground, { variant: 'lines' }));
+    const bg = w.find('[data-flow-background]');
+    expect(bg.exists()).toBe(true);
+    expect(bg.attributes('data-variant')).toBe('lines');
+    expect(w.find('pattern').exists()).toBe(true);
+  });
+});
+
+describe('FlowControls', () => {
+  it('renders zoom/fit buttons that drive the viewport', async () => {
+    const w = mountWithChrome(() => h(FlowControls));
+    const zoomIn = w.find('[data-flow-control="zoom-in"]');
+    expect(zoomIn.exists()).toBe(true);
+    expect(w.find('[data-flow-control="fit-view"]').exists()).toBe(true);
+
+    const before = (w.find('[data-flow-viewport]').element as HTMLElement).style.transform;
+    await zoomIn.trigger('click');
+    await nextTick();
+    const after = (w.find('[data-flow-viewport]').element as HTMLElement).style.transform;
+    expect(after).not.toBe(before);
+  });
+});
+
+describe('FlowMiniMap', () => {
+  it('renders a rect per node plus a viewport mask', async () => {
+    const w = mountWithChrome(() => h(FlowMiniMap));
+    await nextTick();
+    expect(w.find('[data-flow-minimap]').exists()).toBe(true);
+    expect(w.findAll('[data-flow-minimap-node]')).toHaveLength(2);
+    expect(w.find('[data-flow-minimap-mask]').exists()).toBe(true);
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/Connect.test.ts b/vue/primitives/src/canvas/flow/__test__/Connect.test.ts
new file mode 100644
index 0000000..7b2a8cb
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/Connect.test.ts
@@ -0,0 +1,80 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { h, nextTick } from 'vue';
+import { FlowHandle, FlowRoot } from '../index';
+import type { Connection, FlowNode } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function center(el: Element): { x: number; y: number } {
+  const r = el.getBoundingClientRect();
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+}
+
+const nodeSlot = () => [
+  h('div', { style: 'width:80px;height:40px' }, 'n'),
+  h(FlowHandle, { type: 'target', position: 'left', id: 'in', style: 'width:10px;height:10px' }),
+  h(FlowHandle, { type: 'source', position: 'right', id: 'out', style: 'width:10px;height:10px' }),
+];
+
+describe('connection creation (regression: connecting did nothing)', () => {
+  it('drags from a source handle to a target handle and emits @connect + adds the edge', async () => {
+    const connections: Connection[] = [];
+    const nodes: FlowNode[] = [
+      { id: 'a', position: { x: 20, y: 20 } },
+      { id: 'b', position: { x: 240, y: 20 } },
+    ];
+    const w = mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes, defaultEdges: [], onConnect: (c: Connection) => connections.push(c) },
+      slots: { 'node-default': nodeSlot },
+    });
+    wrappers.push(w);
+    await nextTick();
+    await nextTick(); // allow handle measurement
+
+    const sourceHandle = w.find('[data-id="a"] [data-handletype="source"]').element;
+    const targetHandle = w.find('[data-id="b"] [data-handletype="target"]').element;
+    const target = center(targetHandle);
+
+    // Fast-flick gesture: NO awaits between events. With reactive (watch-based)
+    // listener attachment this dropped the moves and never connected; the
+    // always-on window listeners make it reliable.
+    sourceHandle.dispatchEvent(new PointerEvent('pointerdown', { button: 0, pointerId: 1, ...center(sourceHandle), bubbles: true }));
+    globalThis.dispatchEvent(new PointerEvent('pointermove', { pointerId: 1, clientX: target.x, clientY: target.y }));
+    globalThis.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX: target.x, clientY: target.y }));
+    await nextTick();
+
+    expect(connections).toHaveLength(1);
+    expect(connections[0]).toMatchObject({ source: 'a', target: 'b', sourceHandle: 'out', targetHandle: 'in' });
+    expect(w.findAll('[data-flow-edge]')).toHaveLength(1);
+  });
+
+  it('does not connect a node to itself (strict mode)', async () => {
+    const connections: Connection[] = [];
+    const nodes: FlowNode[] = [{ id: 'a', position: { x: 20, y: 20 } }];
+    const w = mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes, defaultEdges: [], onConnect: (c: Connection) => connections.push(c) },
+      slots: { 'node-default': nodeSlot },
+    });
+    wrappers.push(w);
+    await nextTick();
+    await nextTick();
+
+    const sourceHandle = w.find('[data-id="a"] [data-handletype="source"]').element;
+    const targetHandle = w.find('[data-id="a"] [data-handletype="target"]').element;
+    const target = center(targetHandle);
+    sourceHandle.dispatchEvent(new PointerEvent('pointerdown', { button: 0, pointerId: 1, ...center(sourceHandle), bubbles: true }));
+    await nextTick();
+    globalThis.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX: target.x, clientY: target.y }));
+    await nextTick();
+
+    expect(connections).toHaveLength(0);
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/Drag.test.ts b/vue/primitives/src/canvas/flow/__test__/Drag.test.ts
new file mode 100644
index 0000000..c25620e
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/Drag.test.ts
@@ -0,0 +1,73 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { h, nextTick } from 'vue';
+import { FlowRoot } from '../index';
+import type { FlowEdge, FlowNode } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function raf(): Promise<void> {
+  return new Promise(resolve => requestAnimationFrame(() => resolve()));
+}
+
+function pointer(el: Element, type: string, x: number, y: number) {
+  el.dispatchEvent(new PointerEvent(type, { button: 0, pointerId: 1, clientX: x, clientY: y, bubbles: true, cancelable: true }));
+}
+
+const nodes: FlowNode[] = [
+  { id: 'a', position: { x: 0, y: 0 } },
+  { id: 'b', position: { x: 300, y: 200 } },
+];
+const edges: FlowEdge[] = [{ id: 'e', source: 'a', target: 'b', type: 'straight' }];
+
+function mountFlow() {
+  return mount(FlowRoot, {
+    attachTo: document.body,
+    props: { defaultNodes: nodes, defaultEdges: edges },
+    slots: { 'node-default': () => h('div', { style: 'width:80px;height:40px' }, 'n') },
+  });
+}
+
+describe('node drag updates the DOM (regression: in-place mutation froze nodes)', () => {
+  it('moves the dragged node element and follows with the edge path', async () => {
+    const w = mountFlow();
+    wrappers.push(w);
+    await nextTick();
+
+    const nodeEl = w.find('[data-id="a"]').element as HTMLElement;
+    const edgeBefore = w.find('[data-flow-edge-path]').attributes('d');
+
+    pointer(nodeEl, 'pointerdown', 10, 10);
+    pointer(nodeEl, 'pointermove', 70, 50); // delta (60, 40) at zoom 1
+    await raf();
+    await nextTick();
+
+    const transform = (w.find('[data-id="a"]').element as HTMLElement).style.transform;
+    expect(transform).toBe('translate(60px, 40px)');
+
+    const edgeAfter = w.find('[data-flow-edge-path]').attributes('d');
+    expect(edgeAfter).not.toBe(edgeBefore); // edge endpoint followed the node
+
+    pointer(nodeEl, 'pointerup', 70, 50);
+    await nextTick();
+    // committed to the model
+    expect((w.findAll('[data-flow-node]')[0]!.element as HTMLElement).style.transform).toBe('translate(60px, 40px)');
+  });
+
+  it('does not move other nodes', async () => {
+    const w = mountFlow();
+    wrappers.push(w);
+    await nextTick();
+    const nodeEl = w.find('[data-id="a"]').element as HTMLElement;
+    pointer(nodeEl, 'pointerdown', 10, 10);
+    pointer(nodeEl, 'pointermove', 70, 50);
+    await raf();
+    await nextTick();
+    expect((w.find('[data-id="b"]').element as HTMLElement).style.transform).toBe('translate(300px, 200px)');
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/Flow.test.ts b/vue/primitives/src/canvas/flow/__test__/Flow.test.ts
new file mode 100644
index 0000000..6ef6045
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/Flow.test.ts
@@ -0,0 +1,142 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { h, nextTick, ref } from 'vue';
+import { FlowRoot } from '../index';
+import type { FlowEdge, FlowNode, Viewport } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+const nodeSlot = (p: { data?: { label?: string } }) => h('div', { class: 'node-body' }, p.data?.label ?? '');
+
+function mountFlow(props: Record<string, unknown> = {}) {
+  return track(mount(FlowRoot, {
+    attachTo: document.body,
+    props,
+    slots: { 'node-default': nodeSlot },
+  }));
+}
+
+describe('FlowRoot skeleton', () => {
+  it('renders pane, single transformed viewport and the edge svg', () => {
+    const w = mountFlow({ defaultNodes: [], defaultEdges: [] });
+    expect(w.find('[data-flow-pane]').exists()).toBe(true);
+    const viewport = w.find('[data-flow-viewport]');
+    expect(viewport.exists()).toBe(true);
+    expect((viewport.element as HTMLElement).style.transformOrigin).toBe('0px 0px');
+    // exactly one shared edge layer
+    expect(w.findAll('[data-flow-edges]')).toHaveLength(1);
+  });
+
+  it('applies the viewport transform string', () => {
+    const w = mountFlow({ defaultViewport: { x: 40, y: 20, zoom: 2 } });
+    const t = (w.find('[data-flow-viewport]').element as HTMLElement).style.transform;
+    expect(t).toContain('translate(40px, 20px)');
+    expect(t).toContain('scale(2)');
+  });
+});
+
+describe('node state model', () => {
+  const nodes: FlowNode[] = [
+    { id: 'a', position: { x: 0, y: 0 }, data: { label: 'A' } },
+    { id: 'b', position: { x: 200, y: 100 }, data: { label: 'B' } },
+  ];
+
+  it('uncontrolled defaultNodes seeds the canvas', () => {
+    const w = mountFlow({ defaultNodes: nodes });
+    const els = w.findAll('[data-flow-node]');
+    expect(els).toHaveLength(2);
+    expect(els[0]!.attributes('data-id')).toBe('a');
+    expect((els[1]!.element as HTMLElement).style.transform).toBe('translate(200px, 100px)');
+  });
+
+  it('controlled v-model:nodes reflects external updates', async () => {
+    const model = ref<FlowNode[]>([{ id: 'a', position: { x: 0, y: 0 }, data: { label: 'A' } }]);
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { nodes: model.value, 'onUpdate:nodes': (v: FlowNode[]) => { model.value = v; } },
+      slots: { 'node-default': nodeSlot },
+    }));
+    expect(w.findAll('[data-flow-node]')).toHaveLength(1);
+
+    await w.setProps({ nodes: [...model.value, { id: 'c', position: { x: 10, y: 10 }, data: { label: 'C' } }] });
+    await nextTick();
+    expect(w.findAll('[data-flow-node]')).toHaveLength(2);
+  });
+
+  it('renders the node-default slot content', () => {
+    const w = mountFlow({ defaultNodes: nodes });
+    expect(w.find('[data-id="a"] .node-body').text()).toBe('A');
+  });
+
+  it('hides hidden nodes', () => {
+    const w = mountFlow({ defaultNodes: [{ id: 'a', position: { x: 0, y: 0 } }, { id: 'h', position: { x: 0, y: 0 }, hidden: true }] });
+    expect(w.findAll('[data-flow-node]')).toHaveLength(1);
+  });
+});
+
+describe('edges', () => {
+  const nodes: FlowNode[] = [
+    { id: 'a', position: { x: 0, y: 0 } },
+    { id: 'b', position: { x: 200, y: 100 } },
+  ];
+  const edges: FlowEdge[] = [{ id: 'e1', source: 'a', target: 'b', type: 'straight' }];
+
+  it('renders an edge path between two nodes', async () => {
+    const w = mountFlow({ defaultNodes: nodes, defaultEdges: edges });
+    await nextTick();
+    const edge = w.find('[data-flow-edge]');
+    expect(edge.exists()).toBe(true);
+    expect(edge.attributes('data-id')).toBe('e1');
+    const d = w.find('[data-flow-edge-path]').attributes('d');
+    expect(d).toMatch(/^M /);
+    expect(d).not.toContain('NaN');
+  });
+
+  it('drops edges whose endpoints are missing', () => {
+    const w = mountFlow({ defaultNodes: nodes, defaultEdges: [{ id: 'bad', source: 'a', target: 'zzz' }] });
+    expect(w.find('[data-flow-edge]').exists()).toBe(false);
+  });
+});
+
+describe('selection', () => {
+  it('selects a node on click and marks data-selected', async () => {
+    const onSel = ref<{ nodes: string[]; edges: string[] } | null>(null);
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: {
+        defaultNodes: [{ id: 'a', position: { x: 0, y: 0 } }],
+        onSelectionChange: (s: { nodes: string[]; edges: string[] }) => { onSel.value = s; },
+      },
+      slots: { 'node-default': nodeSlot },
+    }));
+    const node = w.find('[data-id="a"]');
+    node.element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    expect(onSel.value?.nodes).toEqual(['a']);
+    expect(w.find('[data-id="a"]').attributes('data-selected')).toBe('');
+  });
+});
+
+describe('viewport v-model', () => {
+  it('exposes the viewport and updates on prop change', async () => {
+    const vp = ref<Viewport>({ x: 0, y: 0, zoom: 1 });
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { viewport: vp.value, 'onUpdate:viewport': (v: Viewport) => { vp.value = v; } },
+      slots: { 'node-default': nodeSlot },
+    }));
+    await w.setProps({ viewport: { x: 100, y: 50, zoom: 1.5 } });
+    await nextTick();
+    const t = (w.find('[data-flow-viewport]').element as HTMLElement).style.transform;
+    expect(t).toContain('translate(100px, 50px)');
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/Handles.test.ts b/vue/primitives/src/canvas/flow/__test__/Handles.test.ts
new file mode 100644
index 0000000..618dff4
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/Handles.test.ts
@@ -0,0 +1,77 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { h, nextTick } from 'vue';
+import { FlowHandle, FlowRoot } from '../index';
+import type { FlowEdge, FlowNode } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+const nodeWithHandles = () => [
+  h('div', { class: 'body' }, 'node'),
+  h(FlowHandle, { type: 'target', position: 'left', id: 'in' }),
+  h(FlowHandle, { type: 'source', position: 'right', id: 'out' }),
+];
+
+describe('FlowHandle', () => {
+  const nodes: FlowNode[] = [
+    { id: 'a', position: { x: 0, y: 0 } },
+    { id: 'b', position: { x: 300, y: 0 } },
+  ];
+
+  it('renders handles with the right data attributes and side positioning', () => {
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes },
+      slots: { 'node-default': nodeWithHandles },
+    }));
+    const source = w.find('[data-flow-handle][data-handletype="source"]');
+    const target = w.find('[data-flow-handle][data-handletype="target"]');
+    expect(source.exists()).toBe(true);
+    expect(target.exists()).toBe(true);
+    expect(source.attributes('data-handlepos')).toBe('right');
+    expect(source.attributes('data-handleid')).toBe('out');
+    expect((source.element as HTMLElement).style.position).toBe('absolute');
+  });
+
+  it('measures handle bounds so handle ids are present in the DOM for hit-testing', async () => {
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes },
+      slots: { 'node-default': nodeWithHandles },
+    }));
+    await nextTick();
+    expect(w.findAll('[data-handleid]').length).toBeGreaterThanOrEqual(4);
+  });
+});
+
+describe('edge markers', () => {
+  it('renders a deduped marker def and references it from the path', async () => {
+    const nodes: FlowNode[] = [
+      { id: 'a', position: { x: 0, y: 0 } },
+      { id: 'b', position: { x: 200, y: 0 } },
+    ];
+    const edges: FlowEdge[] = [
+      { id: 'e1', source: 'a', target: 'b', markerEnd: { type: 'arrowclosed', color: '#333' } },
+      { id: 'e2', source: 'b', target: 'a', markerEnd: { type: 'arrowclosed', color: '#333' } },
+    ];
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes, defaultEdges: edges },
+      slots: { 'node-default': () => h('div', 'n') },
+    }));
+    await nextTick();
+    // identical markers dedupe to a single <marker>
+    expect(w.findAll('marker')).toHaveLength(1);
+    const path = w.find('[data-flow-edge-path]');
+    expect(path.attributes('marker-end')).toMatch(/^url\(#/);
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/Interactions.test.ts b/vue/primitives/src/canvas/flow/__test__/Interactions.test.ts
new file mode 100644
index 0000000..6a93647
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/Interactions.test.ts
@@ -0,0 +1,95 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { FlowRoot, useFlow } from '../index';
+import type { FlowNode, UseFlowReturn } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  delete (globalThis as any).__api;
+});
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+const nodes: FlowNode[] = [
+  { id: 'a', position: { x: 0, y: 0 } },
+  { id: 'b', position: { x: 200, y: 0 } },
+  { id: 'c', position: { x: 0, y: 200 } },
+];
+
+function key(el: Element, k: string, opts: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key: k, bubbles: true, cancelable: true, ...opts }));
+}
+
+describe('keyboard', () => {
+  it('select-all then delete removes all selected nodes', async () => {
+    const events: Array<{ nodes: string[] }> = [];
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: {
+        defaultNodes: nodes,
+        onSelectionChange: (s: { nodes: string[] }) => events.push(s),
+        onNodesChange: () => {},
+      },
+      slots: { 'node-default': () => h('div', 'n') },
+    }));
+    const pane = w.find('[data-flow-pane]').element;
+
+    key(pane, 'a', { metaKey: true });
+    await nextTick();
+    expect(events.at(-1)?.nodes.sort()).toEqual(['a', 'b', 'c']);
+
+    key(pane, 'Delete');
+    await nextTick();
+    expect(w.findAll('[data-flow-node]')).toHaveLength(0);
+  });
+
+  it('arrow keys nudge the selected node', async () => {
+    const changes: any[] = [];
+    const w = track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes, onNodesChange: (c: any) => changes.push(...c) },
+      slots: { 'node-default': () => h('div', 'n') },
+    }));
+    const pane = w.find('[data-flow-pane]').element;
+    w.find('[data-id="a"]').element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    key(pane, 'ArrowRight');
+    await nextTick();
+    const move = changes.find(c => c.type === 'position' && c.id === 'a');
+    expect(move?.position.x).toBe(5);
+  });
+});
+
+describe('useFlow imperative API', () => {
+  const Capture = defineComponent({
+    setup() {
+      (globalThis as any).__api = useFlow();
+      return () => null;
+    },
+  });
+
+  it('exposes nodes and drives the viewport', async () => {
+    track(mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes },
+      slots: {
+        'node-default': () => h('div', 'n'),
+        default: () => h(Capture),
+      },
+    }));
+    await nextTick();
+    const api = (globalThis as any).__api as UseFlowReturn;
+    expect(api.getNodes()).toHaveLength(3);
+    expect(api.getNode('a')?.id).toBe('a');
+
+    const before = api.getViewport().zoom;
+    api.zoomIn();
+    expect(api.getViewport().zoom).toBeGreaterThan(before);
+  });
+});
diff --git a/vue/primitives/src/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-does-not-call-preventDefault-when-scrollbar-is-non-interactive-1.png b/vue/primitives/src/canvas/flow/__test__/__screenshots__/Advanced.test.ts/FlowNodeToolbar-teleports-a-toolbar-to-the-body-only-while-the-node-is-selected-1.png
similarity index 100%
rename from vue/primitives/src/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-does-not-call-preventDefault-when-scrollbar-is-non-interactive-1.png
rename to vue/primitives/src/canvas/flow/__test__/__screenshots__/Advanced.test.ts/FlowNodeToolbar-teleports-a-toolbar-to-the-body-only-while-the-node-is-selected-1.png
diff --git a/vue/primitives/src/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-is-a-no-op-when-content-does-not-overflow-1.png b/vue/primitives/src/canvas/flow/__test__/__screenshots__/Chrome.test.ts/FlowMiniMap-renders-a-rect-per-node-plus-a-viewport-mask-1.png
similarity index 100%
rename from vue/primitives/src/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-is-a-no-op-when-content-does-not-overflow-1.png
rename to vue/primitives/src/canvas/flow/__test__/__screenshots__/Chrome.test.ts/FlowMiniMap-renders-a-rect-per-node-plus-a-viewport-mask-1.png
diff --git a/vue/primitives/src/canvas/flow/__test__/__screenshots__/Connect.test.ts/connection-creation--regression--connecting-did-nothing--drags-from-a-source-handle-to-a-target-handle-and-emits--connect---adds-the-edge-1.png b/vue/primitives/src/canvas/flow/__test__/__screenshots__/Connect.test.ts/connection-creation--regression--connecting-did-nothing--drags-from-a-source-handle-to-a-target-handle-and-emits--connect---adds-the-edge-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/flow/__test__/__screenshots__/Connect.test.ts/connection-creation--regression--connecting-did-nothing--drags-from-a-source-handle-to-a-target-handle-and-emits--connect---adds-the-edge-1.png differ
diff --git a/vue/primitives/src/canvas/flow/__test__/changes.test.ts b/vue/primitives/src/canvas/flow/__test__/changes.test.ts
new file mode 100644
index 0000000..1ff5dcd
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/changes.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import type { FlowEdge, FlowNode } from '../types';
+import { addEdge, applyEdgeChanges, applyNodeChanges } from '../changes';
+
+const nodes: FlowNode[] = [
+  { id: 'a', position: { x: 0, y: 0 } },
+  { id: 'b', position: { x: 10, y: 10 } },
+];
+
+describe('applyNodeChanges', () => {
+  it('returns the same array reference for no changes', () => {
+    expect(applyNodeChanges([], nodes)).toBe(nodes);
+  });
+
+  it('applies position changes without touching other nodes', () => {
+    const out = applyNodeChanges([{ type: 'position', id: 'a', position: { x: 99, y: 99 } }], nodes);
+    expect(out[0]!.position).toEqual({ x: 99, y: 99 });
+    expect(out[1]).toBe(nodes[1]); // identity preserved for untouched node
+  });
+
+  it('removes nodes', () => {
+    const out = applyNodeChanges([{ type: 'remove', id: 'a' }], nodes);
+    expect(out.map(n => n.id)).toEqual(['b']);
+  });
+
+  it('adds a node at an index', () => {
+    const out = applyNodeChanges([{ type: 'add', item: { id: 'c', position: { x: 0, y: 0 } }, index: 1 }], nodes);
+    expect(out.map(n => n.id)).toEqual(['a', 'c', 'b']);
+  });
+
+  it('toggles selection', () => {
+    const out = applyNodeChanges([{ type: 'select', id: 'b', selected: true }], nodes);
+    expect(out[1]!.selected).toBe(true);
+  });
+
+  it('applies dimensions', () => {
+    const out = applyNodeChanges([{ type: 'dimensions', id: 'a', dimensions: { width: 120, height: 60 } }], nodes);
+    expect(out[0]).toMatchObject({ width: 120, height: 60 });
+  });
+});
+
+describe('applyEdgeChanges', () => {
+  const edges: FlowEdge[] = [{ id: 'e1', source: 'a', target: 'b' }];
+  it('removes and selects edges', () => {
+    expect(applyEdgeChanges([{ type: 'remove', id: 'e1' }], edges)).toHaveLength(0);
+    expect(applyEdgeChanges([{ type: 'select', id: 'e1', selected: true }], edges)[0]!.selected).toBe(true);
+  });
+});
+
+describe('addEdge', () => {
+  const edges: FlowEdge[] = [{ id: 'xy-edge__as-bt', source: 'a', target: 'b', sourceHandle: 's', targetHandle: 't' }];
+  it('appends a connection as an edge', () => {
+    const out = addEdge({ source: 'a', target: 'c', sourceHandle: null, targetHandle: null }, edges);
+    expect(out).toHaveLength(2);
+    expect(out[1]!.source).toBe('a');
+    expect(out[1]!.target).toBe('c');
+  });
+
+  it('skips duplicates by id', () => {
+    const out = addEdge({ source: 'a', target: 'b', sourceHandle: 's', targetHandle: 't' }, edges);
+    expect(out).toBe(edges);
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/connection.test.ts b/vue/primitives/src/canvas/flow/__test__/connection.test.ts
new file mode 100644
index 0000000..52270aa
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/connection.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import type { FlowEdge, HandleBound, InternalNode } from '../types';
+import { buildConnection, connectionToEdgeId, findClosestHandle, isValidConnection } from '../connection';
+
+function handle(id: string | null, type: 'source' | 'target', x: number, y: number): HandleBound {
+  return { id, type, position: type === 'source' ? 'right' : 'left', x, y, width: 0, height: 0 };
+}
+
+function node(id: string, x: number, y: number, handles: HandleBound[]): InternalNode {
+  const bounds = { source: handles.filter(h => h.type === 'source'), target: handles.filter(h => h.type === 'target') };
+  return {
+    id,
+    position: { x, y },
+    measured: { width: 100, height: 40 },
+    positionAbsolute: { x, y },
+    handleBounds: bounds,
+  };
+}
+
+function lookup(...nodes: InternalNode[]): Map<string, InternalNode> {
+  return new Map(nodes.map(n => [n.id, n]));
+}
+
+describe('findClosestHandle', () => {
+  const map = lookup(
+    node('a', 0, 0, [handle('s', 'source', 100, 20)]),
+    node('b', 200, 0, [handle('t', 'target', 0, 20)]),
+  );
+
+  it('finds the opposite-type handle within radius (strict)', () => {
+    // dragging from a's source; target b's target at (200,20)
+    const hit = findClosestHandle({ x: 205, y: 22 }, map, 'source', 'a', 's', 'strict', 30);
+    expect(hit?.nodeId).toBe('b');
+    expect(hit?.handle.id).toBe('t');
+  });
+
+  it('returns null when nothing is within radius', () => {
+    expect(findClosestHandle({ x: 500, y: 500 }, map, 'source', 'a', 's', 'strict', 30)).toBeNull();
+  });
+
+  it('excludes the same node in strict mode', () => {
+    const self = lookup(node('a', 0, 0, [handle('s', 'source', 100, 20), handle('t', 'target', 0, 20)]));
+    expect(findClosestHandle({ x: 0, y: 20 }, self, 'source', 'a', 's', 'strict', 30)).toBeNull();
+  });
+
+  it('allows other handle types on any node in loose mode', () => {
+    const m = lookup(node('a', 0, 0, [handle('s', 'source', 100, 20)]), node('b', 110, 20, [handle('s2', 'source', 0, 0)]));
+    const hit = findClosestHandle({ x: 110, y: 20 }, m, 'source', 'a', 's', 'loose', 30);
+    expect(hit?.nodeId).toBe('b');
+  });
+});
+
+describe('isValidConnection', () => {
+  const edges: FlowEdge[] = [{ id: 'e', source: 'a', target: 'b', sourceHandle: 's', targetHandle: 't' }];
+
+  it('rejects self-connections', () => {
+    expect(isValidConnection({ source: 'a', target: 'a', sourceHandle: null, targetHandle: null }, [])).toBe(false);
+  });
+
+  it('rejects duplicate edges', () => {
+    expect(isValidConnection({ source: 'a', target: 'b', sourceHandle: 's', targetHandle: 't' }, edges)).toBe(false);
+  });
+
+  it('accepts a new distinct connection', () => {
+    expect(isValidConnection({ source: 'a', target: 'c', sourceHandle: null, targetHandle: null }, edges)).toBe(true);
+  });
+
+  it('defers to a custom predicate', () => {
+    const conn = { source: 'a', target: 'c', sourceHandle: null, targetHandle: null };
+    expect(isValidConnection(conn, edges, () => false)).toBe(false);
+    expect(isValidConnection(conn, edges, c => c.target === 'c')).toBe(true);
+  });
+});
+
+describe('buildConnection', () => {
+  const target = { nodeId: 'b', handle: handle('t', 'target', 0, 0), point: { x: 0, y: 0 } };
+
+  it('keeps source/target orientation when dragging from a source', () => {
+    const conn = buildConnection('source', 'a', handle('s', 'source', 0, 0), target);
+    expect(conn).toEqual({ source: 'a', target: 'b', sourceHandle: 's', targetHandle: 't' });
+  });
+
+  it('inverts orientation when dragging from a target', () => {
+    const src = { nodeId: 'b', handle: handle('s', 'source', 0, 0), point: { x: 0, y: 0 } };
+    const conn = buildConnection('target', 'a', handle('t', 'target', 0, 0), src);
+    expect(conn).toEqual({ source: 'b', target: 'a', sourceHandle: 's', targetHandle: 't' });
+  });
+});
+
+describe('connectionToEdgeId', () => {
+  it('is deterministic', () => {
+    const conn = { source: 'a', target: 'b', sourceHandle: 's', targetHandle: 't' };
+    expect(connectionToEdgeId(conn)).toBe(connectionToEdgeId({ ...conn }));
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/edge-paths.test.ts b/vue/primitives/src/canvas/flow/__test__/edge-paths.test.ts
new file mode 100644
index 0000000..afed8b2
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/edge-paths.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getBezierPath,
+  getEdgeCenter,
+  getMarkerId,
+  getSmoothStepPath,
+  getStepPath,
+  getStraightPath,
+} from '../edge-paths';
+
+describe('getStraightPath', () => {
+  it('draws a line and reports the midpoint', () => {
+    const [path, labelX, labelY, ox, oy] = getStraightPath({ sourceX: 0, sourceY: 0, targetX: 100, targetY: 50 });
+    expect(path).toBe('M 0,0 L 100,50');
+    expect([labelX, labelY]).toEqual([50, 25]);
+    expect([ox, oy]).toEqual([50, 25]);
+  });
+});
+
+describe('getEdgeCenter', () => {
+  it('returns centre and absolute offset', () => {
+    expect(getEdgeCenter({ sourceX: 0, sourceY: 0, targetX: 40, targetY: -20 })).toEqual([20, -10, 20, 10]);
+  });
+});
+
+describe('getBezierPath', () => {
+  it('produces a cubic with control points', () => {
+    const [path, labelX, labelY] = getBezierPath({ sourceX: 0, sourceY: 0, sourcePosition: 'bottom', targetX: 0, targetY: 200, targetPosition: 'top' });
+    expect(path.startsWith('M 0,0 C')).toBe(true);
+    expect(Number.isFinite(labelX)).toBe(true);
+    expect(labelY).toBeCloseTo(100, 6);
+  });
+
+  it('does not collapse to NaN when the target is behind the source (sqrt fallback)', () => {
+    const [path] = getBezierPath({ sourceX: 0, sourceY: 0, sourcePosition: 'bottom', targetX: 0, targetY: -200, targetPosition: 'top' });
+    expect(path).not.toContain('NaN');
+  });
+});
+
+describe('getSmoothStepPath', () => {
+  it('produces an orthogonal path with rounded corners', () => {
+    const [path, labelX, labelY] = getSmoothStepPath({ sourceX: 0, sourceY: 0, sourcePosition: 'bottom', targetX: 200, targetY: 200, targetPosition: 'top' });
+    expect(path.startsWith('M ')).toBe(true);
+    expect(path).toContain('Q'); // at least one rounded corner
+    expect(path).not.toContain('NaN');
+    expect(Number.isFinite(labelX) && Number.isFinite(labelY)).toBe(true);
+  });
+
+  it('clamps the corner radius and never emits NaN for close handles', () => {
+    const [path] = getSmoothStepPath({ sourceX: 0, sourceY: 0, sourcePosition: 'right', targetX: 5, targetY: 5, targetPosition: 'left', borderRadius: 100 });
+    expect(path).not.toContain('NaN');
+  });
+});
+
+describe('getStepPath', () => {
+  it('is a smooth-step path with zero radius (no curve)', () => {
+    const [path] = getStepPath({ sourceX: 0, sourceY: 0, sourcePosition: 'bottom', targetX: 200, targetY: 200, targetPosition: 'top' });
+    expect(path).not.toContain('NaN');
+    expect(path.startsWith('M ')).toBe(true);
+  });
+});
+
+describe('getMarkerId', () => {
+  it('is deterministic for identical descriptors (dedupe key)', () => {
+    const a = getMarkerId({ type: 'arrowclosed', color: '#222' }, 'flow1');
+    const b = getMarkerId({ type: 'arrowclosed', color: '#222' }, 'flow1');
+    expect(a).toBe(b);
+  });
+
+  it('differs for different markers or flows', () => {
+    expect(getMarkerId({ type: 'arrow' }, 'flow1')).not.toBe(getMarkerId({ type: 'arrowclosed' }, 'flow1'));
+    expect(getMarkerId({ type: 'arrow' }, 'flow1')).not.toBe(getMarkerId({ type: 'arrow' }, 'flow2'));
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/interaction-state.test.ts b/vue/primitives/src/canvas/flow/__test__/interaction-state.test.ts
new file mode 100644
index 0000000..0eb110c
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/interaction-state.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import { effectScope, nextTick, shallowRef } from 'vue';
+import type { Viewport } from '../types';
+import { useInteractionState } from '../composables/useInteractionState';
+
+describe('useInteractionState', () => {
+  it('flips true on a viewport change and back to false after the idle delay', async () => {
+    vi.useFakeTimers();
+    try {
+      const viewport = shallowRef<Viewport>({ x: 0, y: 0, zoom: 1 });
+      const scope = effectScope();
+      const interacting = scope.run(() => useInteractionState(() => viewport.value, 200))!;
+
+      expect(interacting.value).toBe(false);
+
+      viewport.value = { x: 10, y: 0, zoom: 1.2 };
+      await nextTick();
+      expect(interacting.value).toBe(true);
+
+      // Still interacting before the idle delay elapses.
+      vi.advanceTimersByTime(150);
+      expect(interacting.value).toBe(true);
+
+      // A further change (continuous zoom) resets the idle countdown.
+      viewport.value = { x: 20, y: 0, zoom: 1.5 };
+      await nextTick();
+      vi.advanceTimersByTime(150);
+      expect(interacting.value).toBe(true);
+
+      // Settles to false once motion stops for the full delay.
+      vi.advanceTimersByTime(200);
+      expect(interacting.value).toBe(false);
+
+      scope.stop();
+    }
+    finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('clears its pending timer on scope dispose so it never resolves late', async () => {
+    vi.useFakeTimers();
+    try {
+      const viewport = shallowRef<Viewport>({ x: 0, y: 0, zoom: 1 });
+      const scope = effectScope();
+      const interacting = scope.run(() => useInteractionState(() => viewport.value, 200))!;
+
+      viewport.value = { x: 5, y: 5, zoom: 1 };
+      await nextTick();
+      expect(interacting.value).toBe(true);
+
+      scope.stop();
+      // The pending idle timer was cleared on dispose: advancing past it must
+      // not flip the (now detached) ref.
+      vi.advanceTimersByTime(500);
+      expect(interacting.value).toBe(true);
+    }
+    finally {
+      vi.useRealTimers();
+    }
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/utils.test.ts b/vue/primitives/src/canvas/flow/__test__/utils.test.ts
new file mode 100644
index 0000000..408f663
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/utils.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+import type { InternalNode, Viewport } from '../types';
+import {
+  fitViewTransform,
+  flowToScreen,
+  getAbsoluteHandlePoint,
+  getNodePositionAbsolute,
+  getNodesBounds,
+  getNodesInsideRect,
+  nodeInRect,
+  rectContains,
+  rectsIntersect,
+  screenToFlow,
+  snapPoint,
+  visibleFlowRect,
+  zoomAtPointer,
+} from '../utils';
+
+const ORIGIN = { left: 0, top: 0 };
+
+function node(id: string, x: number, y: number, w = 100, h = 50, parentId?: string): InternalNode {
+  return {
+    id,
+    position: { x, y },
+    parentId,
+    measured: { width: w, height: h },
+    positionAbsolute: { x, y },
+    handleBounds: null,
+  };
+}
+
+describe('screenToFlow / flowToScreen', () => {
+  it('are exact inverses at zoom 1', () => {
+    const vp: Viewport = { x: 30, y: -10, zoom: 1 };
+    const p = { x: 123, y: 456 };
+    const flow = screenToFlow(p, vp, ORIGIN);
+    expect(flowToScreen(flow, vp, ORIGIN)).toEqual(p);
+  });
+
+  it('are exact inverses at zoom != 1 and with a pane origin', () => {
+    const vp: Viewport = { x: 200, y: 80, zoom: 1.5 };
+    const origin = { left: 64, top: 40 };
+    const p = { x: 512, y: 300 };
+    const flow = screenToFlow(p, vp, origin);
+    const back = flowToScreen(flow, vp, origin);
+    expect(back.x).toBeCloseTo(p.x, 6);
+    expect(back.y).toBeCloseTo(p.y, 6);
+  });
+
+  it('divides out zoom and translation', () => {
+    const vp: Viewport = { x: 100, y: 50, zoom: 2 };
+    expect(screenToFlow({ x: 100, y: 50 }, vp, ORIGIN)).toEqual({ x: 0, y: 0 });
+    expect(screenToFlow({ x: 300, y: 250 }, vp, ORIGIN)).toEqual({ x: 100, y: 100 });
+  });
+});
+
+describe('zoomAtPointer', () => {
+  it('keeps the pointer anchored while zooming', () => {
+    const vp: Viewport = { x: 0, y: 0, zoom: 1 };
+    const pointer = { x: 400, y: 300 };
+    const next = zoomAtPointer(vp, pointer, 2);
+    // The flow point under the pointer must be identical before and after.
+    const before = screenToFlow(pointer, vp, ORIGIN);
+    const after = screenToFlow(pointer, next, ORIGIN);
+    expect(after.x).toBeCloseTo(before.x, 6);
+    expect(after.y).toBeCloseTo(before.y, 6);
+    expect(next.zoom).toBe(2);
+  });
+});
+
+describe('snapPoint', () => {
+  it('rounds to the nearest grid intersection', () => {
+    expect(snapPoint({ x: 23, y: 47 }, [10, 10])).toEqual({ x: 20, y: 50 });
+    expect(snapPoint({ x: 26, y: 41 }, [10, 20])).toEqual({ x: 30, y: 40 });
+  });
+
+  it('passes through on a zero grid axis', () => {
+    expect(snapPoint({ x: 7, y: 9 }, [0, 0])).toEqual({ x: 7, y: 9 });
+  });
+});
+
+describe('getNodesBounds', () => {
+  it('encloses all nodes', () => {
+    const bounds = getNodesBounds([node('a', 0, 0, 100, 50), node('b', 200, 100, 50, 50)]);
+    expect(bounds).toEqual({ x: 0, y: 0, width: 250, height: 150 });
+  });
+
+  it('returns a zero rect when empty', () => {
+    expect(getNodesBounds([])).toEqual({ x: 0, y: 0, width: 0, height: 0 });
+  });
+});
+
+describe('fitViewTransform', () => {
+  it('centres known bounds in the container', () => {
+    const bounds = { x: 0, y: 0, width: 100, height: 100 };
+    const vp = fitViewTransform(bounds, { width: 400, height: 400 }, { padding: 0, minZoom: 0.1, maxZoom: 4 });
+    expect(vp.zoom).toBeCloseTo(4, 6);
+    // center of bounds (50,50) maps to container center (200,200)
+    const center = flowToScreen({ x: 50, y: 50 }, vp, ORIGIN);
+    expect(center.x).toBeCloseTo(200, 6);
+    expect(center.y).toBeCloseTo(200, 6);
+  });
+
+  it('respects maxZoom', () => {
+    const vp = fitViewTransform({ x: 0, y: 0, width: 10, height: 10 }, { width: 1000, height: 1000 }, { padding: 0, minZoom: 0.5, maxZoom: 2 });
+    expect(vp.zoom).toBe(2);
+  });
+});
+
+describe('rect predicates', () => {
+  const a = { x: 0, y: 0, width: 100, height: 100 };
+  it('detects intersection and containment', () => {
+    expect(rectsIntersect(a, { x: 50, y: 50, width: 100, height: 100 })).toBe(true);
+    expect(rectsIntersect(a, { x: 200, y: 0, width: 10, height: 10 })).toBe(false);
+    expect(rectContains(a, { x: 10, y: 10, width: 20, height: 20 })).toBe(true);
+    expect(rectContains(a, { x: 90, y: 90, width: 20, height: 20 })).toBe(false);
+  });
+
+  it('nodeInRect honours partial vs full', () => {
+    const n = node('n', 80, 80, 40, 40); // overlaps a but not contained
+    expect(nodeInRect(n, a, 'partial')).toBe(true);
+    expect(nodeInRect(n, a, 'full')).toBe(false);
+  });
+
+  it('getNodesInsideRect collects ids and skips hidden', () => {
+    const hidden = { ...node('h', 10, 10), hidden: true };
+    const ids = getNodesInsideRect([node('a', 10, 10), node('b', 500, 500), hidden], a, 'partial');
+    expect(ids).toEqual(['a']);
+  });
+});
+
+describe('visibleFlowRect', () => {
+  it('expands the visible area by the buffer in flow space', () => {
+    const rect = visibleFlowRect({ x: 0, y: 0, zoom: 1 }, { width: 800, height: 600 }, 100);
+    expect(rect).toEqual({ x: -100, y: -100, width: 1000, height: 800 });
+  });
+});
+
+describe('getNodePositionAbsolute', () => {
+  it('sums the parent chain', () => {
+    const lookup = new Map<string, InternalNode>();
+    lookup.set('parent', node('parent', 100, 100));
+    lookup.set('child', node('child', 10, 20, 100, 50, 'parent'));
+    const abs = getNodePositionAbsolute(lookup.get('child')!, lookup);
+    expect(abs).toEqual({ x: 110, y: 120 });
+  });
+});
+
+describe('getAbsoluteHandlePoint', () => {
+  it('returns the handle centre in absolute flow coords', () => {
+    const point = getAbsoluteHandlePoint({ x: 100, y: 100 }, { id: null, type: 'source', position: 'right', x: 100, y: 25, width: 10, height: 10 });
+    expect(point).toEqual({ x: 205, y: 130 });
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/__test__/virtualization.test.ts b/vue/primitives/src/canvas/flow/__test__/virtualization.test.ts
new file mode 100644
index 0000000..30f55f7
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/__test__/virtualization.test.ts
@@ -0,0 +1,62 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { h, nextTick } from 'vue';
+import { getVisibleEdgeIds, getVisibleNodeIds } from '../virtualization';
+import { FlowRoot } from '../index';
+import type { FlowEdge, FlowNode, InternalNode } from '../index';
+
+function internal(id: string, x: number, y: number, w = 100, h = 50): InternalNode {
+  return { id, position: { x, y }, measured: { width: w, height: h }, positionAbsolute: { x, y }, handleBounds: null };
+}
+
+describe('getVisibleNodeIds', () => {
+  const lookup = new Map<string, InternalNode>([
+    ['a', internal('a', 0, 0)],
+    ['b', internal('b', 5000, 5000)],
+  ]);
+  const nodes = [...lookup.values()];
+
+  it('keeps nodes intersecting the rect and culls the rest', () => {
+    const rect = { x: -100, y: -100, width: 800, height: 600 };
+    expect(getVisibleNodeIds(nodes, lookup, rect)).toEqual(['a']);
+  });
+
+  it('keeps unmeasured nodes (no internal entry) so they are not flicker-culled', () => {
+    const ids = getVisibleNodeIds([{ id: 'z', position: { x: 9999, y: 9999 } } as FlowNode], new Map(), { x: 0, y: 0, width: 10, height: 10 });
+    expect(ids).toEqual(['z']);
+  });
+});
+
+describe('getVisibleEdgeIds', () => {
+  it('keeps edges with at least one visible endpoint', () => {
+    const edges: FlowEdge[] = [
+      { id: 'e1', source: 'a', target: 'b' },
+      { id: 'e2', source: 'b', target: 'c' },
+    ];
+    expect(getVisibleEdgeIds(edges, new Set(['a']))).toEqual(['e1']);
+  });
+});
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+describe('FlowRoot onlyRenderVisibleElements', () => {
+  it('renders all nodes by default', async () => {
+    const nodes: FlowNode[] = [
+      { id: 'a', position: { x: 0, y: 0 } },
+      { id: 'far', position: { x: 100000, y: 100000 } },
+    ];
+    const w = mount(FlowRoot, {
+      attachTo: document.body,
+      props: { defaultNodes: nodes },
+      slots: { 'node-default': () => h('div', 'n') },
+    });
+    wrappers.push(w);
+    await nextTick();
+    expect(w.findAll('[data-flow-node]')).toHaveLength(2);
+  });
+});
diff --git a/vue/primitives/src/canvas/flow/changes.ts b/vue/primitives/src/canvas/flow/changes.ts
new file mode 100644
index 0000000..f0683e0
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/changes.ts
@@ -0,0 +1,111 @@
+import type { Connection, EdgeChange, FlowEdge, FlowNode, NodeChange } from './types';
+import { connectionToEdgeId } from './connection';
+
+/**
+ * Apply a batch of node changes to a nodes array, returning a NEW array (and new
+ * objects only for changed nodes — untouched nodes keep identity so per-node
+ * `v-memo` stays effective). The React-Flow-style helper for controlled mode:
+ * bind `@nodes-change` and call this in your handler.
+ */
+export function applyNodeChanges<Data = unknown>(changes: Array<NodeChange<Data>>, nodes: Array<FlowNode<Data>>): Array<FlowNode<Data>> {
+  if (changes.length === 0) return nodes;
+
+  const byId = new Map(nodes.map(n => [n.id, n]));
+  const removed = new Set<string>();
+  const added: Array<{ item: FlowNode<Data>; index?: number }> = [];
+
+  for (const c of changes) {
+    switch (c.type) {
+      case 'position': {
+        const n = byId.get(c.id);
+        if (n && c.position) byId.set(c.id, { ...n, position: c.position });
+        break;
+      }
+      case 'dimensions': {
+        const n = byId.get(c.id);
+        if (n) byId.set(c.id, { ...n, width: c.dimensions.width, height: c.dimensions.height });
+        break;
+      }
+      case 'select': {
+        const n = byId.get(c.id);
+        if (n) byId.set(c.id, { ...n, selected: c.selected });
+        break;
+      }
+      case 'remove':
+        removed.add(c.id);
+        break;
+      case 'add':
+        added.push({ item: c.item, index: c.index });
+        break;
+      case 'replace':
+        if (byId.has(c.id)) byId.set(c.id, c.item);
+        break;
+    }
+  }
+
+  const result = nodes
+    .filter(n => !removed.has(n.id))
+    .map(n => byId.get(n.id) ?? n);
+
+  for (const { item, index } of added) {
+    if (index === undefined || index >= result.length) result.push(item);
+    else result.splice(index, 0, item);
+  }
+
+  return result;
+}
+
+/** Apply a batch of edge changes to an edges array, returning a NEW array. */
+export function applyEdgeChanges<Data = unknown>(changes: Array<EdgeChange<Data>>, edges: Array<FlowEdge<Data>>): Array<FlowEdge<Data>> {
+  if (changes.length === 0) return edges;
+
+  const byId = new Map(edges.map(e => [e.id, e]));
+  const removed = new Set<string>();
+  const added: Array<{ item: FlowEdge<Data>; index?: number }> = [];
+
+  for (const c of changes) {
+    switch (c.type) {
+      case 'select': {
+        const e = byId.get(c.id);
+        if (e) byId.set(c.id, { ...e, selected: c.selected });
+        break;
+      }
+      case 'remove':
+        removed.add(c.id);
+        break;
+      case 'add':
+        added.push({ item: c.item, index: c.index });
+        break;
+      case 'replace':
+        if (byId.has(c.id)) byId.set(c.id, c.item);
+        break;
+    }
+  }
+
+  const result = edges
+    .filter(e => !removed.has(e.id))
+    .map(e => byId.get(e.id) ?? e);
+
+  for (const { item, index } of added) {
+    if (index === undefined || index >= result.length) result.push(item);
+    else result.splice(index, 0, item);
+  }
+
+  return result;
+}
+
+/**
+ * Append an edge for a connection (or a full edge) to an edges array, skipping
+ * duplicates. Returns the same array when the edge already exists.
+ */
+export function addEdge<Data = unknown>(
+  edgeOrConnection: Connection | FlowEdge<Data>,
+  edges: Array<FlowEdge<Data>>,
+): Array<FlowEdge<Data>> {
+  const edge: FlowEdge<Data> = 'id' in edgeOrConnection
+    ? edgeOrConnection
+    : { id: connectionToEdgeId(edgeOrConnection), ...edgeOrConnection } as FlowEdge<Data>;
+
+  if (edges.some(e => e.id === edge.id)) return edges;
+  return [...edges, edge];
+}
diff --git a/vue/primitives/src/canvas/flow/composables/dom.ts b/vue/primitives/src/canvas/flow/composables/dom.ts
new file mode 100644
index 0000000..e26b25a
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/dom.ts
@@ -0,0 +1,22 @@
+/**
+ * `setPointerCapture` / `releasePointerCapture` throw when there is no live
+ * pointer for the id — which happens for synthetic events in tests and for
+ * pointers that were already released. These guards swallow only that case.
+ */
+export function capturePointer(el: HTMLElement | undefined, id: number): void {
+  try {
+    el?.setPointerCapture?.(id);
+  }
+  catch {
+    /* no active pointer (synthetic event) */
+  }
+}
+
+export function releasePointer(el: HTMLElement | undefined, id: number): void {
+  try {
+    el?.releasePointerCapture?.(id);
+  }
+  catch {
+    /* pointer already released */
+  }
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useConnection.ts b/vue/primitives/src/canvas/flow/composables/useConnection.ts
new file mode 100644
index 0000000..176552b
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useConnection.ts
@@ -0,0 +1,63 @@
+import { onScopeDispose } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import type { FlowContext } from '../context';
+import type { XYPosition } from '../types';
+
+/**
+ * Drives an in-progress connection: while `connection.inProgress`, follows the
+ * pointer (converting to flow space and hit-testing candidate handles via
+ * `ctx.updateConnection`) and finalises on pointerup (`ctx.endConnection`).
+ *
+ * Listeners are bound to the window ONCE on mount (client only) and stay bound
+ * for the component's life — the handlers no-op unless a connection is active.
+ * This avoids the race of attaching them reactively when a drag starts.
+ *
+ * `updateConnection` is RAF-batched: a pointermove only stashes the latest flow
+ * point, and at most one hit-test (`findClosestHandle` scans every handle) +
+ * state write runs per frame — matching usePanZoom / useNodeDrag, instead of
+ * 60–120×/sec. pointerup flushes the pending point synchronously first so the
+ * committed connection reflects the final cursor position.
+ */
+export function useConnection(ctx: FlowContext): void {
+  let rafId: number | null = null;
+  let pending: XYPosition | null = null;
+
+  function flush(): void {
+    rafId = null;
+    if (pending) {
+      ctx.updateConnection(pending);
+      pending = null;
+    }
+  }
+
+  function onMove(event: PointerEvent): void {
+    if (!ctx.connection.value.inProgress) return;
+    pending = ctx.screenToFlow({ x: event.clientX, y: event.clientY });
+    if (rafId === null) rafId = requestAnimationFrame(flush);
+  }
+
+  function onUp(): void {
+    if (!ctx.connection.value.inProgress) return;
+    // Apply the last pointer position before committing.
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    flush();
+    ctx.endConnection();
+  }
+
+  // Listeners stay bound to the window for the component's life and are
+  // auto-removed on scope dispose. SSR-safe: the window default no-ops without a
+  // `window`. The handlers no-op unless a connection is active.
+  useEventListener('pointermove', onMove);
+  useEventListener('pointerup', onUp);
+
+  // `useEventListener` owns the listeners; we still cancel any pending RAF here.
+  onScopeDispose(() => {
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  });
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useFlow.ts b/vue/primitives/src/canvas/flow/composables/useFlow.ts
new file mode 100644
index 0000000..8a455cf
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useFlow.ts
@@ -0,0 +1,40 @@
+import type { Ref, ShallowRef } from 'vue';
+import { useFlowContext } from '../context';
+import type { FlowSelection } from '../context';
+import type { Viewport } from '../types';
+import type { FlowApi } from './useViewportApi';
+import { useViewportApi } from './useViewportApi';
+
+/** Everything a consumer needs to drive a flow imperatively from app code. */
+export interface UseFlowReturn extends FlowApi {
+  /** Reactive viewport. */
+  viewport: Ref<Viewport>;
+  /** Reactive selection sets. */
+  selection: ShallowRef<FlowSelection>;
+  selectNode: (id: string, additive?: boolean) => void;
+  selectEdge: (id: string, additive?: boolean) => void;
+  setSelection: (nodes: string[], edges: string[]) => void;
+  clearSelection: () => void;
+  removeSelected: () => void;
+}
+
+/**
+ * Public consumer hook (the "useReactFlow"/"useVueFlow" equivalent). Call from
+ * any component inside a `FlowRoot` to read reactive state and drive the canvas:
+ * `fitView`, `setViewport`, `zoomIn/Out`, `screenToFlowPosition`, selection, and
+ * node/edge getters. Throws if used outside a `FlowRoot`.
+ */
+export function useFlow(): UseFlowReturn {
+  const ctx = useFlowContext();
+  const api = useViewportApi(ctx);
+  return {
+    ...api,
+    viewport: ctx.viewport,
+    selection: ctx.selection,
+    selectNode: ctx.selectNode,
+    selectEdge: ctx.selectEdge,
+    setSelection: ctx.setSelection,
+    clearSelection: ctx.clearSelection,
+    removeSelected: ctx.removeSelected,
+  };
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useInteractionState.ts b/vue/primitives/src/canvas/flow/composables/useInteractionState.ts
new file mode 100644
index 0000000..7bfefe0
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useInteractionState.ts
@@ -0,0 +1,40 @@
+import type { Ref, WatchSource } from 'vue';
+import { onScopeDispose, shallowRef, watch } from 'vue';
+import type { Viewport } from '../types';
+
+/**
+ * True while the viewport is actively panning/zooming, flipped back to `false`
+ * `idleDelay` ms after the last change. Driven purely by viewport mutations, so
+ * it covers every path — wheel, pinch, drag-pan, double-click and the imperative
+ * `zoomIn`/`zoomTo`/`fitView` API — without each call site having to opt in.
+ *
+ * Used to gate `will-change: transform` on `FlowViewport`. Keeping that hint on
+ * permanently pins the compositor's raster scale: the layer is rasterised once
+ * and the `scale(zoom)` is applied by GPU-upscaling that cached texture, so at
+ * high zoom every node and edge stays blurry even after the gesture ends.
+ * Toggling the hint on only while interacting lets the browser re-rasterise the
+ * layer crisply once motion settles — the same pattern `FlowNode` already uses
+ * for its drag transform.
+ */
+export function useInteractionState(
+  source: WatchSource<Viewport>,
+  idleDelay = 200,
+): Readonly<Ref<boolean>> {
+  const interacting = shallowRef(false);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  watch(source, () => {
+    interacting.value = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => {
+      interacting.value = false;
+      timer = undefined;
+    }, idleDelay);
+  });
+
+  onScopeDispose(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+
+  return interacting;
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useKeyboard.ts b/vue/primitives/src/canvas/flow/composables/useKeyboard.ts
new file mode 100644
index 0000000..da2adf0
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useKeyboard.ts
@@ -0,0 +1,107 @@
+import type { Ref } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import type { FlowContext } from '../context';
+import type { XYPosition } from '../types';
+import type { FlowApi } from './useViewportApi';
+
+export interface KeyboardOptions {
+  /** Keys that delete the selection. @default ['Backspace', 'Delete'] */
+  deleteKeyCode?: string[];
+  /** Pixel step for arrow-key node nudging. @default 5 */
+  nudgeStep?: number;
+}
+
+const EDITABLE = /^(?:input|textarea|select)$/i;
+
+/** True when focus is in a text field, so global shortcuts must stand down. */
+function isTyping(): boolean {
+  const el = document.activeElement as HTMLElement | null;
+  return !!el && (EDITABLE.test(el.tagName) || el.isContentEditable);
+}
+
+/**
+ * Canvas keyboard layer (scoped to the pane, suppressed while typing): Delete /
+ * Backspace removes the selection, ⌘/Ctrl+A selects all, Arrows nudge selected
+ * nodes (Shift = ×4), ⌘/Ctrl +/-/0 zoom-in/out/fit, Escape clears selection and
+ * cancels an in-progress connection. Disabled via `disableKeyboardA11y`.
+ */
+export function useKeyboard(
+  target: Ref<HTMLElement | undefined>,
+  ctx: FlowContext,
+  api: FlowApi,
+  options: KeyboardOptions = {},
+): void {
+  const deleteKeys = options.deleteKeyCode ?? ['Backspace', 'Delete'];
+  const step = options.nudgeStep ?? 5;
+
+  function nudge(dx: number, dy: number): void {
+    const sel = ctx.selection.value.nodes;
+    if (sel.size === 0) return;
+    const moves = new Map<string, XYPosition>();
+    for (const id of sel) {
+      const node = ctx.nodeLookup.value.get(id);
+      if (node && node.draggable !== false)
+        moves.set(id, { x: node.position.x + dx, y: node.position.y + dy });
+    }
+    if (moves.size === 0) return;
+    ctx.updateNodePositions(moves, false);
+    ctx.commitNodeDrag();
+  }
+
+  useEventListener(target, 'keydown', (event: KeyboardEvent) => {
+    if (ctx.disableKeyboardA11y.value || !ctx.interactive.value || isTyping()) return;
+    const mod = event.metaKey || event.ctrlKey;
+
+    if (deleteKeys.includes(event.key)) {
+      event.preventDefault();
+      ctx.removeSelected();
+      return;
+    }
+
+    if (mod && (event.key === 'a' || event.key === 'A')) {
+      event.preventDefault();
+      ctx.setSelection(
+        [...ctx.nodeLookup.value.keys()],
+        ctx.elementsSelectable.value ? [...ctx.edgeLookup.value.keys()] : [],
+      );
+      return;
+    }
+
+    if (event.key === 'Escape') {
+      ctx.endConnection();
+      ctx.clearSelection();
+      return;
+    }
+
+    if (mod) {
+      if (event.key === '=' || event.key === '+') {
+        event.preventDefault();
+        api.zoomIn();
+        return;
+      }
+      if (event.key === '-') {
+        event.preventDefault();
+        api.zoomOut();
+        return;
+      }
+      if (event.key === '0') {
+        event.preventDefault();
+        api.fitView();
+        return;
+      }
+    }
+
+    const dist = event.shiftKey ? step * 4 : step;
+    const arrows: Record<string, XYPosition> = {
+      ArrowUp: { x: 0, y: -dist },
+      ArrowDown: { x: 0, y: dist },
+      ArrowLeft: { x: -dist, y: 0 },
+      ArrowRight: { x: dist, y: 0 },
+    };
+    const delta = arrows[event.key];
+    if (delta) {
+      event.preventDefault();
+      nudge(delta.x, delta.y);
+    }
+  });
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useMarquee.ts b/vue/primitives/src/canvas/flow/composables/useMarquee.ts
new file mode 100644
index 0000000..9e157ef
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useMarquee.ts
@@ -0,0 +1,84 @@
+import type { Ref } from 'vue';
+import { shallowRef } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import type { FlowContext } from '../context';
+import { getNodesInsideRect } from '../utils';
+import { capturePointer, releasePointer } from './dom';
+
+/** A marquee rectangle in pane-relative pixels, for rendering the overlay. */
+export interface MarqueeRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Shift + drag on the empty pane draws a selection rectangle and selects the
+ * nodes it covers on release (`selectionMode` decides partial vs full). Pan is
+ * suppressed while Shift is held (see `usePanZoom`), so the two never fight.
+ * Returns the live rect for `FlowPane` to render.
+ */
+export function useMarquee(
+  target: Ref<HTMLElement | undefined>,
+  ctx: FlowContext,
+): { active: Readonly<Ref<boolean>>; rect: Readonly<Ref<MarqueeRect | null>> } {
+  const active = shallowRef(false);
+  const rect = shallowRef<MarqueeRect | null>(null);
+
+  let pointerId = -1;
+  let startClientX = 0;
+  let startClientY = 0;
+
+  function paneRelative(clientX: number, clientY: number): { x: number; y: number } {
+    const pane = ctx.paneRect.value;
+    return { x: clientX - pane.left, y: clientY - pane.top };
+  }
+
+  useEventListener(target, 'pointerdown', (event: PointerEvent) => {
+    if (event.button !== 0 || !event.shiftKey) return;
+    if (!ctx.interactive.value || !ctx.elementsSelectable.value) return;
+    pointerId = event.pointerId;
+    startClientX = event.clientX;
+    startClientY = event.clientY;
+    active.value = true;
+    rect.value = { ...paneRelative(event.clientX, event.clientY), width: 0, height: 0 };
+    capturePointer(target.value, event.pointerId);
+  });
+
+  useEventListener(target, 'pointermove', (event: PointerEvent) => {
+    if (!active.value || event.pointerId !== pointerId) return;
+    const start = paneRelative(startClientX, startClientY);
+    const cur = paneRelative(event.clientX, event.clientY);
+    rect.value = {
+      x: Math.min(start.x, cur.x),
+      y: Math.min(start.y, cur.y),
+      width: Math.abs(cur.x - start.x),
+      height: Math.abs(cur.y - start.y),
+    };
+  });
+
+  function end(event: PointerEvent): void {
+    if (!active.value || event.pointerId !== pointerId) return;
+    const a = ctx.screenToFlow({ x: startClientX, y: startClientY });
+    const b = ctx.screenToFlow({ x: event.clientX, y: event.clientY });
+    const flowRect = {
+      x: Math.min(a.x, b.x),
+      y: Math.min(a.y, b.y),
+      width: Math.abs(b.x - a.x),
+      height: Math.abs(b.y - a.y),
+    };
+    const ids = getNodesInsideRect(ctx.nodeLookup.value.values(), flowRect, ctx.selectionMode.value);
+    ctx.setSelection(ids, []);
+
+    active.value = false;
+    rect.value = null;
+    pointerId = -1;
+    releasePointer(target.value, event.pointerId);
+  }
+
+  useEventListener(target, 'pointerup', end);
+  useEventListener(target, 'pointercancel', end);
+
+  return { active, rect };
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useNodeDrag.ts b/vue/primitives/src/canvas/flow/composables/useNodeDrag.ts
new file mode 100644
index 0000000..abe483a
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useNodeDrag.ts
@@ -0,0 +1,164 @@
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import { onScopeDispose, shallowRef, toValue } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import { clamp } from '@robonen/stdlib';
+import type { FlowContext } from '../context';
+import type { InternalNode, XYPosition } from '../types';
+import { snapPoint } from '../utils';
+import { capturePointer, releasePointer } from './dom';
+
+/** Constrain a dragged position by a node's `extent` (parent box or explicit rect). */
+function applyExtent(pos: XYPosition, node: InternalNode, lookup: Map<string, InternalNode>): XYPosition {
+  if (node.extent === 'parent' && node.parentId) {
+    const parent = lookup.get(node.parentId);
+    if (!parent) return pos;
+    return {
+      x: clamp(pos.x, 0, Math.max(0, parent.measured.width - node.measured.width)),
+      y: clamp(pos.y, 0, Math.max(0, parent.measured.height - node.measured.height)),
+    };
+  }
+  if (Array.isArray(node.extent)) {
+    const [[x1, y1], [x2, y2]] = node.extent;
+    return {
+      x: clamp(pos.x, x1, x2 - node.measured.width),
+      y: clamp(pos.y, y1, y2 - node.measured.height),
+    };
+  }
+  return pos;
+}
+
+export interface NodeDragOptions {
+  /** Pixels the pointer must travel before a click becomes a drag. @default 1 */
+  threshold?: number;
+}
+
+/** Elements inside a node that must not initiate a drag. */
+const NO_DRAG_SELECTOR = 'input, textarea, select, button, [contenteditable="true"], [data-handleid], .nodrag';
+
+/**
+ * Pointer-capture node drag. Moves the node (and every co-selected node) by the
+ * pointer delta converted to flow space (`delta / zoom`), optionally snapped to
+ * the grid. Positions are written to the transient drag overlay every frame and
+ * committed to the model once on pointerup — never 60×/sec.
+ *
+ * Stops propagation so the pane never pans while a node is grabbed. A pointer
+ * that never crosses `threshold` stays a click (selection handled elsewhere).
+ */
+export function useNodeDrag(
+  target: Ref<HTMLElement | undefined>,
+  ctx: FlowContext,
+  nodeId: MaybeRefOrGetter<string>,
+  options: NodeDragOptions = {},
+): { dragging: Readonly<Ref<boolean>> } {
+  const threshold = options.threshold ?? 1;
+  const dragging = shallowRef(false);
+
+  let pointerId = -1;
+  let startX = 0;
+  let startY = 0;
+  let started = false;
+  let lastX = 0;
+  let lastY = 0;
+  let rafId: number | null = null;
+  /** id → starting flow-space position, snapshot at pointerdown. */
+  let snapshot = new Map<string, XYPosition>();
+  /** Reused across RAF frames — only the container is pooled; entries are fresh. */
+  const nextPositions = new Map<string, XYPosition>();
+
+  function eligible(): boolean {
+    if (!ctx.interactive.value || !ctx.nodesDraggable.value) return false;
+    const node = ctx.nodeLookup.value.get(toValue(nodeId));
+    return !!node && node.draggable !== false;
+  }
+
+  function collectDragSet(id: string): Map<string, XYPosition> {
+    const set = new Map<string, XYPosition>();
+    const selected = ctx.selection.value.nodes;
+    const ids = selected.has(id) && selected.size > 1 ? selected : new Set([id]);
+    for (const nid of ids) {
+      const node = ctx.nodeLookup.value.get(nid);
+      if (node && node.draggable !== false)
+        set.set(nid, { x: node.position.x, y: node.position.y });
+    }
+    return set;
+  }
+
+  function flush() {
+    rafId = null;
+    const dx = (lastX - startX) / ctx.viewport.value.zoom;
+    const dy = (lastY - startY) / ctx.viewport.value.zoom;
+    const snap = ctx.snapToGrid.value;
+    const grid = ctx.snapGrid.value;
+    const next = nextPositions;
+    next.clear();
+    for (const [id, start] of snapshot) {
+      let pos: XYPosition = { x: start.x + dx, y: start.y + dy };
+      if (snap) pos = snapPoint(pos, grid);
+      const node = ctx.nodeLookup.value.get(id);
+      if (node?.extent) pos = applyExtent(pos, node, ctx.nodeLookup.value);
+      next.set(id, pos);
+    }
+    ctx.updateNodePositions(next, true);
+  }
+
+  function schedule() {
+    if (rafId === null) rafId = requestAnimationFrame(flush);
+  }
+
+  onScopeDispose(() => {
+    if (rafId !== null) cancelAnimationFrame(rafId);
+  });
+
+  useEventListener(target, 'pointerdown', (event: PointerEvent) => {
+    if (event.button !== 0) return;
+    if (event.target instanceof Element && event.target.closest(NO_DRAG_SELECTOR)) return;
+    // Always stop the pane from treating this as a pan, even when not draggable.
+    event.stopPropagation();
+    if (!eligible()) return;
+
+    const id = toValue(nodeId);
+    snapshot = collectDragSet(id);
+    if (snapshot.size === 0) return;
+
+    pointerId = event.pointerId;
+    startX = lastX = event.clientX;
+    startY = lastY = event.clientY;
+    started = false;
+    capturePointer(target.value, event.pointerId);
+  });
+
+  useEventListener(target, 'pointermove', (event: PointerEvent) => {
+    if (pointerId !== event.pointerId || snapshot.size === 0) return;
+    lastX = event.clientX;
+    lastY = event.clientY;
+
+    if (!started) {
+      if (Math.abs(lastX - startX) < threshold && Math.abs(lastY - startY) < threshold) return;
+      started = true;
+      dragging.value = true;
+    }
+    schedule();
+  });
+
+  function endDrag(event: PointerEvent) {
+    if (pointerId !== event.pointerId) return;
+    releasePointer(target.value, event.pointerId);
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    if (started) {
+      flush();
+      ctx.commitNodeDrag();
+    }
+    pointerId = -1;
+    started = false;
+    dragging.value = false;
+    snapshot = new Map();
+  }
+
+  useEventListener(target, 'pointerup', endDrag);
+  useEventListener(target, 'pointercancel', endDrag);
+
+  return { dragging };
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useNodesInView.ts b/vue/primitives/src/canvas/flow/composables/useNodesInView.ts
new file mode 100644
index 0000000..687c40e
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useNodesInView.ts
@@ -0,0 +1,43 @@
+import type { ComputedRef } from 'vue';
+import { computed } from 'vue';
+import type { FlowContext } from '../context';
+import type { Rect } from '../types';
+import { visibleFlowRect } from '../utils';
+import { getVisibleEdgeIds, getVisibleNodeIds } from '../virtualization';
+
+export interface UseNodesInViewOptions {
+  /** Extra px around the viewport kept "in view". @default 200 */
+  buffer?: number;
+}
+
+export interface UseNodesInViewReturn {
+  /** Flow-space rect currently visible (buffered). */
+  visibleRect: ComputedRef<Rect>;
+  /** Ids of nodes intersecting the visible rect. */
+  visibleNodeIds: ComputedRef<string[]>;
+  /** Ids of edges with an endpoint in view. */
+  visibleEdgeIds: ComputedRef<string[]>;
+}
+
+/**
+ * Reactive viewport culling for very large graphs. `FlowRoot` already culls
+ * internally when `onlyRenderVisibleElements` is set; this composable exposes
+ * the same computation to advanced consumers building custom renderers or
+ * spatial overlays. Recomputes on pan/zoom — only enable where the node count
+ * makes culling worth the per-frame cost.
+ */
+export function useNodesInView(ctx: FlowContext, options: UseNodesInViewOptions = {}): UseNodesInViewReturn {
+  const buffer = options.buffer ?? 200;
+
+  const visibleRect = computed(() => visibleFlowRect(ctx.viewport.value, ctx.paneRect.value, buffer));
+
+  const visibleNodeIds = computed(() =>
+    getVisibleNodeIds(ctx.nodeLookup.value.values(), ctx.nodeLookup.value, visibleRect.value));
+
+  const visibleNodeSet = computed(() => new Set(visibleNodeIds.value));
+
+  const visibleEdgeIds = computed(() =>
+    getVisibleEdgeIds(ctx.edgeLookup.value.values(), visibleNodeSet.value));
+
+  return { visibleRect, visibleNodeIds, visibleEdgeIds };
+}
diff --git a/vue/primitives/src/canvas/flow/composables/usePanZoom.ts b/vue/primitives/src/canvas/flow/composables/usePanZoom.ts
new file mode 100644
index 0000000..414aa1c
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/usePanZoom.ts
@@ -0,0 +1,169 @@
+import type { Ref } from 'vue';
+import { onScopeDispose, shallowRef } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import type { FlowContext } from '../context';
+import type { Viewport } from '../types';
+import { clampZoom, wheelToZoomFactor, zoomAtPointer } from '../utils';
+import { capturePointer, releasePointer } from './dom';
+
+export interface PanZoomOptions {
+  /** Wheel scroll zooms toward the pointer. @default true */
+  zoomOnScroll?: boolean;
+  /** Trackpad pinch (ctrl+wheel) zooms. @default true */
+  zoomOnPinch?: boolean;
+  /** Wheel scroll pans instead of zooms (pinch still zooms). @default false */
+  panOnScroll?: boolean;
+  /** Scroll-pan speed multiplier. @default 0.5 */
+  panOnScrollSpeed?: number;
+  /** Drag the empty pane to pan. @default true */
+  panOnDrag?: boolean;
+  /** Double-click zooms in toward the pointer. @default true */
+  zoomOnDoubleClick?: boolean;
+  /** Factor applied per double-click. @default 1.2 */
+  doubleClickZoomFactor?: number;
+}
+
+/** True if the event target opts out of panning via a `.nopan` ancestor. */
+function isPanBlocked(target: EventTarget | null): boolean {
+  return target instanceof Element && !!target.closest('.nopan');
+}
+
+/**
+ * Wires wheel zoom-at-pointer, optional scroll-pan, and drag-pan onto the pane
+ * element, writing the master `viewport` through one RAF-batched flush per frame
+ * so a burst of wheel/pointer events never causes more than one layout write.
+ *
+ * Node drag stops propagation on its own pointerdown, so any pointerdown that
+ * reaches the pane is a pan (or, later, a marquee — gated by the caller).
+ */
+export function usePanZoom(
+  target: Ref<HTMLElement | undefined>,
+  ctx: FlowContext,
+  options: PanZoomOptions = {},
+): { isPanning: Readonly<Ref<boolean>>; panningRef: Ref<boolean> } {
+  const {
+    zoomOnScroll = true,
+    zoomOnPinch = true,
+    panOnScroll = false,
+    panOnScrollSpeed = 0.5,
+    panOnDrag = true,
+    zoomOnDoubleClick = true,
+    doubleClickZoomFactor = 1.2,
+  } = options;
+
+  // ── RAF-batched viewport writes ──────────────────────────────────────────
+  let rafId: number | null = null;
+  let pending: Viewport | null = null;
+
+  function flush() {
+    rafId = null;
+    if (pending) {
+      ctx.viewport.value = pending;
+      pending = null;
+    }
+  }
+
+  function schedule(next: Viewport) {
+    pending = next;
+    if (rafId === null) rafId = requestAnimationFrame(flush);
+  }
+
+  /** Latest known viewport, including any not-yet-flushed pending value. */
+  function current(): Viewport {
+    return pending ?? ctx.viewport.value;
+  }
+
+  onScopeDispose(() => {
+    if (rafId !== null) cancelAnimationFrame(rafId);
+  });
+
+  function paneOffset(event: { clientX: number; clientY: number }) {
+    const rect = ctx.paneRect.value;
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  }
+
+  // ── wheel ────────────────────────────────────────────────────────────────
+  useEventListener(target, 'wheel', (event: WheelEvent) => {
+    if (!ctx.interactive.value) return;
+    if (event.target instanceof Element && event.target.closest('.nowheel')) return;
+
+    const pinch = event.ctrlKey;
+    const shouldZoom = pinch ? zoomOnPinch : zoomOnScroll && !panOnScroll;
+
+    event.preventDefault();
+
+    if (shouldZoom) {
+      const vp = current();
+      const factor = wheelToZoomFactor(event);
+      const newZoom = clampZoom(vp.zoom * factor, ctx.minZoom.value, ctx.maxZoom.value);
+      if (newZoom === vp.zoom) return;
+      schedule(zoomAtPointer(vp, paneOffset(event), newZoom));
+      return;
+    }
+
+    // Scroll-pan.
+    const vp = current();
+    schedule({
+      zoom: vp.zoom,
+      x: vp.x - event.deltaX * panOnScrollSpeed,
+      y: vp.y - event.deltaY * panOnScrollSpeed,
+    });
+  }, { passive: false });
+
+  // ── drag-pan ───────────────────────────────────────────────────────────────
+  const panningRef = shallowRef(false);
+  let startX = 0;
+  let startY = 0;
+  let baseX = 0;
+  let baseY = 0;
+  let pointerId = -1;
+
+  useEventListener(target, 'pointerdown', (event: PointerEvent) => {
+    if (!panOnDrag || !ctx.interactive.value) return;
+    if (event.button !== 0 && event.button !== 1) return;
+    // Shift + drag is reserved for marquee selection.
+    if (event.button === 0 && event.shiftKey) return;
+    if (isPanBlocked(event.target)) return;
+
+    const vp = current();
+    startX = event.clientX;
+    startY = event.clientY;
+    baseX = vp.x;
+    baseY = vp.y;
+    pointerId = event.pointerId;
+    panningRef.value = true;
+    capturePointer(target.value, event.pointerId);
+  });
+
+  useEventListener(target, 'pointermove', (event: PointerEvent) => {
+    if (!panningRef.value || event.pointerId !== pointerId) return;
+    const vp = current();
+    schedule({
+      zoom: vp.zoom,
+      x: baseX + (event.clientX - startX),
+      y: baseY + (event.clientY - startY),
+    });
+  });
+
+  function endPan(event: PointerEvent) {
+    if (!panningRef.value || event.pointerId !== pointerId) return;
+    panningRef.value = false;
+    pointerId = -1;
+    releasePointer(target.value, event.pointerId);
+  }
+
+  useEventListener(target, 'pointerup', endPan);
+  useEventListener(target, 'pointercancel', endPan);
+
+  // ── double-click zoom ──────────────────────────────────────────────────────
+  useEventListener(target, 'dblclick', (event: MouseEvent) => {
+    if (!zoomOnDoubleClick || !ctx.interactive.value) return;
+    if (event.target instanceof Element && event.target.closest('.nopan')) return;
+    const vp = current();
+    const newZoom = clampZoom(vp.zoom * doubleClickZoomFactor, ctx.minZoom.value, ctx.maxZoom.value);
+    if (newZoom === vp.zoom) return;
+    schedule(zoomAtPointer(vp, paneOffset(event), newZoom));
+  });
+
+  return { isPanning: panningRef, panningRef };
+}
diff --git a/vue/primitives/src/canvas/flow/composables/useViewportApi.ts b/vue/primitives/src/canvas/flow/composables/useViewportApi.ts
new file mode 100644
index 0000000..7d3ab54
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/composables/useViewportApi.ts
@@ -0,0 +1,86 @@
+import type { FlowContext } from '../context';
+import type { FlowEdge, InternalNode, Viewport, XYPosition } from '../types';
+import { clampZoom, fitViewTransform, getNodesBounds, zoomAtPointer } from '../utils';
+
+export interface FitViewParams {
+  /** Fractional inset on each side, 0–1. @default 0.1 */
+  padding?: number;
+  /** Restrict the fit to these node ids. */
+  nodes?: string[];
+}
+
+/** Imperative, framework-agnostic control surface for the flow. */
+export interface FlowApi {
+  /** Current viewport `{x,y,zoom}`. */
+  getViewport: () => Viewport;
+  /** Replace the viewport. */
+  setViewport: (viewport: Viewport) => void;
+  /** Zoom in toward the pane centre. */
+  zoomIn: (factor?: number) => void;
+  /** Zoom out from the pane centre. */
+  zoomOut: (factor?: number) => void;
+  /** Zoom to an absolute level, anchored at the pane centre. */
+  zoomTo: (zoom: number) => void;
+  /** Fit all (or the given) nodes into view. */
+  fitView: (params?: FitViewParams) => void;
+  /** Convert a screen (client) point to flow space. */
+  screenToFlowPosition: (point: XYPosition) => XYPosition;
+  /** Convert a flow-space point to a screen (client) point. */
+  flowToScreenPosition: (point: XYPosition) => XYPosition;
+  /** All internal nodes (with measured geometry). */
+  getNodes: () => InternalNode[];
+  /** One internal node by id. */
+  getNode: (id: string) => InternalNode | undefined;
+  /** All edges. */
+  getEdges: () => FlowEdge[];
+  /** One edge by id. */
+  getEdge: (id: string) => FlowEdge | undefined;
+}
+
+/** Builds the imperative API over a flow context. */
+export function useViewportApi(ctx: FlowContext): FlowApi {
+  function center(): XYPosition {
+    const rect = ctx.paneRect.value;
+    return { x: rect.width / 2, y: rect.height / 2 };
+  }
+
+  function zoomBy(factor: number): void {
+    const vp = ctx.viewport.value;
+    const next = clampZoom(vp.zoom * factor, ctx.minZoom.value, ctx.maxZoom.value);
+    if (next === vp.zoom) return;
+    ctx.viewport.value = zoomAtPointer(vp, center(), next);
+  }
+
+  return {
+    getViewport: () => ctx.viewport.value,
+    setViewport: (vp) => { ctx.viewport.value = vp; },
+    zoomIn: (factor = 1.2) => zoomBy(factor),
+    zoomOut: (factor = 1.2) => zoomBy(1 / factor),
+    zoomTo: (zoom) => {
+      const vp = ctx.viewport.value;
+      const next = clampZoom(zoom, ctx.minZoom.value, ctx.maxZoom.value);
+      ctx.viewport.value = zoomAtPointer(vp, center(), next);
+    },
+    fitView: (params = {}) => {
+      const rect = ctx.paneRect.value;
+      if (rect.width === 0 || rect.height === 0) return;
+      const all = [...ctx.nodeLookup.value.values()].filter(n => !n.hidden);
+      const subset = params.nodes
+        ? all.filter(n => params.nodes!.includes(n.id))
+        : all;
+      if (subset.length === 0) return;
+      const bounds = getNodesBounds(subset);
+      ctx.viewport.value = fitViewTransform(bounds, { width: rect.width, height: rect.height }, {
+        padding: params.padding ?? 0.1,
+        minZoom: ctx.minZoom.value,
+        maxZoom: ctx.maxZoom.value,
+      });
+    },
+    screenToFlowPosition: point => ctx.screenToFlow(point),
+    flowToScreenPosition: point => ctx.flowToScreen(point),
+    getNodes: () => [...ctx.nodeLookup.value.values()],
+    getNode: id => ctx.nodeLookup.value.get(id),
+    getEdges: () => [...ctx.edgeLookup.value.values()],
+    getEdge: id => ctx.edgeLookup.value.get(id),
+  };
+}
diff --git a/vue/primitives/src/canvas/flow/connection.ts b/vue/primitives/src/canvas/flow/connection.ts
new file mode 100644
index 0000000..43038ab
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/connection.ts
@@ -0,0 +1,100 @@
+import type {
+  Connection,
+  ConnectionMode,
+  FlowEdge,
+  HandleBound,
+  HandleType,
+  InternalNode,
+  IsValidConnection,
+  XYPosition,
+} from './types';
+import { getAbsoluteHandlePoint } from './utils';
+
+/** A hovered drop candidate during a connection drag. */
+export interface ConnectionTarget {
+  nodeId: string;
+  handle: HandleBound;
+}
+
+/**
+ * Closest handle to `point` (flow space) within `radius`, eligible as a drop
+ * target given the drag origin. In `strict` mode only the opposite handle type
+ * on a *different* node qualifies; in `loose` mode any handle but the origin's
+ * own does. Returns `null` when nothing is in range.
+ */
+export function findClosestHandle(
+  point: XYPosition,
+  nodeLookup: Map<string, InternalNode>,
+  fromType: HandleType,
+  fromNodeId: string,
+  fromHandleId: string | null,
+  mode: ConnectionMode,
+  radius: number,
+): ConnectionTarget | null {
+  const types: HandleType[] = mode === 'loose'
+    ? ['source', 'target']
+    : [fromType === 'source' ? 'target' : 'source'];
+
+  let best: ConnectionTarget | null = null;
+  let bestDist = radius;
+
+  for (const node of nodeLookup.values()) {
+    if (node.hidden || !node.handleBounds) continue;
+    if (mode === 'strict' && node.id === fromNodeId) continue;
+
+    for (const type of types) {
+      for (const handle of node.handleBounds[type]) {
+        if (node.id === fromNodeId && handle.id === fromHandleId && handle.type === fromType) continue;
+        const p = getAbsoluteHandlePoint(node.positionAbsolute, handle);
+        const dist = Math.hypot(p.x - point.x, p.y - point.y);
+        if (dist <= bestDist) {
+          bestDist = dist;
+          best = { nodeId: node.id, handle };
+        }
+      }
+    }
+  }
+
+  return best;
+}
+
+/** Orient a connection so `source` is always the source-typed end. */
+export function buildConnection(
+  fromType: HandleType,
+  fromNodeId: string,
+  fromHandle: HandleBound,
+  target: ConnectionTarget,
+): Connection {
+  return fromType === 'source'
+    ? { source: fromNodeId, target: target.nodeId, sourceHandle: fromHandle.id, targetHandle: target.handle.id }
+    : { source: target.nodeId, target: fromNodeId, sourceHandle: target.handle.id, targetHandle: fromHandle.id };
+}
+
+/**
+ * Default connection gate: rejects self-loops and duplicates, then defers to a
+ * consumer-supplied `custom` predicate.
+ */
+export function isValidConnection(
+  conn: Connection,
+  edges: Iterable<FlowEdge>,
+  custom?: IsValidConnection,
+): boolean {
+  if (conn.source === conn.target) return false;
+
+  for (const e of edges) {
+    if (
+      e.source === conn.source
+      && e.target === conn.target
+      && (e.sourceHandle ?? null) === conn.sourceHandle
+      && (e.targetHandle ?? null) === conn.targetHandle
+    ) return false;
+  }
+
+  if (custom && !custom(conn)) return false;
+  return true;
+}
+
+/** Deterministic edge id from a connection's endpoints. */
+export function connectionToEdgeId(conn: Connection): string {
+  return `xy-edge__${conn.source}${conn.sourceHandle ?? ''}-${conn.target}${conn.targetHandle ?? ''}`;
+}
diff --git a/vue/primitives/src/canvas/flow/context.ts b/vue/primitives/src/canvas/flow/context.ts
new file mode 100644
index 0000000..51fea4f
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/context.ts
@@ -0,0 +1,150 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type {
+  ConnectionMode,
+  ConnectionState,
+  Dimensions,
+  EdgeChange,
+  FlowEdge,
+  FlowNode,
+  HandleType,
+  InternalNode,
+  NodeChange,
+  Position,
+  SelectionMode,
+  Viewport,
+  XYPosition,
+} from './types';
+
+/**
+ * Namespaced collection keys. Two `useCollectionProvider` instances live under
+ * one `FlowRoot` — one for node elements, one for edge `<g>` elements — so they
+ * MUST use distinct keys, otherwise the inner provider shadows the outer for
+ * every descendant (see `useCollection` namespacing note).
+ */
+export const FLOW_NODES_COLLECTION = 'flow-nodes';
+export const FLOW_EDGES_COLLECTION = 'flow-edges';
+
+/** Canonical selection store: Sets give O(1) membership on the hot path. */
+export interface FlowSelection {
+  nodes: Set<string>;
+  edges: Set<string>;
+}
+
+/** A handle registering itself into its node's sub-context. */
+export interface HandleRegistration {
+  id: string | null;
+  type: HandleType;
+  position: Position;
+  element: HTMLElement;
+}
+
+/**
+ * Root context shared by every flow part. Reactive fields are `Ref`/`ShallowRef`
+ * (never raw values — descendants would lose reactivity); mutations go through
+ * the action functions so behaviour stays in one place.
+ */
+export interface FlowContext {
+  /** Stable id for scoping DOM ids / marker ids per flow instance. */
+  flowId: string;
+
+  // ── viewport + measurement ──────────────────────────────────────────────
+  /** The master transform `{x,y,zoom}`. */
+  viewport: Ref<Viewport>;
+  /** Live bounding rect of `FlowPane`; the screen origin for coord math. */
+  paneRect: Readonly<Ref<{ left: number; top: number; width: number; height: number }>>;
+  minZoom: Ref<number>;
+  maxZoom: Ref<number>;
+  /** True while the viewport is actively panning/zooming (gates `will-change`). */
+  isInteracting: Readonly<Ref<boolean>>;
+
+  // ── capability flags (global defaults, overridable per element) ───────────
+  nodesDraggable: Ref<boolean>;
+  nodesConnectable: Ref<boolean>;
+  elementsSelectable: Ref<boolean>;
+  snapToGrid: Ref<boolean>;
+  snapGrid: Ref<[number, number]>;
+  connectionMode: Ref<ConnectionMode>;
+  connectionRadius: Ref<number>;
+  selectionMode: Ref<SelectionMode>;
+  /** Master interactivity switch (lock). */
+  interactive: Ref<boolean>;
+  /** Disable the keyboard a11y layer (and `role=application`). */
+  disableKeyboardA11y: Ref<boolean>;
+
+  // ── data access (shallow Maps — mutate in place + triggerRef) ────────────
+  /** Read path for components, keyed by node id. */
+  nodeLookup: ShallowRef<Map<string, InternalNode>>;
+  /** Read path for components, keyed by edge id. */
+  edgeLookup: ShallowRef<Map<string, FlowEdge>>;
+  /** Canonical selection state (replace wholesale + triggerRef). */
+  selection: ShallowRef<FlowSelection>;
+  /** Live connection-drag state (only the preview + hovered handle subscribe). */
+  connection: ShallowRef<ConnectionState>;
+  /** Ordered id list of currently rendered (post-virtualization) nodes. */
+  visibleNodeIds: ComputedRef<string[]>;
+  /** Ordered id list of currently rendered edges. */
+  visibleEdgeIds: ComputedRef<string[]>;
+
+  // ── coordinate actions ───────────────────────────────────────────────────
+  /** Screen (client) point → flow space. */
+  screenToFlow: (point: XYPosition) => XYPosition;
+  /** Flow space → screen (client) point. */
+  flowToScreen: (point: XYPosition) => XYPosition;
+  /** `FlowPane` reports its live bounding rect here (the screen origin). */
+  setPaneRect: (rect: { left: number; top: number; width: number; height: number }) => void;
+
+  // ── node actions ─────────────────────────────────────────────────────────
+  /** Apply a batch of per-node flow-space deltas (drag). Transient. */
+  updateNodePositions: (deltas: Map<string, XYPosition>, dragging: boolean) => void;
+  /** Commit the in-flight drag overlay into the model (one change). */
+  commitNodeDrag: () => void;
+  /** Write a measured size for a node into `nodeLookup`. */
+  setNodeMeasured: (id: string, size: Dimensions, handleBounds: InternalNode['handleBounds']) => void;
+  /** Patch a node in the model (e.g. resize/move) and emit the matching change. */
+  updateNode: (id: string, patch: Partial<FlowNode>) => void;
+  /** True while a node drag is in progress (blocks external sync clobber). */
+  isDragging: Readonly<Ref<boolean>>;
+
+  // ── selection actions ────────────────────────────────────────────────────
+  selectNode: (id: string, additive?: boolean) => void;
+  selectEdge: (id: string, additive?: boolean) => void;
+  setSelection: (nodes: string[], edges: string[]) => void;
+  clearSelection: () => void;
+  removeSelected: () => void;
+
+  // ── connection actions ───────────────────────────────────────────────────
+  startConnection: (from: HandleRegistration, nodeId: string) => void;
+  updateConnection: (flowPoint: XYPosition) => void;
+  endConnection: () => void;
+
+  // ── change emission ──────────────────────────────────────────────────────
+  emitNodesChange: (changes: NodeChange[]) => void;
+  emitEdgesChange: (changes: EdgeChange[]) => void;
+}
+
+const flow = useContextFactory<FlowContext>('FlowContext');
+export const provideFlowContext = flow.provide;
+export const useFlowContext = flow.inject;
+
+/**
+ * Per-node sub-context. Read by `FlowHandle`, `FlowNodeResizer`,
+ * `FlowNodeToolbar` so they never DOM-walk to find their node's state.
+ */
+export interface FlowNodeContext {
+  nodeId: string;
+  node: ComputedRef<InternalNode | undefined>;
+  positionAbsolute: ComputedRef<XYPosition>;
+  measured: ComputedRef<Dimensions>;
+  selected: ComputedRef<boolean>;
+  dragging: ComputedRef<boolean>;
+  connectable: ComputedRef<boolean>;
+  /** Element of the node wrapper, for handle measurement. */
+  nodeRef: Readonly<Ref<HTMLElement | undefined>>;
+  registerHandle: (reg: HandleRegistration) => void;
+  unregisterHandle: (id: string | null, type: HandleType) => void;
+}
+
+const flowNode = useContextFactory<FlowNodeContext>('FlowNodeContext');
+export const provideFlowNodeContext = flowNode.provide;
+export const useFlowNodeContext = flowNode.inject;
diff --git a/vue/primitives/src/canvas/flow/demo.vue b/vue/primitives/src/canvas/flow/demo.vue
new file mode 100644
index 0000000..b1d66d6
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/demo.vue
@@ -0,0 +1,278 @@
+<script setup lang="ts">
+import {
+  FlowBackground,
+  FlowControls,
+  FlowHandle,
+  FlowMiniMap,
+  FlowNodeResizer,
+  FlowNodeToolbar,
+  FlowPanel,
+  FlowRoot,
+} from '@robonen/primitives';
+import type { FlowEdge, FlowNode } from '@robonen/primitives';
+import { computed, ref, useTemplateRef } from 'vue';
+
+interface NodeData {
+  label: string;
+  hint?: string;
+}
+
+const nodes = ref<FlowNode<NodeData>[]>([
+  { id: 'group', type: 'group', position: { x: 380, y: 220 }, width: 360, height: 190, data: { label: 'Processing pipeline' }, selectable: true, draggable: true },
+  { id: 'src', type: 'input', position: { x: 60, y: 120 }, data: { label: 'Source', hint: 'HTTP ingest' } },
+  { id: 'norm', type: 'process', position: { x: 24, y: 60 }, parentId: 'group', extent: 'parent', data: { label: 'Normalize' } },
+  { id: 'enrich', type: 'process', position: { x: 200, y: 60 }, parentId: 'group', extent: 'parent', data: { label: 'Enrich' } },
+  { id: 'score', type: 'process', position: { x: 60, y: 300 }, data: { label: 'Score', hint: 'ML model' } },
+  { id: 'sink', type: 'output', position: { x: 820, y: 180 }, data: { label: 'Sink', hint: 'Warehouse' } },
+]);
+
+const edges = ref<FlowEdge[]>([
+  { id: 'e-src-norm', source: 'src', target: 'norm', type: 'smoothstep', animated: true, markerEnd: { type: 'arrowclosed' } },
+  { id: 'e-norm-enrich', source: 'norm', target: 'enrich', type: 'smoothstep', markerEnd: { type: 'arrowclosed' } },
+  { id: 'e-src-score', source: 'src', target: 'score', type: 'bezier', markerEnd: { type: 'arrowclosed' } },
+  { id: 'e-enrich-sink', source: 'enrich', target: 'sink', type: 'labeled', label: 'records', markerEnd: { type: 'arrowclosed' } },
+  { id: 'e-score-sink', source: 'score', target: 'sink', type: 'labeled', label: 'anomalies', markerEnd: { type: 'arrowclosed' } },
+]);
+
+const flow = useTemplateRef<InstanceType<typeof FlowRoot>>('flow');
+const selectedCount = computed(() => {
+  const sel = flow.value?.selection?.value;
+  return sel ? sel.nodes.size + sel.edges.size : 0;
+});
+
+let seq = 0;
+function addNode() {
+  seq += 1;
+  const id = `dyn-${seq}`;
+  nodes.value = [...nodes.value, { id, type: 'process', position: { x: 120 + seq * 30, y: 440 + seq * 10 }, data: { label: `Step ${seq}` } }];
+}
+
+function removeNode(id: string) {
+  nodes.value = nodes.value.filter(n => n.id !== id && n.parentId !== id);
+  edges.value = edges.value.filter(e => e.source !== id && e.target !== id);
+}
+
+function duplicateNode(id: string) {
+  const node = nodes.value.find(n => n.id === id);
+  if (!node) return;
+  seq += 1;
+  nodes.value = [...nodes.value, { ...node, id: `${id}-copy-${seq}`, position: { x: node.position.x + 40, y: node.position.y + 40 }, parentId: undefined }];
+}
+</script>
+
+<template>
+  <div class="demo-card h-[520px] w-full overflow-hidden rounded-xl border border-border bg-bg-inset text-fg-subtle">
+    <FlowRoot
+      ref="flow"
+      v-model:nodes="nodes"
+      v-model:edges="edges"
+      class="size-full"
+      :min-zoom="0.2"
+      :max-zoom="2.5"
+      :snap-to-grid="true"
+      :snap-grid="[16, 16]"
+    >
+      <!-- Group / subflow container -->
+      <template #node-group="{ data, selected }">
+        <div
+          class="relative size-full rounded-xl border-2 border-dashed bg-accent/5"
+          :class="selected ? 'border-accent' : 'border-border'"
+        >
+          <span class="absolute left-3 top-2 text-xs font-semibold uppercase tracking-wide text-fg-muted">{{ data?.label }}</span>
+          <FlowNodeResizer :min-width="220" :min-height="140" />
+        </div>
+      </template>
+
+      <!-- Input node -->
+      <template #node-input="{ id, data, selected }">
+        <div
+          class="relative flex min-w-[150px] flex-col rounded-lg border-l-4 border-l-success bg-bg px-4 py-2.5 shadow-sm transition"
+          :class="selected ? 'border border-accent ring-2 ring-ring' : 'border border-border'"
+        >
+          <span class="text-sm font-semibold text-fg">{{ data?.label }}</span>
+          <span v-if="data?.hint" class="text-xs text-fg-muted">{{ data.hint }}</span>
+          <FlowHandle type="source" position="right" class="flow-handle" />
+          <FlowNodeToolbar class="flow-toolbar">
+            <button type="button" class="flow-tool-btn" @click="duplicateNode(id)">Duplicate</button>
+            <button type="button" class="flow-tool-btn flow-tool-btn--danger" @click="removeNode(id)">Delete</button>
+          </FlowNodeToolbar>
+        </div>
+      </template>
+
+      <!-- Process node -->
+      <template #node-process="{ id, data, selected }">
+        <div
+          class="relative flex min-w-[140px] items-center justify-center rounded-lg bg-bg px-4 py-3 text-sm font-medium text-fg shadow-sm transition"
+          :class="selected ? 'border border-accent ring-2 ring-ring' : 'border border-border'"
+        >
+          <FlowHandle type="target" position="left" class="flow-handle" />
+          {{ data?.label }}
+          <FlowHandle type="source" position="right" class="flow-handle" />
+          <FlowNodeToolbar class="flow-toolbar">
+            <button type="button" class="flow-tool-btn" @click="duplicateNode(id)">Duplicate</button>
+            <button type="button" class="flow-tool-btn flow-tool-btn--danger" @click="removeNode(id)">Delete</button>
+          </FlowNodeToolbar>
+        </div>
+      </template>
+
+      <!-- Output node -->
+      <template #node-output="{ data, selected }">
+        <div
+          class="relative flex min-w-[150px] flex-col rounded-lg border-r-4 border-r-accent bg-bg px-4 py-2.5 shadow-sm transition"
+          :class="selected ? 'border border-accent ring-2 ring-ring' : 'border border-border'"
+        >
+          <span class="text-sm font-semibold text-fg">{{ data?.label }}</span>
+          <span v-if="data?.hint" class="text-xs text-fg-muted">{{ data.hint }}</span>
+          <FlowHandle type="target" position="left" class="flow-handle" />
+        </div>
+      </template>
+
+      <!-- Custom edge type with a label badge -->
+      <template #edge-labeled="{ path, labelX, labelY, label, markerEndUrl }">
+        <path :d="path" class="edge-base" fill="none" :marker-end="markerEndUrl" />
+        <foreignObject :x="labelX - 44" :y="labelY - 12" width="88" height="24" style="overflow: visible">
+          <div class="edge-label">{{ label }}</div>
+        </foreignObject>
+      </template>
+
+      <!-- Chrome -->
+      <FlowBackground variant="dots" :gap="20" class="text-border" />
+
+      <FlowPanel position="top-left" class="m-3 rounded-lg border border-border bg-bg/85 px-3 py-2 text-xs shadow-sm backdrop-blur">
+        <div class="font-semibold text-fg">Headless flow</div>
+        <div class="mt-1 flex gap-3 text-fg-muted">
+          <span>{{ nodes.length }} nodes</span>
+          <span>{{ edges.length }} edges</span>
+          <span>{{ selectedCount }} selected</span>
+        </div>
+      </FlowPanel>
+
+      <FlowPanel position="top-right" class="m-3 flex gap-2">
+        <button type="button" class="panel-btn" @click="addNode()">+ Node</button>
+        <button type="button" class="panel-btn" @click="flow?.fitView()">Fit</button>
+        <button type="button" class="panel-btn" @click="flow?.clearSelection()">Deselect</button>
+      </FlowPanel>
+
+      <FlowControls class="m-3 flex flex-col gap-1 rounded-lg border border-border bg-bg p-1 shadow-sm" />
+      <FlowMiniMap class="m-3 rounded-lg border border-border bg-bg/80 text-fg-subtle shadow-sm backdrop-blur" :width="180" :height="120" />
+    </FlowRoot>
+  </div>
+</template>
+
+<style scoped>
+:deep(.flow-handle) {
+  width: 11px;
+  height: 11px;
+  border-radius: 9999px;
+  background: var(--ui-accent, #6366f1);
+  border: 2px solid var(--ui-bg, #fff);
+  box-shadow: 0 0 0 1px var(--ui-border, #cbd5e1);
+}
+:deep(.flow-handle[data-handletype='target']) {
+  background: var(--ui-bg, #fff);
+}
+
+:deep(.flow-toolbar) {
+  display: flex;
+  gap: 4px;
+  padding: 4px;
+  border-radius: 8px;
+  border: 1px solid var(--ui-border, #cbd5e1);
+  background: var(--ui-bg, #fff);
+  box-shadow: 0 4px 12px rgb(0 0 0 / 0.12);
+}
+:deep(.flow-tool-btn) {
+  font-size: 12px;
+  padding: 2px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  color: var(--ui-fg, #0f172a);
+}
+:deep(.flow-tool-btn:hover) {
+  background: var(--ui-bg-inset, #f1f5f9);
+}
+:deep(.flow-tool-btn--danger:hover) {
+  background: color-mix(in oklch, var(--ui-danger, #ef4444) 14%, transparent);
+  color: var(--ui-danger, #ef4444);
+}
+
+:deep([data-flow-edge-path]),
+.edge-base {
+  stroke: var(--ui-border, #94a3b8);
+  stroke-width: 1.5;
+}
+:deep([data-flow-edge][data-selected] [data-flow-edge-path]) {
+  stroke: var(--ui-accent, #6366f1);
+  stroke-width: 2;
+}
+:deep([data-flow-edge][data-animated] [data-flow-edge-path]) {
+  stroke-dasharray: 6 4;
+  animation: flow-dash 0.6s linear infinite;
+}
+@keyframes flow-dash {
+  to { stroke-dashoffset: -10; }
+}
+
+.edge-label {
+  display: inline-block;
+  transform: translateX(-50%);
+  margin-left: 44px;
+  padding: 1px 8px;
+  border-radius: 9999px;
+  font-size: 11px;
+  font-weight: 500;
+  white-space: nowrap;
+  color: var(--ui-fg-muted, #64748b);
+  background: var(--ui-bg, #fff);
+  border: 1px solid var(--ui-border, #cbd5e1);
+}
+
+:deep([data-flow-connection-line] path) {
+  stroke: var(--ui-accent, #6366f1);
+  stroke-width: 2;
+  stroke-dasharray: 4 4;
+}
+:deep([data-flow-selection-rect]) {
+  border: 1px solid var(--ui-accent, #6366f1);
+  background: color-mix(in oklch, var(--ui-accent, #6366f1) 12%, transparent);
+}
+
+:deep([data-flow-control]) {
+  display: grid;
+  place-items: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  border-radius: 0.375rem;
+  cursor: pointer;
+  color: var(--ui-fg, #0f172a);
+}
+:deep([data-flow-control]:hover) {
+  background: var(--ui-bg-inset, #f1f5f9);
+}
+
+.panel-btn {
+  padding: 4px 10px;
+  font-size: 12px;
+  font-weight: 500;
+  border-radius: 6px;
+  cursor: pointer;
+  color: var(--ui-fg, #0f172a);
+  background: var(--ui-bg, #fff);
+  border: 1px solid var(--ui-border, #cbd5e1);
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.06);
+}
+.panel-btn:hover {
+  background: var(--ui-bg-inset, #f1f5f9);
+}
+
+:deep([data-flow-minimap-node]) {
+  fill: var(--ui-fg-subtle, #94a3b8);
+}
+:deep([data-flow-minimap-node][data-selected]) {
+  fill: var(--ui-accent, #6366f1);
+}
+:deep([data-flow-minimap-mask]) {
+  stroke: var(--ui-accent, #6366f1);
+  fill: color-mix(in oklch, var(--ui-accent, #6366f1) 8%, transparent);
+}
+</style>
diff --git a/vue/primitives/src/canvas/flow/edge-paths.ts b/vue/primitives/src/canvas/flow/edge-paths.ts
new file mode 100644
index 0000000..38ccebf
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/edge-paths.ts
@@ -0,0 +1,253 @@
+import type { EdgeMarker, Position, XYPosition } from './types';
+
+/**
+ * Result of every path builder: the SVG `d` string plus the label anchor
+ * (`labelX`/`labelY`) and its offset from the source (`offsetX`/`offsetY`),
+ * used to place edge labels and badges.
+ */
+export type PathResult = [path: string, labelX: number, labelY: number, offsetX: number, offsetY: number];
+
+/** Geometric centre of two points + the |centre − source| offset. */
+export function getEdgeCenter(p: {
+  sourceX: number;
+  sourceY: number;
+  targetX: number;
+  targetY: number;
+}): [centerX: number, centerY: number, offsetX: number, offsetY: number] {
+  const centerX = (p.sourceX + p.targetX) / 2;
+  const centerY = (p.sourceY + p.targetY) / 2;
+  return [centerX, centerY, Math.abs(centerX - p.sourceX), Math.abs(centerY - p.sourceY)];
+}
+
+/** Straight line between two endpoints. */
+export function getStraightPath(p: {
+  sourceX: number;
+  sourceY: number;
+  targetX: number;
+  targetY: number;
+}): PathResult {
+  const [labelX, labelY, offsetX, offsetY] = getEdgeCenter(p);
+  return [`M ${p.sourceX},${p.sourceY} L ${p.targetX},${p.targetY}`, labelX, labelY, offsetX, offsetY];
+}
+
+// ── Bezier ──────────────────────────────────────────────────────────────────
+
+/**
+ * Control-point offset for a bezier endpoint. Positive distance scales linearly;
+ * a negative distance (target behind source) uses a `sqrt` fallback so the curve
+ * bows out instead of collapsing into a cusp.
+ */
+function calculateControlOffset(distance: number, curvature: number): number {
+  if (distance >= 0) return 0.5 * distance;
+  return curvature * 25 * Math.sqrt(-distance);
+}
+
+function getControlWithCurvature(
+  pos: Position,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  c: number,
+): [number, number] {
+  switch (pos) {
+    case 'left': return [x1 - calculateControlOffset(x1 - x2, c), y1];
+    case 'right': return [x1 + calculateControlOffset(x2 - x1, c), y1];
+    case 'top': return [x1, y1 - calculateControlOffset(y1 - y2, c)];
+    case 'bottom': return [x1, y1 + calculateControlOffset(y2 - y1, c)];
+  }
+}
+
+/** Cubic bezier respecting handle sides. `curvature` (0–1) controls bow. */
+export function getBezierPath(p: {
+  sourceX: number;
+  sourceY: number;
+  sourcePosition?: Position;
+  targetX: number;
+  targetY: number;
+  targetPosition?: Position;
+  curvature?: number;
+}): PathResult {
+  const {
+    sourceX, sourceY, sourcePosition = 'bottom',
+    targetX, targetY, targetPosition = 'top',
+    curvature = 0.25,
+  } = p;
+
+  const [sourceCx, sourceCy] = getControlWithCurvature(sourcePosition, sourceX, sourceY, targetX, targetY, curvature);
+  const [targetCx, targetCy] = getControlWithCurvature(targetPosition, targetX, targetY, sourceX, sourceY, curvature);
+
+  // Point on the cubic at t = 0.5 (binomial weights 1/8, 3/8, 3/8, 1/8).
+  const labelX = sourceX * 0.125 + sourceCx * 0.375 + targetCx * 0.375 + targetX * 0.125;
+  const labelY = sourceY * 0.125 + sourceCy * 0.375 + targetCy * 0.375 + targetY * 0.125;
+
+  const path = `M ${sourceX},${sourceY} C ${sourceCx},${sourceCy} ${targetCx},${targetCy} ${targetX},${targetY}`;
+  return [path, labelX, labelY, Math.abs(labelX - sourceX), Math.abs(labelY - sourceY)];
+}
+
+// ── Smooth step / step ────────────────────────────────────────────────────────
+
+const handleDirections: Record<Position, XYPosition> = {
+  top: { x: 0, y: -1 },
+  right: { x: 1, y: 0 },
+  bottom: { x: 0, y: 1 },
+  left: { x: -1, y: 0 },
+};
+
+function getDirection(source: XYPosition, sourcePosition: Position, target: XYPosition): XYPosition {
+  if (sourcePosition === 'left' || sourcePosition === 'right')
+    return source.x < target.x ? { x: 1, y: 0 } : { x: -1, y: 0 };
+  return source.y < target.y ? { x: 0, y: 1 } : { x: 0, y: -1 };
+}
+
+function distance(a: XYPosition, b: XYPosition): number {
+  return Math.hypot((b.x - a.x), (b.y - a.y));
+}
+
+/**
+ * One rounded corner at point `b` between segments `a→b` and `b→c`. Bend radius
+ * is clamped to half of each adjacent segment so it never overshoots.
+ */
+function getBend(a: XYPosition, b: XYPosition, c: XYPosition, size: number): string {
+  const bend = Math.min(distance(a, b) / 2, distance(b, c) / 2, size);
+  const { x, y } = b;
+
+  // Collinear → no corner.
+  if ((a.x === x && x === c.x) || (a.y === y && y === c.y))
+    return `L ${x},${y}`;
+
+  if (a.y === y) {
+    const xDir = a.x < c.x ? -1 : 1;
+    const yDir = a.y < c.y ? 1 : -1;
+    return `L ${x + bend * xDir},${y} Q ${x},${y} ${x},${y + bend * yDir}`;
+  }
+
+  const xDir = a.x < c.x ? 1 : -1;
+  const yDir = a.y < c.y ? -1 : 1;
+  return `L ${x},${y + bend * yDir} Q ${x},${y} ${x + bend * xDir},${y}`;
+}
+
+function getStepPoints(
+  source: XYPosition,
+  sourcePosition: Position,
+  target: XYPosition,
+  targetPosition: Position,
+  offset: number,
+  center: { x?: number; y?: number },
+): { points: XYPosition[]; labelX: number; labelY: number } {
+  const sourceDir = handleDirections[sourcePosition];
+  const targetDir = handleDirections[targetPosition];
+  const sourceGapped: XYPosition = { x: source.x + sourceDir.x * offset, y: source.y + sourceDir.y * offset };
+  const targetGapped: XYPosition = { x: target.x + targetDir.x * offset, y: target.y + targetDir.y * offset };
+  const dir = getDirection(sourceGapped, sourcePosition, targetGapped);
+  const dirAccessor: keyof XYPosition = dir.x !== 0 ? 'x' : 'y';
+  const currDir = dir[dirAccessor];
+
+  let points: XYPosition[];
+  let centerX: number;
+  let centerY: number;
+  const sourceGapPoint: XYPosition = { ...sourceGapped };
+  const targetGapPoint: XYPosition = { ...targetGapped };
+  const dirX = dir.x !== 0;
+
+  if (sourceDir[dirAccessor] * targetDir[dirAccessor] === -1) {
+    centerX = center.x ?? (sourceGapped.x + targetGapped.x) / 2;
+    centerY = center.y ?? (sourceGapped.y + targetGapped.y) / 2;
+
+    // Build only the split that is actually used (avoids allocating both).
+    const useVertical = (sourceDir[dirAccessor] === currDir) === dirX;
+    points = useVertical
+      ? [{ x: centerX, y: sourceGapped.y }, { x: centerX, y: targetGapped.y }]
+      : [{ x: sourceGapped.x, y: centerY }, { x: targetGapped.x, y: centerY }];
+  }
+  else {
+    const useTargetSource = dirX ? sourceDir.y === currDir : sourceDir.x !== currDir;
+    points = useTargetSource
+      ? [{ x: targetGapped.x, y: sourceGapped.y }]
+      : [{ x: sourceGapped.x, y: targetGapped.y }];
+
+    centerX = (sourceGapped.x + targetGapped.x) / 2;
+    centerY = (sourceGapped.y + targetGapped.y) / 2;
+
+    // Same side: nudge the gap point so it doesn't overlap when handles are close.
+    if (sourcePosition === targetPosition) {
+      const diff = Math.abs(source[dirAccessor] - target[dirAccessor]);
+      if (diff <= offset) {
+        const gapOffset = Math.min(offset - 1, offset - diff);
+        if (sourceDir[dirAccessor] === currDir)
+          sourceGapPoint[dirAccessor] = source[dirAccessor] + sourceDir[dirAccessor] * gapOffset;
+        else
+          targetGapPoint[dirAccessor] = target[dirAccessor] + targetDir[dirAccessor] * gapOffset;
+      }
+    }
+  }
+
+  return {
+    points: [source, sourceGapPoint, ...points, targetGapPoint, target],
+    labelX: centerX,
+    labelY: centerY,
+  };
+}
+
+/** Orthogonal path with rounded corners. `borderRadius` 0 yields sharp steps. */
+export function getSmoothStepPath(p: {
+  sourceX: number;
+  sourceY: number;
+  sourcePosition?: Position;
+  targetX: number;
+  targetY: number;
+  targetPosition?: Position;
+  borderRadius?: number;
+  offset?: number;
+  centerX?: number;
+  centerY?: number;
+}): PathResult {
+  const {
+    sourceX, sourceY, sourcePosition = 'bottom',
+    targetX, targetY, targetPosition = 'top',
+    borderRadius = 5, offset = 20, centerX, centerY,
+  } = p;
+
+  const { points, labelX, labelY } = getStepPoints(
+    { x: sourceX, y: sourceY }, sourcePosition,
+    { x: targetX, y: targetY }, targetPosition,
+    offset, { x: centerX, y: centerY },
+  );
+
+  let path = '';
+  for (let i = 0; i < points.length; i++) {
+    const cur = points[i]!;
+    if (i > 0 && i < points.length - 1)
+      path += getBend(points[i - 1]!, cur, points[i + 1]!, borderRadius);
+    else
+      path += `${i === 0 ? 'M' : 'L'} ${cur.x},${cur.y} `;
+  }
+
+  return [path.trim(), labelX, labelY, Math.abs(labelX - sourceX), Math.abs(labelY - sourceY)];
+}
+
+/** Sharp orthogonal path (smooth step with zero corner radius). */
+export function getStepPath(p: Parameters<typeof getSmoothStepPath>[0]): PathResult {
+  return getSmoothStepPath({ ...p, borderRadius: 0 });
+}
+
+// ── Markers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Deterministic, dedupe-safe id for a marker `<defs>` entry, scoped to the flow
+ * instance. Identical descriptors collapse to one DOM marker.
+ */
+export function getMarkerId(marker: EdgeMarker | string, flowId: string): string {
+  if (typeof marker === 'string')
+    return `${flowId}__marker-url-${marker.replaceAll(/\W/g, '')}`;
+  const parts = [
+    marker.type,
+    marker.color ?? '',
+    marker.width ?? '',
+    marker.height ?? '',
+    marker.strokeWidth ?? '',
+    marker.orient ?? '',
+    marker.markerUnits ?? '',
+  ];
+  return `${flowId}__marker-${parts.join('-').replaceAll(/[^\w-]/g, '')}`;
+}
diff --git a/vue/primitives/src/canvas/flow/index.ts b/vue/primitives/src/canvas/flow/index.ts
new file mode 100644
index 0000000..6f3c410
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/index.ts
@@ -0,0 +1,119 @@
+// Composable parts. The per-item `FlowNode` / `FlowEdge` components are internal
+// (rendered by the renderers); the public `FlowNode` / `FlowEdge` names below are
+// the DATA types consumers bind their `nodes` / `edges` arrays to.
+export { default as FlowBackground } from './FlowBackground.vue';
+export { default as FlowConnectionLine } from './FlowConnectionLine.vue';
+export { default as FlowControls } from './FlowControls.vue';
+export { default as FlowEdgeRenderer } from './FlowEdgeRenderer.vue';
+export { default as FlowHandle } from './FlowHandle.vue';
+export { default as FlowMiniMap } from './FlowMiniMap.vue';
+export { default as FlowNodeRenderer } from './FlowNodeRenderer.vue';
+export { default as FlowNodeResizer } from './FlowNodeResizer.vue';
+export { default as FlowNodeToolbar } from './FlowNodeToolbar.vue';
+export { default as FlowPane } from './FlowPane.vue';
+export { default as FlowPanel } from './FlowPanel.vue';
+export { default as FlowRoot } from './FlowRoot.vue';
+export { default as FlowViewport } from './FlowViewport.vue';
+
+export type { FlowBackgroundProps, FlowBackgroundVariant } from './FlowBackground.vue';
+export type { FlowConnectionLineProps } from './FlowConnectionLine.vue';
+export type { FlowControlsProps } from './FlowControls.vue';
+export type { FlowEdgeRendererProps } from './FlowEdgeRenderer.vue';
+export type { FlowHandleProps } from './FlowHandle.vue';
+export type { FlowMiniMapProps } from './FlowMiniMap.vue';
+export type { FlowNodeRendererProps } from './FlowNodeRenderer.vue';
+export type { FlowNodeResizerProps } from './FlowNodeResizer.vue';
+export type { FlowNodeToolbarProps } from './FlowNodeToolbar.vue';
+export type { FlowPaneProps } from './FlowPane.vue';
+export type { FlowPanelPosition, FlowPanelProps } from './FlowPanel.vue';
+export type { FlowRootEmits, FlowRootProps } from './FlowRoot.vue';
+export type { FlowViewportProps } from './FlowViewport.vue';
+
+export {
+  FLOW_EDGES_COLLECTION,
+  FLOW_NODES_COLLECTION,
+  provideFlowContext,
+  provideFlowNodeContext,
+  useFlowContext,
+  useFlowNodeContext,
+} from './context';
+export type { FlowContext, FlowNodeContext, FlowSelection, HandleRegistration } from './context';
+
+export type {
+  AriaLabelConfig,
+  Connection,
+  ConnectionMode,
+  ConnectionState,
+  Dimensions,
+  EdgeChange,
+  EdgeMarker,
+  EdgeMarkerType,
+  FlowEdge,
+  FlowNode,
+  HandleBound,
+  HandleBounds,
+  HandleType,
+  InternalNode,
+  IsValidConnection,
+  NodeChange,
+  Position,
+  Rect,
+  SelectionMode,
+  Viewport,
+  XYPosition,
+} from './types';
+
+export type { FitViewOptions, NodeBox, PaneOrigin } from './utils';
+export {
+  clampZoom,
+  findHandle,
+  fitViewTransform,
+  flowToScreen,
+  getAbsoluteHandlePoint,
+  getDefaultEndpoint,
+  getHandleBoundsFromDom,
+  getNodePositionAbsolute,
+  getNodesBounds,
+  getNodesInsideRect,
+  nodeInRect,
+  rectContains,
+  rectsIntersect,
+  screenToFlow,
+  snapPoint,
+  visibleFlowRect,
+  wheelToZoomFactor,
+  zoomAtPointer,
+} from './utils';
+
+export type { PathResult } from './edge-paths';
+export {
+  getBezierPath,
+  getEdgeCenter,
+  getMarkerId,
+  getSmoothStepPath,
+  getStepPath,
+  getStraightPath,
+} from './edge-paths';
+
+export type { ConnectionTarget } from './connection';
+export { buildConnection, connectionToEdgeId, findClosestHandle } from './connection';
+
+export { addEdge, applyEdgeChanges, applyNodeChanges } from './changes';
+
+export { getVisibleEdgeIds, getVisibleNodeIds } from './virtualization';
+
+export { usePanZoom } from './composables/usePanZoom';
+export type { PanZoomOptions } from './composables/usePanZoom';
+export { useNodeDrag } from './composables/useNodeDrag';
+export type { NodeDragOptions } from './composables/useNodeDrag';
+export { useConnection } from './composables/useConnection';
+export { useMarquee } from './composables/useMarquee';
+export type { MarqueeRect } from './composables/useMarquee';
+export { useKeyboard } from './composables/useKeyboard';
+export type { KeyboardOptions } from './composables/useKeyboard';
+export { useViewportApi } from './composables/useViewportApi';
+export type { FitViewParams, FlowApi } from './composables/useViewportApi';
+export { useFlow } from './composables/useFlow';
+export type { UseFlowReturn } from './composables/useFlow';
+export { useNodesInView } from './composables/useNodesInView';
+export type { UseNodesInViewOptions, UseNodesInViewReturn } from './composables/useNodesInView';
diff --git a/vue/primitives/src/canvas/flow/types.ts b/vue/primitives/src/canvas/flow/types.ts
new file mode 100644
index 0000000..1e240d1
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/types.ts
@@ -0,0 +1,224 @@
+/**
+ * Domain model for the headless flow canvas.
+ *
+ * Public types (`FlowNode`, `FlowEdge`, `Viewport`, …) are what consumers bind
+ * through `v-model` and serialize. Internal types (`InternalNode`,
+ * `HandleBound`, `ConnectionState`) live only in the state layer and are never
+ * emitted — they hold measured DOM geometry derived from the public model.
+ */
+
+/** A point in flow space (unscaled, viewport-independent coordinates). */
+export interface XYPosition {
+  x: number;
+  y: number;
+}
+
+/** Measured size of an element in flow space. */
+export interface Dimensions {
+  width: number;
+  height: number;
+}
+
+/** Axis-aligned rectangle in flow space. */
+export interface Rect extends XYPosition, Dimensions {}
+
+/**
+ * The single master transform. `x`/`y` are unscaled screen pixels applied
+ * *before* `scale(zoom)` on the one transformed layer (`transform-origin:0 0`).
+ */
+export interface Viewport {
+  x: number;
+  y: number;
+  zoom: number;
+}
+
+/** Side of a node a handle/edge attaches to. */
+export type Position = 'top' | 'right' | 'bottom' | 'left';
+
+/** Whether a handle starts (`source`) or ends (`target`) a connection. */
+export type HandleType = 'source' | 'target';
+
+/** SVG arrowhead descriptor resolved into a shared `<defs>` marker. */
+export interface EdgeMarker {
+  type: 'arrow' | 'arrowclosed';
+  color?: string;
+  width?: number;
+  height?: number;
+  strokeWidth?: number;
+  orient?: string;
+  markerUnits?: string;
+}
+
+export type EdgeMarkerType = EdgeMarker | string;
+
+/**
+ * Public node model. Bound via `v-model:nodes`; only these fields round-trip
+ * through serialization. `data` carries the consumer's payload.
+ */
+export interface FlowNode<Data = unknown, Type extends string = string> {
+  /** Unique, stable identity. Used as the render key — never reuse. */
+  id: string;
+  /** Position in flow space. Relative to `parentId` when set. */
+  position: XYPosition;
+  /** Consumer payload passed to the node slot/component. */
+  data?: Data;
+  /** Resolves the renderer via `nodeTypes` / `#node-<type>` slot. */
+  type?: Type;
+  /** Optional explicit width; otherwise measured from the DOM. */
+  width?: number;
+  /** Optional explicit height; otherwise measured from the DOM. */
+  height?: number;
+  /** Default side for outgoing edges when a node renders implicit handles. */
+  sourcePosition?: Position;
+  /** Default side for incoming edges. */
+  targetPosition?: Position;
+  /** Per-node override of the global drag flag. */
+  draggable?: boolean;
+  /** Per-node override of the global selectable flag. */
+  selectable?: boolean;
+  /** Per-node override of the global connectable flag. */
+  connectable?: boolean;
+  /** Per-node override of the global deletable flag. */
+  deletable?: boolean;
+  /** Selection state mirrored from the canonical selection Set on serialize. */
+  selected?: boolean;
+  /** Skip rendering without removing from the model. */
+  hidden?: boolean;
+  /** Parent node id for subflows; `position` becomes parent-relative. */
+  parentId?: string;
+  /** Constrain dragging to the parent's box or an explicit rect. */
+  extent?: 'parent' | [[number, number], [number, number]];
+  /** Explicit stacking order; otherwise derived (selected/dragging lift). */
+  zIndex?: number;
+  /** Accessible label override for keyboard users / screen readers. */
+  ariaLabel?: string;
+}
+
+/**
+ * State-layer node. Extends the public node with measured geometry that is
+ * recomputed from the DOM (never serialized). Lives in `nodeLookup`.
+ */
+export interface InternalNode<Data = unknown, Type extends string = string>
+  extends FlowNode<Data, Type> {
+  /** Measured size in flow space (from the shared ResizeObserver). */
+  measured: Dimensions;
+  /** Absolute flow position = sum of the `parentId` chain + `position`. */
+  positionAbsolute: XYPosition;
+  /** Handle rects measured once per node (already divided by zoom). */
+  handleBounds: HandleBounds | null;
+  /** Live drag flag; set on pointerdown, cleared on commit. */
+  dragging?: boolean;
+  /**
+   * @internal The public node this entry was derived from. Identity is the
+   * change signal: when the consumer replaces a node object, reconcile rebuilds
+   * a fresh `InternalNode` so that node (and only that node) re-renders.
+   */
+  _source?: FlowNode<Data, Type>;
+}
+
+/** Measured handle rectangles grouped by type, in node-local flow space. */
+export interface HandleBounds {
+  source: HandleBound[];
+  target: HandleBound[];
+}
+
+/** One measured handle anchor relative to its node's top-left, in flow space. */
+export interface HandleBound {
+  id: string | null;
+  type: HandleType;
+  position: Position;
+  /** Offset from node left, flow space. */
+  x: number;
+  /** Offset from node top, flow space. */
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Public edge model. Bound via `v-model:edges`. Endpoints reference node ids
+ * and optional handle ids.
+ */
+export interface FlowEdge<Data = unknown, Type extends string = string> {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string | null;
+  targetHandle?: string | null;
+  /** Resolves the renderer via `edgeTypes` / `#edge-<type>` slot. */
+  type?: Type;
+  data?: Data;
+  label?: string;
+  selected?: boolean;
+  animated?: boolean;
+  hidden?: boolean;
+  deletable?: boolean;
+  selectable?: boolean;
+  updatable?: boolean;
+  markerStart?: EdgeMarkerType;
+  markerEnd?: EdgeMarkerType;
+  zIndex?: number;
+  ariaLabel?: string;
+}
+
+/** A proposed or committed connection between two handles. */
+export interface Connection {
+  source: string;
+  target: string;
+  sourceHandle: string | null;
+  targetHandle: string | null;
+}
+
+/** Strict requires matching source→target types; loose allows any handle. */
+export type ConnectionMode = 'strict' | 'loose';
+
+/** Predicate gating which connections may be committed. */
+export type IsValidConnection = (connection: Connection) => boolean;
+
+/** Live state of an in-progress connection drag (only the preview subscribes). */
+export interface ConnectionState {
+  inProgress: boolean;
+  /** Node the drag originated from. */
+  fromNode: string | null;
+  /** Handle the drag originated from. */
+  fromHandle: HandleBound | null;
+  /** Absolute flow position of the origin handle. */
+  fromPosition: XYPosition | null;
+  /** Whether the origin acts as source or target (loose mode can invert). */
+  fromType: HandleType | null;
+  /** Current pointer position in flow space. */
+  toPosition: XYPosition | null;
+  /** Hovered candidate handle, if any. */
+  toHandle: HandleBound | null;
+  toNode: string | null;
+  /** Null until a candidate is hovered; then validity of dropping there. */
+  isValid: boolean | null;
+}
+
+/** Whether a node counts as "inside" a marquee rect. */
+export type SelectionMode = 'partial' | 'full';
+
+/** Granular node mutations emitted via `@nodes-change`. */
+export type NodeChange<Data = unknown>
+  = | { type: 'position'; id: string; position?: XYPosition; dragging?: boolean }
+    | { type: 'dimensions'; id: string; dimensions: Dimensions; resizing?: boolean }
+    | { type: 'select'; id: string; selected: boolean }
+    | { type: 'remove'; id: string }
+    | { type: 'add'; item: FlowNode<Data>; index?: number }
+    | { type: 'replace'; id: string; item: FlowNode<Data> };
+
+/** Granular edge mutations emitted via `@edges-change`. */
+export type EdgeChange<Data = unknown>
+  = | { type: 'select'; id: string; selected: boolean }
+    | { type: 'remove'; id: string }
+    | { type: 'add'; item: FlowEdge<Data>; index?: number }
+    | { type: 'replace'; id: string; item: FlowEdge<Data> };
+
+/** Override strings for screen-reader announcements (i18n). */
+export interface AriaLabelConfig {
+  'node.a11yDescription.default'?: string;
+  'node.a11yDescription.keyboardDisabled'?: string;
+  'edge.a11yDescription.default'?: string;
+  'controls.ariaLabel'?: string;
+  'minimap.ariaLabel'?: string;
+}
diff --git a/vue/primitives/src/canvas/flow/utils.ts b/vue/primitives/src/canvas/flow/utils.ts
new file mode 100644
index 0000000..643e783
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/utils.ts
@@ -0,0 +1,293 @@
+import { clamp } from '@robonen/stdlib';
+import type {
+  Dimensions,
+  HandleBound,
+  HandleBounds,
+  InternalNode,
+  Position,
+  Rect,
+  SelectionMode,
+  Viewport,
+  XYPosition,
+} from './types';
+
+/** Re-exported so flow code has one import surface for clamping. */
+export { clamp };
+
+/** A pane origin: only `left`/`top` matter for coordinate conversion. */
+export interface PaneOrigin {
+  left: number;
+  top: number;
+}
+
+/**
+ * Convert a screen (client) point to flow space.
+ *
+ * Inverse of {@link flowToScreen}. The client point must have the pane's
+ * `left`/`top` subtracted first, then the viewport translation removed and the
+ * zoom divided out. On the pointer hot path — no allocations beyond the result.
+ */
+export function screenToFlow(point: XYPosition, vp: Viewport, origin: PaneOrigin): XYPosition {
+  return {
+    x: (point.x - origin.left - vp.x) / vp.zoom,
+    y: (point.y - origin.top - vp.y) / vp.zoom,
+  };
+}
+
+/** Convert a flow-space point to a screen (client) point. Inverse of {@link screenToFlow}. */
+export function flowToScreen(point: XYPosition, vp: Viewport, origin: PaneOrigin): XYPosition {
+  return {
+    x: point.x * vp.zoom + vp.x + origin.left,
+    y: point.y * vp.zoom + vp.y + origin.top,
+  };
+}
+
+/**
+ * New viewport that keeps `pointer` (pane-relative pixels) fixed on screen while
+ * the zoom changes to `newZoom`. Caller is expected to clamp `newZoom` first
+ * via {@link clampZoom}.
+ */
+export function zoomAtPointer(vp: Viewport, pointer: XYPosition, newZoom: number): Viewport {
+  const ratio = newZoom / vp.zoom;
+  return {
+    zoom: newZoom,
+    x: pointer.x - (pointer.x - vp.x) * ratio,
+    y: pointer.y - (pointer.y - vp.y) * ratio,
+  };
+}
+
+/**
+ * Multiplicative zoom factor for a wheel event, normalising the three
+ * `deltaMode` units and amplifying trackpad pinch (`ctrlKey`). Multiply the
+ * current zoom by the result.
+ */
+export function wheelToZoomFactor(event: WheelEvent): number {
+  const unit = event.deltaMode === 1 ? 0.05 : event.deltaMode ? 1 : 0.002;
+  const delta = -event.deltaY * unit * (event.ctrlKey ? 10 : 1);
+  return 2 ** delta;
+}
+
+/** Clamp a zoom level to `[min, max]`. */
+export function clampZoom(zoom: number, min: number, max: number): number {
+  return clamp(zoom, min, max);
+}
+
+/** Snap a flow-space point to the nearest grid intersection. */
+export function snapPoint(point: XYPosition, grid: [number, number]): XYPosition {
+  const [gx, gy] = grid;
+  return {
+    x: gx ? Math.round(point.x / gx) * gx : point.x,
+    y: gy ? Math.round(point.y / gy) * gy : point.y,
+  };
+}
+
+/** Node geometry needed for bounds/hit-testing: absolute position + measured size. */
+export interface NodeBox {
+  positionAbsolute: XYPosition;
+  measured: Dimensions;
+}
+
+/**
+ * Bounding rect (flow space) enclosing every node. Single pass. Returns a zero
+ * rect when the iterable is empty.
+ */
+export function getNodesBounds(nodes: Iterable<NodeBox>): Rect {
+  let xMin = Infinity;
+  let yMin = Infinity;
+  let xMax = -Infinity;
+  let yMax = -Infinity;
+  let seen = false;
+
+  for (const node of nodes) {
+    seen = true;
+    const { x, y } = node.positionAbsolute;
+    const { width, height } = node.measured;
+    if (x < xMin) xMin = x;
+    if (y < yMin) yMin = y;
+    if (x + width > xMax) xMax = x + width;
+    if (y + height > yMax) yMax = y + height;
+  }
+
+  if (!seen) return { x: 0, y: 0, width: 0, height: 0 };
+  return { x: xMin, y: yMin, width: xMax - xMin, height: yMax - yMin };
+}
+
+export interface FitViewOptions {
+  /** Fractional inset on each side, 0–1. @default 0.1 */
+  padding?: number;
+  minZoom: number;
+  maxZoom: number;
+}
+
+/**
+ * Viewport that fits `bounds` inside a `container` of the given size, centred,
+ * with `padding`. Zoom is clamped to `[minZoom, maxZoom]`.
+ */
+export function fitViewTransform(bounds: Rect, container: Dimensions, opts: FitViewOptions): Viewport {
+  const padding = opts.padding ?? 0.1;
+  const { width: cw, height: ch } = container;
+  const bw = bounds.width || 1;
+  const bh = bounds.height || 1;
+
+  const zoom = clamp(Math.min(cw / bw, ch / bh) * (1 - padding), opts.minZoom, opts.maxZoom);
+  const centerX = bounds.x + bounds.width / 2;
+  const centerY = bounds.y + bounds.height / 2;
+
+  return {
+    zoom,
+    x: cw / 2 - centerX * zoom,
+    y: ch / 2 - centerY * zoom,
+  };
+}
+
+/** Whether two flow-space rects overlap (touching edges count as overlap). */
+export function rectsIntersect(a: Rect, b: Rect): boolean {
+  return (
+    a.x <= b.x + b.width
+    && a.x + a.width >= b.x
+    && a.y <= b.y + b.height
+    && a.y + a.height >= b.y
+  );
+}
+
+/** Whether rect `a` fully contains rect `b`. */
+export function rectContains(a: Rect, b: Rect): boolean {
+  return (
+    b.x >= a.x
+    && b.y >= a.y
+    && b.x + b.width <= a.x + a.width
+    && b.y + b.height <= a.y + a.height
+  );
+}
+
+/** Whether a node falls inside a marquee `rect` per the selection `mode`. */
+export function nodeInRect(node: NodeBox, rect: Rect, mode: SelectionMode): boolean {
+  const box: Rect = {
+    x: node.positionAbsolute.x,
+    y: node.positionAbsolute.y,
+    width: node.measured.width,
+    height: node.measured.height,
+  };
+  return mode === 'full' ? rectContains(rect, box) : rectsIntersect(rect, box);
+}
+
+/** Ids of nodes selected by a marquee `rect`. */
+export function getNodesInsideRect(
+  nodes: Iterable<InternalNode>,
+  rect: Rect,
+  mode: SelectionMode,
+): string[] {
+  const ids: string[] = [];
+  for (const node of nodes) {
+    if (node.hidden) continue;
+    if (nodeInRect(node, rect, mode)) ids.push(node.id);
+  }
+  return ids;
+}
+
+/**
+ * The flow-space rect currently visible through the viewport, expanded by
+ * `buffer` screen pixels on each side. Drives virtualization culling.
+ */
+export function visibleFlowRect(vp: Viewport, container: Dimensions, buffer: number): Rect {
+  return {
+    x: (-vp.x - buffer) / vp.zoom,
+    y: (-vp.y - buffer) / vp.zoom,
+    width: (container.width + 2 * buffer) / vp.zoom,
+    height: (container.height + 2 * buffer) / vp.zoom,
+  };
+}
+
+/**
+ * Absolute flow position of a node = its `position` plus the sum of every
+ * ancestor's position. Guards against cycles via a depth cap.
+ */
+export function getNodePositionAbsolute(
+  node: { id: string; position: XYPosition; parentId?: string },
+  lookup: Map<string, InternalNode>,
+): XYPosition {
+  let x = node.position.x;
+  let y = node.position.y;
+  let parentId = node.parentId;
+  let guard = 0;
+
+  while (parentId && guard++ < 100) {
+    const parent = lookup.get(parentId);
+    if (!parent) break;
+    x += parent.position.x;
+    y += parent.position.y;
+    parentId = parent.parentId;
+  }
+
+  return { x, y };
+}
+
+/**
+ * Measure a node's handle rectangles from the DOM, relative to the node's
+ * top-left and converted to flow space (divided by `zoom`). Called once per
+ * measurement, not per frame.
+ */
+export function getHandleBoundsFromDom(
+  nodeEl: HTMLElement,
+  zoom: number,
+): HandleBounds {
+  const nodeRect = nodeEl.getBoundingClientRect();
+  const handles = nodeEl.querySelectorAll<HTMLElement>('[data-handleid]');
+  const bounds: HandleBounds = { source: [], target: [] };
+
+  for (const handle of handles) {
+    const type = (handle.dataset['handletype'] as HandleBound['type']) ?? 'source';
+    const rect = handle.getBoundingClientRect();
+    const bound: HandleBound = {
+      id: handle.dataset['handleid'] || null,
+      type,
+      position: (handle.dataset['handlepos'] as Position) ?? 'top',
+      x: (rect.left - nodeRect.left) / zoom,
+      y: (rect.top - nodeRect.top) / zoom,
+      width: rect.width / zoom,
+      height: rect.height / zoom,
+    };
+    bounds[type].push(bound);
+  }
+
+  return bounds;
+}
+
+/** Absolute flow point at the centre of a measured handle. */
+export function getAbsoluteHandlePoint(positionAbsolute: XYPosition, handle: HandleBound): XYPosition {
+  return {
+    x: positionAbsolute.x + handle.x + handle.width / 2,
+    y: positionAbsolute.y + handle.y + handle.height / 2,
+  };
+}
+
+/**
+ * Pick a handle from a node's measured bounds. Falls back to the first handle of
+ * the right type when `handleId` is null (single-handle nodes).
+ */
+export function findHandle(
+  node: InternalNode | undefined,
+  type: HandleBound['type'],
+  handleId: string | null | undefined,
+): HandleBound | undefined {
+  const list = node?.handleBounds?.[type];
+  if (!list || list.length === 0) return undefined;
+  if (handleId === null || handleId === undefined) return list[0];
+  return list.find(h => h.id === handleId) ?? list[0];
+}
+
+/**
+ * Default attachment point for an edge endpoint when a node has no measured
+ * handles yet — the centre of the appropriate side, or the node centre.
+ */
+export function getDefaultEndpoint(node: NodeBox, position?: Position): XYPosition {
+  const { x, y } = node.positionAbsolute;
+  const { width, height } = node.measured;
+  switch (position) {
+    case 'top': return { x: x + width / 2, y };
+    case 'bottom': return { x: x + width / 2, y: y + height };
+    case 'left': return { x, y: y + height / 2 };
+    case 'right': return { x: x + width, y: y + height / 2 };
+    default: return { x: x + width / 2, y: y + height / 2 };
+  }
+}
diff --git a/vue/primitives/src/canvas/flow/virtualization.ts b/vue/primitives/src/canvas/flow/virtualization.ts
new file mode 100644
index 0000000..c8fddb1
--- /dev/null
+++ b/vue/primitives/src/canvas/flow/virtualization.ts
@@ -0,0 +1,45 @@
+import type { FlowEdge, FlowNode, InternalNode, Rect } from './types';
+import { rectsIntersect } from './utils';
+
+/**
+ * Ids of nodes whose box intersects the (buffered) visible `rect`. Unmeasured
+ * nodes are treated as points at their absolute position, so they are kept while
+ * near the viewport rather than flickering out before first measure.
+ */
+export function getVisibleNodeIds(
+  nodes: Iterable<FlowNode>,
+  nodeLookup: Map<string, InternalNode>,
+  rect: Rect,
+): string[] {
+  const ids: string[] = [];
+  for (const node of nodes) {
+    if (node.hidden) continue;
+    const internal = nodeLookup.get(node.id);
+    if (!internal) {
+      ids.push(node.id);
+      continue;
+    }
+    const box: Rect = {
+      x: internal.positionAbsolute.x,
+      y: internal.positionAbsolute.y,
+      width: internal.measured.width,
+      height: internal.measured.height,
+    };
+    if (rectsIntersect(rect, box)) ids.push(node.id);
+  }
+  return ids;
+}
+
+/**
+ * Ids of edges with at least one endpoint among the visible nodes. Cheap and
+ * good enough: short edges between two off-screen nodes are culled, which is the
+ * desired behaviour for large graphs.
+ */
+export function getVisibleEdgeIds(edges: Iterable<FlowEdge>, visibleNodes: Set<string>): string[] {
+  const ids: string[] = [];
+  for (const edge of edges) {
+    if (edge.hidden) continue;
+    if (visibleNodes.has(edge.source) || visibleNodes.has(edge.target)) ids.push(edge.id);
+  }
+  return ids;
+}
diff --git a/vue/primitives/src/canvas/gradient-editor/GradientEditorAngle.vue b/vue/primitives/src/canvas/gradient-editor/GradientEditorAngle.vue
new file mode 100644
index 0000000..75cfd78
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/GradientEditorAngle.vue
@@ -0,0 +1,70 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Optional angle control for the linear gradient, wrapping an `AngleDialRoot` +
+ * `AngleDialThumb` bound to the root's `angle` model. It renders nothing when
+ * the gradient `type` is `'radial'` (the angle is meaningless there). Compose
+ * the dial's slot to position the thumb, or pass your own children via the
+ * default slot (which receives `{ angle }`).
+ */
+export interface GradientEditorAngleProps extends PrimitiveProps {
+  /** Min angle in degrees. @default 0 */
+  min?: number;
+  /** Max angle in degrees. @default 360 */
+  max?: number;
+  /** Step granularity in degrees. @default 1 */
+  step?: number;
+  /** Large step (Page keys / Shift+Arrow) in degrees. @default 15 */
+  largeStep?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { AngleDialRoot, AngleDialThumb } from '../angle-dial';
+import { useForwardExpose } from '@robonen/vue';
+import { useGradientEditorContext } from './context';
+
+const {
+  as = 'div',
+  min = 0,
+  max = 360,
+  step = 1,
+  largeStep = 15,
+} = defineProps<GradientEditorAngleProps>();
+
+const ctx = useGradientEditorContext();
+const { forwardRef } = useForwardExpose();
+
+// Two-way bridge between AngleDial's `v-model:value` and the gradient's angle.
+// The setter widens to AngleDial's `number | null` model contract.
+const angle = computed<number | null | undefined>({
+  get: () => ctx.angle.value,
+  set: (v) => {
+    if (v === null || v === undefined) return;
+    ctx.setAngle(v);
+  },
+});
+
+const isLinear = computed(() => ctx.type.value === 'linear');
+</script>
+
+<template>
+  <AngleDialRoot
+    v-if="isLinear"
+    :ref="forwardRef"
+    :as="as"
+    v-model:value="angle"
+    :min="min"
+    :max="max"
+    :step="step"
+    :large-step="largeStep"
+    :disabled="ctx.disabled.value"
+    :dir="ctx.direction.value"
+  >
+    <slot :angle="angle">
+      <AngleDialThumb aria-label="Gradient angle" />
+    </slot>
+  </AngleDialRoot>
+</template>
diff --git a/vue/primitives/src/canvas/gradient-editor/GradientEditorColorEditor.vue b/vue/primitives/src/canvas/gradient-editor/GradientEditorColorEditor.vue
new file mode 100644
index 0000000..567529c
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/GradientEditorColorEditor.vue
@@ -0,0 +1,71 @@
+<script lang="ts">
+import type { ColorFormat } from '../../color/color-field';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Optional color editor for the selected stop. It mounts a `ColorFieldRoot`
+ * (from `../color-field`) whose `v-model` is bridged to the selected stop's
+ * `color`, so editing the color in any `ColorField` part (area, sliders, input,
+ * swatch) writes straight back to the stop via the root's `updateStop`. The
+ * `ColorField` parts are exposed through the default slot — drop in
+ * `ColorArea`, `HueSlider`, `ColorFieldInput`, etc.
+ *
+ * Renders nothing when no stop is selected (the default slot is suppressed).
+ * Consumers who want a different color UI can compose a `ColorField` themselves
+ * and bind it to `ctx.selectedId` / `ctx.updateStop` the same way.
+ */
+export interface GradientEditorColorEditorProps extends PrimitiveProps {
+  /**
+   * Serialization format written back to the stop's `color`.
+   * @default 'rgba'
+   */
+  format?: ColorFormat;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import type { HSVA } from '../../internal/color';
+import { ColorFieldRoot } from '../../color/color-field';
+import { useForwardExpose } from '@robonen/vue';
+import { useGradientEditorContext } from './context';
+
+const { as = 'div', format = 'rgba' } = defineProps<GradientEditorColorEditorProps>();
+
+const ctx = useGradientEditorContext();
+const { forwardRef } = useForwardExpose();
+
+const selectedStop = computed(() => {
+  const id = ctx.selectedId.value;
+  if (id === null) return null;
+  return ctx.stopIndex.value.get(id)?.stop ?? null;
+});
+
+// Bridge the ColorField model (a CSS color string in `format`) to the selected
+// stop's color. Writing flows back through `updateStop`. The getter feeds a CSS
+// string in; the setter receives whatever the ColorField emits (a string in the
+// configured `format`, but typed as `HSVA | string | null` by its model).
+const color = computed<HSVA | string | null | undefined>({
+  get: () => selectedStop.value?.color ?? '#000000',
+  set: (value) => {
+    const id = ctx.selectedId.value;
+    if (id === null || value === null || value === undefined || typeof value !== 'string') return;
+    ctx.updateStop(id, { color: value });
+  },
+});
+</script>
+
+<template>
+  <ColorFieldRoot
+    v-if="selectedStop"
+    :ref="forwardRef"
+    :as="as"
+    v-model="color"
+    :format="format"
+    :disabled="ctx.disabled.value"
+  >
+    <template #default="slotProps">
+      <slot v-bind="slotProps" :stop="selectedStop" />
+    </template>
+  </ColorFieldRoot>
+</template>
diff --git a/vue/primitives/src/canvas/gradient-editor/GradientEditorRoot.vue b/vue/primitives/src/canvas/gradient-editor/GradientEditorRoot.vue
new file mode 100644
index 0000000..738aa00
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/GradientEditorRoot.vue
@@ -0,0 +1,372 @@
+<script lang="ts">
+import type { GradientEditorDirection, GradientEditorValueText, GradientStop, GradientStopEntry, GradientStopPatch, GradientType } from './context';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The headless root of a gradient-stop editor. It owns the list of color stops
+ * (controlled via `v-model` or uncontrolled via `defaultValue`), the gradient
+ * `type` (`'linear'` / `'radial'`), and the linear `angle`, and exposes a shared
+ * context so `GradientEditorTrack`, `GradientEditorStops`, `GradientEditorStop`,
+ * `GradientEditorAngle`, and `GradientEditorColorEditor` stay in sync.
+ *
+ * Each stop is `{ id, position, color }` with `position` a fraction in `[0, 1]`
+ * and `color` any CSS color string. The root keeps the stops sorted (stable
+ * tie-break at identical positions), drags/keys a stop with snapping and either
+ * neighbour-clamp (`reorder: false`) or cross-and-re-sort (`reorder: true`),
+ * adds a stop on track clicks (color interpolated from neighbours), and never
+ * removes below `minStops`. It also derives a `cssGradient` string for previews.
+ *
+ * Per-stop color editing is delegated to a `ColorField` (compose
+ * `GradientEditorColorEditor`, or mount one yourself). Reach for it whenever a
+ * user should design a multi-stop gradient (CSS backgrounds, color ramps,
+ * heatmap scales).
+ */
+export interface GradientEditorRootProps extends PrimitiveProps {
+  /** Uncontrolled initial stops. @default [] */
+  defaultValue?: GradientStop[];
+  /** Gradient type. @default 'linear' */
+  type?: GradientType;
+  /** Uncontrolled initial linear angle in degrees. @default 90 */
+  defaultAngle?: number;
+  /** Uncontrolled initial selected stop id. */
+  defaultSelectedId?: string | null;
+  /** Minimum number of stops; removal is blocked at this floor. @default 2 */
+  minStops?: number;
+  /**
+   * Whether dragging / nudging a stop past a neighbour re-sorts the list
+   * (`true`, each id keeps its color) or clamps to the neighbour so ids never
+   * cross (`false`). @default true
+   */
+  reorder?: boolean;
+  /** Keyboard step (fraction) for Arrow nudges. @default 0.001 */
+  step?: number;
+  /** Large keyboard step (Shift+Arrow / Page keys). @default 0.05 */
+  largeStep?: number;
+  /**
+   * Optional grid snap increment (fraction) applied to drags and keyboard
+   * moves. `undefined` disables grid snapping. @default undefined
+   */
+  snapStep?: number;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
+  dir?: GradientEditorDirection;
+  /** Optional per-stop `aria-valuetext` formatter. */
+  valueText?: GradientEditorValueText;
+}
+
+export interface GradientEditorRootEmits {
+  /** Emitted when a stop is added (after the model updates), with its id. */
+  addStop: [id: string];
+  /** Emitted when a stop is removed, with its id. */
+  removeStop: [id: string];
+  /** Emitted when a stop is selected (or cleared with `null`). */
+  selectStop: [id: string | null];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideGradientEditorContext } from './context';
+import { useDirection, useId } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+import { clamp } from '@robonen/stdlib';
+import {
+  buildCssGradient,
+  getStepDecimals,
+  interpolateColorAt,
+  neighboursAt,
+  roundToStep,
+  sortStops,
+} from './utils';
+
+const {
+  defaultValue,
+  type = 'linear',
+  defaultAngle = 90,
+  defaultSelectedId,
+  minStops = 2,
+  reorder = true,
+  step = 0.001,
+  largeStep = 0.05,
+  snapStep,
+  disabled = false,
+  dir,
+  valueText,
+  as = 'div',
+} = defineProps<GradientEditorRootProps>();
+
+const emit = defineEmits<GradientEditorRootEmits>();
+
+const direction = useDirection(() => dir);
+
+// A stable per-instance id base captured ONCE during setup (`useId` routes
+// through the active config). New stops append an incrementing counter so fresh
+// ids can be minted at event time without re-injecting the config context.
+const idBase = useId(undefined, 'gradient-stop').value;
+let stopIdCounter = 0;
+function nextStopId(): string {
+  return `${idBase}-${stopIdCounter++}`;
+}
+
+// `defineModel` drives controlled (`v-model`) and uncontrolled modes. The stops
+// array is always replaced wholesale, so `shallowRef` is enough.
+const model = defineModel<GradientStop[] | null>();
+const angleModel = defineModel<number | null>('angle');
+const selectedModel = defineModel<string | null>('selectedId');
+
+function normalizeStops(v: GradientStop[] | null | undefined): GradientStop[] {
+  return Array.isArray(v) ? v.slice() : [];
+}
+
+const seed = Array.isArray(model.value) ? model.value.slice() : normalizeStops(defaultValue);
+const localStops = shallowRef<GradientStop[]>(seed);
+
+const seedAngle = typeof angleModel.value === 'number' ? angleModel.value : defaultAngle;
+const localAngle = shallowRef<number>(seedAngle);
+
+const seedSelected = selectedModel.value !== undefined
+  ? selectedModel.value
+  : (defaultSelectedId ?? null);
+const localSelected = shallowRef<string | null>(seedSelected);
+
+// Cache decimals per `step` out of the pointermove hot path.
+let stepDecimals = getStepDecimals(step);
+watch(() => step, (s) => {
+  stepDecimals = getStepDecimals(s);
+});
+
+// ── adopt external model changes (controlled mode) ──────────────────────────
+watch(model, (v) => {
+  if (v === null || v === undefined) return;
+  if (v === localStops.value) return;
+  localStops.value = v.slice();
+});
+watch(angleModel, (v) => {
+  if (v === null || v === undefined) return;
+  if (v === localAngle.value) return;
+  localAngle.value = v;
+});
+watch(selectedModel, (v) => {
+  if (v === undefined) return;
+  if (v === localSelected.value) return;
+  localSelected.value = v;
+});
+
+// ── derived, sorted view (stable tie-break) ─────────────────────────────────
+const sorted = computed<GradientStop[]>(() => sortStops(localStops.value));
+
+// Memoized `id -> { stop, index }` over the sorted stops, rebuilt once whenever
+// `sorted` changes. Per-stop parts read this for O(1) lookups instead of each
+// running an O(n) find + indexOf every drag frame (which was O(n^2) per frame).
+const stopIndex = computed<Map<string, GradientStopEntry>>(() => {
+  const list = sorted.value;
+  const map = new Map<string, GradientStopEntry>();
+  for (let i = 0; i < list.length; i++) {
+    const s = list[i]!;
+    map.set(s.id, { stop: s, index: i });
+  }
+  return map;
+});
+
+const cssGradient = computed(() => buildCssGradient(sorted.value, type, localAngle.value));
+
+const canRemove = computed(() => localStops.value.length > minStops);
+
+function indexOf(id: string): number {
+  return stopIndex.value.get(id)?.index ?? -1;
+}
+
+// ── writes ──────────────────────────────────────────────────────────────────
+function commitStops(next: GradientStop[]): void {
+  localStops.value = next;
+  // `defineModel` emits `update:modelValue` on write.
+  model.value = next;
+}
+
+function setAngle(next: number): void {
+  if (disabled) return;
+  if (next === localAngle.value) return;
+  localAngle.value = next;
+  angleModel.value = next;
+}
+
+function select(id: string | null): void {
+  if (id === localSelected.value) return;
+  localSelected.value = id;
+  selectedModel.value = id;
+  emit('selectStop', id);
+}
+
+/** Snap a fractional position to the grid (when configured) then to `step`. */
+function resolvePosition(raw: number): number {
+  let v = clamp(raw, 0, 1);
+  if (snapStep !== undefined && snapStep > 0) {
+    const snapDecimals = getStepDecimals(snapStep);
+    v = roundToStep(v, snapStep, snapDecimals);
+  }
+  v = roundToStep(v, step, stepDecimals);
+  return clamp(v, 0, 1);
+}
+
+function addStop(position: number, color?: string): string | undefined {
+  if (disabled) return undefined;
+  const pos = resolvePosition(position);
+  const { before, after } = neighboursAt(sorted.value, pos);
+  const resolvedColor = color ?? interpolateColorAt(pos, before, after, '#000000');
+  const id = nextStopId();
+  const next = localStops.value.slice();
+  next.push({ id, position: pos, color: resolvedColor });
+  commitStops(next);
+  select(id);
+  emit('addStop', id);
+  return id;
+}
+
+function removeStop(id: string): void {
+  if (disabled) return;
+  // No-op at the floor — surfaced via `canRemove` so consumers disable a button.
+  if (localStops.value.length <= minStops) return;
+  const idx = localStops.value.findIndex(s => s.id === id);
+  if (idx === -1) return;
+  const next = localStops.value.slice();
+  next.splice(idx, 1);
+  commitStops(next);
+  if (localSelected.value === id) {
+    // Select the nearest surviving stop (in sorted order) for a smooth handoff.
+    const survivors = sortStops(next);
+    const fallback = survivors[Math.min(idx, survivors.length - 1)] ?? survivors[0] ?? null;
+    select(fallback ? fallback.id : null);
+  }
+  emit('removeStop', id);
+}
+
+function updateStop(id: string, patch: GradientStopPatch): void {
+  if (disabled) return;
+  const idx = localStops.value.findIndex(s => s.id === id);
+  if (idx === -1) return;
+  const cur = localStops.value[idx]!;
+  const nextPosition = patch.position !== undefined
+    ? clampPosition(id, patch.position)
+    : cur.position;
+  const nextColor = patch.color !== undefined ? patch.color : cur.color;
+  if (nextPosition === cur.position && nextColor === cur.color) return;
+  const next = localStops.value.slice();
+  next[idx] = { ...cur, position: nextPosition, color: nextColor };
+  commitStops(next);
+}
+
+/**
+ * Resolve the position for a move/update honoring the `reorder` policy:
+ * `reorder: false` clamps between the immediate neighbours in sorted order so
+ * ids never cross; `reorder: true` only resolves to step/grid (the sort handles
+ * crossing). Always snapped to grid/step first.
+ */
+function clampPosition(id: string, raw: number): number {
+  const pos = resolvePosition(raw);
+  if (reorder) return pos;
+  const list = sorted.value;
+  const i = list.findIndex(s => s.id === id);
+  if (i === -1) return pos;
+  const lower = list[i - 1]?.position ?? 0;
+  const upper = list[i + 1]?.position ?? 1;
+  return clamp(pos, lower, upper);
+}
+
+function moveStop(id: string, position: number): void {
+  if (disabled) return;
+  updateStop(id, { position });
+}
+
+// The bar element, set by `GradientEditorTrack` so pointer math has a rect.
+const trackRef = shallowRef<HTMLElement | null>(null);
+
+// ── stop element registry (roving focus) ────────────────────────────────────
+const stopEls = new Map<string, HTMLElement>();
+function registerStopEl(id: string, el: HTMLElement | null): void {
+  if (el) stopEls.set(id, el);
+  else stopEls.delete(id);
+}
+function getStopEl(id: string): HTMLElement | null {
+  return stopEls.get(id) ?? null;
+}
+
+// Keep selection valid: if the selected stop disappears, clear it.
+watch(sorted, (list) => {
+  const sel = localSelected.value;
+  if (sel !== null && !list.some(s => s.id === sel)) {
+    select(list[0]?.id ?? null);
+  }
+});
+
+provideGradientEditorContext({
+  stops: sorted,
+  stopIndex,
+  selectedId: localSelected,
+  type: toRef(() => type),
+  angle: localAngle,
+  minStops: toRef(() => minStops),
+  step: toRef(() => step),
+  largeStep: toRef(() => largeStep),
+  snapStep: toRef(() => snapStep),
+  reorder: toRef(() => reorder),
+  valueText: toRef(() => valueText),
+  direction,
+  disabled: toRef(() => disabled),
+  cssGradient,
+  canRemove,
+  trackRef,
+  setAngle,
+  select,
+  addStop,
+  removeStop,
+  updateStop,
+  moveStop,
+  registerStopEl,
+  getStopEl,
+  indexOf,
+});
+
+defineExpose({
+  /** The sorted stops (read-only view). */
+  stops: sorted,
+  /** The CSS gradient string. */
+  cssGradient,
+  /** The selected stop id. */
+  selectedId: localSelected,
+  addStop,
+  removeStop,
+  updateStop,
+  moveStop,
+  select,
+});
+
+// `useForwardExpose` runs AFTER `defineExpose` so the composable merges the
+// prior expose bindings (plus props + `$el`) instead of clobbering them.
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :data-type="type"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-can-remove="canRemove ? '' : undefined"
+    :dir="direction"
+  >
+    <slot
+      :stops="sorted"
+      :selected-id="localSelected"
+      :css-gradient="cssGradient"
+      :type="type"
+      :angle="localAngle"
+      :can-remove="canRemove"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/gradient-editor/GradientEditorStop.vue b/vue/primitives/src/canvas/gradient-editor/GradientEditorStop.vue
new file mode 100644
index 0000000..d0bb6bf
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/GradientEditorStop.vue
@@ -0,0 +1,192 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A single draggable color stop, rendered as `role="slider"`. It positions
+ * itself along the track by its `position` (`left: position * 100%`), carries
+ * the full ARIA value attributes (`aria-valuemin=0`, `aria-valuemax=1`,
+ * `aria-valuenow=position`, and an `aria-valuetext` of `` `<color> at <pct>%` ``
+ * — color is NEVER surfaced alone, WCAG 1.4.1), and reflects selection via
+ * `aria-selected` + `data-selected`.
+ *
+ * Only the selected stop is tabbable (roving tabindex); the arrow keys move it.
+ * Dragging moves the position with snapping and either neighbour-clamp or
+ * cross-and-re-sort per the root's `reorder`. Delete / Backspace removes it
+ * (a no-op at `minStops`). Give the stop an `aria-label` (defaults to
+ * `Stop N of M`). Exposes `{ stop, index, selected, percent }` as slot props.
+ */
+export interface GradientEditorStopProps extends PrimitiveProps {
+  /** The id of the stop this thumb represents. */
+  stopId: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useAttrs, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useGradientEditorContext } from './context';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { defaultStopValueText } from './utils';
+
+const { as = 'span', stopId } = defineProps<GradientEditorStopProps>();
+
+const ctx = useGradientEditorContext();
+const attrs = useAttrs();
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Register the element so the root can move roving focus between stops.
+watch(currentElement, (el) => {
+  ctx.registerStopEl(stopId, el ?? null);
+}, { immediate: true });
+
+// Single O(1) lookup into the root's memoized id->{stop,index} map, shared by
+// every mounted stop. Replaces a per-stop `find` + `indexOf` (two O(n) scans of
+// the wholesale-replaced sorted array on every drag frame, i.e. O(n^2)/frame).
+const entry = computed(() => ctx.stopIndex.value.get(stopId) ?? null);
+const stop = computed(() => entry.value?.stop ?? null);
+const index = computed(() => entry.value?.index ?? -1);
+const total = computed(() => ctx.stops.value.length);
+const position = computed(() => stop.value?.position ?? 0);
+const color = computed(() => stop.value?.color ?? 'transparent');
+const selected = computed(() => ctx.selectedId.value === stopId);
+
+const percentage = computed(() => position.value * 100);
+
+// `left: P%` keeps a stable, monomorphic style shape (dir flips via the `dir`
+// attribute inherited from the root, mirroring the slider's positioning).
+const positionStyle = computed<{
+  left: string | undefined;
+  right: string | undefined;
+}>(() => {
+  const edge = `${percentage.value}%`;
+  if (ctx.direction.value === 'rtl') return { left: undefined, right: edge };
+  return { left: edge, right: undefined };
+});
+
+// Roving tabindex: only the selected stop is in the tab order; when nothing is
+// selected the first stop is tabbable so Tab can still enter the editor.
+const tabindex = computed<number>(() => {
+  if (ctx.disabled.value) return -1;
+  if (selected.value) return 0;
+  if (ctx.selectedId.value === null && index.value === 0) return 0;
+  return -1;
+});
+
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return `Stop ${index.value + 1} of ${total.value}`;
+});
+
+// `aria-valuetext` always pairs color WITH position (WCAG 1.4.1). A consumer
+// `aria-valuetext` attr wins (it falls through via `$attrs`).
+const valueTextAttr = computed<string | undefined>(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  const fmt = ctx.valueText.value;
+  return fmt ? fmt(color.value, position.value) : defaultStopValueText(color.value, position.value);
+});
+
+function onSelect(): void {
+  if (ctx.disabled.value) return;
+  if (!selected.value) ctx.select(stopId);
+}
+
+// ── pointer drag (x → position) ─────────────────────────────────────────────
+let dragStartPosition = 0;
+
+usePointerDrag(currentElement, {
+  axis: 'x',
+  threshold: 0,
+  disabled: () => ctx.disabled.value,
+  // Stop the press from bubbling to the track (which would add a stop).
+  stopPropagation: true,
+  onStart: () => {
+    onSelect();
+    dragStartPosition = position.value;
+  },
+  onMove: (state) => {
+    const track = ctx.trackRef.value;
+    if (!track) return;
+    const width = track.getBoundingClientRect().width;
+    if (width === 0) return;
+    let deltaFraction = state.total.x / width;
+    if (ctx.direction.value === 'rtl') deltaFraction = -deltaFraction;
+    ctx.moveStop(stopId, dragStartPosition + deltaFraction);
+  },
+});
+
+// ── keyboard ────────────────────────────────────────────────────────────────
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const ltr = ctx.direction.value !== 'rtl';
+  const step = ctx.step.value;
+  const big = ctx.largeStep.value;
+  const unit = event.shiftKey ? big : step;
+  const cur = position.value;
+  switch (event.key) {
+    case 'ArrowRight':
+      event.preventDefault();
+      ctx.moveStop(stopId, cur + (ltr ? unit : -unit));
+      return;
+    case 'ArrowLeft':
+      event.preventDefault();
+      ctx.moveStop(stopId, cur + (ltr ? -unit : unit));
+      return;
+    case 'PageUp':
+      event.preventDefault();
+      ctx.moveStop(stopId, cur + big);
+      return;
+    case 'PageDown':
+      event.preventDefault();
+      ctx.moveStop(stopId, cur - big);
+      return;
+    case 'Home':
+      event.preventDefault();
+      ctx.moveStop(stopId, 0);
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.moveStop(stopId, 1);
+      return;
+    case 'Delete':
+    case 'Backspace':
+      event.preventDefault();
+      ctx.removeStop(stopId);
+      break;
+    default:
+  }
+}
+</script>
+
+<template>
+  <Primitive
+    :as="as"
+    :ref="forwardRef"
+    role="slider"
+    :tabindex="tabindex"
+    :aria-label="accessibleLabel"
+    :aria-valuemin="0"
+    :aria-valuemax="1"
+    :aria-valuenow="position"
+    :aria-valuetext="valueTextAttr"
+    :aria-orientation="'horizontal'"
+    :aria-selected="selected || undefined"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-selected="selected ? '' : undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+    @focus="onSelect"
+    @pointerdown="onSelect"
+  >
+    <slot
+      :stop="stop"
+      :index="index"
+      :selected="selected"
+      :percent="percentage"
+      :color="color"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/gradient-editor/GradientEditorStops.vue b/vue/primitives/src/canvas/gradient-editor/GradientEditorStops.vue
new file mode 100644
index 0000000..7b15da4
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/GradientEditorStops.vue
@@ -0,0 +1,38 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Iterator part that keeps the DOM in sync with the root's sorted stops across
+ * add / remove / reorder. By default it renders a `GradientEditorStop` per
+ * entry (keyed by stop `id`). Provide a default slot to template each stop
+ * yourself — it receives `{ stop, index, selected }` and you wrap your markup in
+ * a `GradientEditorStop :stop-id="stop.id"`.
+ */
+export interface GradientEditorStopsProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useGradientEditorContext } from './context';
+import GradientEditorStop from './GradientEditorStop.vue';
+
+const { as = 'div' } = defineProps<GradientEditorStopsProps>();
+
+const ctx = useGradientEditorContext();
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive :ref="forwardRef" :as="as">
+    <template v-for="(stop, index) in ctx.stops.value" :key="stop.id">
+      <slot
+        :stop="stop"
+        :index="index"
+        :selected="ctx.selectedId.value === stop.id"
+      >
+        <GradientEditorStop :stop-id="stop.id" />
+      </slot>
+    </template>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/gradient-editor/GradientEditorTrack.vue b/vue/primitives/src/canvas/gradient-editor/GradientEditorTrack.vue
new file mode 100644
index 0000000..53dc8ba
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/GradientEditorTrack.vue
@@ -0,0 +1,83 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The gradient bar. Clicking an empty part of the track adds a stop at the click
+ * position (its color is interpolated from the neighbouring stops); pressing
+ * Enter / Space while the track is focused adds a stop at the center. It owns the
+ * shared `trackRef` used by `GradientEditorStop` for pointer ↔ position math and
+ * exposes the live `cssGradient` so consumers can paint the bar (e.g. as a CSS
+ * `background`). A press that lands on a stop is ignored here — the stop handles
+ * its own drag.
+ *
+ * Render the gradient preview yourself via the slot's `cssGradient`, e.g.
+ * `:style="{ background: cssGradient }"`.
+ */
+export interface GradientEditorTrackProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useGradientEditorContext } from './context';
+
+const { as = 'div' } = defineProps<GradientEditorTrackProps>();
+
+const ctx = useGradientEditorContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Publish the bar element to the root so stops can resolve px ↔ position.
+watch(currentElement, (el) => {
+  ctx.trackRef.value = el ?? null;
+}, { immediate: true });
+
+/** Map a client x to a fraction in `[0, 1]` across the track (dir-aware). */
+function positionFromClientX(clientX: number): number {
+  const el = ctx.trackRef.value;
+  if (!el) return 0;
+  const rect = el.getBoundingClientRect();
+  if (rect.width === 0) return 0;
+  let offset = clientX - rect.left;
+  if (ctx.direction.value === 'rtl') offset = rect.width - offset;
+  return Math.min(1, Math.max(0, offset / rect.width));
+}
+
+function isStopTarget(event: Event): boolean {
+  const target = event.target as HTMLElement | null;
+  // Ignore presses that originate on (or inside) a stop thumb.
+  return !!target?.closest('[role="slider"]');
+}
+
+function onPointerDown(event: PointerEvent): void {
+  if (ctx.disabled.value || event.button !== 0) return;
+  if (isStopTarget(event)) return;
+  event.preventDefault();
+  const position = positionFromClientX(event.clientX);
+  ctx.addStop(position);
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  // Only act when the track itself is focused (not a bubbled stop key).
+  if (event.target !== currentElement.value) return;
+  if (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') {
+    event.preventDefault();
+    ctx.addStop(0.5);
+  }
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :tabindex="ctx.disabled.value ? undefined : 0"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    @pointerdown="onPointerDown"
+    @keydown="onKeyDown"
+  >
+    <slot :css-gradient="ctx.cssGradient.value" :stops="ctx.stops.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/gradient-editor/__test__/GradientEditor.test.ts b/vue/primitives/src/canvas/gradient-editor/__test__/GradientEditor.test.ts
new file mode 100644
index 0000000..85568e7
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/__test__/GradientEditor.test.ts
@@ -0,0 +1,446 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  GradientEditorRoot,
+  GradientEditorStops,
+  GradientEditorTrack,
+} from '../index';
+import type { GradientStop } from '../index';
+import { buildCssGradient, interpolateColorAt, neighboursAt, sortStops } from '../utils';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+type RootOpts = Partial<{
+  type: 'linear' | 'radial';
+  defaultAngle: number;
+  minStops: number;
+  reorder: boolean;
+  step: number;
+  largeStep: number;
+  snapStep: number;
+  disabled: boolean;
+  dir: 'ltr' | 'rtl';
+  defaultSelectedId: string | null;
+}>;
+
+function mountEditor(initial: GradientStop[], opts: RootOpts = {}) {
+  const model = ref<GradientStop[]>(initial.map(s => ({ ...s })));
+  const angle = ref<number | undefined>(undefined);
+  const Harness = defineComponent({
+    setup() {
+      return () => h(GradientEditorRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: GradientStop[] | null | undefined) => { if (v) model.value = v; },
+        angle: angle.value,
+        'onUpdate:angle': (v: number | null | undefined) => { angle.value = v ?? undefined; },
+        defaultSelectedId: initial[0]?.id ?? null,
+        ...opts,
+      }, {
+        default: () => h(GradientEditorTrack, null, {
+          default: () => h(GradientEditorStops),
+        }),
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model, angle };
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false });
+  el.dispatchEvent(event);
+}
+
+function pointer(el: Element, type: string, x: number, y: number, button = 0): void {
+  const ev = new PointerEvent(type, {
+    pointerId: 1,
+    button,
+    clientX: x,
+    clientY: y,
+    bubbles: true,
+    cancelable: true,
+  });
+  el.dispatchEvent(ev);
+}
+
+function stopEls(): HTMLElement[] {
+  return Array.from(document.querySelectorAll<HTMLElement>('[role="slider"]'));
+}
+
+function sizeTrack(el: HTMLElement): { left: number; width: number } {
+  el.style.position = 'fixed';
+  el.style.left = '0px';
+  el.style.top = '0px';
+  el.style.width = '200px';
+  el.style.height = '20px';
+  const rect = el.getBoundingClientRect();
+  return { left: rect.left, width: rect.width };
+}
+
+function trackEl(): HTMLElement {
+  // The track is the GradientEditorStops' parent (the Track's rendered element).
+  return stopEls()[0]!.parentElement!.parentElement!;
+}
+
+const STOPS: GradientStop[] = [
+  { id: 'a', position: 0, color: '#ff0000' },
+  { id: 'b', position: 1, color: '#0000ff' },
+];
+
+describe('GradientEditorStop — ARIA', () => {
+  it('renders role=slider with aria-valuemin/max/now and "<color> at <pct>%" valuetext', async () => {
+    mountEditor(STOPS);
+    await nextTick();
+    const stops = stopEls();
+    expect(stops).toHaveLength(2);
+    expect(stops[0]!.getAttribute('role')).toBe('slider');
+    expect(stops[0]!.getAttribute('aria-valuemin')).toBe('0');
+    expect(stops[0]!.getAttribute('aria-valuemax')).toBe('1');
+    expect(stops[0]!.getAttribute('aria-valuenow')).toBe('0');
+    expect(stops[0]!.getAttribute('aria-valuetext')).toBe('#ff0000 at 0%');
+    expect(stops[1]!.getAttribute('aria-valuetext')).toBe('#0000ff at 100%');
+  });
+
+  it('roving tabindex: only the selected stop is tabbable', async () => {
+    mountEditor(STOPS, { defaultSelectedId: 'a' });
+    await nextTick();
+    const stops = stopEls();
+    expect(stops[0]!.tabIndex).toBe(0);
+    expect(stops[1]!.tabIndex).toBe(-1);
+  });
+
+  it('reflects selection via aria-selected + data-selected', async () => {
+    mountEditor(STOPS, { defaultSelectedId: 'a' });
+    await nextTick();
+    const stops = stopEls();
+    expect(stops[0]!.getAttribute('aria-selected')).toBe('true');
+    expect(stops[0]!.hasAttribute('data-selected')).toBe(true);
+    expect(stops[1]!.getAttribute('aria-selected')).toBeNull();
+  });
+
+  it('default aria-label is "Stop N of M"; explicit label wins', async () => {
+    mountEditor(STOPS);
+    await nextTick();
+    expect(stopEls()[0]!.getAttribute('aria-label')).toBe('Stop 1 of 2');
+  });
+});
+
+describe('GradientEditorStop — keyboard', () => {
+  it('ArrowRight moves the selected stop by step; ArrowLeft moves it back', async () => {
+    const { model } = mountEditor(
+      [{ id: 'a', position: 0.5, color: '#ff0000' }, { id: 'b', position: 1, color: '#0000ff' }],
+      { step: 0.01, defaultSelectedId: 'a' },
+    );
+    await nextTick();
+    const stop = stopEls()[0]!;
+    keydown(stop, 'ArrowRight');
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBeCloseTo(0.51);
+    keydown(stop, 'ArrowLeft');
+    keydown(stop, 'ArrowLeft');
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBeCloseTo(0.49);
+  });
+
+  it('Shift+Arrow / Page move by largeStep', async () => {
+    const { model } = mountEditor(
+      [{ id: 'a', position: 0.5, color: '#f00' }, { id: 'b', position: 1, color: '#00f' }],
+      { step: 0.001, largeStep: 0.1, defaultSelectedId: 'a' },
+    );
+    await nextTick();
+    const stop = stopEls()[0]!;
+    keydown(stop, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBeCloseTo(0.6);
+    keydown(stop, 'PageDown');
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBeCloseTo(0.5);
+  });
+
+  it('Home/End jump to 0 / 1', async () => {
+    const { model } = mountEditor(
+      [{ id: 'a', position: 0.5, color: '#f00' }, { id: 'b', position: 0.6, color: '#00f' }],
+      { reorder: true, defaultSelectedId: 'a' },
+    );
+    await nextTick();
+    const stop = stopEls()[0]!;
+    keydown(stop, 'Home');
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBe(0);
+    keydown(stop, 'End');
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBe(1);
+  });
+
+  it('ArrowLeft is reversed in RTL', async () => {
+    const { model } = mountEditor(
+      [{ id: 'a', position: 0.5, color: '#f00' }, { id: 'b', position: 1, color: '#00f' }],
+      { step: 0.01, dir: 'rtl', defaultSelectedId: 'a' },
+    );
+    await nextTick();
+    keydown(stopEls()[0]!, 'ArrowLeft');
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBeCloseTo(0.51);
+  });
+
+  it('Delete removes the selected stop', async () => {
+    const { model } = mountEditor(
+      [
+        { id: 'a', position: 0, color: '#f00' },
+        { id: 'b', position: 0.5, color: '#0f0' },
+        { id: 'c', position: 1, color: '#00f' },
+      ],
+      { minStops: 2, defaultSelectedId: 'b' },
+    );
+    await nextTick();
+    const stop = stopEls()[1]!;
+    keydown(stop, 'Delete');
+    await nextTick();
+    expect(model.value.map(s => s.id)).toEqual(['a', 'c']);
+  });
+
+  it('Delete is a no-op at minStops', async () => {
+    const { model } = mountEditor(STOPS, { minStops: 2, defaultSelectedId: 'a' });
+    await nextTick();
+    keydown(stopEls()[0]!, 'Delete');
+    await nextTick();
+    expect(model.value).toHaveLength(2);
+  });
+});
+
+describe('GradientEditorTrack — add on click', () => {
+  it('clicking the track adds a stop at the click position', async () => {
+    const { model } = mountEditor(STOPS, { step: 0.01 });
+    await nextTick();
+    const track = trackEl();
+    const { left, width } = sizeTrack(track);
+    // Click at 25% of the track.
+    pointer(track, 'pointerdown', left + width * 0.25, 10);
+    await nextTick();
+    expect(model.value).toHaveLength(3);
+    const added = model.value.find(s => s.id !== 'a' && s.id !== 'b')!;
+    expect(added.position).toBeCloseTo(0.25, 2);
+  });
+
+  it('interpolates the new stop color from the neighbours', async () => {
+    const { model } = mountEditor(
+      [{ id: 'a', position: 0, color: '#000000' }, { id: 'b', position: 1, color: '#ffffff' }],
+      { step: 0.01 },
+    );
+    await nextTick();
+    const track = trackEl();
+    const { left, width } = sizeTrack(track);
+    pointer(track, 'pointerdown', left + width * 0.5, 10);
+    await nextTick();
+    const added = model.value.find(s => s.id !== 'a' && s.id !== 'b')!;
+    // Midway between black and white → mid grey ~ rgb(128,128,128).
+    expect(added.color).toMatch(/^rgba\(12[78], 12[78], 12[78], 1\)$/);
+  });
+
+  it('Enter on the focused track adds a stop at the center', async () => {
+    const { model } = mountEditor(STOPS);
+    await nextTick();
+    const track = trackEl();
+    track.focus();
+    keydown(track, 'Enter');
+    await nextTick();
+    expect(model.value).toHaveLength(3);
+    const added = model.value.find(s => s.id !== 'a' && s.id !== 'b')!;
+    expect(added.position).toBe(0.5);
+  });
+});
+
+describe('GradientEditorRoot — reorder policy', () => {
+  it('reorder=false neighbour-clamps (ids never cross)', async () => {
+    const { model } = mountEditor(
+      [
+        { id: 'a', position: 0.4, color: '#f00' },
+        { id: 'b', position: 0.5, color: '#0f0' },
+        { id: 'c', position: 0.6, color: '#00f' },
+      ],
+      { reorder: false, defaultSelectedId: 'a' },
+    );
+    await nextTick();
+    // Push 'a' hard right past 'b'; it must clamp to b's position, never cross.
+    keydown(stopEls()[0]!, 'End');
+    await nextTick();
+    const a = model.value.find(s => s.id === 'a')!;
+    expect(a.position).toBe(0.5);
+    // Order preserved.
+    expect(sortStops(model.value).map(s => s.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('reorder=true lets a stop cross and re-sorts; each id keeps its color', async () => {
+    const { model } = mountEditor(
+      [
+        { id: 'a', position: 0.4, color: '#ff0000' },
+        { id: 'b', position: 0.5, color: '#00ff00' },
+        { id: 'c', position: 0.6, color: '#0000ff' },
+      ],
+      { reorder: true, defaultSelectedId: 'a' },
+    );
+    await nextTick();
+    keydown(stopEls()[0]!, 'End');
+    await nextTick();
+    // 'a' is now last by position but keeps its red color.
+    const a = model.value.find(s => s.id === 'a')!;
+    expect(a.position).toBe(1);
+    expect(a.color).toBe('#ff0000');
+    expect(sortStops(model.value).map(s => s.id)).toEqual(['b', 'c', 'a']);
+  });
+});
+
+describe('GradientEditorRoot — disabled', () => {
+  it('blocks keyboard moves, removal, and track clicks', async () => {
+    const { model } = mountEditor(
+      [{ id: 'a', position: 0.5, color: '#f00' }, { id: 'b', position: 1, color: '#00f' }],
+      { disabled: true, defaultSelectedId: 'a' },
+    );
+    await nextTick();
+    const stops = stopEls();
+    expect(stops[0]!.tabIndex).toBe(-1);
+    expect(stops[0]!.getAttribute('aria-disabled')).toBe('true');
+    keydown(stops[0]!, 'ArrowRight');
+    keydown(stops[0]!, 'Delete');
+    await nextTick();
+    expect(model.value.find(s => s.id === 'a')!.position).toBe(0.5);
+    expect(model.value).toHaveLength(2);
+    // Track click does nothing.
+    const track = trackEl();
+    const { left, width } = sizeTrack(track);
+    pointer(track, 'pointerdown', left + width * 0.5, 10);
+    await nextTick();
+    expect(model.value).toHaveLength(2);
+  });
+});
+
+describe('GradientEditorRoot — cssGradient via exposed root', () => {
+  it('reflects stops + type + angle', async () => {
+    const exposed = ref<any>(null);
+    const Harness = defineComponent({
+      setup() {
+        const model = ref<GradientStop[]>([
+          { id: 'a', position: 0, color: '#ff0000' },
+          { id: 'b', position: 1, color: '#0000ff' },
+        ]);
+        return () => h(GradientEditorRoot, {
+          ref: (r: any) => { exposed.value = r; },
+          modelValue: model.value,
+          'onUpdate:modelValue': (v: GradientStop[] | null | undefined) => { if (v) model.value = v; },
+          type: 'linear',
+          defaultAngle: 45,
+        }, {
+          default: () => h(GradientEditorTrack, null, { default: () => h(GradientEditorStops) }),
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    expect(exposed.value.cssGradient).toBe('linear-gradient(45deg, #ff0000 0%, #0000ff 100%)');
+  });
+});
+
+describe('utils — sort / tie-break', () => {
+  it('sorts ascending by position', () => {
+    const out = sortStops([
+      { id: 'b', position: 0.8, color: '#00f' },
+      { id: 'a', position: 0.2, color: '#f00' },
+    ]);
+    expect(out.map(s => s.id)).toEqual(['a', 'b']);
+  });
+
+  it('keeps both stops at identical positions (stable tie-break by index)', () => {
+    const input: GradientStop[] = [
+      { id: 'x', position: 0.5, color: '#f00' },
+      { id: 'y', position: 0.5, color: '#0f0' },
+      { id: 'z', position: 0.5, color: '#00f' },
+    ];
+    const out = sortStops(input);
+    // Order preserved (stable) and all three present.
+    expect(out.map(s => s.id)).toEqual(['x', 'y', 'z']);
+    expect(out).toHaveLength(3);
+  });
+
+  it('does not mutate the input', () => {
+    const input: GradientStop[] = [
+      { id: 'b', position: 1, color: '#00f' },
+      { id: 'a', position: 0, color: '#f00' },
+    ];
+    const snapshot = input.map(s => s.id);
+    sortStops(input);
+    expect(input.map(s => s.id)).toEqual(snapshot);
+  });
+});
+
+describe('utils — buildCssGradient', () => {
+  it('builds a linear gradient with the angle', () => {
+    const css = buildCssGradient(
+      [{ id: 'a', position: 0, color: 'red' }, { id: 'b', position: 1, color: 'blue' }],
+      'linear',
+      90,
+    );
+    expect(css).toBe('linear-gradient(90deg, red 0%, blue 100%)');
+  });
+
+  it('builds a radial gradient (ignores angle)', () => {
+    const css = buildCssGradient(
+      [{ id: 'a', position: 0, color: 'red' }, { id: 'b', position: 0.5, color: 'blue' }],
+      'radial',
+      45,
+    );
+    expect(css).toBe('radial-gradient(circle, red 0%, blue 50%)');
+  });
+
+  it('compacts fractional percentages', () => {
+    const css = buildCssGradient([{ id: 'a', position: 1 / 3, color: 'red' }], 'linear', 0);
+    expect(css).toBe('linear-gradient(0deg, red 33.333%)');
+  });
+
+  it('returns empty string for no stops', () => {
+    expect(buildCssGradient([], 'linear', 90)).toBe('');
+  });
+});
+
+describe('utils — color interpolation / neighbours', () => {
+  it('interpolates midway between two colors', () => {
+    const c = interpolateColorAt(
+      0.5,
+      { id: 'a', position: 0, color: '#000000' },
+      { id: 'b', position: 1, color: '#ffffff' },
+      '#000000',
+    );
+    expect(c).toMatch(/^rgba\(12[78], 12[78], 12[78], 1\)$/);
+  });
+
+  it('copies the single neighbour when only one exists', () => {
+    const c = interpolateColorAt(0.3, { id: 'a', position: 0, color: '#abcdef' }, null, '#000000');
+    expect(c).toBe('#abcdef');
+  });
+
+  it('falls back when there are no neighbours', () => {
+    expect(interpolateColorAt(0.5, null, null, '#123456')).toBe('#123456');
+  });
+
+  it('neighboursAt finds the bracketing stops', () => {
+    const sorted: GradientStop[] = [
+      { id: 'a', position: 0, color: '#f00' },
+      { id: 'b', position: 0.5, color: '#0f0' },
+      { id: 'c', position: 1, color: '#00f' },
+    ];
+    const { before, after } = neighboursAt(sorted, 0.3);
+    expect(before!.id).toBe('a');
+    expect(after!.id).toBe('b');
+  });
+});
diff --git a/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-Enter-on-the-focused-track-adds-a-stop-at-the-center-1.png b/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-Enter-on-the-focused-track-adds-a-stop-at-the-center-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-Enter-on-the-focused-track-adds-a-stop-at-the-center-1.png differ
diff --git a/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-clicking-the-track-adds-a-stop-at-the-click-position-1.png b/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-clicking-the-track-adds-a-stop-at-the-click-position-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-clicking-the-track-adds-a-stop-at-the-click-position-1.png differ
diff --git a/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-interpolates-the-new-stop-color-from-the-neighbours-1.png b/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-interpolates-the-new-stop-color-from-the-neighbours-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/gradient-editor/__test__/__screenshots__/GradientEditor.test.ts/GradientEditorTrack---add-on-click-interpolates-the-new-stop-color-from-the-neighbours-1.png differ
diff --git a/vue/primitives/src/canvas/gradient-editor/context.ts b/vue/primitives/src/canvas/gradient-editor/context.ts
new file mode 100644
index 0000000..638beaf
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/context.ts
@@ -0,0 +1,122 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+export type GradientEditorDirection = 'ltr' | 'rtl';
+
+/** Whether the gradient is rendered linearly (with an `angle`) or radially. */
+export type GradientType = 'linear' | 'radial';
+
+/**
+ * A single color stop on the gradient bar.
+ *
+ * `position` is a fraction in `[0, 1]` (`0` = start of the bar, `1` = end) and
+ * `color` is any CSS color string (`#rrggbb`, `rgb()/rgba()`, `hsl()/hsla()`).
+ * `id` is a stable identity used as the `v-for` key, the roving-focus handle,
+ * and the tie-break for two stops sharing a `position`.
+ */
+export interface GradientStop {
+  /** Stable identity (v-for key, roving-focus handle, selection target). */
+  id: string;
+  /** Position along the bar as a fraction in `[0, 1]`. */
+  position: number;
+  /** Any CSS color string. */
+  color: string;
+}
+
+/** Patch applied to a stop by {@link GradientEditorContext.updateStop}. */
+export interface GradientStopPatch {
+  /** New position (fraction `[0, 1]`). */
+  position?: number;
+  /** New CSS color string. */
+  color?: string;
+}
+
+/**
+ * Formatter turning a stop's `color` + `position` into a human-friendly string
+ * for `aria-valuetext`. Defaults to `` `${color} at ${pct}%` ``. Color is NEVER
+ * surfaced alone (WCAG 1.4.1) — keep the position in any override.
+ */
+export type GradientEditorValueText = (color: string, position: number) => string;
+
+/** A stop paired with its index in the sorted list, keyed by id in {@link GradientEditorContext.stopIndex}. */
+export interface GradientStopEntry {
+  /** The stop. */
+  stop: GradientStop;
+  /** Its index within the sorted stops. */
+  index: number;
+}
+
+/**
+ * Context shared between `GradientEditorRoot` and its descendants.
+ *
+ * Scalar props are exposed as plain `Ref<T>` values, built by the root with
+ * `toRef(() => prop)` (a `GetterRefImpl` that is reactive without an extra
+ * `ReactiveEffect` / cache), mirroring the slider / curve-editor convention.
+ */
+export interface GradientEditorContext {
+  /** The live stops, sorted ascending by position (stable tie-break by index). */
+  stops: Ref<GradientStop[]>;
+  /**
+   * Memoized `id -> { stop, index }` over the sorted stops, rebuilt once per
+   * stops change. Per-stop parts read this for O(1) lookups instead of scanning
+   * the wholesale-replaced array each drag frame.
+   */
+  stopIndex: Ref<Map<string, GradientStopEntry>>;
+  /** The id of the currently selected stop, or `null`. */
+  selectedId: Ref<string | null>;
+  /** Gradient type — `'linear'` (uses `angle`) or `'radial'`. */
+  type: Ref<GradientType>;
+  /** Linear gradient angle in degrees. */
+  angle: Ref<number>;
+  /** Minimum number of stops; removal is blocked at this floor. */
+  minStops: Ref<number>;
+  /** Keyboard step (fraction) for Arrow nudges. */
+  step: Ref<number>;
+  /** Large keyboard step (Shift+Arrow / Page keys). */
+  largeStep: Ref<number>;
+  /** Optional grid snap increment (fraction); `undefined` disables grid snap. */
+  snapStep: Ref<number | undefined>;
+  /** Whether dragging a stop past a neighbour re-sorts (`true`) or clamps (`false`). */
+  reorder: Ref<boolean>;
+  /** Optional per-stop `aria-valuetext` formatter. */
+  valueText: Ref<GradientEditorValueText | undefined>;
+  direction: Ref<GradientEditorDirection>;
+  disabled: Ref<boolean>;
+  /** The CSS gradient string for the current stops + type + angle (preview). */
+  cssGradient: Ref<string>;
+  /** Whether removal is allowed (`stops.length > minStops`). */
+  canRemove: Ref<boolean>;
+  /** The bar element used for pointer ↔ position math (set by the Track). */
+  trackRef: Ref<HTMLElement | null>;
+  /** Set the linear gradient angle (degrees), writing the `angle` model. */
+  setAngle: (deg: number) => void;
+  /** Select a stop (or clear with `null`). */
+  select: (id: string | null) => void;
+  /**
+   * Add a stop at `position` (fraction `[0, 1]`). When `color` is omitted it is
+   * interpolated from the neighbouring stops. Returns the new stop's id, or
+   * `undefined` when disabled.
+   */
+  addStop: (position: number, color?: string) => string | undefined;
+  /** Remove a stop by id (no-op at `minStops` or when disabled). */
+  removeStop: (id: string) => void;
+  /** Patch a stop's `position` / `color` by id (neighbour-clamped position). */
+  updateStop: (id: string, patch: GradientStopPatch) => void;
+  /**
+   * Move a stop to `position` honoring the `reorder` policy: when `reorder` is
+   * `false` the position is clamped between its neighbours (ids never cross);
+   * when `true` it may cross and the array re-sorts (each id keeps its color).
+   */
+  moveStop: (id: string, position: number) => void;
+  /** Register a stop's DOM element so roving focus can move between them. */
+  registerStopEl: (id: string, el: HTMLElement | null) => void;
+  /** The element for a stop id, or `null`. */
+  getStopEl: (id: string) => HTMLElement | null;
+  /** Index of a stop id within the sorted stops (`-1` when absent). */
+  indexOf: (id: string) => number;
+}
+
+const ctx = useContextFactory<GradientEditorContext>('GradientEditorContext');
+
+export const provideGradientEditorContext = ctx.provide;
+export const useGradientEditorContext = ctx.inject;
diff --git a/vue/primitives/src/canvas/gradient-editor/demo.vue b/vue/primitives/src/canvas/gradient-editor/demo.vue
new file mode 100644
index 0000000..2325972
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/demo.vue
@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import type { GradientStop } from '@robonen/primitives';
+import {
+  GradientEditorRoot,
+  GradientEditorStop,
+  GradientEditorStops,
+  GradientEditorTrack,
+} from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+// A couple of synthetic stops to seed the bar. `position` is a fraction [0, 1].
+const stops = ref<GradientStop[]>([
+  { id: 'stop-a', position: 0, color: '#6366f1' },
+  { id: 'stop-b', position: 0.5, color: '#ec4899' },
+  { id: 'stop-c', position: 1, color: '#f59e0b' },
+]);
+
+const selectedId = ref<string | null>('stop-b');
+
+const selectedStop = computed(() =>
+  stops.value.find(s => s.id === selectedId.value) ?? null,
+);
+
+// A small palette to recolor the selected stop without an embedded color picker.
+const swatches = ['#6366f1', '#ec4899', '#f59e0b', '#10b981', '#0ea5e9', '#ef4444', '#ffffff', '#111827'];
+
+function recolorSelected(color: string): void {
+  const stop = selectedStop.value;
+  if (stop) stop.color = color;
+}
+
+function fmtPct(position: number): string {
+  return `${Math.round(position * 100)}%`;
+}
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-md space-y-6 p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <span class="font-medium">Gradient editor</span>
+      <span class="font-mono text-fg-muted">{{ stops.length }} stops</span>
+    </div>
+
+    <GradientEditorRoot
+      v-model="stops"
+      v-model:selected-id="selectedId"
+      :min-stops="2"
+      class="space-y-4"
+    >
+      <template #default="{ cssGradient }">
+        <!-- Live CSS-gradient preview painted from the exposed cssGradient -->
+        <div
+          class="h-16 w-full rounded-card border border-border shadow-(--shadow-card)"
+          :style="{ background: cssGradient }"
+        />
+
+        <!-- The interactive stop bar: track paints itself, stops sit on top -->
+        <GradientEditorTrack
+          class="relative h-7 w-full cursor-copy touch-none select-none rounded-full border border-border-strong outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          :style="{ background: cssGradient }"
+        >
+          <GradientEditorStops>
+            <template #default="{ stop, selected }">
+              <GradientEditorStop
+                :stop-id="stop.id"
+                :aria-label="`Stop at ${fmtPct(stop.position)}`"
+                class="absolute top-1/2 size-5 -translate-x-1/2 -translate-y-1/2 cursor-grab touch-none rounded-full border-2 border-white shadow-md outline-none ring-1 ring-black/30 transition-transform focus-visible:ring-2 focus-visible:ring-ring active:cursor-grabbing hover:scale-115"
+                :class="selected ? 'z-10 scale-115 ring-2 ring-accent' : ''"
+                :style="{ backgroundColor: stop.color }"
+              />
+            </template>
+          </GradientEditorStops>
+        </GradientEditorTrack>
+      </template>
+    </GradientEditorRoot>
+
+    <p class="text-xs text-fg-subtle">
+      Drag a stop to move it, or click an empty part of the bar to add one.
+    </p>
+
+    <!-- Selected stop inspector + a swatch palette to recolor it -->
+    <div v-if="selectedStop" class="space-y-3 rounded-card bg-bg-inset p-3">
+      <div class="flex items-center gap-3">
+        <span
+          class="size-9 shrink-0 rounded-lg border border-border-strong"
+          :style="{ backgroundColor: selectedStop.color }"
+        />
+        <div class="flex flex-col text-sm leading-tight">
+          <span class="font-mono text-fg">{{ selectedStop.color }}</span>
+          <span class="font-mono text-xs text-fg-subtle">at {{ fmtPct(selectedStop.position) }}</span>
+        </div>
+      </div>
+
+      <div class="flex flex-wrap gap-1.5">
+        <button
+          v-for="swatch in swatches"
+          :key="swatch"
+          type="button"
+          class="size-6 rounded-md border border-border-strong outline-none transition focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+          :class="selectedStop.color.toLowerCase() === swatch.toLowerCase() ? 'ring-2 ring-accent' : ''"
+          :style="{ backgroundColor: swatch }"
+          :aria-label="`Set selected stop to ${swatch}`"
+          @click="recolorSelected(swatch)"
+        />
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/gradient-editor/index.ts b/vue/primitives/src/canvas/gradient-editor/index.ts
new file mode 100644
index 0000000..e07eb2b
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/index.ts
@@ -0,0 +1,34 @@
+export { default as GradientEditorRoot } from './GradientEditorRoot.vue';
+export { default as GradientEditorAngle } from './GradientEditorAngle.vue';
+export { default as GradientEditorColorEditor } from './GradientEditorColorEditor.vue';
+export { default as GradientEditorStop } from './GradientEditorStop.vue';
+export { default as GradientEditorStops } from './GradientEditorStops.vue';
+export { default as GradientEditorTrack } from './GradientEditorTrack.vue';
+
+export type { GradientEditorRootEmits, GradientEditorRootProps } from './GradientEditorRoot.vue';
+export type { GradientEditorAngleProps } from './GradientEditorAngle.vue';
+export type { GradientEditorColorEditorProps } from './GradientEditorColorEditor.vue';
+export type { GradientEditorStopProps } from './GradientEditorStop.vue';
+export type { GradientEditorStopsProps } from './GradientEditorStops.vue';
+export type { GradientEditorTrackProps } from './GradientEditorTrack.vue';
+
+export type {
+  GradientEditorContext,
+  GradientEditorDirection,
+  GradientEditorValueText,
+  GradientStop,
+  GradientStopPatch,
+  GradientType,
+} from './context';
+export {
+  provideGradientEditorContext,
+  useGradientEditorContext,
+} from './context';
+
+export {
+  buildCssGradient,
+  defaultStopValueText,
+  interpolateColorAt,
+  neighboursAt,
+  sortStops,
+} from './utils';
diff --git a/vue/primitives/src/canvas/gradient-editor/utils.ts b/vue/primitives/src/canvas/gradient-editor/utils.ts
new file mode 100644
index 0000000..8799aa0
--- /dev/null
+++ b/vue/primitives/src/canvas/gradient-editor/utils.ts
@@ -0,0 +1,168 @@
+import type { GradientStop, GradientType } from './context';
+import { clamp } from '@robonen/stdlib';
+import { hsvToRgb, parseColor } from '../../internal/color';
+import type { RGB } from '../../internal/color';
+
+/**
+ * Returns the number of decimal digits in a numeric `step`.
+ *
+ * Used by {@link roundToStep} to compensate floating-point drift without
+ * allocating strings on every invocation (the cost is paid once per `step`
+ * change and cached by the caller).
+ */
+export function getStepDecimals(step: number): number {
+  if (!Number.isFinite(step)) return 0;
+  const str = String(step);
+  const dot = str.indexOf('.');
+  if (dot === -1) return 0;
+  return str.length - dot - 1;
+}
+
+/**
+ * Snap `value` to the nearest multiple of `step` anchored at `0`.
+ *
+ * `decimals` must be pre-computed by the caller via {@link getStepDecimals} and
+ * cached per-`step` — this is on the pointermove hot path.
+ */
+export function roundToStep(value: number, step: number, decimals: number): number {
+  if (!(step > 0)) return value;
+  const nearest = Math.round(value / step) * step;
+  return decimals > 0 ? Number(nearest.toFixed(decimals)) : nearest;
+}
+
+/**
+ * Stable comparator for two stops: ascending by `position`, then by the
+ * positional `index` they held in the source array as a tie-break.
+ *
+ * Tying on the source index (rather than `id`) keeps an O(n log n) sort total
+ * order deterministic AND stable — two stops at the same position never swap on
+ * an unrelated re-render, and the CSS string stays byte-identical frame to
+ * frame (important so the browser does not re-rasterize the preview).
+ */
+function compareIndexed(a: { stop: GradientStop; index: number }, b: { stop: GradientStop; index: number }): number {
+  if (a.stop.position !== b.stop.position) return a.stop.position - b.stop.position;
+  return a.index - b.index;
+}
+
+/**
+ * Return a new array of `stops` sorted ascending by `position`, breaking ties at
+ * identical positions by the stop's original index so the order is stable and
+ * deterministic (both stops remain present and individually selectable).
+ *
+ * The input is never mutated.
+ */
+export function sortStops(stops: readonly GradientStop[]): GradientStop[] {
+  const indexed = stops.map((stop, index) => ({ stop, index }));
+  indexed.sort(compareIndexed);
+  return indexed.map(e => e.stop);
+}
+
+/** Round a fractional position to a percentage string used in CSS gradients. */
+function positionToPercent(position: number): string {
+  const pct = clamp(position, 0, 1) * 100;
+  // Trim to at most 3 decimals, then drop trailing zeros for a stable, compact
+  // string (`50%` not `50.000%`); avoids float noise like `33.333333%`.
+  const rounded = Math.round(pct * 1000) / 1000;
+  return `${rounded}%`;
+}
+
+/**
+ * Build a CSS `linear-gradient(...)` / `radial-gradient(...)` string from the
+ * (already-sorted) `stops`.
+ *
+ * For `'linear'` the `angle` (degrees) is emitted as `${angle}deg`; `'radial'`
+ * ignores the angle and produces `radial-gradient(circle, ...)`. Each stop
+ * contributes `<color> <pct>%`. Returns an empty string when there are no stops.
+ */
+export function buildCssGradient(stops: readonly GradientStop[], type: GradientType, angle: number): string {
+  if (stops.length === 0) return '';
+  let body = '';
+  for (let i = 0; i < stops.length; i++) {
+    const s = stops[i]!;
+    if (i > 0) body += ', ';
+    body += `${s.color} ${positionToPercent(s.position)}`;
+  }
+  if (type === 'radial') return `radial-gradient(circle, ${body})`;
+  return `linear-gradient(${angle}deg, ${body})`;
+}
+
+/** Resolve any CSS color string to opaque-or-alpha RGBA channels, or `null`. */
+function toRgb(color: string): (RGB & { a: number }) | null {
+  const hsva = parseColor(color);
+  if (!hsva) return null;
+  const rgb = hsvToRgb(hsva);
+  return { r: rgb.r, g: rgb.g, b: rgb.b, a: hsva.a };
+}
+
+/** Linear interpolation of a single numeric channel. */
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+/**
+ * Interpolate a color at fractional `position` (0..1) between two neighbouring
+ * stops `before`/`after` (either may be `null` at the ends). The blend happens
+ * in sRGB space and the result is returned as an `rgba(...)` string.
+ *
+ * - Both neighbours present: linearly blend by the relative position.
+ * - One neighbour: copy that neighbour's color.
+ * - Neither (no stops): fall back to `fallback`.
+ * - A neighbour whose color cannot be parsed is treated as absent.
+ */
+export function interpolateColorAt(
+  position: number,
+  before: GradientStop | null,
+  after: GradientStop | null,
+  fallback: string,
+): string {
+  const lo = before ? toRgb(before.color) : null;
+  const hi = after ? toRgb(after.color) : null;
+
+  if (lo && hi) {
+    const span = after!.position - before!.position;
+    const t = span <= 0 ? 0.5 : clamp((position - before!.position) / span, 0, 1);
+    const r = Math.round(lerp(lo.r, hi.r, t));
+    const g = Math.round(lerp(lo.g, hi.g, t));
+    const b = Math.round(lerp(lo.b, hi.b, t));
+    const a = lerp(lo.a, hi.a, t);
+    return `rgba(${r}, ${g}, ${b}, ${a})`;
+  }
+  if (lo) return before!.color;
+  if (hi) return after!.color;
+  return fallback;
+}
+
+/**
+ * Given the sorted stops and an insertion `position`, find the immediate
+ * lower/upper neighbours (by position) used to interpolate a new stop's color.
+ * `before` is the last stop at or below `position`; `after` is the first stop
+ * strictly above it.
+ */
+export function neighboursAt(
+  sorted: readonly GradientStop[],
+  position: number,
+): { before: GradientStop | null; after: GradientStop | null } {
+  let before: GradientStop | null = null;
+  let after: GradientStop | null = null;
+  for (let i = 0; i < sorted.length; i++) {
+    const s = sorted[i]!;
+    if (s.position <= position) {
+      before = s;
+    }
+    else {
+      after = s;
+      break;
+    }
+  }
+  return { before, after };
+}
+
+/**
+ * Default accessible value text for a stop: `<color> at <pct>%`. NEVER the color
+ * alone — a screen-reader user must hear the position too, and color must never
+ * be the sole carrier of meaning (WCAG 1.4.1 Use of Color).
+ */
+export function defaultStopValueText(color: string, position: number): string {
+  const pct = Math.round(clamp(position, 0, 1) * 100);
+  return `${color} at ${pct}%`;
+}
diff --git a/vue/primitives/src/canvas/histogram/HistogramBars.vue b/vue/primitives/src/canvas/histogram/HistogramBars.vue
new file mode 100644
index 0000000..b07f619
--- /dev/null
+++ b/vue/primitives/src/canvas/histogram/HistogramBars.vue
@@ -0,0 +1,96 @@
+<script lang="ts">
+import type { HistogramBarChannel } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Renders the per-channel bars of the enclosing `HistogramRoot` as a dense,
+ * `aria-hidden` visual. Supply a single `channel` to draw one channel, or omit
+ * it to draw every primary the root's `channel` requests (the three primaries
+ * for `'rgb'`, otherwise the single resolved channel). Each rendered bar group
+ * carries `data-channel` and a `--histogram-color` hint; bar heights come from
+ * the root's projection (already normalised to `[0, 1]` with the all-zero
+ * guard, so they are `0` — never `NaN` — for an empty histogram). The default
+ * slot receives the per-bar `{ channel, heights }` so consumers own the paint.
+ */
+export interface HistogramBarsProps extends PrimitiveProps {
+  /** Draw a single channel. Omit to draw every channel the root requests. */
+  channel?: HistogramBarChannel;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useHistogramContext } from './context';
+import { HISTOGRAM_CHANNEL_COLORS } from './utils';
+import { useForwardExpose } from '@robonen/vue';
+
+const { channel, as = 'div' } = defineProps<HistogramBarsProps>();
+const ctx = useHistogramContext();
+
+/** Channels this part draws: the explicit `channel`, else whatever the root asks for. */
+const channels = computed<HistogramBarChannel[]>(() => {
+  if (channel) return [channel];
+  const rootChannel = ctx.channel.value;
+  // `'rgb'` expands to the three primaries; any other value is already a single
+  // concrete channel.
+  return rootChannel === 'rgb' ? ['r', 'g', 'b'] : [rootChannel];
+});
+
+/**
+ * Per-channel rows of `{ channel, color, heights }` (heights normalised
+ * `[0,1]`). The `varStyle`/`barStyles` fields are precomputed render styling
+ * for the built-in fallback paint so the `v-for` binds stable object
+ * references instead of allocating a fresh style object per channel/per bar on
+ * every render; they are internal and not part of the slot contract.
+ */
+const series = computed(() =>
+  channels.value.map((ch) => {
+    const heights = ctx.bars(ch);
+    const barStyles: Array<{ height: string }> = [];
+    for (let i = 0; i < heights.length; i++) {
+      barStyles.push({ height: `${heights[i]! * 100}%` });
+    }
+    return {
+      channel: ch,
+      color: HISTOGRAM_CHANNEL_COLORS[ch],
+      heights,
+      varStyle: { '--histogram-color': HISTOGRAM_CHANNEL_COLORS[ch] },
+      barStyles,
+    };
+  }),
+);
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+  >
+    <template v-for="row in series" :key="row.channel">
+      <slot
+        :channel="row.channel"
+        :color="row.color"
+        :heights="row.heights"
+      >
+        <Primitive
+          as="div"
+          :data-channel="row.channel"
+          :style="row.varStyle"
+        >
+          <Primitive
+            v-for="(barStyle, i) in row.barStyles"
+            :key="i"
+            as="div"
+            :data-bar="i"
+            :style="barStyle"
+          />
+        </Primitive>
+      </slot>
+    </template>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/histogram/HistogramRoot.vue b/vue/primitives/src/canvas/histogram/HistogramRoot.vue
new file mode 100644
index 0000000..cde60f5
--- /dev/null
+++ b/vue/primitives/src/canvas/histogram/HistogramRoot.vue
@@ -0,0 +1,129 @@
+<script lang="ts">
+import type { HistogramBarChannel, HistogramChannel, HistogramData, HistogramScaleType } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A headless, accessible per-channel image histogram. The root owns the bin
+ * `data` (single-channel `number[]` or a per-channel record), normalises each
+ * channel against its own peak under the chosen `scaleType` (`'linear'` or
+ * `'log'`), and provides the resulting `[0, 1]` bar heights to `HistogramBars`.
+ * It is a dense visual: the rendered bars are `aria-hidden`, while the root
+ * carries `role="img"` with an `aria-label` summary (or `role="group"`).
+ *
+ * The all-zero / empty guard is built in — a flat or empty histogram projects to
+ * zero height (no divide-by-zero, no `NaN`) and the summary label reports
+ * "no data". Pair it with `LevelsRoot` for a Photoshop-style levels editor, or
+ * use it standalone to visualise tonal distribution.
+ */
+export interface HistogramRootProps extends PrimitiveProps {
+  /**
+   * Bin counts. A single `number[]` is interpreted as the channel named by
+   * `channel`; a record carries any subset of `'r'`/`'g'`/`'b'`/`'l'`.
+   * @default []
+   */
+  data?: HistogramData;
+  /**
+   * Primary channel. `'rgb'` is the composite (all three primaries overlaid);
+   * the others are single channels. `HistogramBars` defaults to this channel.
+   * @default 'l'
+   */
+  channel?: HistogramChannel;
+  /** Requested bin count (the rendered bar count follows the supplied data). @default 256 */
+  bins?: number;
+  /** Bar-height mapping. @default 'linear' */
+  scaleType?: HistogramScaleType;
+  /** Disable / dim the histogram (purely presentational — it has no interaction). @default false */
+  disabled?: boolean;
+  /**
+   * Use `role="group"` instead of the default `role="img"`. Reach for it when
+   * the bars are themselves interactive descendants. @default false
+   */
+  group?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, toRef } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideHistogramContext } from './context';
+import { getChannelBins, histogramMax, isSingleChannelData, projectBars } from './utils';
+import { useForwardExpose } from '@robonen/vue';
+
+const {
+  data = [],
+  channel = 'l',
+  bins = 256,
+  scaleType = 'linear',
+  disabled = false,
+  group = false,
+  as = 'div',
+} = defineProps<HistogramRootProps>();
+
+// A single concrete channel to resolve the `number[]` form against and to drive
+// the "has data" summary. `'rgb'` falls back to `'l'` for the array form but the
+// summary still inspects whichever primaries are present (see `hasData`).
+const primaryChannel = computed<HistogramBarChannel>(() => (channel === 'rgb' ? 'l' : channel));
+
+/** Concrete channels to consider for the "has data" check. */
+const summaryChannels = computed<HistogramBarChannel[]>(() => {
+  if (channel === 'rgb') return ['r', 'g', 'b'];
+  return [primaryChannel.value];
+});
+
+const hasData = computed<boolean>(() => {
+  for (const ch of summaryChannels.value) {
+    const binsForChannel = getChannelBins(data, ch, primaryChannel.value);
+    if (histogramMax(binsForChannel) > 0) return true;
+  }
+  // The single-array form keyed under a different channel still counts as data
+  // if it carries any signal (e.g. `channel: 'r'` with a bare array).
+  if (isSingleChannelData(data) && data.length > 0 && histogramMax(data) > 0) return true;
+  return false;
+});
+
+/**
+ * Normalised heights for `ch`. Each channel is normalised against ITS OWN peak
+ * so a quiet channel still fills the box — the standard per-channel histogram
+ * behaviour. The `projectBars` peak guard makes an empty/all-zero channel
+ * project to all zeros.
+ */
+function bars(ch: HistogramBarChannel): number[] {
+  const binsForChannel = getChannelBins(data, ch, primaryChannel.value);
+  return projectBars(binsForChannel, scaleType);
+}
+
+const ariaLabel = computed<string>(() => {
+  const channelName = channel === 'rgb' ? 'RGB' : channel.toUpperCase();
+  if (!hasData.value) return `Histogram, ${channelName}, no data`;
+  return `Histogram, ${channelName}`;
+});
+
+provideHistogramContext({
+  data: toRef(() => data),
+  channel: toRef(() => channel),
+  scaleType: toRef(() => scaleType),
+  bins: toRef(() => bins),
+  disabled: toRef(() => disabled),
+  hasData,
+  bars,
+});
+
+defineExpose({ hasData, bars });
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :role="group ? 'group' : 'img'"
+    :aria-label="ariaLabel"
+    :data-channel="channel"
+    :data-scale="scaleType"
+    :data-empty="hasData ? undefined : ''"
+    :data-disabled="disabled ? '' : undefined"
+  >
+    <slot :bars="bars" :has-data="hasData" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/histogram/__test__/Histogram.test.ts b/vue/primitives/src/canvas/histogram/__test__/Histogram.test.ts
new file mode 100644
index 0000000..b4adca6
--- /dev/null
+++ b/vue/primitives/src/canvas/histogram/__test__/Histogram.test.ts
@@ -0,0 +1,136 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { HistogramBars, HistogramRoot } from '../index';
+import { histogramMax, projectBarHeight, projectBars } from '../utils';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function mountHistogram(props: Record<string, unknown>) {
+  const Harness = defineComponent({
+    setup: () => () => h(HistogramRoot, props, { default: () => h(HistogramBars) }),
+  });
+  return track(mount(Harness, { attachTo: document.body }));
+}
+
+describe('Histogram — bar projection (unit)', () => {
+  it('histogramMax returns the peak; 0 for empty / all-zero', () => {
+    expect(histogramMax([])).toBe(0);
+    expect(histogramMax([0, 0, 0])).toBe(0);
+    expect(histogramMax([1, 9, 3])).toBe(9);
+  });
+
+  it('linear projection normalises against the peak', () => {
+    const heights = projectBars([0, 5, 10], 'linear');
+    expect(heights[0]).toBe(0);
+    expect(heights[1]).toBeCloseTo(0.5, 5);
+    expect(heights[2]).toBe(1);
+  });
+
+  it('log projection is 0 at empty bins and 1 at the peak, monotonic', () => {
+    const heights = projectBars([0, 5, 100], 'log');
+    expect(heights[0]).toBe(0);
+    expect(heights[2]).toBeCloseTo(1, 5);
+    // Monotonic non-decreasing.
+    expect(heights[1]!).toBeGreaterThan(heights[0]!);
+    expect(heights[2]!).toBeGreaterThan(heights[1]!);
+    // Log compresses: the midpoint sits well above its linear 0.05.
+    expect(heights[1]!).toBeGreaterThan(0.05);
+  });
+
+  it('all-zero / empty input yields 0 height with no NaN', () => {
+    for (const scale of ['linear', 'log'] as const) {
+      const zeros = projectBars([0, 0, 0], scale);
+      expect(zeros.every(h => h === 0)).toBe(true);
+      expect(zeros.some(Number.isNaN)).toBe(false);
+      const empty = projectBars([], scale);
+      expect(empty).toHaveLength(0);
+    }
+  });
+
+  it('projectBarHeight guards divide-by-zero (max <= 0 → 0)', () => {
+    expect(projectBarHeight(5, 0, 'linear')).toBe(0);
+    expect(projectBarHeight(5, 0, 'log')).toBe(0);
+    expect(Number.isNaN(projectBarHeight(5, 0, 'linear'))).toBe(false);
+  });
+});
+
+describe('Histogram — root ARIA + rendering', () => {
+  it('exposes role="img" with a channel summary label', async () => {
+    mountHistogram({ data: [1, 2, 3], channel: 'l' });
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[role="img"]')!;
+    expect(root).toBeTruthy();
+    expect(root.getAttribute('aria-label')).toBe('Histogram, L');
+    expect(root.getAttribute('data-channel')).toBe('l');
+  });
+
+  it('reports "no data" for an all-zero / empty histogram', async () => {
+    mountHistogram({ data: [0, 0, 0], channel: 'r' });
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[role="img"]')!;
+    expect(root.getAttribute('aria-label')).toBe('Histogram, R, no data');
+    expect(root.hasAttribute('data-empty')).toBe(true);
+  });
+
+  it('role="group" when group is set', async () => {
+    mountHistogram({ data: [1, 2], group: true });
+    await nextTick();
+    expect(document.querySelector('[role="group"]')).toBeTruthy();
+    expect(document.querySelector('[role="img"]')).toBeNull();
+  });
+
+  it('bars are aria-hidden and compute normalised heights', async () => {
+    mountHistogram({ data: [0, 50, 100], channel: 'l' });
+    await nextTick();
+    const bars = document.querySelector<HTMLElement>('[aria-hidden="true"]')!;
+    expect(bars).toBeTruthy();
+    const drawn = bars.querySelectorAll<HTMLElement>('[data-bar]');
+    expect(drawn).toHaveLength(3);
+    // Peak (100) → 100% height.
+    expect(drawn[2]!.style.height).toBe('100%');
+    expect(drawn[0]!.style.height).toBe('0%');
+  });
+
+  it('rgb composite expands to three primary channels', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(
+        HistogramRoot,
+        { data: { r: [1, 2], g: [3, 4], b: [5, 6] }, channel: 'rgb' },
+        { default: () => h(HistogramBars) },
+      ),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    expect(document.querySelector('[data-channel="r"]')).toBeTruthy();
+    expect(document.querySelector('[data-channel="g"]')).toBeTruthy();
+    expect(document.querySelector('[data-channel="b"]')).toBeTruthy();
+    expect(document.querySelector('[role="img"]')!.getAttribute('aria-label')).toBe('Histogram, RGB');
+  });
+
+  it('record data renders the requested single channel', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(
+        HistogramRoot,
+        { data: { r: [10, 20], g: [0, 0] }, channel: 'r' },
+        { default: () => h(HistogramBars) },
+      ),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const group = document.querySelector<HTMLElement>('[data-channel="r"]')!;
+    const drawn = group.querySelectorAll<HTMLElement>('[data-bar]');
+    expect(drawn[1]!.style.height).toBe('100%');
+  });
+});
diff --git a/vue/primitives/src/canvas/histogram/context.ts b/vue/primitives/src/canvas/histogram/context.ts
new file mode 100644
index 0000000..88e012a
--- /dev/null
+++ b/vue/primitives/src/canvas/histogram/context.ts
@@ -0,0 +1,35 @@
+import type { ComputedRef, Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { HistogramBarChannel, HistogramChannel, HistogramData, HistogramScaleType } from './utils';
+
+/**
+ * Context shared between `HistogramRoot` and its descendants.
+ *
+ * `bars` returns the normalised heights `[0, 1]` for the requested concrete
+ * channel under the active scale (with the all-zero / empty guard applied), so
+ * `HistogramBars` never re-implements the projection or touches the peak.
+ */
+export interface HistogramContext {
+  /** Raw per-channel bin data, as supplied to the root. */
+  data: Ref<HistogramData>;
+  /** The root's primary channel (`'l'`/`'r'`/`'g'`/`'b'`/`'rgb'`). */
+  channel: Ref<HistogramChannel>;
+  /** Bar-height mapping (`'linear'` or `'log'`). */
+  scaleType: Ref<HistogramScaleType>;
+  /** Requested bin count (bars are clamped/derived from the supplied data length). */
+  bins: Ref<number>;
+  /** Whether the histogram is non-interactive / dimmed. */
+  disabled: Ref<boolean>;
+  /** Whether the resolved primary channel has any non-zero data. */
+  hasData: ComputedRef<boolean>;
+  /**
+   * Normalised heights `[0, 1]` for `channel`. Empty/all-zero input yields
+   * all-zero heights — never `NaN`. Stable function identity.
+   */
+  bars: (channel: HistogramBarChannel) => number[];
+}
+
+export const {
+  inject: useHistogramContext,
+  provide: provideHistogramContext,
+} = useContextFactory<HistogramContext>('histogram');
diff --git a/vue/primitives/src/canvas/histogram/demo.vue b/vue/primitives/src/canvas/histogram/demo.vue
new file mode 100644
index 0000000..f992cc9
--- /dev/null
+++ b/vue/primitives/src/canvas/histogram/demo.vue
@@ -0,0 +1,130 @@
+<script setup lang="ts">
+import type { HistogramChannel, HistogramScaleType } from '@robonen/primitives';
+import { HISTOGRAM_CHANNEL_COLORS, HistogramBars, HistogramRoot } from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+const BINS = 64;
+
+/** A bell-ish bump centred on `center` (in bins) with the given spread + peak. */
+function bell(center: number, spread: number, peak: number): number[] {
+  return Array.from({ length: BINS }, (_, i) => {
+    const d = (i - center) / spread;
+    return Math.round(peak * Math.exp(-0.5 * d * d));
+  });
+}
+
+/** Sum two distributions bin-by-bin (a midtone hump + a brighter highlight bump). */
+function add(a: number[], b: number[]): number[] {
+  return a.map((v, i) => v + (b[i] ?? 0));
+}
+
+// Synthetic per-channel data: each primary peaks at a slightly different tone,
+// plus a shared luminance curve. Tall central spike to show off the log view.
+const data = {
+  l: add(bell(28, 9, 1000), bell(50, 5, 280)),
+  r: add(bell(34, 10, 760), bell(52, 6, 220)),
+  g: add(bell(26, 8, 940), bell(46, 5, 180)),
+  b: add(bell(20, 11, 620), bell(44, 7, 120)),
+};
+
+const channel = ref<HistogramChannel>('l');
+const scaleType = ref<HistogramScaleType>('linear');
+
+const channelOptions: Array<{ value: HistogramChannel; label: string }> = [
+  { value: 'l', label: 'Luminance' },
+  { value: 'rgb', label: 'RGB' },
+  { value: 'r', label: 'Red' },
+  { value: 'g', label: 'Green' },
+  { value: 'b', label: 'Blue' },
+];
+
+const scaleOptions: HistogramScaleType[] = ['linear', 'log'];
+
+const channelLabel = computed(
+  () => channelOptions.find(o => o.value === channel.value)?.label ?? '',
+);
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-md space-y-5 p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <span class="font-medium">{{ channelLabel }} histogram</span>
+      <span class="font-mono text-fg-muted">{{ scaleType }}</span>
+    </div>
+
+    <!-- The histogram. Root normalises each channel against its own peak. -->
+    <HistogramRoot
+      :data="data"
+      :channel="channel"
+      :scale-type="scaleType"
+      :bins="BINS"
+      class="rounded-card border border-border bg-bg-inset p-3 shadow-(--shadow-card)"
+    >
+      <!-- Bars: overlay each requested channel as a row of positioned spans -->
+      <HistogramBars class="relative grid h-32 w-full">
+        <template #default="{ channel: ch, color, heights }">
+          <div
+            class="pointer-events-none absolute inset-0 flex items-end gap-px"
+            :style="{ color }"
+            :data-channel="ch"
+          >
+            <span
+              v-for="(h, i) in heights"
+              :key="i"
+              class="min-w-0 flex-1 rounded-t-sm"
+              :style="{
+                height: `${h * 100}%`,
+                background: 'currentColor',
+                opacity: channel === 'rgb' ? 0.55 : 0.9,
+                mixBlendMode: channel === 'rgb' ? 'screen' : 'normal',
+              }"
+            />
+          </div>
+        </template>
+      </HistogramBars>
+
+      <!-- Tonal axis: shadows → highlights -->
+      <div class="mt-2 h-1.5 w-full rounded-full" style="background: linear-gradient(to right, #000, #fff)" />
+    </HistogramRoot>
+
+    <!-- Channel toggle -->
+    <div class="flex flex-wrap gap-1.5">
+      <button
+        v-for="opt in channelOptions"
+        :key="opt.value"
+        type="button"
+        class="flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium outline-none transition focus-visible:ring-2 focus-visible:ring-ring"
+        :class="channel === opt.value
+          ? 'border-transparent bg-accent text-accent-text'
+          : 'border-border bg-bg text-fg-muted hover:bg-bg-elevated'"
+        @click="channel = opt.value"
+      >
+        <span
+          v-if="opt.value !== 'rgb' && opt.value !== 'l'"
+          class="size-2 rounded-full"
+          :style="{ backgroundColor: HISTOGRAM_CHANNEL_COLORS[opt.value] }"
+        />
+        {{ opt.label }}
+      </button>
+    </div>
+
+    <!-- Linear / log toggle -->
+    <div class="flex items-center gap-2 text-sm">
+      <span class="text-fg-muted">Scale</span>
+      <div class="inline-flex rounded-card border border-border bg-bg p-0.5">
+        <button
+          v-for="opt in scaleOptions"
+          :key="opt"
+          type="button"
+          class="rounded-[6px] px-3 py-1 text-xs font-medium capitalize outline-none transition focus-visible:ring-2 focus-visible:ring-ring"
+          :class="scaleType === opt
+            ? 'bg-accent text-accent-text'
+            : 'text-fg-muted hover:text-fg'"
+          @click="scaleType = opt"
+        >
+          {{ opt }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/histogram/index.ts b/vue/primitives/src/canvas/histogram/index.ts
new file mode 100644
index 0000000..0c4434c
--- /dev/null
+++ b/vue/primitives/src/canvas/histogram/index.ts
@@ -0,0 +1,23 @@
+export { default as HistogramRoot } from './HistogramRoot.vue';
+export { default as HistogramBars } from './HistogramBars.vue';
+export type { HistogramRootProps } from './HistogramRoot.vue';
+export type { HistogramBarsProps } from './HistogramBars.vue';
+export {
+  provideHistogramContext,
+  useHistogramContext,
+  type HistogramContext,
+} from './context';
+export {
+  HISTOGRAM_CHANNEL_COLORS,
+  getChannelBins,
+  histogramMax,
+  isSingleChannelData,
+  projectBarHeight,
+  projectBars,
+} from './utils';
+export type {
+  HistogramBarChannel,
+  HistogramChannel,
+  HistogramData,
+  HistogramScaleType,
+} from './utils';
diff --git a/vue/primitives/src/canvas/histogram/utils.ts b/vue/primitives/src/canvas/histogram/utils.ts
new file mode 100644
index 0000000..26fc9dc
--- /dev/null
+++ b/vue/primitives/src/canvas/histogram/utils.ts
@@ -0,0 +1,111 @@
+/**
+ * The channels a histogram can describe. `'l'` is luminance (a single combined
+ * channel), `'r'`/`'g'`/`'b'` are the colour primaries, and `'rgb'` is the
+ * composite request that asks the display to render all three primaries
+ * overlaid.
+ */
+export type HistogramChannel = 'l' | 'r' | 'g' | 'b' | 'rgb';
+
+/** A single concrete channel whose bins can be drawn (excludes the `'rgb'` composite). */
+export type HistogramBarChannel = 'l' | 'r' | 'g' | 'b';
+
+/** How bin counts are mapped to bar heights. */
+export type HistogramScaleType = 'linear' | 'log';
+
+/**
+ * Per-channel bin counts. Either a single `number[]` (interpreted as the channel
+ * named by the root's `channel` prop) or an object carrying any subset of the
+ * four concrete channels.
+ */
+export type HistogramData = number[] | Partial<Record<HistogramBarChannel, number[]>>;
+
+/**
+ * Default CSS colour stamped on `--histogram-color` for each channel so a
+ * consumer can style bars purely from the data-attribute without re-deriving the
+ * colour. These are plain hints; the consumer owns the final paint.
+ */
+export const HISTOGRAM_CHANNEL_COLORS: Record<HistogramBarChannel, string> = {
+  l: '#888888',
+  r: '#ff3b30',
+  g: '#34c759',
+  b: '#0a84ff',
+};
+
+/** Whether `data` is the single-array form (vs. the per-channel record). */
+export function isSingleChannelData(data: HistogramData): data is number[] {
+  return Array.isArray(data);
+}
+
+/**
+ * Resolve the bin array for `channel` out of `data`. The single-array form maps
+ * onto `fallbackChannel` (the root's `channel`); the record form is keyed
+ * directly. Returns an empty array when the channel is absent — callers must
+ * tolerate a zero-length result (an empty histogram is a valid state).
+ */
+export function getChannelBins(
+  data: HistogramData,
+  channel: HistogramBarChannel,
+  fallbackChannel: HistogramBarChannel,
+): number[] {
+  if (isSingleChannelData(data)) {
+    return channel === fallbackChannel ? data : [];
+  }
+  return data[channel] ?? [];
+}
+
+/**
+ * The peak bin count across `bins`. `0` for an empty or all-zero array — the
+ * caller uses this as the normalisation divisor and MUST guard against `0` so a
+ * flat/empty histogram projects to zero height rather than `NaN`.
+ *
+ * Single pass, allocation-free.
+ */
+export function histogramMax(bins: number[]): number {
+  let max = 0;
+  for (let i = 0; i < bins.length; i++) {
+    const v = bins[i]!;
+    if (v > max) max = v;
+  }
+  return max;
+}
+
+/**
+ * Project a raw bin `count` to a normalised bar height in `[0, 1]` against the
+ * histogram peak `max`, under the chosen `scaleType`.
+ *
+ * The all-zero guard is load-bearing: when `max <= 0` every bar is `0` (no
+ * divide-by-zero, no `NaN`). `log` uses `log1p` so an empty bin maps to `0` and
+ * the peak maps to `1`, compressing tall spikes the way an image histogram's
+ * log view does.
+ */
+export function projectBarHeight(count: number, max: number, scaleType: HistogramScaleType): number {
+  if (max <= 0) return 0;
+  if (count <= 0) return 0;
+  if (scaleType === 'log') {
+    // log1p(count)/log1p(max): 0→0, max→1, monotonic in between.
+    return Math.log1p(count) / Math.log1p(max);
+  }
+  const h = count / max;
+  return h > 1 ? 1 : h;
+}
+
+/**
+ * Map a channel's bins to normalised heights `[0, 1]` for rendering. Returns a
+ * fresh packed array; an empty/all-zero input yields all-zero heights (no
+ * `NaN`). The peak may be supplied (e.g. a shared peak across channels) or
+ * derived from `bins`.
+ */
+export function projectBars(
+  bins: number[],
+  scaleType: HistogramScaleType,
+  max = histogramMax(bins),
+): number[] {
+  // Grow from empty with `push` so the array stays in V8's packed numeric
+  // elements-kind. Pre-sizing via `Array.from({ length })` would seed it with
+  // `undefined` (a tagged hole), defeating the PACKED_DOUBLE fast path.
+  const out: number[] = [];
+  for (let i = 0; i < bins.length; i++) {
+    out.push(projectBarHeight(bins[i]!, max, scaleType));
+  }
+  return out;
+}
diff --git a/vue/primitives/src/canvas/keyframe-track/KeyframeTrackEasingEditor.vue b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackEasingEditor.vue
new file mode 100644
index 0000000..6410cb6
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackEasingEditor.vue
@@ -0,0 +1,97 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Embeds a `CurveEditorRoot` (in `'bezier'` interpolation) bound to the SELECTED
+ * keyframe's segment easing. The curve's two anchors are pinned at `(0, 0)` and
+ * `(1, 1)` (CSS `cubic-bezier` semantics); the start anchor's `outHandle` and the
+ * end anchor's `inHandle` map to the easing tuple `[x1, y1, x2, y2]`.
+ *
+ * The binding is one-way IN (the editor is seeded from the keyframe's easing via
+ * the CurveEditor `defaultValue`) and one-way OUT (every anchor commit reads the
+ * handles back and calls `ctx.setEasing`). The CurveEditor is remounted (keyed on
+ * the selected id) whenever the selection changes so its seed always reflects the
+ * newly selected keyframe.
+ *
+ * Renders nothing unless a keyframe with a FOLLOWING segment is selected (the
+ * last keyframe has no outgoing segment to ease).
+ */
+export interface KeyframeTrackEasingEditorProps extends PrimitiveProps {
+  /** Sample count for the rendered easing polyline. @default 256 */
+  samples?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { CurveEditorRoot } from '../curve-editor';
+import type { CurveEditorAnchor } from '../curve-editor';
+import { DEFAULT_KEYFRAME_EASING, useKeyframeTrackContext } from './context';
+
+const { samples = 256, as = 'div' } = defineProps<KeyframeTrackEasingEditorProps>();
+const ctx = useKeyframeTrackContext();
+
+const { forwardRef } = useForwardExpose();
+
+// The selected keyframe must exist AND have a following segment to ease.
+const selected = computed(() => {
+  const id = ctx.selectedId.value;
+  if (id === null) return null;
+  const list = ctx.keyframes.value;
+  const i = list.findIndex(k => k.id === id);
+  if (i === -1 || i >= list.length - 1) return null;
+  return list[i]!;
+});
+
+// Seed anchors for the embedded CurveEditor from the segment's easing tuple.
+// Anchors are pinned at (0,0)/(1,1); the handles are the bezier control points
+// relative to their anchor (CSS cubic-bezier control points).
+const seedAnchors = computed<CurveEditorAnchor[]>(() => {
+  const kf = selected.value;
+  const e = kf?.easing ?? DEFAULT_KEYFRAME_EASING;
+  const [x1, y1, x2, y2] = e;
+  return [
+    { id: 'kf-easing-start', x: 0, y: 0, outHandle: { x: x1, y: y1 } },
+    { id: 'kf-easing-end', x: 1, y: 1, inHandle: { x: x2 - 1, y: y2 - 1 } },
+  ];
+});
+
+// Read the handles back off the committed anchors and write the easing tuple.
+function onAnchorsCommit(anchors: CurveEditorAnchor[]): void {
+  const kf = selected.value;
+  if (!kf || anchors.length < 2) return;
+  const startA = anchors[0]!;
+  const endA = anchors[anchors.length - 1]!;
+  const x1 = startA.outHandle ? startA.x + startA.outHandle.x : 0;
+  const y1 = startA.outHandle ? startA.y + startA.outHandle.y : 0;
+  const x2 = endA.inHandle ? endA.x + endA.inHandle.x : 1;
+  const y2 = endA.inHandle ? endA.y + endA.inHandle.y : 1;
+  ctx.setEasing(kf.id, [x1, y1, x2, y2]);
+}
+</script>
+
+<template>
+  <Primitive
+    v-if="selected"
+    :ref="forwardRef"
+    :as="as"
+    data-easing-editor
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+  >
+    <CurveEditorRoot
+      :key="selected.id"
+      interpolation="bezier"
+      :default-value="seedAnchors"
+      :samples="samples"
+      :disabled="ctx.disabled.value"
+      :dir="ctx.direction.value"
+      @anchors-commit="onAnchorsCommit"
+    >
+      <template #default="curveProps">
+        <slot v-bind="curveProps" :keyframe="selected" />
+      </template>
+    </CurveEditorRoot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/keyframe-track/KeyframeTrackKeyframe.vue b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackKeyframe.vue
new file mode 100644
index 0000000..a6cf1a2
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackKeyframe.vue
@@ -0,0 +1,211 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A single draggable keyframe on the track, rendered as `role="slider"`. It
+ * positions itself by its `time` (horizontal projection) and — in `valueAxis`
+ * mode — its `value` (vertical projection), and handles pointer drags plus
+ * keyboard editing.
+ *
+ * The single `aria-valuenow` carries the keyframe TIME in seconds (or its value
+ * in `valueAxis` mode); `aria-valuetext` announces the formatted time, the
+ * property name, and the value. Keyframes share one tab-stop (roving focus): Tab
+ * moves between them, the selected keyframe is the active stop. Left/Right nudge
+ * the time by `step` (Shift = `largeStep`, dir-aware, neighbour-clamped);
+ * Up/Down nudge the `value` by `valueStep` in `valueAxis` mode (else roving
+ * focus); Home/End jump the time to min/max; Delete removes the keyframe.
+ */
+export interface KeyframeTrackKeyframeProps extends PrimitiveProps {
+  /** The id of the keyframe this slider renders. */
+  keyframeId: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useKeyframeTrackContext } from './context';
+import { defaultKeyframeValueText } from './utils';
+
+const { keyframeId, as = 'div' } = defineProps<KeyframeTrackKeyframeProps>();
+const ctx = useKeyframeTrackContext();
+
+// O(1) lookup via the root's memoized id → index map instead of scanning the
+// keyframe array twice (find + findIndex) per part on every drag frame.
+const index = computed(() => ctx.indexById.value.get(keyframeId) ?? -1);
+const keyframe = computed(() => ctx.keyframes.value[index.value]);
+
+const isSelected = computed(() => ctx.selectedId.value === keyframeId);
+const isDragging = computed(() => ctx.draggingId.value === keyframeId);
+
+// Roving focus: only the selected keyframe (or the first, when none selected) is
+// in the tab order.
+const isTabStop = computed(() => {
+  if (ctx.disabled.value) return false;
+  if (ctx.selectedId.value === null) return index.value === 0;
+  return isSelected.value;
+});
+const tabindex = computed(() => {
+  if (ctx.disabled.value) return -1;
+  return isTabStop.value ? 0 : -1;
+});
+
+// ── position ───────────────────────────────────────────────────────────────
+const pxX = computed(() => (keyframe.value ? ctx.projection(keyframe.value.time) : 0));
+const pxY = computed(() => (keyframe.value ? ctx.projectValue(keyframe.value.value) : 0));
+
+const positionStyle = computed<{ left: string; top: string | undefined }>(() => ({
+  left: `${pxX.value}px`,
+  top: ctx.valueAxis.value ? `${pxY.value}px` : undefined,
+}));
+
+// ── ARIA ─────────────────────────────────────────────────────────────────────
+const ariaValueMin = computed(() => {
+  if (ctx.valueAxis.value) return Math.min(ctx.valueRange.value[0], ctx.valueRange.value[1]);
+  return 0;
+});
+const ariaValueMax = computed(() => {
+  if (ctx.valueAxis.value) return Math.max(ctx.valueRange.value[0], ctx.valueRange.value[1]);
+  return ctx.duration.value;
+});
+const ariaValueNow = computed(() => {
+  if (!keyframe.value) return 0;
+  return ctx.valueAxis.value ? keyframe.value.value : keyframe.value.time;
+});
+const ariaValueText = computed(() => {
+  if (!keyframe.value) return undefined;
+  const time = ctx.formatTime(keyframe.value.time);
+  const valueText = defaultKeyframeValueText(keyframe.value.value, ctx.property.value);
+  return `${time}, ${valueText}`;
+});
+
+// ── roving registration ───────────────────────────────────────────────────────
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (node) => {
+  ctx.registerKeyframeEl(keyframeId, node ?? null);
+});
+onBeforeUnmount(() => ctx.registerKeyframeEl(keyframeId, null));
+
+// ── pointer drag ──────────────────────────────────────────────────────────────
+// x → time, y → value (valueAxis). Capture the keyframe's pixel origin at drag
+// start so cumulative client-px totals (which equal lane px 1:1) project back
+// through the projections without needing the lane rect.
+let dragOriginX = 0;
+let dragOriginY = 0;
+usePointerDrag(currentElement, {
+  axis: 'both',
+  threshold: 0,
+  disabled: () => ctx.disabled.value,
+  onStart: () => {
+    ctx.select(keyframeId);
+    dragOriginX = pxX.value;
+    dragOriginY = pxY.value;
+  },
+  onMove: (state) => {
+    if (!keyframe.value) return;
+    const rawTime = ctx.invert(dragOriginX + state.total.x);
+    const time = ctx.snapTime(rawTime, keyframeId);
+    const value = ctx.valueAxis.value ? ctx.invertValue(dragOriginY + state.total.y) : undefined;
+    ctx.moveKeyframe(keyframeId, time, value, true);
+  },
+  onEnd: () => {
+    ctx.commit();
+  },
+});
+
+// ── click / keyboard ──────────────────────────────────────────────────────────
+function onPointerDownSelect(): void {
+  if (ctx.disabled.value) return;
+  ctx.select(keyframeId);
+}
+
+function nudgeTime(deltaSeconds: number): void {
+  if (!keyframe.value) return;
+  ctx.moveKeyframe(keyframeId, keyframe.value.time + deltaSeconds, undefined, false);
+}
+
+function nudgeValue(deltaValue: number): void {
+  if (!keyframe.value) return;
+  ctx.moveKeyframe(keyframeId, keyframe.value.time, keyframe.value.value + deltaValue, false);
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value || !keyframe.value) return;
+  const rtl = ctx.direction.value === 'rtl';
+  const unit = event.shiftKey ? ctx.largeStep.value : ctx.step.value;
+
+  switch (event.key) {
+    case 'ArrowRight':
+      event.preventDefault();
+      nudgeTime(rtl ? -unit : unit);
+      return;
+    case 'ArrowLeft':
+      event.preventDefault();
+      nudgeTime(rtl ? unit : -unit);
+      return;
+    case 'ArrowUp':
+      event.preventDefault();
+      if (ctx.valueAxis.value) nudgeValue(ctx.valueStep.value);
+      else ctx.focusAdjacent(keyframeId, 1);
+      return;
+    case 'ArrowDown':
+      event.preventDefault();
+      if (ctx.valueAxis.value) nudgeValue(-ctx.valueStep.value);
+      else ctx.focusAdjacent(keyframeId, -1);
+      return;
+    case 'Home':
+      event.preventDefault();
+      nudgeTime(-Number.MAX_SAFE_INTEGER);
+      return;
+    case 'End':
+      event.preventDefault();
+      nudgeTime(Number.MAX_SAFE_INTEGER);
+      return;
+    case 'Delete':
+    case 'Backspace':
+      event.preventDefault();
+      ctx.removeKeyframe(keyframeId);
+      break;
+    default:
+      break;
+  }
+}
+
+function onFocus(): void {
+  if (!ctx.disabled.value) ctx.select(keyframeId);
+}
+</script>
+
+<template>
+  <Primitive
+    v-if="keyframe"
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="tabindex"
+    :aria-valuemin="ariaValueMin"
+    :aria-valuemax="ariaValueMax"
+    :aria-valuenow="ariaValueNow"
+    :aria-valuetext="ariaValueText"
+    :aria-orientation="ctx.valueAxis.value ? 'vertical' : 'horizontal'"
+    :aria-selected="isSelected || undefined"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-selected="isSelected ? '' : undefined"
+    :data-dragging="isDragging ? '' : undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+    @pointerdown="onPointerDownSelect"
+    @focus="onFocus"
+  >
+    <slot
+      :keyframe="keyframe"
+      :selected="isSelected"
+      :dragging="isDragging"
+      :x="pxX"
+      :y="pxY"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/keyframe-track/KeyframeTrackRoot.vue b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackRoot.vue
new file mode 100644
index 0000000..2bb8f1d
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackRoot.vue
@@ -0,0 +1,520 @@
+<script lang="ts">
+import type { Ref } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Direction } from '../../utilities/config-provider';
+import type { KeyframeTrackContext, KeyframeTrackKeyframeData } from './context';
+
+/**
+ * Root of the headless keyframe track: animation keyframes laid out on a time
+ * axis, each segment carrying an editable cubic-bezier easing. It owns the
+ * keyframe array (two-way via `v-model` or uncontrolled via `defaultValue`),
+ * builds the time↔pixel projection (its own `useScale` when standalone, or the
+ * injected Timeline's scale when nested as a lane), and exposes the live
+ * sampler `sampleAt(time)` plus the easing editor binding.
+ *
+ * Transient drag positions are written to an in-flight overlay and committed on
+ * pointerup (`commit`); an external `v-model` write during a gesture is ignored
+ * (the `isMutating` early-return) so it never clobbers the live drag — mirroring
+ * the Timeline reconcile.
+ *
+ * Provides `KeyframeTrackContext` to every part: the projection, the shared
+ * frame-grid snap engine, the keyframe actions, and the roving-focus registry.
+ * When nested in a Timeline it derives `duration` / `fps` from that context and
+ * renders as a `listitem`; standalone it measures its own lane and renders as a
+ * `group`.
+ */
+export interface KeyframeTrackRootProps extends PrimitiveProps {
+  /** Controlled keyframes (`v-model`). */
+  modelValue?: KeyframeTrackKeyframeData[];
+  /** Uncontrolled initial keyframes (ignored when `v-model` is bound). @default [] */
+  defaultValue?: KeyframeTrackKeyframeData[];
+  /** The animated property name (drives the a11y label / value text). */
+  property?: string;
+  /** Keyframes move vertically to edit `value` (else a single horizontal lane). @default false */
+  valueAxis?: boolean;
+  /** Value domain `[min, max]` (the y-axis extent in `valueAxis` mode). @default [0, 1] */
+  valueRange?: [number, number];
+  /**
+   * Total track duration in seconds. When omitted it is auto-derived from the
+   * keyframes (largest `time`) standalone, or inherited from a Timeline.
+   * @default auto
+   */
+  duration?: number;
+  /** Frame rate (timecode + frame snapping + keyboard nudge). @default 30 */
+  fps?: number;
+  /** Keyboard nudge step in seconds. @default 1/fps */
+  step?: number;
+  /** Large keyboard step in seconds (Shift+Arrow). @default 10/fps */
+  largeStep?: number;
+  /** Value-axis keyboard nudge step (per Arrow Up/Down in `valueAxis` mode). @default 0.01 */
+  valueStep?: number;
+  /** Snap step in seconds (frame grid). @default 1/fps */
+  snapStep?: number;
+  /** Enable magnetic snapping to the frame grid. @default true */
+  snapping?: boolean;
+  /** Allow keyframes to overlap in time (else neighbour-clamped to keep order). @default false */
+  allowOverlap?: boolean;
+  /** Minimum time gap between neighbours (seconds) when `allowOverlap` is false. @default 1/fps */
+  minTimeBetween?: number;
+  /** Snap radius in pixels. @default 8 */
+  snapThresholdPx?: number;
+  /** Selected keyframe id (`v-model:selectedId`). */
+  selectedId?: string | null;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
+  dir?: Direction;
+}
+
+// `update:*` events are declared by their `defineModel`s and must NOT be
+// re-declared here.
+export interface KeyframeTrackRootEmits {
+  /** Emitted when a keyframe drag / keypress settles, with the affected id. */
+  keyframeCommit: [id: string];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, triggerRef, watch } from 'vue';
+import { clamp } from '@robonen/stdlib';
+import { useElementSize, useForwardExpose, useId } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useDirection } from '../../utilities/config-provider';
+import { formatClock, framesToTimecode, secondsToFrames, useScale } from '../../internal/scale';
+import { gridTargets, useSnapping } from '../../internal/snapping';
+import type { SnapTarget } from '../../internal/snapping';
+import { useTimelineContext } from '../timeline/context';
+import type { TimelineContext } from '../timeline/context';
+import { provideKeyframeTrackContext } from './context';
+import { clampKeyframeTime, sampleKeyframes, sortKeyframes } from './utils';
+
+const {
+  modelValue,
+  defaultValue,
+  property,
+  valueAxis = false,
+  valueRange = [0, 1] as [number, number],
+  duration: durationProp,
+  fps: fpsProp = 30,
+  step: stepProp,
+  largeStep: largeStepProp,
+  valueStep = 0.01,
+  snapStep: snapStepProp,
+  snapping = true,
+  allowOverlap = false,
+  minTimeBetween: minTimeBetweenProp,
+  snapThresholdPx = 8,
+  selectedId: selectedIdProp,
+  disabled = false,
+  dir,
+  as = 'div',
+} = defineProps<KeyframeTrackRootProps>();
+
+const emit = defineEmits<KeyframeTrackRootEmits>();
+
+const trackId = useId(undefined, 'keyframe-track').value;
+const localDirection = useDirection(() => dir);
+
+// Optionally nest inside a Timeline: when present, derive duration / fps from it.
+// The factory's inject returns the `null` fallback when no Timeline is provided
+// (never undefined), so it does not throw; cast keeps the optional null type.
+const timeline = useTimelineContext(null as unknown as TimelineContext) as TimelineContext | null;
+const inTimeline = timeline !== null;
+
+// ── models (controlled + uncontrolled) ──────────────────────────────────────
+const localKeyframes = shallowRef<KeyframeTrackKeyframeData[]>(
+  sortKeyframes(modelValue ?? defaultValue ?? []),
+);
+const model = defineModel<KeyframeTrackKeyframeData[]>('modelValue', {
+  get: external => external ?? localKeyframes.value,
+  set: (value) => {
+    localKeyframes.value = sortKeyframes(value);
+    return value;
+  },
+});
+
+const selectedModel = defineModel<string | null>('selectedId', {
+  default: undefined as unknown as string | null,
+});
+if (selectedModel.value === undefined) selectedModel.value = selectedIdProp ?? null;
+
+// ── transient overlay (in-flight drag) ───────────────────────────────────────
+const isMutating = shallowRef(false);
+const draggingId = shallowRef<string | null>(null);
+// The live working copy: an immutable, sorted array. During a drag this holds
+// the transient positions; on commit it is written back to the model.
+const working = shallowRef<KeyframeTrackKeyframeData[]>(sortKeyframes(model.value ?? []));
+
+function reconcile(): void {
+  // During an active gesture the model array is stale on purpose; don't clobber
+  // the live overlay until the gesture commits.
+  if (isMutating.value) return;
+  working.value = sortKeyframes(model.value ?? []);
+}
+// `deep: 1` (not full `deep: true`): the component's own writes always replace
+// the array AND every element by reference (`candidate.map(k => ({ ...k }))`),
+// and external `v-model` writes replace the whole array, so depth-1 (array ref +
+// per-index element ref) catches every supported change without the O(n) deep
+// walk into each keyframe's nested `value`/`easing` fields on every reconcile.
+watch(model, reconcile, { immediate: true, deep: 1 });
+
+const keyframes = computed(() => working.value);
+
+// Memoized id → index over the live keyframes, rebuilt once per change. Parts
+// read this for O(1) lookup instead of scanning the array (find/findIndex) per
+// part per frame — keeps the whole-track per-frame cost O(n) rather than O(n²).
+const indexById = computed(() => {
+  const m = new Map<string, number>();
+  const list = working.value;
+  for (let i = 0; i < list.length; i++) m.set(list[i]!.id, i);
+  return m;
+});
+
+// ── reactive prop refs ───────────────────────────────────────────────────────
+const fps = toRef(() => fpsProp);
+const frameStep = computed(() => (fpsProp > 0 ? 1 / fpsProp : 1));
+const step = computed(() => (stepProp !== undefined && stepProp > 0 ? stepProp : frameStep.value));
+const largeStep = computed(() => (largeStepProp !== undefined && largeStepProp > 0 ? largeStepProp : frameStep.value * 10));
+const snapStep = computed(() => (snapStepProp !== undefined && snapStepProp > 0 ? snapStepProp : frameStep.value));
+const minTimeBetween = computed(() => (minTimeBetweenProp !== undefined ? minTimeBetweenProp : frameStep.value));
+
+// When nested, the Timeline owns direction / fps; standalone uses our own.
+const direction = computed(() => (inTimeline ? timeline!.direction.value : localDirection.value));
+const effectiveFps = computed(() => (inTimeline ? timeline!.fps.value : fpsProp));
+
+// ── duration ─────────────────────────────────────────────────────────────────
+const duration = computed(() => {
+  if (durationProp !== undefined && durationProp > 0) return durationProp;
+  if (inTimeline) return timeline!.duration.value;
+  let max = 0;
+  for (const k of working.value) if (k.time > max) max = k.time;
+  // A non-zero floor so a single keyframe still has a projectable range.
+  return max > 0 ? max : 1;
+});
+
+// ── element measurement (standalone) ─────────────────────────────────────────
+const rootEl = shallowRef<HTMLElement | null>(null);
+const { width: measuredWidth, height: measuredHeight } = useElementSize(rootEl);
+
+const laneWidth = computed(() => {
+  if (inTimeline) return timeline!.viewportWidth.value;
+  return measuredWidth.value;
+});
+const laneHeight = computed(() => measuredHeight.value);
+
+// ── coordinate model ─────────────────────────────────────────────────────────
+const isRtl = computed(() => direction.value === 'rtl');
+
+// Standalone time scale: domain [0, duration] → range [0, laneWidth].
+const localScale = useScale({
+  domain: () => [0, duration.value] as const,
+  range: () => [0, measuredWidth.value] as const,
+  rtl: () => isRtl.value,
+  tickKind: 'none',
+});
+
+function projection(seconds: number): number {
+  if (inTimeline) return timeline!.scale(seconds);
+  if (measuredWidth.value <= 0) return 0;
+  return localScale.scale(seconds);
+}
+
+function invert(px: number): number {
+  if (inTimeline) return timeline!.invert(px);
+  if (measuredWidth.value <= 0) return 0;
+  return localScale.invert(px);
+}
+
+// Value y-axis (value-up): valueRange[0] → bottom (laneHeight), valueRange[1] → top (0).
+const valueScale = useScale({
+  domain: () => valueRange,
+  range: () => [0, laneHeight.value] as const,
+  orientation: 'vertical',
+  clamp: true,
+});
+
+function projectValue(value: number): number {
+  if (laneHeight.value <= 0) return 0;
+  return valueScale.scale(value);
+}
+
+function invertValue(px: number): number {
+  if (laneHeight.value <= 0) return valueRange[0];
+  return valueScale.invert(px);
+}
+
+// ── formatting ─────────────────────────────────────────────────────────────
+function formatTime(seconds: number): string {
+  // Inside a Timeline match its timecode; standalone use a wall-clock string,
+  // unless a sub-second frame resolution is meaningful.
+  if (inTimeline) return timeline!.formatTimecode(seconds);
+  if (effectiveFps.value > 0) return framesToTimecode(secondsToFrames(seconds, effectiveFps.value), effectiveFps.value);
+  return formatClock(seconds);
+}
+
+// ── snap engine (frame grid) ─────────────────────────────────────────────────
+const snapTargets = computed<SnapTarget[]>(() => {
+  if (!snapping || laneWidth.value <= 0) return [];
+  const lo = inTimeline ? timeline!.invert(0) : 0;
+  const hi = inTimeline ? timeline!.invert(laneWidth.value) : duration.value;
+  return gridTargets(Math.min(lo, hi), Math.max(lo, hi), snapStep.value, projection, 'x');
+});
+
+const snapEngine = useSnapping({
+  enabled: () => snapping && !disabled && laneWidth.value > 0,
+  thresholdPx: () => snapThresholdPx,
+  // '1d' uses every target as a single pool with no per-call filter. All
+  // `snapTargets` are produced by `gridTargets(..., 'x')`, so they are already
+  // x-axis only — '1d' is behaviour-equivalent to 'x' here but skips the
+  // `allTargets.filter(t => t.axis === 'x')` allocation on every snap1d() call.
+  axis: '1d',
+  project: (value: number) => projection(value),
+  targets: () => snapTargets.value,
+});
+
+function snapTime(seconds: number, exclude?: string): number {
+  if (!snapping || disabled || laneWidth.value <= 0) return seconds;
+  return snapEngine.snap1d(seconds, exclude !== undefined ? { exclude } : undefined).value;
+}
+
+// ── sampling ─────────────────────────────────────────────────────────────────
+function sampleAt(time: number): number {
+  return sampleKeyframes(working.value, time, valueRange);
+}
+
+/** Sample the value curve into `samples` evenly-spaced points across the duration. */
+function getValueCurve(samples = 64): Array<{ time: number; value: number }> {
+  const out: Array<{ time: number; value: number }> = [];
+  const total = duration.value;
+  if (samples < 2 || total <= 0) return out;
+  for (let i = 0; i < samples; i++) {
+    const time = (i / (samples - 1)) * total;
+    out.push({ time, value: sampleAt(time) });
+  }
+  return out;
+}
+
+// ── selection ─────────────────────────────────────────────────────────────────
+function select(id: string | null): void {
+  if (disabled) return;
+  if (selectedModel.value === id) return;
+  selectedModel.value = id;
+}
+
+// External selection writes are honoured (not blocked by mutation).
+watch(() => selectedIdProp, (id) => {
+  if (id !== undefined && id !== selectedModel.value) selectedModel.value = id;
+});
+
+// ── mutation ────────────────────────────────────────────────────────────────
+const dirtyIds = new Set<string>();
+
+/** Write the working overlay (sorted, immutable) and flag the touched id dirty. */
+function setKeyframes(next: KeyframeTrackKeyframeData[], dirtyId?: string): void {
+  working.value = sortKeyframes(next);
+  if (dirtyId !== undefined) dirtyIds.add(dirtyId);
+  triggerRef(working);
+}
+
+function indexOf(id: string): number {
+  const list = working.value;
+  for (let i = 0; i < list.length; i++) if (list[i]!.id === id) return i;
+  return -1;
+}
+
+function addKeyframe(time: number, value?: number): string | undefined {
+  if (disabled) return undefined;
+  const t = clamp(time, 0, duration.value || Number.MAX_SAFE_INTEGER);
+  const v = value ?? sampleAt(t);
+  const id = `${trackId}-kf-${idCounter++}`;
+  const next: KeyframeTrackKeyframeData = { id, time: t, value: v };
+  const candidate = sortKeyframes([...working.value, next]);
+  working.value = candidate;
+  // A keyframe add is a single committed mutation.
+  model.value = candidate.map(k => ({ ...k }));
+  emit('keyframeCommit', id);
+  return id;
+}
+
+function removeKeyframe(id: string): void {
+  if (disabled) return;
+  const candidate = working.value.filter(k => k.id !== id);
+  if (candidate.length === working.value.length) return;
+  working.value = candidate;
+  model.value = candidate.map(k => ({ ...k }));
+  if (selectedModel.value === id) selectedModel.value = null;
+  emit('keyframeCommit', id);
+}
+
+function moveKeyframe(id: string, time: number, value?: number, mutating = false): void {
+  if (disabled) return;
+  const index = indexOf(id);
+  if (index === -1) return;
+  const current = working.value[index]!;
+  isMutating.value = mutating;
+  draggingId.value = mutating ? id : draggingId.value;
+
+  const t = clampKeyframeTime(working.value, index, time, {
+    allowOverlap,
+    minTimeBetween: minTimeBetween.value,
+    duration: duration.value,
+  });
+  let v = current.value;
+  if (value !== undefined) v = clamp(value, Math.min(valueRange[0], valueRange[1]), Math.max(valueRange[0], valueRange[1]));
+
+  // Unchanged frame: the drag state was already set above; nothing to write.
+  if (t === current.time && v === current.value) return;
+
+  const candidate = working.value.slice();
+  candidate[index] = { ...current, time: t, value: v };
+  setKeyframes(candidate, id);
+
+  // A non-mutating move is an immediate commit (keyboard nudge).
+  if (!mutating) commit();
+}
+
+function setEasing(id: string, bezier: [number, number, number, number]): void {
+  if (disabled) return;
+  const index = indexOf(id);
+  if (index === -1) return;
+  const current = working.value[index]!;
+  const candidate = working.value.slice();
+  candidate[index] = { ...current, easing: bezier };
+  working.value = candidate;
+  triggerRef(working);
+  model.value = candidate.map(k => ({ ...k }));
+  emit('keyframeCommit', id);
+}
+
+function commit(): void {
+  const wasMutating = isMutating.value;
+  isMutating.value = false;
+  draggingId.value = null;
+  if (dirtyIds.size === 0 && !wasMutating) return;
+  const ids = [...dirtyIds];
+  dirtyIds.clear();
+  if (ids.length === 0) return;
+  // Write the model immutably from the working overlay.
+  model.value = working.value.map(k => ({ ...k }));
+  for (const id of ids) emit('keyframeCommit', id);
+}
+
+let idCounter = working.value.length;
+
+// ── roving focus ─────────────────────────────────────────────────────────────
+const keyframeEls = new Map<string, HTMLElement>();
+function registerKeyframeEl(id: string, el: HTMLElement | null): void {
+  if (el) keyframeEls.set(id, el);
+  else keyframeEls.delete(id);
+}
+
+function focusKeyframe(id: string): void {
+  keyframeEls.get(id)?.focus();
+}
+
+function focusAdjacent(fromId: string, dirSign: 1 | -1): void {
+  const order = working.value;
+  const idx = order.findIndex(k => k.id === fromId);
+  if (idx === -1) return;
+  const nextIdx = idx + dirSign;
+  if (nextIdx < 0 || nextIdx >= order.length) return;
+  focusKeyframe(order[nextIdx]!.id);
+}
+
+// ── a11y ──────────────────────────────────────────────────────────────────────
+const ariaLabel = computed(() => (property ? `${property} keyframes` : undefined));
+
+// ── provide ────────────────────────────────────────────────────────────────────
+const context: KeyframeTrackContext = {
+  trackId,
+  keyframes,
+  indexById,
+  selectedId: selectedModel as Ref<string | null>,
+  property: toRef(() => property),
+  valueAxis: toRef(() => valueAxis),
+  valueRange: toRef(() => valueRange),
+  duration,
+  fps,
+  step,
+  largeStep,
+  valueStep: toRef(() => valueStep),
+  allowOverlap: toRef(() => allowOverlap),
+  minTimeBetween,
+  snapping: toRef(() => snapping),
+  disabled: toRef(() => disabled),
+  direction,
+  laneWidth,
+  laneHeight,
+  projection,
+  invert,
+  projectValue,
+  invertValue,
+  formatTime,
+  snapTime,
+  snapEngine,
+  isMutating,
+  draggingId,
+  inTimeline,
+  sampleAt,
+  select,
+  addKeyframe,
+  removeKeyframe,
+  moveKeyframe,
+  setEasing,
+  commit,
+  registerKeyframeEl,
+  focusAdjacent,
+  focusKeyframe,
+};
+provideKeyframeTrackContext(context);
+
+defineExpose({
+  sampleAt,
+  getValueCurve,
+  addKeyframe,
+  removeKeyframe,
+  moveKeyframe,
+  setEasing,
+  select,
+  keyframes,
+  projection,
+  invert,
+});
+
+// `useForwardExpose` runs AFTER `defineExpose` so it merges the prior bindings
+// (plus props + `$el`) instead of clobbering them.
+const { forwardRef } = useForwardExpose();
+
+function setRootRef(el: unknown): void {
+  forwardRef(el as never);
+  rootEl.value = (el && typeof el === 'object' && '$el' in el ? (el as { $el: HTMLElement }).$el : el) as HTMLElement | null;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRootRef"
+    :as="as"
+    :role="inTimeline ? 'listitem' : 'group'"
+    aria-roledescription="keyframe track"
+    :aria-label="ariaLabel"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-value-axis="valueAxis ? '' : undefined"
+    :data-in-timeline="inTimeline ? '' : undefined"
+    :data-mutating="isMutating ? '' : undefined"
+    data-orientation="horizontal"
+    :dir="direction"
+  >
+    <slot
+      :keyframes="keyframes"
+      :selected-id="selectedModel"
+      :duration="duration"
+      :projection="projection"
+      :sample-at="sampleAt"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/keyframe-track/KeyframeTrackSegment.vue b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackSegment.vue
new file mode 100644
index 0000000..eab9a9f
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/KeyframeTrackSegment.vue
@@ -0,0 +1,123 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The interval between two adjacent keyframes — the visual + interactive
+ * representation of a segment's easing. It spans from the keyframe identified by
+ * `keyframeId` to the next keyframe in time order, and clicking it selects the
+ * starting keyframe (so the easing editor can edit this segment's curve).
+ *
+ * It is `role="presentation"` by default (decorative); the keyframes themselves
+ * are the focusable controls. When `samples` is set it also renders an SVG
+ * `<path>` of the eased value curve across the segment (sampled via the shared
+ * spline), so consumers get a ready-to-style preview of the easing.
+ */
+export interface KeyframeTrackSegmentProps extends PrimitiveProps {
+  /** The id of the keyframe that STARTS this segment. */
+  keyframeId: string;
+  /**
+   * When set, render an SVG path of the eased value curve sampled this many
+   * times across the segment (exposed as the `path` slot prop). @default 0
+   */
+  samples?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useKeyframeTrackContext } from './context';
+
+const { keyframeId, samples = 0, as = 'div' } = defineProps<KeyframeTrackSegmentProps>();
+const ctx = useKeyframeTrackContext();
+
+// O(1) lookup via the root's memoized id → index map instead of an O(n)
+// findIndex scan per segment on every drag frame.
+const startIndex = computed(() => ctx.indexById.value.get(keyframeId) ?? -1);
+const start = computed(() => ctx.keyframes.value[startIndex.value]);
+const end = computed(() => {
+  const i = startIndex.value;
+  return i === -1 ? undefined : ctx.keyframes.value[i + 1];
+});
+
+const isSelected = computed(() => ctx.selectedId.value === keyframeId);
+
+// Pixel span of the segment along the time axis.
+const left = computed(() => (start.value ? ctx.projection(start.value.time) : 0));
+const right = computed(() => (end.value ? ctx.projection(end.value.time) : left.value));
+const width = computed(() => Math.abs(right.value - left.value));
+
+const positionStyle = computed<{ left: string; width: string }>(() => ({
+  left: `${Math.min(left.value, right.value)}px`,
+  width: `${width.value}px`,
+}));
+
+// Optional SVG path of the eased value curve across the segment (lane-relative
+// pixels). Uses the value projection in `valueAxis` mode; otherwise normalizes
+// to the lane height so the easing shape is still previewable.
+const path = computed<string>(() => {
+  const a = start.value;
+  const b = end.value;
+  const n = samples;
+  if (!a || !b || n < 2) return '';
+  const x0 = ctx.projection(a.time);
+  const x1 = ctx.projection(b.time);
+  const h = ctx.laneHeight.value || 1;
+  const valueAxis = ctx.valueAxis.value;
+  // Build each "M/L x,y" command into a packed array and join once, instead of
+  // repeated string concatenation per sample on the drag hot path.
+  const segs: string[] = [];
+  for (let i = 0; i < n; i++) {
+    const t = i / (n - 1);
+    const time = a.time + (b.time - a.time) * t;
+    const x = x0 + (x1 - x0) * t;
+    const value = ctx.sampleAt(time);
+    const y = valueAxis
+      ? ctx.projectValue(value)
+      // Normalize value into the lane height (value-up) when there is no y-axis.
+      : h - normalize(value, a.value, b.value) * h;
+    segs.push(`${i === 0 ? 'M' : 'L'}${round(x)},${round(y)}`);
+  }
+  return segs.join(' ');
+});
+
+function normalize(value: number, a: number, b: number): number {
+  if (a === b) return 0.5;
+  const t = (value - a) / (b - a);
+  return Math.min(Math.max(t, 0), 1);
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+function onSelect(): void {
+  if (ctx.disabled.value) return;
+  ctx.select(keyframeId);
+}
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    v-if="start && end"
+    :ref="forwardRef"
+    :as="as"
+    role="presentation"
+    data-segment
+    :data-selected="isSelected ? '' : undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :style="positionStyle"
+    @pointerdown="onSelect"
+  >
+    <slot
+      :start="start"
+      :end="end"
+      :selected="isSelected"
+      :width="width"
+      :path="path"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/keyframe-track/__test__/KeyframeTrack.test.ts b/vue/primitives/src/canvas/keyframe-track/__test__/KeyframeTrack.test.ts
new file mode 100644
index 0000000..c5ffed0
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/__test__/KeyframeTrack.test.ts
@@ -0,0 +1,261 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  KeyframeTrackEasingEditor,
+  KeyframeTrackKeyframe,
+  KeyframeTrackRoot,
+} from '../index';
+import type { KeyframeTrackKeyframeData } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false }));
+}
+
+interface MountOpts {
+  defaultValue?: KeyframeTrackKeyframeData[];
+  modelValue?: KeyframeTrackKeyframeData[];
+  property?: string;
+  valueAxis?: boolean;
+  valueRange?: [number, number];
+  duration?: number;
+  fps?: number;
+  step?: number;
+  allowOverlap?: boolean;
+  disabled?: boolean;
+  selectedId?: string | null;
+}
+
+function mountTrack(opts: MountOpts = {}, withEasing = false) {
+  const model = ref<KeyframeTrackKeyframeData[] | undefined>(opts.modelValue);
+  const selected = ref<string | null>(opts.selectedId ?? null);
+  const commits: string[] = [];
+  const Harness = defineComponent({
+    setup() {
+      // Cast to `any` for the `h()` call: vue-tsc cannot resolve the `h` overload
+      // for a `defineModel` component passed an inline props object (same pattern
+      // the accordion/checkbox suites use); the runtime props are correct.
+      return () => h(KeyframeTrackRoot as any, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: KeyframeTrackKeyframeData[]) => { model.value = v; },
+        selectedId: selected.value,
+        'onUpdate:selectedId': (v: string | null) => { selected.value = v; },
+        onKeyframeCommit: (id: string) => { commits.push(id); },
+        defaultValue: opts.defaultValue,
+        property: opts.property,
+        valueAxis: opts.valueAxis,
+        valueRange: opts.valueRange,
+        duration: opts.duration,
+        fps: opts.fps,
+        step: opts.step,
+        allowOverlap: opts.allowOverlap,
+        disabled: opts.disabled,
+        style: 'width: 300px; height: 40px; position: relative; display: block;',
+      }, {
+        default: ({ keyframes }: { keyframes: KeyframeTrackKeyframeData[] }) => [
+          ...keyframes.map(k => h(KeyframeTrackKeyframe, { key: k.id, keyframeId: k.id, id: `kf-${k.id}` })),
+          ...(withEasing ? [h(KeyframeTrackEasingEditor)] : []),
+        ],
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model, selected, commits };
+}
+
+const TWO = (): KeyframeTrackKeyframeData[] => [
+  { id: 'a', time: 0, value: 0, easing: [0, 0, 1, 1] },
+  { id: 'b', time: 1, value: 1 },
+];
+
+describe('KeyframeTrack — rendering', () => {
+  it('standalone root is a group with keyframe-track roledescription', async () => {
+    mountTrack({ defaultValue: TWO(), property: 'opacity' });
+    await nextTick();
+    const root = document.querySelector('[aria-roledescription="keyframe track"]')!;
+    expect(root).toBeTruthy();
+    expect(root.getAttribute('role')).toBe('group');
+    expect(root.getAttribute('aria-label')).toBe('opacity keyframes');
+  });
+
+  it('renders each keyframe as role="slider" with seconds aria-valuetext announcing the property + value', async () => {
+    mountTrack({ defaultValue: TWO(), property: 'opacity' });
+    await nextTick();
+    const sliders = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(sliders).toHaveLength(2);
+    // aria-valuenow is the TIME in seconds (default, non-valueAxis).
+    expect(sliders[0]!.getAttribute('aria-valuenow')).toBe('0');
+    expect(sliders[1]!.getAttribute('aria-valuenow')).toBe('1');
+    // aria-valuetext leads with the formatted time then property + value.
+    expect(sliders[0]!.getAttribute('aria-valuetext')).toContain('opacity 0');
+    expect(sliders[1]!.getAttribute('aria-valuetext')).toContain('opacity 1');
+    expect(sliders[0]!.getAttribute('aria-orientation')).toBe('horizontal');
+  });
+});
+
+describe('KeyframeTrack — keyboard', () => {
+  it('ArrowRight nudges the keyframe forward by one frame (neighbour-clamped)', async () => {
+    const { model } = mountTrack({ defaultValue: TWO(), fps: 30 });
+    await nextTick();
+    const first = document.getElementById('kf-a')!;
+    keydown(first, 'ArrowRight');
+    await nextTick();
+    const a = model.value!.find(k => k.id === 'a')!;
+    expect(a.time).toBeCloseTo(1 / 30, 6);
+  });
+
+  it('ArrowRight does not cross the next keyframe unless allowOverlap', async () => {
+    mountTrack({
+      defaultValue: [
+        { id: 'a', time: 0, value: 0 },
+        { id: 'b', time: 5 / 30, value: 1 },
+      ],
+      fps: 30,
+    });
+    await nextTick();
+    const first = document.getElementById('kf-a')!;
+    // Push hard into b; neighbour-clamp keeps a strictly before b by minTimeBetween (1 frame).
+    for (let i = 0; i < 20; i++) keydown(first, 'ArrowRight');
+    await nextTick();
+    // aria-valuenow always reflects the live time (seconds), even when clamped.
+    const aTime = Number(first.getAttribute('aria-valuenow'));
+    const bTime = Number(document.getElementById('kf-b')!.getAttribute('aria-valuenow'));
+    expect(aTime).toBeLessThan(bTime);
+    // Clamped exactly one frame before b.
+    expect(aTime).toBeCloseTo(4 / 30, 6);
+  });
+
+  it('ArrowLeft nudges backward and clamps at 0', async () => {
+    mountTrack({ defaultValue: [{ id: 'a', time: 2 / 30, value: 0 }, { id: 'b', time: 1, value: 1 }], fps: 30 });
+    await nextTick();
+    const first = document.getElementById('kf-a')!;
+    keydown(first, 'ArrowLeft');
+    await nextTick();
+    expect(Number(first.getAttribute('aria-valuenow'))).toBeCloseTo(1 / 30, 6);
+    keydown(first, 'ArrowLeft');
+    keydown(first, 'ArrowLeft');
+    await nextTick();
+    expect(Number(first.getAttribute('aria-valuenow'))).toBe(0);
+  });
+
+  it('ArrowUp/ArrowDown change the value in valueAxis mode', async () => {
+    const { model } = mountTrack({ defaultValue: TWO(), valueAxis: true, valueRange: [0, 1] });
+    await nextTick();
+    const first = document.getElementById('kf-a')!;
+    keydown(first, 'ArrowUp');
+    await nextTick();
+    expect(model.value!.find(k => k.id === 'a')!.value).toBeCloseTo(0.01, 6);
+    keydown(first, 'ArrowDown');
+    keydown(first, 'ArrowDown');
+    await nextTick();
+    expect(model.value!.find(k => k.id === 'a')!.value).toBeCloseTo(0, 6);
+  });
+
+  it('Home/End jump to min / max time (neighbour-clamped)', async () => {
+    const { model } = mountTrack({ defaultValue: TWO(), duration: 1, fps: 30 });
+    await nextTick();
+    const second = document.getElementById('kf-b')!;
+    keydown(second, 'Home');
+    await nextTick();
+    // b is neighbour-clamped one frame after a (time 0).
+    expect(model.value!.find(k => k.id === 'b')!.time).toBeCloseTo(1 / 30, 6);
+    keydown(second, 'End');
+    await nextTick();
+    expect(model.value!.find(k => k.id === 'b')!.time).toBeCloseTo(1, 6);
+  });
+
+  it('Delete removes the keyframe', async () => {
+    const { model } = mountTrack({ defaultValue: TWO() });
+    await nextTick();
+    const first = document.getElementById('kf-a')!;
+    keydown(first, 'Delete');
+    await nextTick();
+    expect(model.value!.map(k => k.id)).toEqual(['b']);
+  });
+
+  it('disabled: keys do nothing and tabindex is -1', async () => {
+    const { model } = mountTrack({ defaultValue: TWO(), disabled: true });
+    await nextTick();
+    const first = document.getElementById('kf-a')!;
+    expect(first.tabIndex).toBe(-1);
+    expect(first.getAttribute('aria-disabled')).toBe('true');
+    keydown(first, 'ArrowRight');
+    keydown(first, 'Delete');
+    await nextTick();
+    // unchanged (model never written, stays the seeded uncontrolled value).
+    expect(model.value).toBeUndefined();
+  });
+});
+
+describe('KeyframeTrack — selection', () => {
+  it('focus selects the keyframe and marks it selected', async () => {
+    const { selected } = mountTrack({ defaultValue: TWO() });
+    await nextTick();
+    const second = document.getElementById('kf-b')!;
+    second.dispatchEvent(new FocusEvent('focus', { bubbles: true }));
+    await nextTick();
+    expect(selected.value).toBe('b');
+    expect(second.getAttribute('aria-selected')).toBe('true');
+  });
+});
+
+describe('KeyframeTrack — sampling expose', () => {
+  it('sampleAt returns the eased value between two keyframes (linear midpoint ≈ average)', async () => {
+    const { wrapper } = mountTrack({ defaultValue: TWO() });
+    await nextTick();
+    const root = wrapper.findComponent(KeyframeTrackRoot);
+    const sampleAt = (root.vm as any).sampleAt as (t: number) => number;
+    expect(sampleAt(0.5)).toBeCloseTo(0.5, 6);
+    expect(sampleAt(-1)).toBe(0);
+    expect(sampleAt(5)).toBe(1);
+  });
+
+  it('addKeyframe / removeKeyframe via the exposed API mutate the model', async () => {
+    const { wrapper, model } = mountTrack({ defaultValue: TWO() });
+    await nextTick();
+    const root = wrapper.findComponent(KeyframeTrackRoot);
+    const id = (root.vm as any).addKeyframe(0.5) as string;
+    await nextTick();
+    expect(model.value!.some(k => k.id === id)).toBe(true);
+    expect(model.value!.find(k => k.id === id)!.value).toBeCloseTo(0.5, 6);
+    (root.vm as any).removeKeyframe(id);
+    await nextTick();
+    expect(model.value!.some(k => k.id === id)).toBe(false);
+  });
+});
+
+describe('KeyframeTrack — easing editor', () => {
+  it('embeds a CurveEditor for the selected keyframe and setEasing updates it', async () => {
+    const { wrapper, model, selected } = mountTrack({ defaultValue: TWO(), selectedId: 'a' }, true);
+    await nextTick();
+    // The selected keyframe (a) has a following segment → the editor renders a CurveEditor.
+    expect(selected.value).toBe('a');
+    expect(document.querySelector('[data-easing-editor]')).toBeTruthy();
+    expect(document.querySelector('[data-interpolation="bezier"]')).toBeTruthy();
+
+    // Drive setEasing directly through the context-backed API.
+    const root = wrapper.findComponent(KeyframeTrackRoot);
+    (root.vm as any).setEasing('a', [0.42, 0, 0.58, 1]);
+    await nextTick();
+    expect(model.value!.find(k => k.id === 'a')!.easing).toEqual([0.42, 0, 0.58, 1]);
+  });
+
+  it('renders no editor when the selected keyframe is the last (no following segment)', async () => {
+    mountTrack({ defaultValue: TWO(), selectedId: 'b' }, true);
+    await nextTick();
+    expect(document.querySelector('[data-interpolation="bezier"]')).toBeNull();
+  });
+});
diff --git a/vue/primitives/src/canvas/keyframe-track/__test__/__screenshots__/KeyframeTrack.test.ts/KeyframeTrack---keyboard-ArrowLeft-nudges-backward-and-clamps-at-0-1.png b/vue/primitives/src/canvas/keyframe-track/__test__/__screenshots__/KeyframeTrack.test.ts/KeyframeTrack---keyboard-ArrowLeft-nudges-backward-and-clamps-at-0-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/keyframe-track/__test__/__screenshots__/KeyframeTrack.test.ts/KeyframeTrack---keyboard-ArrowLeft-nudges-backward-and-clamps-at-0-1.png differ
diff --git a/vue/primitives/src/canvas/keyframe-track/__test__/__screenshots__/KeyframeTrack.test.ts/KeyframeTrack---keyboard-ArrowRight-does-not-cross-the-next-keyframe-unless-allowOverlap-1.png b/vue/primitives/src/canvas/keyframe-track/__test__/__screenshots__/KeyframeTrack.test.ts/KeyframeTrack---keyboard-ArrowRight-does-not-cross-the-next-keyframe-unless-allowOverlap-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/keyframe-track/__test__/__screenshots__/KeyframeTrack.test.ts/KeyframeTrack---keyboard-ArrowRight-does-not-cross-the-next-keyframe-unless-allowOverlap-1.png differ
diff --git a/vue/primitives/src/canvas/keyframe-track/__test__/utils.test.ts b/vue/primitives/src/canvas/keyframe-track/__test__/utils.test.ts
new file mode 100644
index 0000000..af49c1c
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/__test__/utils.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_KEYFRAME_EASING } from '../context';
+import type { KeyframeTrackKeyframeData } from '../context';
+import {
+  clampKeyframeTime,
+  defaultKeyframeValueText,
+  sampleKeyframes,
+  snapTimeToFrame,
+  sortKeyframes,
+} from '../utils';
+
+function kf(id: string, time: number, value: number, easing?: [number, number, number, number]): KeyframeTrackKeyframeData {
+  return easing ? { id, time, value, easing } : { id, time, value };
+}
+
+describe('sortKeyframes', () => {
+  it('sorts ascending by time without mutating the input', () => {
+    const input = [kf('b', 2, 1), kf('a', 0, 0), kf('c', 1, 0.5)];
+    const sorted = sortKeyframes(input);
+    expect(sorted.map(k => k.id)).toEqual(['a', 'c', 'b']);
+    // input untouched
+    expect(input.map(k => k.id)).toEqual(['b', 'a', 'c']);
+  });
+
+  it('breaks ties deterministically on id', () => {
+    const sorted = sortKeyframes([kf('z', 1, 0), kf('a', 1, 1)]);
+    expect(sorted.map(k => k.id)).toEqual(['a', 'z']);
+  });
+});
+
+describe('sampleKeyframes', () => {
+  it('returns the single value for 0 / 1 keyframes', () => {
+    expect(sampleKeyframes([], 5)).toBe(0);
+    expect(sampleKeyframes([kf('a', 2, 0.7)], 100)).toBe(0.7);
+    expect(sampleKeyframes([kf('a', 2, 0.7)], -100)).toBe(0.7);
+  });
+
+  it('holds constant outside the keyframe range', () => {
+    const ks = [kf('a', 1, 0), kf('b', 3, 1)];
+    expect(sampleKeyframes(ks, 0)).toBe(0);
+    expect(sampleKeyframes(ks, 1)).toBe(0);
+    expect(sampleKeyframes(ks, 3)).toBe(1);
+    expect(sampleKeyframes(ks, 10)).toBe(1);
+  });
+
+  it('linear easing midpoint ≈ the average of the two values', () => {
+    // DEFAULT_KEYFRAME_EASING is a linear ramp.
+    const ks = [kf('a', 0, 0, [...DEFAULT_KEYFRAME_EASING] as [number, number, number, number]), kf('b', 2, 1)];
+    expect(sampleKeyframes(ks, 1)).toBeCloseTo(0.5, 6);
+    expect(sampleKeyframes(ks, 0.5)).toBeCloseTo(0.25, 6);
+  });
+
+  it('an ease curve is off-center at the midpoint (vs linear)', () => {
+    // ease-in: cubic-bezier(0.42, 0, 1, 1) starts slow → midpoint below 0.5.
+    const ks = [kf('a', 0, 0, [0.42, 0, 1, 1]), kf('b', 2, 1)];
+    const mid = sampleKeyframes(ks, 1);
+    expect(mid).toBeLessThan(0.5);
+    expect(mid).toBeGreaterThan(0);
+  });
+
+  it('ease-out is above 0.5 at the midpoint', () => {
+    // ease-out: cubic-bezier(0, 0, 0.58, 1) ends slow → midpoint above 0.5.
+    const ks = [kf('a', 0, 0, [0, 0, 0.58, 1]), kf('b', 2, 1)];
+    expect(sampleKeyframes(ks, 1)).toBeGreaterThan(0.5);
+  });
+});
+
+describe('clampKeyframeTime', () => {
+  const ks = [kf('a', 0, 0), kf('b', 1, 0), kf('c', 2, 0)];
+
+  it('clamps to >= 0 and <= duration', () => {
+    expect(clampKeyframeTime(ks, 1, -5, { allowOverlap: true, minTimeBetween: 0 })).toBe(0);
+    expect(clampKeyframeTime(ks, 1, 99, { allowOverlap: true, minTimeBetween: 0, duration: 2 })).toBe(2);
+  });
+
+  it('neighbour-clamps with minTimeBetween when overlap is disallowed', () => {
+    // Moving b (index 1) far right stops minTimeBetween before c (time 2).
+    expect(clampKeyframeTime(ks, 1, 5, { allowOverlap: false, minTimeBetween: 0.25 })).toBe(1.75);
+    // Moving b far left stops minTimeBetween after a (time 0).
+    expect(clampKeyframeTime(ks, 1, -5, { allowOverlap: false, minTimeBetween: 0.25 })).toBe(0.25);
+  });
+
+  it('allows crossing neighbours when overlap is enabled', () => {
+    expect(clampKeyframeTime(ks, 1, 1.9, { allowOverlap: true, minTimeBetween: 0.25 })).toBe(1.9);
+  });
+});
+
+describe('snapTimeToFrame', () => {
+  it('quantizes to whole frames at fps', () => {
+    expect(snapTimeToFrame(0.51, 30)).toBeCloseTo(15 / 30, 6);
+    expect(snapTimeToFrame(0.49, 30)).toBeCloseTo(15 / 30, 6);
+  });
+
+  it('passes through when fps <= 0', () => {
+    expect(snapTimeToFrame(1.234, 0)).toBe(1.234);
+  });
+});
+
+describe('defaultKeyframeValueText', () => {
+  it('includes the property when present', () => {
+    expect(defaultKeyframeValueText(0.5, 'opacity')).toBe('opacity 0.5');
+  });
+
+  it('omits the property when absent', () => {
+    expect(defaultKeyframeValueText(0.5)).toBe('0.5');
+  });
+});
diff --git a/vue/primitives/src/canvas/keyframe-track/context.ts b/vue/primitives/src/canvas/keyframe-track/context.ts
new file mode 100644
index 0000000..44cdfcd
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/context.ts
@@ -0,0 +1,144 @@
+import type { ComputedRef, Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { Direction } from '../../utilities/config-provider';
+import type { UseSnappingReturn } from '../../internal/snapping';
+
+/**
+ * A single keyframe on the track's time axis.
+ *
+ * `time` is in seconds, `value` is the animated value (in `valueRange` space).
+ * `easing` is the cubic-bezier control tuple `[x1, y1, x2, y2]` for the segment
+ * that STARTS at this keyframe and runs to the next one in time order — the
+ * implicit anchors are `(0,0)` and `(1,1)` (CSS `cubic-bezier` semantics). When
+ * `easing` is absent the segment falls back to {@link DEFAULT_KEYFRAME_EASING}.
+ */
+export interface KeyframeTrackKeyframeData {
+  /** Stable identity used as the `v-for` key, roving-focus handle, and selection id. */
+  id: string;
+  /** Time of the keyframe in seconds. */
+  time: number;
+  /** The animated value at this keyframe (in `valueRange` space). */
+  value: number;
+  /** Cubic-bezier control points `[x1, y1, x2, y2]` for the segment starting here. */
+  easing?: [number, number, number, number];
+}
+
+/**
+ * Default easing for a segment with no explicit `easing` tuple: a linear ramp
+ * (`cubic-bezier(0, 0, 1, 1)`), so an un-eased segment interpolates straight.
+ */
+export const DEFAULT_KEYFRAME_EASING: readonly [number, number, number, number] = [0, 0, 1, 1];
+
+/**
+ * Context shared between `KeyframeTrackRoot` and its parts.
+ *
+ * Scalar props are exposed as plain `Ref<T>` — `KeyframeTrackRoot` builds them
+ * with `toRef(() => prop)` (a reactive getter ref without an extra effect),
+ * matching the slider / timeline / curve-editor convention. `projection` /
+ * `invert` are stable closures safe on the pointer hot path.
+ */
+export interface KeyframeTrackContext {
+  /** Stable id base for scoping DOM ids per track instance. */
+  trackId: string;
+  /** The live keyframes, sorted ascending by `time`. */
+  keyframes: ComputedRef<KeyframeTrackKeyframeData[]>;
+  /**
+   * Memoized `id → array index` map over {@link keyframes}, rebuilt once per
+   * change. Parts use it for O(1) id lookup instead of an O(n) `find`/`findIndex`
+   * scan per part per frame (the whole-track cost stays O(n), not O(n²)).
+   */
+  indexById: ComputedRef<Map<string, number>>;
+  /** Currently selected keyframe id (drives the easing editor + roving focus), or null. */
+  selectedId: Ref<string | null>;
+  /** The animated property name (for the a11y label). */
+  property: Ref<string | undefined>;
+  /** Whether keyframes move vertically to edit `value` (else single horizontal lane). */
+  valueAxis: Ref<boolean>;
+  /** Value domain `[min, max]` (the y-axis extent in `valueAxis` mode). */
+  valueRange: Ref<readonly [number, number]>;
+  /** Total track duration in seconds (auto / injected from a Timeline / explicit). */
+  duration: ComputedRef<number>;
+  /** Frame rate (timecode + frame snapping + keyboard nudge). */
+  fps: Ref<number>;
+  /** Keyboard nudge step in seconds. */
+  step: Ref<number>;
+  /** Large keyboard step in seconds (Shift+Arrow). */
+  largeStep: Ref<number>;
+  /** Value-axis keyboard nudge step (per Arrow Up/Down in `valueAxis` mode). */
+  valueStep: Ref<number>;
+  /** Whether keyframes may overlap in time (else neighbour-clamped to keep order). */
+  allowOverlap: Ref<boolean>;
+  /** Minimum time gap between neighbouring keyframes (seconds) when `allowOverlap` is false. */
+  minTimeBetween: Ref<number>;
+  /** Snapping master enable. */
+  snapping: Ref<boolean>;
+  /** Master interactivity / disabled switch. */
+  disabled: Ref<boolean>;
+  /** Resolved reading direction. */
+  direction: ComputedRef<Direction>;
+  /** Live width (px) of the lane; `projection` range is `[0, width]`. */
+  laneWidth: Ref<number>;
+  /** Live height (px) of the lane (used by `valueAxis` y-projection). */
+  laneHeight: Ref<number>;
+
+  // ── coordinate model ──────────────────────────────────────────────────────
+  /** Project a time (seconds) to a pixel offset in the lane. Stable identity. */
+  projection: (seconds: number) => number;
+  /** Invert a pixel offset back to a time (seconds). Stable identity. */
+  invert: (px: number) => number;
+  /** Project a value to a pixel offset on the y-axis (value-up). Stable identity. */
+  projectValue: (value: number) => number;
+  /** Invert a y pixel offset back to a value. Stable identity. */
+  invertValue: (px: number) => number;
+  /** Format a time (seconds) as a wall-clock string. */
+  formatTime: (seconds: number) => string;
+  /** Snap a candidate time to the nearest snap target (frame grid). */
+  snapTime: (seconds: number, exclude?: string) => number;
+  /** The shared snap engine (frame-grid targets). */
+  snapEngine: UseSnappingReturn;
+
+  // ── data access ───────────────────────────────────────────────────────────
+  /** True while a keyframe drag is in flight (blocks external sync clobber). */
+  isMutating: Readonly<Ref<boolean>>;
+  /** The id of the keyframe currently being dragged (or null). */
+  draggingId: Readonly<Ref<string | null>>;
+  /** Whether this track is nested inside a Timeline (renders as a `listitem`). */
+  inTimeline: boolean;
+
+  // ── sampling ──────────────────────────────────────────────────────────────
+  /**
+   * Sample the animated value at an arbitrary time: find the bracketing
+   * keyframes and apply the segment easing via the spline. Constant outside the
+   * keyframe range (and for 0 / 1 keyframes).
+   */
+  sampleAt: (time: number) => number;
+
+  // ── selection ─────────────────────────────────────────────────────────────
+  /** Select a keyframe by id (null clears). */
+  select: (id: string | null) => void;
+
+  // ── mutation ──────────────────────────────────────────────────────────────
+  /** Insert a keyframe at `time` (value defaults to the sampled curve). Returns its id. */
+  addKeyframe: (time: number, value?: number) => string | undefined;
+  /** Remove a keyframe by id. */
+  removeKeyframe: (id: string) => void;
+  /** Move a keyframe (transient overlay while `mutating`; commit on settle). */
+  moveKeyframe: (id: string, time: number, value?: number, mutating?: boolean) => void;
+  /** Set the segment easing (cubic-bezier tuple) of the segment starting at `id`. */
+  setEasing: (id: string, bezier: [number, number, number, number]) => void;
+  /** Commit the in-flight transient mutation into the model (one commit). */
+  commit: () => void;
+
+  // ── roving focus registration ─────────────────────────────────────────────
+  /** Register a keyframe element for roving focus. */
+  registerKeyframeEl: (id: string, el: HTMLElement | null) => void;
+  /** Focus the next/prev keyframe in time order from `fromId` (roving). */
+  focusAdjacent: (fromId: string, direction: 1 | -1) => void;
+  /** Focus a keyframe element by id. */
+  focusKeyframe: (id: string) => void;
+}
+
+const ctx = useContextFactory<KeyframeTrackContext>('KeyframeTrackContext');
+
+export const provideKeyframeTrackContext = ctx.provide;
+export const useKeyframeTrackContext = ctx.inject;
diff --git a/vue/primitives/src/canvas/keyframe-track/demo.vue b/vue/primitives/src/canvas/keyframe-track/demo.vue
new file mode 100644
index 0000000..6e392e3
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/demo.vue
@@ -0,0 +1,250 @@
+<script setup lang="ts">
+import type { KeyframeTrackKeyframeData } from '@robonen/primitives';
+import {
+  CurveEditorHandle,
+  CurveEditorPoint,
+  KeyframeTrackEasingEditor,
+  KeyframeTrackKeyframe,
+  KeyframeTrackRoot,
+  KeyframeTrackSegment,
+} from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+// Cubic-bezier easing tuples for the segment STARTING at each keyframe
+// (CSS `cubic-bezier(x1, y1, x2, y2)` semantics).
+const EASE_OUT: [number, number, number, number] = [0, 0, 0.2, 1];
+const EASE_IN: [number, number, number, number] = [0.5, 0, 1, 1];
+const EASE_IN_OUT: [number, number, number, number] = [0.65, 0, 0.35, 1];
+
+const keyframes = ref<KeyframeTrackKeyframeData[]>([
+  { id: 'k1', time: 0, value: 0, easing: EASE_OUT },
+  { id: 'k2', time: 1.2, value: 1, easing: EASE_IN_OUT },
+  { id: 'k3', time: 2.6, value: 0.35, easing: EASE_IN },
+  { id: 'k4', time: 4, value: 0.9 },
+]);
+
+const selectedId = ref<string | null>('k2');
+
+const duration = 4;
+const fps = 30;
+
+// Live sampler, mirrored from the Root's `sampleAt` slot prop, for the readout.
+const sampleFn = ref<(time: number) => number>(() => 0);
+
+// A scrubbing probe so the demo shows the sampled value at an arbitrary time.
+const probeTime = ref(1.6);
+const probeValue = computed(() => sampleFn.value(probeTime.value));
+
+const selectedKeyframe = computed(() =>
+  keyframes.value.find(k => k.id === selectedId.value),
+);
+
+function easingLabel(e?: [number, number, number, number]): string {
+  if (!e) return 'linear';
+  return `cubic-bezier(${e.map(n => +n.toFixed(2)).join(', ')})`;
+}
+
+// Build an SVG polyline of the whole value curve in lane-local coordinates.
+// `projection` maps time → px (x); we map value → px (y) ourselves so the curve
+// fills the lane height regardless of the component's own (horizontal) lane mode.
+function curvePath(projection: (t: number) => number, sample: (t: number) => number, width: number, height: number): string {
+  if (width <= 0) return '';
+  const pad = 10;
+  const usable = height - pad * 2;
+  const samples = 120;
+  let d = '';
+  for (let i = 0; i < samples; i++) {
+    const t = (i / (samples - 1)) * duration;
+    const x = projection(t);
+    const y = pad + (1 - sample(t)) * usable;
+    d += `${i === 0 ? 'M' : 'L'}${x.toFixed(1)},${y.toFixed(1)} `;
+  }
+  return d.trim();
+}
+
+function yForValue(value: number, height: number): number {
+  const pad = 10;
+  return pad + (1 - value) * (height - pad * 2);
+}
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-xl space-y-4 rounded-card border border-border bg-bg p-5 text-fg shadow-(--shadow-card)">
+    <div class="flex items-baseline justify-between">
+      <div>
+        <h3 class="text-sm font-semibold text-fg">Opacity</h3>
+        <p class="text-xs text-fg-subtle">Animation keyframes with editable easing</p>
+      </div>
+      <span class="rounded-md bg-bg-inset px-2 py-1 font-mono text-xs tabular-nums text-fg-muted">
+        f({{ probeTime.toFixed(2) }}s) = {{ probeValue.toFixed(3) }}
+      </span>
+    </div>
+
+    <!-- ── the keyframe lane ──────────────────────────────────────────────
+         The Root measures its OWN box (standalone), so it needs an explicit
+         height + relative positioning; the curve SVG, segments, and keyframe
+         diamonds all read pixel coords from that box. -->
+    <KeyframeTrackRoot
+      v-model="keyframes"
+      v-model:selected-id="selectedId"
+      property="opacity"
+      :duration="duration"
+      :fps="fps"
+      :value-range="[0, 1]"
+      class="block w-full touch-none select-none"
+    >
+      <template #default="{ projection, sampleAt }">
+        {{ (sampleFn = sampleAt, '') }}
+
+        <!-- the lane box: keyframes, curve, and segments position against it -->
+        <div class="relative h-40 w-full overflow-hidden rounded-card border border-border bg-bg-inset">
+
+        <!-- horizontal value gridlines (0 / 0.5 / 1) -->
+        <div class="pointer-events-none absolute inset-0">
+          <div
+            v-for="v in [0, 0.5, 1]"
+            :key="v"
+            class="absolute inset-x-0 flex items-center"
+            :style="{ top: `${yForValue(v, 160)}px` }"
+          >
+            <span class="w-full border-t border-dashed border-border" />
+            <span class="absolute left-1 -translate-y-1/2 font-mono text-[9px] text-fg-subtle">{{ v }}</span>
+          </div>
+        </div>
+
+        <!-- the eased value curve across all segments -->
+        <svg class="pointer-events-none absolute inset-0 size-full" aria-hidden="true" preserveAspectRatio="none">
+          <path
+            :d="`${curvePath(projection, sampleAt, 600, 160)} L 600,170 L 0,170 Z`"
+            fill="var(--color-accent)"
+            fill-opacity="0.08"
+          />
+          <path
+            :d="curvePath(projection, sampleAt, 600, 160)"
+            fill="none"
+            stroke="var(--color-accent)"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          />
+        </svg>
+
+        <!-- selectable segment bands (click selects the starting keyframe) -->
+        <KeyframeTrackSegment
+          v-for="kf in keyframes.slice(0, -1)"
+          :key="`seg-${kf.id}`"
+          :keyframe-id="kf.id"
+          class="absolute inset-y-0 cursor-pointer border-l border-border/60 transition-colors hover:bg-fg/[0.03] data-[selected]:bg-accent/8"
+        />
+
+        <!-- draggable keyframe diamonds, parked on the curve -->
+        <KeyframeTrackKeyframe
+          v-for="kf in keyframes"
+          :key="kf.id"
+          v-slot="{ keyframe, selected, dragging }"
+          :keyframe-id="kf.id"
+          class="absolute z-10 cursor-grab outline-none active:cursor-grabbing"
+          :style="{ top: `${yForValue(kf.value, 160)}px`, transform: 'translate(-50%, -50%)' }"
+        >
+          <span
+            class="block size-3.5 rotate-45 rounded-[2px] border-2 bg-bg shadow-sm transition-transform"
+            :class="[
+              selected ? 'border-accent scale-125 ring-2 ring-accent/40' : 'border-border-strong',
+              dragging ? 'scale-125' : 'hover:scale-110',
+            ]"
+            :style="selected ? { backgroundColor: 'var(--color-accent)' } : undefined"
+          />
+          <span class="sr-only">Keyframe at {{ keyframe?.time.toFixed(2) }}s, value {{ keyframe?.value.toFixed(2) }}</span>
+        </KeyframeTrackKeyframe>
+
+        <!-- a draggable time probe so the sampled value is live -->
+        <input
+          v-model.number="probeTime"
+          type="range"
+          :min="0"
+          :max="duration"
+          :step="0.02"
+          aria-label="Sample time"
+          class="absolute inset-x-0 bottom-0 z-20 m-0 h-5 w-full cursor-ew-resize appearance-none bg-transparent"
+        >
+        <span
+          class="pointer-events-none absolute inset-y-0 z-10 w-px bg-fg-muted/60"
+          :style="{ left: `${projection(probeTime)}px` }"
+        />
+        </div>
+
+        <!-- selected-segment easing editor — INSIDE the Root so it receives the
+             KeyframeTrack context. Renders only when a keyframe with a
+             following segment is selected. -->
+        <div class="grid grid-cols-[1fr_auto] gap-4 mt-4">
+      <div class="space-y-2">
+        <div class="flex items-center justify-between text-xs">
+          <span class="font-medium text-fg-muted">Selected keyframe</span>
+          <span v-if="selectedKeyframe" class="font-mono tabular-nums text-fg-subtle">
+            {{ selectedKeyframe.time.toFixed(2) }}s · {{ selectedKeyframe.value.toFixed(2) }}
+          </span>
+        </div>
+        <p class="text-xs text-fg-subtle">
+          Segment easing:
+          <code class="rounded bg-bg-inset px-1 py-0.5 font-mono text-[11px] text-fg-muted">{{ easingLabel(selectedKeyframe?.easing) }}</code>
+        </p>
+        <p class="text-xs text-fg-subtle">
+          Drag the diamonds to move keyframes; drag the bezier handles to retune
+          the easing of the selected segment. Arrow keys nudge the focused keyframe.
+        </p>
+      </div>
+
+      <!-- the easing curve for the selected segment (an embedded CurveEditor).
+           The editor measures its OWN box; CurveEditorPoint / CurveEditorHandle
+           position themselves in that box's pixel space and are draggable. -->
+      <KeyframeTrackEasingEditor
+        v-slot="{ anchors, sample }"
+        :samples="64"
+        class="relative size-28 shrink-0 touch-none select-none overflow-hidden rounded-card border border-border bg-bg-inset"
+      >
+        <!-- the eased curve, sampled across [0,1] (y flipped for screen coords) -->
+        <svg class="pointer-events-none absolute inset-0 size-full" viewBox="0 0 1 1" preserveAspectRatio="none" aria-hidden="true">
+          <line x1="0" y1="1" x2="1" y2="0" stroke="var(--color-border-strong)" stroke-width="0.012" stroke-dasharray="0.03 0.03" />
+          <polyline
+            :points="Array.from({ length: 33 }, (_, i) => {
+              const x = i / 32;
+              return `${x},${1 - sample(x)}`;
+            }).join(' ')"
+            fill="none"
+            stroke="var(--color-accent)"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            vector-effect="non-scaling-stroke"
+          />
+        </svg>
+
+        <!-- draggable bezier tangent handles -->
+        <CurveEditorHandle
+          v-for="a in anchors"
+          :key="`out-${a.id}`"
+          :anchor="a"
+          side="out"
+          class="absolute z-10 size-2.5 -translate-x-1/2 -translate-y-1/2 cursor-grab rounded-full border-2 border-accent bg-bg outline-none active:cursor-grabbing focus-visible:ring-2 focus-visible:ring-ring"
+        />
+        <CurveEditorHandle
+          v-for="a in anchors"
+          :key="`in-${a.id}`"
+          :anchor="a"
+          side="in"
+          class="absolute z-10 size-2.5 -translate-x-1/2 -translate-y-1/2 cursor-grab rounded-full border-2 border-accent bg-bg outline-none active:cursor-grabbing focus-visible:ring-2 focus-visible:ring-ring"
+        />
+
+        <!-- the two pinned (0,0) / (1,1) anchors -->
+        <CurveEditorPoint
+          v-for="a in anchors"
+          :key="a.id"
+          :anchor="a"
+          class="absolute z-20 size-2.5 -translate-x-1/2 -translate-y-1/2 rounded-sm border-2 border-fg-subtle bg-bg outline-none"
+        />
+      </KeyframeTrackEasingEditor>
+        </div>
+      </template>
+    </KeyframeTrackRoot>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/keyframe-track/index.ts b/vue/primitives/src/canvas/keyframe-track/index.ts
new file mode 100644
index 0000000..820cd29
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/index.ts
@@ -0,0 +1,29 @@
+export { default as KeyframeTrackRoot } from './KeyframeTrackRoot.vue';
+export type { KeyframeTrackRootEmits, KeyframeTrackRootProps } from './KeyframeTrackRoot.vue';
+
+export { default as KeyframeTrackKeyframe } from './KeyframeTrackKeyframe.vue';
+export type { KeyframeTrackKeyframeProps } from './KeyframeTrackKeyframe.vue';
+
+export { default as KeyframeTrackSegment } from './KeyframeTrackSegment.vue';
+export type { KeyframeTrackSegmentProps } from './KeyframeTrackSegment.vue';
+
+export { default as KeyframeTrackEasingEditor } from './KeyframeTrackEasingEditor.vue';
+export type { KeyframeTrackEasingEditorProps } from './KeyframeTrackEasingEditor.vue';
+
+export {
+  DEFAULT_KEYFRAME_EASING,
+  provideKeyframeTrackContext,
+  useKeyframeTrackContext,
+} from './context';
+export type {
+  KeyframeTrackContext,
+  KeyframeTrackKeyframeData,
+} from './context';
+
+export {
+  clampKeyframeTime,
+  defaultKeyframeValueText,
+  sampleKeyframes,
+  snapTimeToFrame,
+  sortKeyframes,
+} from './utils';
diff --git a/vue/primitives/src/canvas/keyframe-track/utils.ts b/vue/primitives/src/canvas/keyframe-track/utils.ts
new file mode 100644
index 0000000..c2d92ff
--- /dev/null
+++ b/vue/primitives/src/canvas/keyframe-track/utils.ts
@@ -0,0 +1,134 @@
+import { solveBezierX } from '../../internal/spline';
+import { framesToSeconds, secondsToFrames } from '../../internal/scale';
+import { DEFAULT_KEYFRAME_EASING } from './context';
+import type { KeyframeTrackKeyframeData } from './context';
+
+/**
+ * Sort keyframes ascending by `time`, returning a NEW array (never mutating the
+ * input). Stable for equal times (a tie breaks on `id`) so the order is
+ * deterministic across reconciles and neighbour-clamping stays predictable.
+ */
+export function sortKeyframes(keyframes: readonly KeyframeTrackKeyframeData[]): KeyframeTrackKeyframeData[] {
+  return keyframes
+    .slice()
+    .sort((a, b) => (a.time - b.time) || a.id.localeCompare(b.id));
+}
+
+/**
+ * Linear interpolate between `a` and `b` by `t ∈ [0, 1]`.
+ */
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+/**
+ * Sample the animated value at an arbitrary `time` (seconds) over a SORTED
+ * keyframe list.
+ *
+ * Finds the bracketing pair `[k, k+1]`, computes the normalized progress along
+ * the segment, applies the starting keyframe's cubic-bezier easing (via the
+ * spline `solveBezierX`, defaulting to {@link DEFAULT_KEYFRAME_EASING} — a linear
+ * ramp), and lerps the value. The result is CONSTANT outside the keyframe range
+ * (held at the first / last keyframe's value) and for the 0- and 1-keyframe
+ * degenerate cases.
+ *
+ * `valueRange` is accepted for parity with the projection model but does not
+ * affect the sampled value (values are sampled in their own space, never
+ * normalized) — it is reserved so callers can pass it without a second overload.
+ *
+ * @param keyframes Keyframes sorted ascending by `time`.
+ * @param time Time to sample, in seconds.
+ * @param valueRange Optional value domain (unused by the maths; see above).
+ */
+export function sampleKeyframes(
+  keyframes: readonly KeyframeTrackKeyframeData[],
+  time: number,
+  _valueRange?: readonly [number, number],
+): number {
+  const n = keyframes.length;
+  if (n === 0) return 0;
+  const first = keyframes[0]!;
+  if (n === 1) return first.value;
+  const last = keyframes[n - 1]!;
+
+  // Held constant outside the keyframe range.
+  if (time <= first.time) return first.value;
+  if (time >= last.time) return last.value;
+
+  // Binary search for the segment [lo, lo+1] containing `time`.
+  let lo = 0;
+  let hi = n - 1;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (keyframes[mid]!.time <= time) lo = mid;
+    else hi = mid;
+  }
+
+  const a = keyframes[lo]!;
+  const b = keyframes[lo + 1]!;
+  const span = b.time - a.time;
+  if (span <= 0) return a.value;
+
+  const progress = (time - a.time) / span;
+  const easing = a.easing ?? DEFAULT_KEYFRAME_EASING;
+  // Easing maps normalized progress (x) to eased progress (y) in [0, 1].
+  const eased = solveBezierX(easing[0], easing[1], easing[2], easing[3], progress);
+  return lerp(a.value, b.value, eased);
+}
+
+/**
+ * Clamp a candidate `time` for the keyframe at `index` so it stays ordered
+ * relative to its neighbours by at least `minTimeBetween` seconds (unless
+ * `allowOverlap`), and never goes below `0`. `keyframes` MUST be sorted by time.
+ *
+ * @param keyframes Keyframes sorted ascending by `time`.
+ * @param index Index of the keyframe being moved.
+ * @param time Candidate time (seconds).
+ * @param options Neighbour-clamp configuration.
+ */
+export function clampKeyframeTime(
+  keyframes: readonly KeyframeTrackKeyframeData[],
+  index: number,
+  time: number,
+  options: { allowOverlap: boolean; minTimeBetween: number; duration?: number },
+): number {
+  const { allowOverlap, minTimeBetween, duration } = options;
+  let v = Math.max(0, time);
+  if (duration !== undefined && duration > 0) v = Math.min(v, duration);
+
+  if (!allowOverlap) {
+    const prev = keyframes[index - 1];
+    const next = keyframes[index + 1];
+    if (prev !== undefined) v = Math.max(v, prev.time + minTimeBetween);
+    if (next !== undefined) v = Math.min(v, next.time - minTimeBetween);
+  }
+  return v;
+}
+
+/**
+ * Snap a `time` (seconds) to the nearest whole frame at `fps`. The default
+ * frame-grid quantizer used as the keyboard nudge granularity / snap fallback.
+ */
+export function snapTimeToFrame(time: number, fps: number): number {
+  if (fps <= 0) return time;
+  return framesToSeconds(secondsToFrames(time, fps), fps);
+}
+
+/**
+ * Round to `decimals` places, trimming float noise (no trailing-zero padding).
+ */
+function round(value: number, decimals: number): number {
+  const f = 10 ** decimals;
+  return Math.round(value * f) / f;
+}
+
+/**
+ * The default `aria-valuetext` value-token for a keyframe: the animated property
+ * (when present) followed by the value, e.g. `"opacity 0.5"` or just `"0.5"`.
+ * The time is announced separately by the caller (a slider's `aria-valuetext`
+ * leads with the formatted time).
+ */
+export function defaultKeyframeValueText(value: number, property?: string, decimals = 3): string {
+  const v = round(value, decimals);
+  return property ? `${property} ${v}` : `${v}`;
+}
diff --git a/vue/primitives/src/canvas/levels/LevelsHandleValue.vue b/vue/primitives/src/canvas/levels/LevelsHandleValue.vue
new file mode 100644
index 0000000..d523a89
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/LevelsHandleValue.vue
@@ -0,0 +1,83 @@
+<script lang="ts">
+import type { LevelsHandleKind } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A visible, editable numeric entry box bound to one levels `kind` — the precise
+ * and screen-reader-friendly path for entering a handle value. It composes the
+ * `NumberField` family (`NumberFieldRoot` / `NumberFieldInput` /
+ * `NumberFieldIncrement` / `NumberFieldDecrement`) wired to the enclosing
+ * `LevelsRoot`: typing or stepping writes back through the same
+ * neighbour-clamped setter the thumb uses, so input black can never cross input
+ * white. The field's `min`/`max`/`step` track the handle's current legal range
+ * (gamma uses `gammaStep` and the `0.1..9.99` bounds). The default slot exposes
+ * the `NumberField` parts for full layout control; omit it for a stepper-free
+ * input.
+ */
+export interface LevelsHandleValueProps extends PrimitiveProps {
+  /** Which handle this entry box edits. */
+  kind: LevelsHandleKind;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+  NumberFieldDecrement,
+  NumberFieldIncrement,
+  NumberFieldInput,
+  NumberFieldRoot,
+} from '../../forms/number-field';
+import { useLevelsContext } from './context';
+import { LEVELS_HANDLE_LABELS, handleBounds } from './utils';
+
+const { kind, as = 'div' } = defineProps<LevelsHandleValueProps>();
+const ctx = useLevelsContext();
+
+const isGamma = computed(() => kind === 'gamma');
+
+/** The handle's live value (the gamma factor for `kind: 'gamma'`). */
+const handleNumber = computed(() => (isGamma.value ? ctx.value.value.gamma : ctx.value.value[kind]));
+
+/** Step for the field — `gammaStep` for gamma, otherwise the shared step. */
+const fieldStep = computed(() => (isGamma.value ? ctx.gammaStep.value : ctx.step.value));
+
+/** Live neighbour-aware bounds so the field clamps exactly like the thumb. */
+const bounds = computed(() => handleBounds(kind, ctx.value.value, ctx.minStepsBetweenHandles.value * ctx.step.value));
+
+const ariaLabel = computed(() => LEVELS_HANDLE_LABELS[kind]);
+
+/**
+ * Route a NumberField write back through the levels setter (which re-applies
+ * snapping + neighbour clamping). `null` (cleared field) is ignored — the handle
+ * keeps its last value.
+ */
+function onValueChange(next: number | null): void {
+  if (next === null) return;
+  ctx.setHandle(kind, next);
+}
+</script>
+
+<template>
+  <NumberFieldRoot
+    :as="as"
+    :model-value="handleNumber"
+    :min="bounds.min"
+    :max="bounds.max"
+    :step="fieldStep"
+    :disabled="ctx.disabled.value"
+    v-bind="{ 'data-kind': kind }"
+    @value-change="onValueChange"
+  >
+    <slot
+      :value="handleNumber"
+      :min="bounds.min"
+      :max="bounds.max"
+      :step="fieldStep"
+    >
+      <NumberFieldDecrement v-bind="{ 'aria-label': `Decrease ${ariaLabel}` }" />
+      <NumberFieldInput v-bind="{ 'aria-label': ariaLabel }" />
+      <NumberFieldIncrement v-bind="{ 'aria-label': `Increase ${ariaLabel}` }" />
+    </slot>
+  </NumberFieldRoot>
+</template>
diff --git a/vue/primitives/src/canvas/levels/LevelsRoot.vue b/vue/primitives/src/canvas/levels/LevelsRoot.vue
new file mode 100644
index 0000000..de2e6c7
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/LevelsRoot.vue
@@ -0,0 +1,300 @@
+<script lang="ts">
+import type { LevelsDirection, LevelsOrientation } from './context';
+import type { LevelsHandleKind, LevelsValue } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A headless, accessible Photoshop-style levels control. The root owns a
+ * `LevelsValue` — input `black`/`white` clipping points (`0..255`), a `gamma`
+ * midtone factor (`0.1..9.99`), and an `outputBlack`/`outputWhite` range
+ * (`0..255`) — controlled via `v-model` or uncontrolled via `defaultValue`. It
+ * is a constrained multi-thumb slider: `black` is kept strictly below `white`
+ * (by `minStepsBetweenHandles * step`) and the output handles keep their order,
+ * with a value pushed past its neighbour pinning rather than swapping. The root
+ * handles pointer drags and keyboard for the thumbs, exposes the `0..255` output
+ * LUT via `getOutputCurve`, and can derive auto black/white from a histogram via
+ * `autoLevels`. Provides context to `LevelsTrack`, `LevelsThumb`, and
+ * `LevelsHandleValue`. Pair it with `HistogramRoot` for a full levels editor.
+ */
+export interface LevelsRootProps extends PrimitiveProps {
+  /** Uncontrolled initial value. @default { black: 0, gamma: 1, white: 255, outputBlack: 0, outputWhite: 255 } */
+  defaultValue?: LevelsValue;
+  /** Step for the `0..255` handles (black/white/output). @default 1 */
+  step?: number;
+  /** Step for the gamma handle. @default 0.01 */
+  gammaStep?: number;
+  /** Large-step multiplier (Page keys / Shift+Arrow). @default 10 */
+  largeStep?: number;
+  /** Minimum gap (in `step`s) the black handle keeps below white. @default 1 */
+  minStepsBetweenHandles?: number;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /** Orientation. @default 'horizontal' */
+  orientation?: LevelsOrientation;
+  /** Writing direction (inherited from `ConfigProvider` when omitted). */
+  dir?: LevelsDirection;
+  /** Invert the direction of interaction. @default false */
+  inverted?: boolean;
+}
+
+export interface LevelsRootEmits {
+  /** Fired when a drag or keypress settles. */
+  valueCommit: [value: LevelsValue];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onScopeDispose, ref, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideLevelsContext } from './context';
+import { useDirection } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+import {
+  LEVELS_DEFAULT_VALUE,
+  LEVELS_GAMMA_MAX,
+  LEVELS_GAMMA_MIN,
+  LEVELS_INPUT_MAX,
+  LEVELS_INPUT_MIN,
+  buildOutputCurve,
+  clampHandle,
+  computeAutoLevels,
+  handleBounds,
+  roundClamp,
+} from './utils';
+import { getStepDecimals, scaleLinear } from '../../internal/scale';
+
+const {
+  defaultValue,
+  step = 1,
+  gammaStep = 0.01,
+  largeStep = 10,
+  minStepsBetweenHandles = 1,
+  disabled = false,
+  orientation = 'horizontal',
+  dir,
+  inverted = false,
+  as = 'div',
+} = defineProps<LevelsRootProps>();
+
+const emit = defineEmits<LevelsRootEmits>();
+
+const direction = useDirection(() => dir);
+
+// `defineModel` drives controlled (`v-model`) + uncontrolled modes; in
+// uncontrolled mode `model.value` is `undefined` until first write, so
+// `localValue` is the live source of truth (synchronous multi-step updates
+// can't wait on a prop re-flow). `null` resets to the seed.
+const model = defineModel<LevelsValue | null>();
+
+function seedValue(): LevelsValue {
+  const v = model.value ?? defaultValue ?? LEVELS_DEFAULT_VALUE;
+  return { ...v };
+}
+
+const localValue = ref<LevelsValue>(seedValue());
+
+watch(model, (v) => {
+  if (v === null || v === undefined) return;
+  if (v === localValue.value) return;
+  localValue.value = { ...v };
+});
+
+const value = computed<LevelsValue>({
+  get: () => localValue.value,
+  set: (v) => {
+    localValue.value = v;
+    // `defineModel` emits `update:modelValue` on write.
+    model.value = v;
+  },
+});
+
+// Cache step decimals out of the pointermove path; refresh on step change.
+let stepDecimals = getStepDecimals(step);
+let gammaDecimals = getStepDecimals(gammaStep);
+watch(() => step, (s) => {
+  stepDecimals = getStepDecimals(s);
+});
+watch(() => gammaStep, (s) => {
+  gammaDecimals = getStepDecimals(s);
+});
+
+const trackRef = shallowRef<HTMLElement | null>(null);
+
+const minGap = computed(() => minStepsBetweenHandles * step);
+
+/** Snap a candidate to the handle's step grid (gamma uses `gammaStep`). */
+function snapHandle(kind: LevelsHandleKind, raw: number): number {
+  if (kind === 'gamma') {
+    const snapped = Math.round(raw / gammaStep) * gammaStep;
+    return roundClamp(snapped, LEVELS_GAMMA_MIN, LEVELS_GAMMA_MAX, Math.max(gammaDecimals, 2));
+  }
+  const snapped = Math.round(raw / step) * step;
+  return roundClamp(snapped, LEVELS_INPUT_MIN, LEVELS_INPUT_MAX, stepDecimals);
+}
+
+function commit(): void {
+  emit('valueCommit', { ...localValue.value });
+}
+
+/** Apply `next` to `kind` with snapping + neighbour clamping; no-op if unchanged. */
+function applyHandle(kind: LevelsHandleKind, next: number, doCommit: boolean): void {
+  if (disabled) return;
+  const snapped = snapHandle(kind, next);
+  const clamped = clampHandle(kind, snapped, localValue.value, minGap.value);
+  if (clamped === localValue.value[kind]) {
+    if (doCommit) commit();
+    return;
+  }
+  value.value = { ...localValue.value, [kind]: clamped };
+  if (doCommit) commit();
+}
+
+function setHandle(kind: LevelsHandleKind, next: number): void {
+  applyHandle(kind, next, false);
+}
+
+function nudgeHandle(kind: LevelsHandleKind, delta: number): void {
+  applyHandle(kind, localValue.value[kind] + delta, true);
+}
+
+function jumpHandle(kind: LevelsHandleKind, edge: 'min' | 'max'): void {
+  if (disabled) return;
+  const bounds = handleBounds(kind, localValue.value, minGap.value);
+  applyHandle(kind, edge === 'min' ? bounds.min : bounds.max, true);
+}
+
+/**
+ * Project a pointer event onto the `0..255` track. Returns `LEVELS_INPUT_MIN`
+ * when the track is unmeasured (zero-width before mount), mirroring the slider.
+ * Gamma handles are positioned on the same `0..255` axis (the gamma thumb sits
+ * between black and white), so pointer math is shared.
+ */
+function getValueFromPointer(event: PointerEvent): number {
+  const track = trackRef.value;
+  if (!track) return LEVELS_INPUT_MIN;
+  const rect = track.getBoundingClientRect();
+  const horizontal = orientation === 'horizontal';
+  const size = horizontal ? rect.width : rect.height;
+  if (size === 0) return LEVELS_INPUT_MIN;
+  let offset = horizontal ? event.clientX - rect.left : event.clientY - rect.top;
+  // ltr horizontal: left = min. rtl flips; vertical inverts by default (top =
+  // max), `inverted` flips back.
+  const flip = (horizontal ? direction.value === 'rtl' : true) !== inverted;
+  if (flip) offset = size - offset;
+  return scaleLinear(offset, 0, size, LEVELS_INPUT_MIN, LEVELS_INPUT_MAX);
+}
+
+let activeKind: LevelsHandleKind | null = null;
+
+/**
+ * Map a `0..255` pointer position onto the gamma factor. The gamma thumb's
+ * screen position is its effective input level within `[black, white]`; we
+ * invert `level → t → gamma` so dragging the thumb across the window changes the
+ * factor. Outside the window it pins to the gamma bounds.
+ */
+function pointerToGamma(pointerLevel: number): number {
+  const { black, white } = localValue.value;
+  const span = white - black;
+  if (span <= 0) return localValue.value.gamma;
+  const t = (pointerLevel - black) / span;
+  if (t <= 0) return LEVELS_GAMMA_MAX;
+  if (t >= 1) return LEVELS_GAMMA_MIN;
+  // level = black + 0.5**gamma * span  ⇒  gamma = log2(1/t).
+  const gamma = Math.log2(1 / t);
+  return gamma;
+}
+
+function applyPointer(kind: LevelsHandleKind, event: PointerEvent): void {
+  const pointerLevel = getValueFromPointer(event);
+  if (kind === 'gamma') {
+    setHandle('gamma', pointerToGamma(pointerLevel));
+  }
+  else {
+    setHandle(kind, pointerLevel);
+  }
+}
+
+function handlePointerMove(event: PointerEvent): void {
+  if (activeKind === null) return;
+  applyPointer(activeKind, event);
+}
+
+function handlePointerUp(): void {
+  if (activeKind === null) return;
+  activeKind = null;
+  globalThis.removeEventListener('pointermove', handlePointerMove);
+  globalThis.removeEventListener('pointerup', handlePointerUp);
+  commit();
+}
+
+function startDrag(kind: LevelsHandleKind, event: PointerEvent): void {
+  if (disabled || event.button !== 0) return;
+  event.preventDefault();
+  (event.target as HTMLElement).setPointerCapture?.(event.pointerId);
+  activeKind = kind;
+  applyPointer(kind, event);
+  globalThis.addEventListener('pointermove', handlePointerMove);
+  globalThis.addEventListener('pointerup', handlePointerUp);
+}
+
+// The window listeners opened by `startDrag` are removed only inside
+// `handlePointerUp`. If the Root unmounts while a thumb drag is active (editor
+// panel closes mid-drag), that pointerup never fires for this scope and both
+// listeners leak — retaining the dead instance and running `setHandle` on it for
+// every later pointermove on the page. Detach on scope dispose (no commit).
+onScopeDispose(() => {
+  globalThis.removeEventListener('pointermove', handlePointerMove);
+  globalThis.removeEventListener('pointerup', handlePointerUp);
+});
+
+function getOutputCurve(size = 256): number[] {
+  return buildOutputCurve(localValue.value, size);
+}
+
+function autoLevels(histogram?: number[]): void {
+  if (disabled) return;
+  const { black, white } = computeAutoLevels(histogram);
+  // Set white first when it would otherwise be pinned below the incoming black.
+  value.value = { ...localValue.value, black, white };
+  commit();
+}
+
+provideLevelsContext({
+  value,
+  step: toRef(() => step),
+  gammaStep: toRef(() => gammaStep),
+  largeStep: toRef(() => largeStep),
+  minStepsBetweenHandles: toRef(() => minStepsBetweenHandles),
+  orientation: toRef(() => orientation),
+  direction,
+  inverted: toRef(() => inverted),
+  disabled: toRef(() => disabled),
+  trackRef,
+  setHandle,
+  nudgeHandle,
+  jumpHandle,
+  getValueFromPointer,
+  startDrag,
+  getOutputCurve,
+  autoLevels,
+});
+
+// `defineExpose` BEFORE `useForwardExpose` so the composable merges these
+// bindings (plus props + `$el`) instead of clobbering them.
+defineExpose({ value, getOutputCurve, autoLevels });
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="group"
+    :dir="direction"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-orientation="orientation"
+  >
+    <slot :value="value" :get-output-curve="getOutputCurve" :auto-levels="autoLevels" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/levels/LevelsThumb.vue b/vue/primitives/src/canvas/levels/LevelsThumb.vue
new file mode 100644
index 0000000..b78f743
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/LevelsThumb.vue
@@ -0,0 +1,183 @@
+<script lang="ts">
+import type { LevelsHandleKind } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A draggable levels handle rendered as `role="slider"`, one per `kind`
+ * (`'black'` / `'gamma'` / `'white'` / `'outputBlack'` / `'outputWhite'`),
+ * placed inside `LevelsTrack`. It positions itself along the `0..255` track,
+ * exposes full per-kind ARIA (`aria-label`, `aria-valuemin/max/now`), and
+ * handles pointer drags and the keyboard (Arrow / Page / Home / End,
+ * neighbour-clamped). The gamma thumb is special: it sits at its effective
+ * midtone input level, its `aria-valuenow` carries the gamma FACTOR
+ * (`0.1..9.99`), and its `aria-valuetext` states the effective level
+ * (e.g. "Gamma 1.00, midtone at 128"). Keyboard nudges use `step` for the
+ * `0..255` handles and `gammaStep` for gamma.
+ */
+export interface LevelsThumbProps extends PrimitiveProps {
+  /** Which handle this thumb controls. */
+  kind: LevelsHandleKind;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useLevelsContext } from './context';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useForwardExpose } from '@robonen/vue';
+import {
+  LEVELS_HANDLE_LABELS,
+  LEVELS_INPUT_MAX,
+  LEVELS_INPUT_MIN,
+  gammaMidtoneLevel,
+  handleBounds,
+} from './utils';
+
+const { kind, as = 'span' } = defineProps<LevelsThumbProps>();
+const ctx = useLevelsContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const value = computed(() => ctx.value.value);
+const isGamma = computed(() => kind === 'gamma');
+
+/** The number reported as `aria-valuenow` (gamma → factor, else the handle value). */
+const ariaValueNow = computed(() => (isGamma.value ? value.value.gamma : value.value[kind]));
+
+/** Per-kind legal bounds (neighbour-aware). For gamma these are the factor bounds. */
+const bounds = computed(() => handleBounds(kind, value.value, ctx.minStepsBetweenHandles.value * ctx.step.value));
+
+/**
+ * The `0..255` level the thumb is drawn at. Every handle but gamma maps directly
+ * to its value; gamma is drawn at its effective midtone level so it slides
+ * between the black and white thumbs.
+ */
+const trackLevel = computed(() => {
+  if (isGamma.value) return gammaMidtoneLevel(value.value);
+  return value.value[kind];
+});
+
+const percentage = computed(() => {
+  const range = LEVELS_INPUT_MAX - LEVELS_INPUT_MIN;
+  if (range === 0) return 0;
+  return ((trackLevel.value - LEVELS_INPUT_MIN) / range) * 100;
+});
+
+const positionStyle = computed<{
+  left: string | undefined;
+  right: string | undefined;
+  top: string | undefined;
+  bottom: string | undefined;
+}>(() => {
+  const pct = `${percentage.value}%`;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const rtl = ctx.direction.value === 'rtl';
+  const inverted = ctx.inverted.value;
+  if (horizontal) {
+    const flip = rtl !== inverted;
+    return { left: flip ? undefined : pct, right: flip ? pct : undefined, top: undefined, bottom: undefined };
+  }
+  return { left: undefined, right: undefined, top: inverted ? pct : undefined, bottom: inverted ? undefined : pct };
+});
+
+const ariaLabel = computed(() => LEVELS_HANDLE_LABELS[kind]);
+
+/** Gamma's `aria-valuetext` carries factor + the effective midtone level. */
+const ariaValueText = computed<string | undefined>(() => {
+  if (!isGamma.value) return undefined;
+  const factor = value.value.gamma.toFixed(2);
+  const level = gammaMidtoneLevel(value.value);
+  return `Gamma ${factor}, midtone at ${level}`;
+});
+
+// Pointer drag is handled by the root (it owns the shared pointermove math and
+// the gamma inversion); the thumb just hands off the kind on press.
+usePointerDrag(currentElement, {
+  axis: ctx.orientation.value === 'horizontal' ? 'x' : 'y',
+  threshold: 0,
+  disabled: () => ctx.disabled.value,
+  onStart: (state, event) => {
+    ctx.startDrag(kind, event);
+    // `startDrag` already applied the press position; consume the event so the
+    // root owns subsequent moves via its window listeners.
+    void state;
+  },
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const rtl = ctx.direction.value === 'rtl';
+  const inverted = ctx.inverted.value;
+  // Gamma steps by `gammaStep`; every other handle by `step`. Shift jumps by the
+  // same large step as Page.
+  const unit = isGamma.value ? ctx.gammaStep.value : ctx.step.value;
+  const big = unit * ctx.largeStep.value;
+  // Per-press magnitude (large for Shift/Page, otherwise one step).
+  const mag = event.shiftKey ? big : unit;
+
+  let delta: number;
+  switch (event.key) {
+    // Horizontal: "increase" is right in ltr (flipped by rtl/inverted).
+    case 'ArrowRight':
+      if (!horizontal) return;
+      delta = (rtl !== inverted ? -1 : 1) * mag;
+      break;
+    case 'ArrowLeft':
+      if (!horizontal) return;
+      delta = (rtl !== inverted ? 1 : -1) * mag;
+      break;
+    // Vertical: "increase" is up (flipped by inverted).
+    case 'ArrowUp':
+      if (horizontal) return;
+      delta = (inverted ? -1 : 1) * mag;
+      break;
+    case 'ArrowDown':
+      if (horizontal) return;
+      delta = (inverted ? 1 : -1) * mag;
+      break;
+    case 'PageUp':
+      delta = big;
+      break;
+    case 'PageDown':
+      delta = -big;
+      break;
+    case 'Home':
+      event.preventDefault();
+      ctx.jumpHandle(kind, 'min');
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.jumpHandle(kind, 'max');
+      return;
+    default:
+      return;
+  }
+  if (delta === 0) return;
+  event.preventDefault();
+  ctx.nudgeHandle(kind, delta);
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="ariaLabel"
+    :aria-valuemin="bounds.min"
+    :aria-valuemax="bounds.max"
+    :aria-valuenow="ariaValueNow"
+    :aria-valuetext="ariaValueText"
+    :aria-orientation="ctx.orientation.value"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-kind="kind"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :value="ariaValueNow" :level="trackLevel" :percent="percentage" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/levels/LevelsTrack.vue b/vue/primitives/src/canvas/levels/LevelsTrack.vue
new file mode 100644
index 0000000..a171a9d
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/LevelsTrack.vue
@@ -0,0 +1,41 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The `0..255` rail the levels thumbs travel along, rendered inside
+ * `LevelsRoot`. It registers itself as the geometry reference for the root's
+ * pointer math. Use it as the container for the histogram backdrop and the
+ * `LevelsThumb`s. (Drag is initiated on each thumb, so pressing a thumb does not
+ * also start a track-position drag.)
+ */
+export interface LevelsTrackProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { onBeforeUnmount, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useLevelsContext } from './context';
+
+const { as = 'div' } = defineProps<LevelsTrackProps>();
+const ctx = useLevelsContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+watch(currentElement, (node) => {
+  ctx.trackRef.value = node ?? null;
+});
+onBeforeUnmount(() => {
+  ctx.trackRef.value = null;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/levels/__test__/Levels.test.ts b/vue/primitives/src/canvas/levels/__test__/Levels.test.ts
new file mode 100644
index 0000000..208c7ac
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/__test__/Levels.test.ts
@@ -0,0 +1,306 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  LevelsHandleValue,
+  LevelsRoot,
+  LevelsThumb,
+  LevelsTrack,
+} from '../index';
+import type { LevelsValue } from '../index';
+import { applyLevels, buildOutputCurve, computeAutoLevels } from '../utils';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', {
+    key,
+    bubbles: true,
+    cancelable: true,
+    shiftKey: opts.shiftKey ?? false,
+  }));
+}
+
+function mountLevels(opts: {
+  defaultValue?: Partial<LevelsValue>;
+  step?: number;
+  gammaStep?: number;
+  minStepsBetweenHandles?: number;
+  disabled?: boolean;
+  kinds?: Array<'black' | 'gamma' | 'white' | 'outputBlack' | 'outputWhite'>;
+} = {}) {
+  const model = ref<LevelsValue | null | undefined>(undefined);
+  const kinds = opts.kinds ?? ['black', 'gamma', 'white', 'outputBlack', 'outputWhite'];
+  const Harness = defineComponent({
+    setup() {
+      return () => h(LevelsRoot, {
+        modelValue: model.value,
+        defaultValue: { black: 0, gamma: 1, white: 255, outputBlack: 0, outputWhite: 255, ...opts.defaultValue },
+        step: opts.step,
+        gammaStep: opts.gammaStep,
+        minStepsBetweenHandles: opts.minStepsBetweenHandles,
+        disabled: opts.disabled,
+        'onUpdate:modelValue': (v: LevelsValue | null | undefined) => { model.value = v; },
+      }, {
+        default: () => h(LevelsTrack, null, {
+          default: () => kinds.map(kind => h(LevelsThumb, { kind, id: `thumb-${kind}` })),
+        }),
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+function thumb(kind: string): HTMLElement {
+  return document.getElementById(`thumb-${kind}`)!;
+}
+
+describe('Levels — utils (unit)', () => {
+  it('applyLevels is the identity for the default adjustment', () => {
+    const v: LevelsValue = { black: 0, gamma: 1, white: 255, outputBlack: 0, outputWhite: 255 };
+    expect(applyLevels(0, v)).toBeCloseTo(0, 5);
+    expect(applyLevels(128, v)).toBeCloseTo(128, 5);
+    expect(applyLevels(255, v)).toBeCloseTo(255, 5);
+  });
+
+  it('getOutputCurve returns a 256-length, monotonic non-decreasing LUT', () => {
+    const lut = buildOutputCurve({ black: 0, gamma: 1, white: 255, outputBlack: 0, outputWhite: 255 });
+    expect(lut).toHaveLength(256);
+    for (let i = 1; i < lut.length; i++) expect(lut[i]!).toBeGreaterThanOrEqual(lut[i - 1]!);
+    // Identity LUT.
+    expect(lut[0]).toBeCloseTo(0, 4);
+    expect(lut[255]).toBeCloseTo(255, 4);
+  });
+
+  it('LUT reflects black/white clipping and the output range', () => {
+    const lut = buildOutputCurve({ black: 64, gamma: 1, white: 192, outputBlack: 10, outputWhite: 240 });
+    // Below black clips to outputBlack, above white clips to outputWhite.
+    expect(lut[0]).toBeCloseTo(10, 4);
+    expect(lut[255]).toBeCloseTo(240, 4);
+    expect(lut[32]).toBeCloseTo(10, 4); // still below black
+    expect(lut[220]).toBeCloseTo(240, 4); // above white
+    // Midpoint of the window maps near the output midpoint at gamma 1.
+    expect(lut[128]!).toBeGreaterThan(10);
+    expect(lut[128]!).toBeLessThan(240);
+  });
+
+  it('gamma > 1 brightens midtones in the LUT', () => {
+    const linear = buildOutputCurve({ black: 0, gamma: 1, white: 255, outputBlack: 0, outputWhite: 255 });
+    const bright = buildOutputCurve({ black: 0, gamma: 2, white: 255, outputBlack: 0, outputWhite: 255 });
+    expect(bright[128]!).toBeGreaterThan(linear[128]!);
+  });
+
+  it('computeAutoLevels clips tails and falls back on empty/flat data', () => {
+    expect(computeAutoLevels(undefined)).toEqual({ black: 0, white: 255 });
+    expect(computeAutoLevels([])).toEqual({ black: 0, white: 255 });
+    expect(computeAutoLevels([0, 0, 0])).toEqual({ black: 0, white: 255 });
+    // Signal concentrated in the middle bins → black moves up, white moves down.
+    const hist = Array.from({ length: 256 }, (_, i) => (i >= 64 && i <= 192 ? 100 : 0));
+    const { black, white } = computeAutoLevels(hist, 0.001);
+    expect(black).toBeGreaterThan(0);
+    expect(white).toBeLessThan(255);
+    expect(black).toBeLessThan(white);
+  });
+});
+
+describe('Levels — thumb ARIA', () => {
+  it('each thumb is role=slider with the per-kind aria-label', async () => {
+    mountLevels();
+    await nextTick();
+    expect(thumb('black').getAttribute('role')).toBe('slider');
+    expect(thumb('black').getAttribute('aria-label')).toBe('Black point');
+    expect(thumb('gamma').getAttribute('aria-label')).toBe('Gamma');
+    expect(thumb('white').getAttribute('aria-label')).toBe('White point');
+    expect(thumb('outputBlack').getAttribute('aria-label')).toBe('Output black');
+    expect(thumb('outputWhite').getAttribute('aria-label')).toBe('Output white');
+  });
+
+  it('reports correct aria-value* for the 0..255 handles', async () => {
+    mountLevels({ defaultValue: { black: 20, white: 230, outputBlack: 5, outputWhite: 250 } });
+    await nextTick();
+    const black = thumb('black');
+    expect(black.getAttribute('aria-valuenow')).toBe('20');
+    expect(black.getAttribute('aria-valuemin')).toBe('0');
+    // black's max is white - minGap (230 - 1).
+    expect(black.getAttribute('aria-valuemax')).toBe('229');
+    expect(thumb('white').getAttribute('aria-valuenow')).toBe('230');
+    expect(thumb('white').getAttribute('aria-valuemin')).toBe('21');
+    expect(thumb('outputBlack').getAttribute('aria-valuemax')).toBe('250');
+    expect(thumb('outputWhite').getAttribute('aria-valuemin')).toBe('5');
+  });
+
+  it('gamma thumb aria-valuenow carries the factor and aria-valuetext the effective level', async () => {
+    mountLevels({ defaultValue: { black: 0, gamma: 1, white: 255 } });
+    await nextTick();
+    const gamma = thumb('gamma');
+    expect(gamma.getAttribute('aria-valuenow')).toBe('1');
+    // gamma 1.00 with black 0 / white 255 → midtone at ~128.
+    expect(gamma.getAttribute('aria-valuetext')).toMatch(/^Gamma 1\.00, midtone at 12[78]$/);
+    expect(gamma.getAttribute('aria-valuemin')).toBe('0.1');
+    expect(gamma.getAttribute('aria-valuemax')).toBe('9.99');
+  });
+});
+
+describe('Levels — keyboard & neighbour clamp', () => {
+  it('ArrowRight/ArrowLeft step the handle by step', async () => {
+    const { model } = mountLevels({ defaultValue: { black: 50 }, step: 5 });
+    await nextTick();
+    keydown(thumb('black'), 'ArrowRight');
+    await nextTick();
+    expect(model.value!.black).toBe(55);
+    keydown(thumb('black'), 'ArrowLeft');
+    keydown(thumb('black'), 'ArrowLeft');
+    await nextTick();
+    expect(model.value!.black).toBe(45);
+  });
+
+  it('gamma steps by gammaStep', async () => {
+    const { model } = mountLevels({ defaultValue: { gamma: 1 }, gammaStep: 0.1 });
+    await nextTick();
+    keydown(thumb('gamma'), 'ArrowRight');
+    await nextTick();
+    expect(model.value!.gamma).toBeCloseTo(1.1, 5);
+  });
+
+  it('black cannot cross white (neighbour clamp, pins instead of swaps)', async () => {
+    const { model } = mountLevels({ defaultValue: { black: 100, white: 110 }, step: 1, minStepsBetweenHandles: 1 });
+    await nextTick();
+    for (let i = 0; i < 40; i++) keydown(thumb('black'), 'ArrowRight');
+    await nextTick();
+    // Pins one minGap (1*1) below white.
+    expect(model.value!.black).toBe(109);
+    expect(model.value!.black).toBeLessThan(model.value!.white);
+  });
+
+  it('Shift+Arrow & Page jump by largeStep', async () => {
+    const { model } = mountLevels({ defaultValue: { black: 50 }, step: 1 });
+    await nextTick();
+    keydown(thumb('black'), 'PageUp');
+    await nextTick();
+    expect(model.value!.black).toBe(60);
+    keydown(thumb('black'), 'ArrowLeft', { shiftKey: true });
+    await nextTick();
+    expect(model.value!.black).toBe(50);
+  });
+
+  it('Home/End jump to the handle lowest/highest legal value', async () => {
+    const { model } = mountLevels({ defaultValue: { black: 50, white: 200 } });
+    await nextTick();
+    keydown(thumb('black'), 'End');
+    await nextTick();
+    // black's legal max is white - minGap = 199.
+    expect(model.value!.black).toBe(199);
+    keydown(thumb('black'), 'Home');
+    await nextTick();
+    expect(model.value!.black).toBe(0);
+  });
+
+  it('disabled: tabindex=-1, aria-disabled, keys do nothing', async () => {
+    const { model } = mountLevels({ defaultValue: { black: 50 }, disabled: true });
+    await nextTick();
+    const black = thumb('black');
+    expect(black.tabIndex).toBe(-1);
+    expect(black.getAttribute('aria-disabled')).toBe('true');
+    keydown(black, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+});
+
+describe('Levels — getOutputCurve via exposed API', () => {
+  it('exposes a 256-length LUT reflecting the current adjustment', async () => {
+    const rootRef = ref<any>(null);
+    const Harness = defineComponent({
+      setup: () => () => h(LevelsRoot, {
+        ref: rootRef,
+        defaultValue: { black: 32, gamma: 1, white: 224, outputBlack: 0, outputWhite: 255 },
+      }, { default: () => h(LevelsTrack, null, { default: () => h(LevelsThumb, { kind: 'black' }) }) }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const lut = rootRef.value.getOutputCurve();
+    expect(lut).toHaveLength(256);
+    expect(lut[0]).toBeCloseTo(0, 3);
+    expect(lut[255]).toBeCloseTo(255, 3);
+    for (let i = 1; i < lut.length; i++) expect(lut[i]!).toBeGreaterThanOrEqual(lut[i - 1]!);
+  });
+
+  it('autoLevels updates black/white from a histogram', async () => {
+    const rootRef = ref<any>(null);
+    const model = ref<LevelsValue | null | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(LevelsRoot, {
+        ref: rootRef,
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: LevelsValue | null | undefined) => { model.value = v; },
+      }, { default: () => h(LevelsTrack, null, { default: () => h(LevelsThumb, { kind: 'black' }) }) }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const hist = Array.from({ length: 256 }, (_, i) => (i >= 80 && i <= 180 ? 100 : 0));
+    rootRef.value.autoLevels(hist);
+    await nextTick();
+    expect(model.value!.black).toBeGreaterThan(0);
+    expect(model.value!.white).toBeLessThan(255);
+    expect(model.value!.black).toBeLessThan(model.value!.white);
+  });
+});
+
+describe('Levels — HandleValue numeric entry', () => {
+  it('composes a number-field bound to the handle and writes back clamped', async () => {
+    const model = ref<LevelsValue | null | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(LevelsRoot, {
+        modelValue: model.value,
+        defaultValue: { black: 50, gamma: 1, white: 200, outputBlack: 0, outputWhite: 255 },
+        'onUpdate:modelValue': (v: LevelsValue | null | undefined) => { model.value = v; },
+      }, {
+        default: () => h(LevelsHandleValue, { kind: 'black' }),
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('input[role="spinbutton"]')!;
+    expect(input).toBeTruthy();
+    expect(input.value).toBe('50');
+    // It carries the handle's neighbour-aware max (white - minGap = 199).
+    expect(input.getAttribute('aria-valuemax')).toBe('199');
+    expect(input.getAttribute('aria-label')).toBe('Black point');
+
+    // Typing past the neighbour clamps to 199, never crossing white.
+    input.value = '240';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    await nextTick();
+    expect(model.value!.black).toBeLessThanOrEqual(199);
+    expect(model.value!.black).toBeLessThan(model.value!.white);
+  });
+
+  it('renders an increment and decrement stepper bound to the handle', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(LevelsRoot, {
+        defaultValue: { black: 50, gamma: 1, white: 200, outputBlack: 0, outputWhite: 255 },
+      }, {
+        default: () => h(LevelsHandleValue, { kind: 'gamma' }),
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('input[role="spinbutton"]')!;
+    expect(input.value).toBe('1');
+    // Gamma field uses the gamma bounds.
+    expect(input.getAttribute('aria-valuemin')).toBe('0.1');
+    expect(input.getAttribute('aria-valuemax')).toBe('9.99');
+  });
+});
diff --git a/vue/primitives/src/canvas/levels/context.ts b/vue/primitives/src/canvas/levels/context.ts
new file mode 100644
index 0000000..73629db
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/context.ts
@@ -0,0 +1,55 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { LevelsHandleKind, LevelsValue } from './utils';
+
+/** Orientation of the levels track. */
+export type LevelsOrientation = 'horizontal' | 'vertical';
+/** Writing direction (flips horizontal pointer/keyboard mapping). */
+export type LevelsDirection = 'ltr' | 'rtl';
+
+/**
+ * Context shared between `LevelsRoot`, `LevelsTrack`, `LevelsThumb`, and
+ * `LevelsHandleValue`.
+ *
+ * Scalar props are plain `Ref<T>` (built with `toRef(() => prop)` in the root —
+ * a reactive getter ref without a `computed` cache). Actions are functions that
+ * apply the neighbour-clamping and commit to the model.
+ */
+export interface LevelsContext {
+  /** The live adjustment (input black/white, gamma factor, output range). */
+  value: Ref<LevelsValue>;
+  /** Keyboard/arrow step for the `0..255` handles. */
+  step: Ref<number>;
+  /** Keyboard step for the gamma handle (`gammaStep`). */
+  gammaStep: Ref<number>;
+  /** Large-step multiplier (Page keys / Shift+Arrow). */
+  largeStep: Ref<number>;
+  /** Minimum gap (in steps) the black handle keeps below white. */
+  minStepsBetweenHandles: Ref<number>;
+  orientation: Ref<LevelsOrientation>;
+  direction: Ref<LevelsDirection>;
+  /** Invert the direction of interaction (independent of `dir`/orientation). */
+  inverted: Ref<boolean>;
+  disabled: Ref<boolean>;
+  /** Geometry reference for pointer math (set by `LevelsTrack`). */
+  trackRef: Ref<HTMLElement | null>;
+  /** Set a handle to `next`, applying step rounding + neighbour clamping + commit. */
+  setHandle: (kind: LevelsHandleKind, next: number) => void;
+  /** Nudge a handle by `delta` (already in the handle's units), clamped + committed. */
+  nudgeHandle: (kind: LevelsHandleKind, delta: number) => void;
+  /** Jump a handle to its lowest (`'min'`) or highest (`'max'`) legal value. */
+  jumpHandle: (kind: LevelsHandleKind, edge: 'min' | 'max') => void;
+  /** Map a pointer event to a `0..255` value along the track (min when unmeasured). */
+  getValueFromPointer: (event: PointerEvent) => number;
+  /** Start a drag for `kind` from `LevelsTrack`/`LevelsThumb` pointer-down. */
+  startDrag: (kind: LevelsHandleKind, event: PointerEvent) => void;
+  /** Build the 256-entry output LUT for the current adjustment. */
+  getOutputCurve: (size?: number) => number[];
+  /** Apply auto black/white from an optional luminance histogram. */
+  autoLevels: (histogram?: number[]) => void;
+}
+
+export const {
+  inject: useLevelsContext,
+  provide: provideLevelsContext,
+} = useContextFactory<LevelsContext>('levels');
diff --git a/vue/primitives/src/canvas/levels/demo.vue b/vue/primitives/src/canvas/levels/demo.vue
new file mode 100644
index 0000000..85b7d5b
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/demo.vue
@@ -0,0 +1,121 @@
+<script setup lang="ts">
+import type { LevelsValue } from '@robonen/primitives';
+import { LevelsRoot, LevelsThumb, LevelsTrack } from '@robonen/primitives';
+import { ref } from 'vue';
+
+// A starting adjustment: clip the shadows a touch, lift midtones, pull highlights.
+const levels = ref<LevelsValue>({
+  black: 20,
+  gamma: 1.2,
+  white: 235,
+  outputBlack: 0,
+  outputWhite: 255,
+});
+
+/** Build the SVG polyline points for a 0..255 → 0..255 output curve. */
+function curvePoints(curve: number[]): string {
+  const last = curve.length - 1;
+  return curve
+    .map((out, i) => {
+      const x = (i / last) * 100;
+      const y = 100 - (out / 255) * 100; // SVG y grows downward
+      return `${x.toFixed(2)},${y.toFixed(2)}`;
+    })
+    .join(' ');
+}
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-md space-y-6 p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <span class="font-medium">Levels</span>
+      <span class="font-mono text-fg-muted">
+        {{ levels.black }} · {{ levels.gamma.toFixed(2) }} · {{ levels.white }}
+      </span>
+    </div>
+
+    <LevelsRoot v-model="levels" class="space-y-6">
+      <template #default="{ value, getOutputCurve }">
+        <!-- Output-curve preview, driven by the live LUT -->
+        <div class="relative aspect-[2/1] w-full overflow-hidden rounded-card border border-border bg-bg-inset shadow-(--shadow-card)">
+          <svg viewBox="0 0 100 100" preserveAspectRatio="none" class="absolute inset-0 size-full">
+            <!-- identity reference -->
+            <line x1="0" y1="100" x2="100" y2="0" class="stroke-border-strong" stroke-width="0.5" stroke-dasharray="2 2" />
+            <!-- the live levels curve -->
+            <polyline
+              :points="curvePoints(getOutputCurve(64))"
+              fill="none"
+              class="stroke-accent"
+              stroke-width="1.5"
+              vector-effect="non-scaling-stroke"
+            />
+          </svg>
+        </div>
+
+        <!-- Input track: black / gamma / white thumbs on a shadows→highlights rail -->
+        <div class="space-y-2">
+          <span class="text-xs font-medium text-fg-muted">Input</span>
+          <LevelsTrack
+            class="relative h-3 w-full touch-none select-none rounded-full"
+            style="background: linear-gradient(to right, #000, #fff)"
+          >
+            <LevelsThumb
+              kind="black"
+              class="absolute top-1/2 size-4 -translate-x-1/2 -translate-y-1/2 cursor-ew-resize touch-none rounded-full border-2 border-white bg-black shadow-md outline-none ring-1 ring-black/40 transition-transform focus-visible:ring-2 focus-visible:ring-ring hover:scale-115"
+            />
+            <LevelsThumb
+              kind="gamma"
+              class="absolute top-1/2 size-4 -translate-x-1/2 -translate-y-1/2 cursor-ew-resize touch-none rounded-full border-2 border-white bg-[#888] shadow-md outline-none ring-1 ring-black/40 transition-transform focus-visible:ring-2 focus-visible:ring-ring hover:scale-115"
+            />
+            <LevelsThumb
+              kind="white"
+              class="absolute top-1/2 size-4 -translate-x-1/2 -translate-y-1/2 cursor-ew-resize touch-none rounded-full border-2 border-border-strong bg-white shadow-md outline-none ring-1 ring-black/20 transition-transform focus-visible:ring-2 focus-visible:ring-ring hover:scale-115"
+            />
+          </LevelsTrack>
+        </div>
+
+        <!-- Output track: the outputBlack / outputWhite pair -->
+        <div class="space-y-2">
+          <span class="text-xs font-medium text-fg-muted">Output</span>
+          <LevelsTrack
+            class="relative h-3 w-full touch-none select-none rounded-full"
+            style="background: linear-gradient(to right, #000, #fff)"
+          >
+            <LevelsThumb
+              kind="outputBlack"
+              class="absolute top-1/2 size-4 -translate-x-1/2 -translate-y-1/2 cursor-ew-resize touch-none rounded-full border-2 border-white bg-black shadow-md outline-none ring-1 ring-black/40 transition-transform focus-visible:ring-2 focus-visible:ring-ring hover:scale-115"
+            />
+            <LevelsThumb
+              kind="outputWhite"
+              class="absolute top-1/2 size-4 -translate-x-1/2 -translate-y-1/2 cursor-ew-resize touch-none rounded-full border-2 border-border-strong bg-white shadow-md outline-none ring-1 ring-black/20 transition-transform focus-visible:ring-2 focus-visible:ring-ring hover:scale-115"
+            />
+          </LevelsTrack>
+        </div>
+
+        <!-- Live readout of all five handles -->
+        <dl class="grid grid-cols-5 gap-2 rounded-card bg-bg-inset p-3 text-center font-mono text-xs">
+          <div>
+            <dt class="text-fg-subtle">Black</dt>
+            <dd class="text-fg">{{ value.black }}</dd>
+          </div>
+          <div>
+            <dt class="text-fg-subtle">Gamma</dt>
+            <dd class="text-fg">{{ value.gamma.toFixed(2) }}</dd>
+          </div>
+          <div>
+            <dt class="text-fg-subtle">White</dt>
+            <dd class="text-fg">{{ value.white }}</dd>
+          </div>
+          <div>
+            <dt class="text-fg-subtle">Out lo</dt>
+            <dd class="text-fg">{{ value.outputBlack }}</dd>
+          </div>
+          <div>
+            <dt class="text-fg-subtle">Out hi</dt>
+            <dd class="text-fg">{{ value.outputWhite }}</dd>
+          </div>
+        </dl>
+      </template>
+    </LevelsRoot>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/levels/index.ts b/vue/primitives/src/canvas/levels/index.ts
new file mode 100644
index 0000000..3cf8fd1
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/index.ts
@@ -0,0 +1,33 @@
+export { default as LevelsRoot } from './LevelsRoot.vue';
+export { default as LevelsTrack } from './LevelsTrack.vue';
+export { default as LevelsThumb } from './LevelsThumb.vue';
+export { default as LevelsHandleValue } from './LevelsHandleValue.vue';
+export type { LevelsRootEmits, LevelsRootProps } from './LevelsRoot.vue';
+export type { LevelsTrackProps } from './LevelsTrack.vue';
+export type { LevelsThumbProps } from './LevelsThumb.vue';
+export type { LevelsHandleValueProps } from './LevelsHandleValue.vue';
+export {
+  provideLevelsContext,
+  useLevelsContext,
+  type LevelsContext,
+  type LevelsDirection,
+  type LevelsOrientation,
+} from './context';
+export {
+  LEVELS_DEFAULT_VALUE,
+  LEVELS_GAMMA_MAX,
+  LEVELS_GAMMA_MIN,
+  LEVELS_HANDLE_LABELS,
+  LEVELS_INPUT_MAX,
+  LEVELS_INPUT_MIN,
+  applyLevels,
+  buildOutputCurve,
+  clampHandle,
+  computeAutoLevels,
+  gammaMidtoneLevel,
+  handleBounds,
+  handleValue,
+  isOutputHandle,
+  roundClamp,
+} from './utils';
+export type { LevelsHandleKind, LevelsValue } from './utils';
diff --git a/vue/primitives/src/canvas/levels/utils.ts b/vue/primitives/src/canvas/levels/utils.ts
new file mode 100644
index 0000000..7c019d9
--- /dev/null
+++ b/vue/primitives/src/canvas/levels/utils.ts
@@ -0,0 +1,228 @@
+import { clamp } from '@robonen/stdlib';
+import { toLUT } from '../../internal/spline';
+
+/** The five handles a levels adjustment exposes. */
+export type LevelsHandleKind = 'black' | 'gamma' | 'white' | 'outputBlack' | 'outputWhite';
+
+/**
+ * A complete levels adjustment.
+ *
+ * - `black` / `white` — input clipping points in the `0..255` domain
+ *   (`black < white`).
+ * - `gamma` — midtone factor in `0.1..9.99`; `1` is linear, `> 1` brightens
+ *   midtones, `< 1` darkens them.
+ * - `outputBlack` / `outputWhite` — the output range the remapped tones are
+ *   compressed into (`0..255`).
+ */
+export interface LevelsValue {
+  black: number;
+  gamma: number;
+  white: number;
+  outputBlack: number;
+  outputWhite: number;
+}
+
+/** Inclusive bounds for the input/output `0..255` domain. */
+export const LEVELS_INPUT_MIN = 0;
+export const LEVELS_INPUT_MAX = 255;
+/** Inclusive bounds for the gamma factor. */
+export const LEVELS_GAMMA_MIN = 0.1;
+export const LEVELS_GAMMA_MAX = 9.99;
+
+/** The canonical identity adjustment (a no-op pass-through). */
+export const LEVELS_DEFAULT_VALUE: LevelsValue = Object.freeze({
+  black: 0,
+  gamma: 1,
+  white: 255,
+  outputBlack: 0,
+  outputWhite: 255,
+});
+
+/** Round to `decimals` places, killing float drift, then clamp to `[lo, hi]`. */
+export function roundClamp(value: number, lo: number, hi: number, decimals = 0): number {
+  const rounded = decimals > 0
+    ? Number((Math.round(value / 10 ** -decimals) / 10 ** decimals).toFixed(decimals))
+    : Math.round(value);
+  return clamp(rounded, lo, hi);
+}
+
+/** Whether `kind` is one of the two `0..255` output handles. */
+export function isOutputHandle(kind: LevelsHandleKind): boolean {
+  return kind === 'outputBlack' || kind === 'outputWhite';
+}
+
+/**
+ * The effective input level the gamma midpoint maps to: the point in
+ * `[black, white]` whose normalised position is `0.5 ** gamma`. With `gamma = 1`
+ * this is the literal midpoint `(black + white) / 2`; raising gamma slides the
+ * midtone anchor toward black. Reported in `aria-valuetext` so screen-reader
+ * users hear where the midtone sits.
+ */
+export function gammaMidtoneLevel(value: Pick<LevelsValue, 'black' | 'gamma' | 'white'>): number {
+  const span = value.white - value.black;
+  if (span <= 0) return value.black;
+  const t = 0.5 ** value.gamma;
+  return Math.round(value.black + t * span);
+}
+
+/**
+ * Apply a levels adjustment to a single normalised-ish `0..255` input sample,
+ * returning the `0..255` output. The pipeline is the standard one:
+ *
+ * 1. remap `[black, white]` → `[0, 1]` (clipping outside the window),
+ * 2. apply gamma as `t ** (1 / gamma)` (so `gamma > 1` lifts midtones),
+ * 3. expand `[0, 1]` → `[outputBlack, outputWhite]`.
+ */
+export function applyLevels(input: number, value: LevelsValue): number {
+  const { black, gamma, white, outputBlack, outputWhite } = value;
+  const span = white - black;
+  // Degenerate window (black >= white): everything below the point is output
+  // black, everything at/above is output white — a hard threshold.
+  if (span <= 0) {
+    return input < black ? outputBlack : outputWhite;
+  }
+  let t = (input - black) / span;
+  t = t < 0 ? 0 : t > 1 ? 1 : t;
+  // gamma > 1 brightens midtones → exponent 1/gamma.
+  const corrected = gamma === 1 ? t : t ** (1 / gamma);
+  return outputBlack + corrected * (outputWhite - outputBlack);
+}
+
+/**
+ * Build the `size`-length lookup table (default 256) that applies `value` across
+ * the full `0..255` input domain, via the shared `toLUT` sampler. Each entry is
+ * the `0..255` output for input index `i`. The curve is monotonic non-decreasing
+ * when `outputBlack <= outputWhite` (the normal case), and is exactly the
+ * identity for the default adjustment.
+ */
+export function buildOutputCurve(value: LevelsValue, size = 256): number[] {
+  // toLUT samples `fn` across `[x0, x1]` → here the full input domain. The LUT
+  // index IS the input level, so we sample over `0..(size-1)` mapped to
+  // `0..255`.
+  return toLUT(
+    input => applyLevels(input, value),
+    size,
+    LEVELS_INPUT_MIN,
+    LEVELS_INPUT_MAX,
+  );
+}
+
+/**
+ * Neighbour-clamp a candidate value for `kind` against the rest of `value`,
+ * preserving the structural invariants:
+ *
+ * - `black` stays in `[0, white - minGap]`,
+ * - `white` stays in `[black + minGap, 255]`,
+ * - `gamma` stays in `[0.1, 9.99]`,
+ * - `outputBlack` stays in `[0, outputWhite]`,
+ * - `outputWhite` stays in `[outputBlack, 255]`.
+ *
+ * `minGap` (`minStepsBetweenHandles * step`) keeps `black` strictly below
+ * `white`. A value pushed past its neighbour PINS at the boundary rather than
+ * swapping order.
+ */
+export function clampHandle(
+  kind: LevelsHandleKind,
+  candidate: number,
+  value: LevelsValue,
+  minGap: number,
+): number {
+  switch (kind) {
+    case 'black':
+      return clamp(candidate, LEVELS_INPUT_MIN, value.white - minGap);
+    case 'white':
+      return clamp(candidate, value.black + minGap, LEVELS_INPUT_MAX);
+    case 'gamma':
+      return clamp(candidate, LEVELS_GAMMA_MIN, LEVELS_GAMMA_MAX);
+    case 'outputBlack':
+      return clamp(candidate, LEVELS_INPUT_MIN, value.outputWhite);
+    case 'outputWhite':
+      return clamp(candidate, value.outputBlack, LEVELS_INPUT_MAX);
+  }
+}
+
+/** Per-kind inclusive bounds reported as `aria-valuemin` / `aria-valuemax`. */
+export function handleBounds(kind: LevelsHandleKind, value: LevelsValue, minGap: number): { min: number; max: number } {
+  switch (kind) {
+    case 'black':
+      return { min: LEVELS_INPUT_MIN, max: value.white - minGap };
+    case 'white':
+      return { min: value.black + minGap, max: LEVELS_INPUT_MAX };
+    case 'gamma':
+      return { min: LEVELS_GAMMA_MIN, max: LEVELS_GAMMA_MAX };
+    case 'outputBlack':
+      return { min: LEVELS_INPUT_MIN, max: value.outputWhite };
+    case 'outputWhite':
+      return { min: value.outputBlack, max: LEVELS_INPUT_MAX };
+  }
+}
+
+/** Read the current numeric value for `kind` out of a `LevelsValue`. */
+export function handleValue(kind: LevelsHandleKind, value: LevelsValue): number {
+  return value[kind];
+}
+
+/** Human-readable label for each handle, used for `aria-label`. */
+export const LEVELS_HANDLE_LABELS: Record<LevelsHandleKind, string> = {
+  black: 'Black point',
+  gamma: 'Gamma',
+  white: 'White point',
+  outputBlack: 'Output black',
+  outputWhite: 'Output white',
+};
+
+/**
+ * Derive auto black/white points from a 256-bin luminance `histogram` by
+ * clipping `clipFraction` of the total pixel count off each tail (Photoshop's
+ * default is 0.1 % per side). Gamma is left at `1` and the output range is left
+ * full. Returns the default adjustment when the histogram is empty/flat so the
+ * caller never produces a degenerate (black >= white) window.
+ */
+export function computeAutoLevels(
+  histogram: number[] | undefined,
+  clipFraction = 0.001,
+): Pick<LevelsValue, 'black' | 'white'> {
+  if (!histogram || histogram.length === 0) {
+    return { black: LEVELS_DEFAULT_VALUE.black, white: LEVELS_DEFAULT_VALUE.white };
+  }
+  let total = 0;
+  for (let i = 0; i < histogram.length; i++) total += histogram[i]!;
+  if (total <= 0) {
+    return { black: LEVELS_DEFAULT_VALUE.black, white: LEVELS_DEFAULT_VALUE.white };
+  }
+
+  const lastBin = histogram.length - 1;
+  const clipCount = total * clipFraction;
+  const toLevel = (bin: number): number => Math.round((bin / lastBin) * LEVELS_INPUT_MAX);
+
+  // Walk in from the dark end until `clipCount` pixels are accounted for.
+  let acc = 0;
+  let blackBin = 0;
+  for (let i = 0; i <= lastBin; i++) {
+    acc += histogram[i]!;
+    if (acc > clipCount) {
+      blackBin = i;
+      break;
+    }
+  }
+
+  // Walk in from the bright end.
+  acc = 0;
+  let whiteBin = lastBin;
+  for (let i = lastBin; i >= 0; i--) {
+    acc += histogram[i]!;
+    if (acc > clipCount) {
+      whiteBin = i;
+      break;
+    }
+  }
+
+  let black = toLevel(blackBin);
+  let white = toLevel(whiteBin);
+  // Guarantee a valid window even on near-flat data.
+  if (white <= black) {
+    black = LEVELS_DEFAULT_VALUE.black;
+    white = LEVELS_DEFAULT_VALUE.white;
+  }
+  return { black, white };
+}
diff --git a/vue/primitives/src/canvas/time-ruler/TimeRulerCursor.vue b/vue/primitives/src/canvas/time-ruler/TimeRulerCursor.vue
new file mode 100644
index 0000000..84cb25f
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/TimeRulerCursor.vue
@@ -0,0 +1,52 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * An optional playhead / hover indicator, positioned at a given `time` (seconds)
+ * projected through the ruler's `scale`. Purely presentational (`role` defaults
+ * to `'presentation'` and it is `aria-hidden`) — it conveys no semantics of its
+ * own; the playhead time should be announced by the host (e.g. a transport
+ * control), not the ruler.
+ *
+ * When the projected pixel falls outside the visible width the cursor is hidden
+ * (rendered with `visibility: hidden`) so an off-screen playhead does not bleed
+ * past the ruler edges; the element stays in the tree for stable transitions.
+ */
+export interface TimeRulerCursorProps extends PrimitiveProps {
+  /** Playhead / hover time in seconds. */
+  time: number;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useTimeRulerContext } from './context';
+
+const { time, as = 'div' } = defineProps<TimeRulerCursorProps>();
+
+const { forwardRef } = useForwardExpose();
+
+const ctx = useTimeRulerContext();
+
+const px = computed(() => ctx.scale(time));
+
+const style = computed(() => ({
+  position: 'absolute' as const,
+  left: `${px.value}px`,
+}));
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="presentation"
+    aria-hidden="true"
+    :data-time="time"
+    :style="style"
+  >
+    <slot :time="time" :px="px" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/time-ruler/TimeRulerLabel.vue b/vue/primitives/src/canvas/time-ruler/TimeRulerLabel.vue
new file mode 100644
index 0000000..43e35be
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/TimeRulerLabel.vue
@@ -0,0 +1,42 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Tick } from '../../internal/scale';
+
+/**
+ * The text label for a tick (`tick.label`). Rendered for `major` ticks in the
+ * default tickers; `aria-hidden` so the visual labels do not duplicate the
+ * screen-reader summary. Positioned at `tick.px` like `TimeRulerTick`; the
+ * default slot falls back to `tick.label` so it works without a slot.
+ */
+export interface TimeRulerLabelProps extends PrimitiveProps {
+  /** The tick whose label to render. */
+  tick: Tick;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+
+const { tick, as = 'span' } = defineProps<TimeRulerLabelProps>();
+
+const { forwardRef } = useForwardExpose();
+
+const style = computed(() => ({
+  position: 'absolute' as const,
+  left: `${tick.px}px`,
+}));
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    :data-value="tick.value"
+    :style="style"
+  >
+    <slot :tick="tick">{{ tick.label }}</slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/time-ruler/TimeRulerRoot.vue b/vue/primitives/src/canvas/time-ruler/TimeRulerRoot.vue
new file mode 100644
index 0000000..731be5a
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/TimeRulerRoot.vue
@@ -0,0 +1,405 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { TimeRulerDirection, TimeRulerMode } from './context';
+
+/**
+ * A headless, zoomable time axis: a horizontal ruler of ticks and labels over a
+ * span of `duration` seconds. It renders the accessible `group` (region when
+ * labelled), measures its own width, and builds a `useScale` whose domain is the
+ * visible time window `[offset, offset + width / zoom]` and range `[0, width]`.
+ *
+ * The visible window is driven by two models — `offset` (the left-edge time in
+ * seconds, `v-model:offset`) and `zoom` (pixels-per-second, `v-model:zoom`) —
+ * which stream continuously while panning / zooming; the root additionally emits
+ * SETTLE events (`panCommit`, `zoomCommit`, `rangeChange`) when a gesture ends.
+ *
+ * Tick generation is selected by `mode`: `'seconds'` uses the human time ladder,
+ * `'timecode'` renders `HH:MM:SS:FF` SMPTE labels at `fps` (drop-frame optional),
+ * and `'frames'` renders integer frame numbers. When focusable the root handles
+ * a keyboard layer (Arrow keys pan, Shift+Arrow pans by a major interval, `+` /
+ * `-` zoom about the canvas centre) and optional wheel / drag panning.
+ *
+ * It is usable standalone or embedded in a `Timeline` via `TimeRulerContext`,
+ * which exposes the tick collections, the `scale` / `invert` projectors, the
+ * `offset` / `zoom` models, and the `formatTime` helper. The default slot
+ * surfaces `{ ticks, majorTicks, minorTicks, scale, formatTime }` so consumers
+ * can render their own tick layer; the `TimeRuler*` parts are opt-in.
+ */
+export interface TimeRulerRootProps extends PrimitiveProps {
+  /** Total content duration in seconds. @default 0 */
+  duration?: number;
+  /** Frame rate used by `'timecode'` / `'frames'` modes. @default 30 */
+  fps?: number;
+  /** How tick labels are rendered. @default 'seconds' */
+  mode?: TimeRulerMode;
+  /** Use drop-frame timecode labels (only meaningful in `'timecode'` mode). @default false */
+  dropFrame?: boolean;
+  /** Minimum zoom in pixels-per-second; `zoom` is clamped to this. @default 1 */
+  minZoom?: number;
+  /** Maximum zoom in pixels-per-second; `zoom` is clamped to this. @default 4000 */
+  maxZoom?: number;
+  /** Disable all interaction (keyboard, wheel, drag). @default false */
+  disabled?: boolean;
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
+  dir?: TimeRulerDirection;
+  /** Target pixel spacing between adjacent ticks, forwarded to the tick generator. @default 80 */
+  targetDensity?: number;
+  /** Make the ruler focusable and enable the keyboard layer. @default false */
+  focusable?: boolean;
+  /** Enable wheel panning (and ctrl/cmd+wheel zoom about the pointer). @default false */
+  wheel?: boolean;
+  /** Enable drag-to-pan (x-only). @default false */
+  draggable?: boolean;
+}
+
+// Note: `update:offset` / `update:zoom` are declared by their `defineModel`s and
+// must NOT be re-declared here (a duplicate emit collapses the handler type to
+// `unknown[]`). These are the SETTLE-only events.
+export interface TimeRulerRootEmits {
+  /** Emitted when a pan gesture settles, with the final `offset` (seconds). */
+  panCommit: [offset: number];
+  /** Emitted when a zoom gesture settles, with the final `zoom` (px/s). */
+  zoomCommit: [zoom: number];
+  /** Emitted when the visible window settles, with `[start, end]` in seconds. */
+  rangeChange: [range: [number, number]];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, watch } from 'vue';
+import { clamp } from '@robonen/stdlib';
+import { useElementSize, useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useScale } from '../../internal/scale';
+import type { TickKind } from '../../internal/scale';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useDirection } from '../../utilities/config-provider';
+import { provideTimeRulerContext } from './context';
+import { formatTimeForMode, modeToTickKind, tickFormatFor } from './utils';
+
+const {
+  duration = 0,
+  fps = 30,
+  mode = 'seconds',
+  dropFrame = false,
+  minZoom = 1,
+  maxZoom = 4000,
+  disabled = false,
+  dir,
+  targetDensity = 80,
+  focusable = false,
+  wheel = false,
+  draggable = false,
+  as = 'div',
+} = defineProps<TimeRulerRootProps>();
+
+const emit = defineEmits<TimeRulerRootEmits>();
+
+const direction = useDirection(() => dir);
+const isRtl = computed(() => direction.value === 'rtl');
+
+// Local element ref used for measurement, pointer rect, and drag binding. It is
+// kept independent of `useForwardExpose` so `defineExpose` can run BEFORE
+// `useForwardExpose` (else Vue warns "expose() called only once" and clobbers
+// the merged `$el` / props). The template wires BOTH this ref and `forwardRef`.
+const rootEl = shallowRef<HTMLElement>();
+
+// The ruler measures its own width; `useScale`'s range is `[0, width]`.
+const { width } = useElementSize(rootEl);
+
+// `offset` / `zoom` are the two visible-window models. They stream continuously;
+// `defineModel` emits `update:offset` / `update:zoom` on write.
+const offset = defineModel<number>('offset', { default: 0 });
+const zoom = defineModel<number>('zoom', {
+  default: 100,
+  // Always present a clamped zoom; clamping in the getter keeps an out-of-range
+  // controlled value from leaking into the scale geometry.
+  get: external => clamp(external, minZoom, maxZoom),
+});
+
+const isPanning = shallowRef(false);
+const isZooming = shallowRef(false);
+
+// Pixels-per-second, guarded against degenerate zoom.
+const pxPerSecond = computed(() => Math.max(zoom.value, 1e-6));
+
+// Visible window in seconds: `[offset, offset + width / zoom]`.
+const visibleStart = computed(() => offset.value);
+const visibleEnd = computed(() => offset.value + width.value / pxPerSecond.value);
+
+const tickKind = computed<TickKind>(() => modeToTickKind(mode));
+
+const tickOptions = computed(() => ({
+  fps,
+  dropFrame,
+  targetDensity,
+  format: tickFormatFor(mode, fps),
+}));
+
+const {
+  ticks,
+  majorTicks,
+  minorTicks,
+  scale,
+  invert,
+} = useScale({
+  domain: () => [visibleStart.value, visibleEnd.value] as const,
+  range: () => [0, width.value] as const,
+  // RTL flips the horizontal mapping so the timeline reads right-to-left.
+  rtl: () => isRtl.value,
+  tickKind: () => tickKind.value,
+  tickOptions: () => tickOptions.value,
+});
+
+function formatTime(seconds: number): string {
+  return formatTimeForMode(seconds, mode, fps, dropFrame);
+}
+
+// --- Pan / zoom helpers -----------------------------------------------------
+
+/** Largest seconds-clamp so the window never scrolls entirely past the content. */
+function clampOffset(next: number): number {
+  if (duration <= 0) return Math.max(0, next);
+  const windowSpan = width.value / pxPerSecond.value;
+  // Allow scrolling until the window's left edge reaches the end of content,
+  // but never before zero.
+  const maxOffset = Math.max(0, duration - windowSpan);
+  // When the window is wider than the content, pin to 0.
+  if (windowSpan >= duration) return 0;
+  return clamp(next, 0, maxOffset);
+}
+
+function setOffset(next: number): void {
+  const clamped = clampOffset(next);
+  if (clamped !== offset.value) offset.value = clamped;
+}
+
+function setZoom(next: number, anchorSeconds?: number): void {
+  const clamped = clamp(next, minZoom, maxZoom);
+  if (clamped === zoom.value) return;
+  // Zoom about an anchor time: keep `anchorSeconds` under the same LOCAL pixel.
+  // The local pixel under the OLD geometry is `scale(anchorSeconds)`; solve the
+  // projection for the new offset under the new zoom (RTL flips the axis):
+  //   ltr: px = (t - O') * z'           → O' = t - px / z'
+  //   rtl: px = width - (t - O') * z'    → O' = t - (width - px) / z'
+  if (anchorSeconds !== undefined && width.value > 0) {
+    const px = scale(anchorSeconds);
+    const newOffset = isRtl.value
+      ? anchorSeconds - (width.value - px) / clamped
+      : anchorSeconds - px / clamped;
+    zoom.value = clamped;
+    setOffset(newOffset);
+  }
+  else {
+    zoom.value = clamped;
+  }
+}
+
+/** Minor / major tick intervals in seconds (for keyboard pan steps). */
+const minorInterval = computed(() => {
+  const t = minorTicks.value;
+  if (t.length >= 2) return Math.abs(t[1]!.value - t[0]!.value);
+  const all = ticks.value;
+  if (all.length >= 2) return Math.abs(all[1]!.value - all[0]!.value);
+  // Fall back to one pixel-equivalent second.
+  return 1 / pxPerSecond.value;
+});
+const majorInterval = computed(() => {
+  const t = majorTicks.value;
+  if (t.length >= 2) return Math.abs(t[1]!.value - t[0]!.value);
+  return minorInterval.value * 5;
+});
+
+// --- Settle (commit) plumbing ----------------------------------------------
+
+function emitRangeChange(): void {
+  emit('rangeChange', [visibleStart.value, visibleEnd.value]);
+}
+
+function commitPan(): void {
+  if (!isPanning.value) return;
+  isPanning.value = false;
+  emit('panCommit', offset.value);
+  emitRangeChange();
+}
+
+function commitZoom(): void {
+  if (!isZooming.value) return;
+  isZooming.value = false;
+  emit('zoomCommit', zoom.value);
+  emitRangeChange();
+}
+
+// --- Keyboard layer ---------------------------------------------------------
+
+function onKeydown(event: KeyboardEvent): void {
+  if (disabled || !focusable) return;
+
+  const { key, shiftKey } = event;
+  const altZoom = event.ctrlKey || event.metaKey;
+  // In RTL, ArrowLeft should move the window the opposite way.
+  const dirSign = isRtl.value ? -1 : 1;
+
+  switch (key) {
+    case 'ArrowLeft':
+    case 'ArrowRight': {
+      event.preventDefault();
+      const forward = key === 'ArrowRight' ? 1 : -1;
+      if (altZoom) {
+        // Ctrl/Cmd+Arrow → zoom about centre (alt zoom gesture).
+        isZooming.value = true;
+        const factor = forward === 1 ? 1.2 : 1 / 1.2;
+        const centre = invert(width.value / 2);
+        setZoom(zoom.value * factor, centre);
+        commitZoom();
+      }
+      else {
+        isPanning.value = true;
+        const step = shiftKey ? majorInterval.value : minorInterval.value;
+        setOffset(offset.value + forward * dirSign * step);
+        commitPan();
+      }
+      break;
+    }
+    case '+':
+    case '=': {
+      event.preventDefault();
+      isZooming.value = true;
+      const centre = invert(width.value / 2);
+      setZoom(zoom.value * 1.2, centre);
+      commitZoom();
+      break;
+    }
+    case '-':
+    case '_': {
+      event.preventDefault();
+      isZooming.value = true;
+      const centre = invert(width.value / 2);
+      setZoom(zoom.value / 1.2, centre);
+      commitZoom();
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+// --- Wheel (optional) -------------------------------------------------------
+
+function onWheel(event: WheelEvent): void {
+  if (disabled || !wheel) return;
+  event.preventDefault();
+  if (event.ctrlKey || event.metaKey) {
+    // ctrl/cmd+wheel → zoom about the pointer.
+    isZooming.value = true;
+    const el = rootEl.value;
+    const rect = el?.getBoundingClientRect();
+    const localX = rect ? event.clientX - rect.left : width.value / 2;
+    const anchor = invert(isRtl.value ? width.value - localX : localX);
+    const factor = event.deltaY < 0 ? 1.1 : 1 / 1.1;
+    setZoom(zoom.value * factor, anchor);
+    commitZoom();
+  }
+  else {
+    isPanning.value = true;
+    const deltaPx = event.deltaX !== 0 ? event.deltaX : event.deltaY;
+    const dirSign = isRtl.value ? -1 : 1;
+    setOffset(offset.value + (deltaPx / pxPerSecond.value) * dirSign);
+    commitPan();
+  }
+}
+
+// --- Drag-to-pan (optional, x-only) ----------------------------------------
+
+let dragStartOffset = 0;
+
+usePointerDrag(() => (draggable && !disabled ? rootEl.value ?? null : null), {
+  axis: 'x',
+  disabled: () => disabled || !draggable,
+  onStart: () => {
+    dragStartOffset = offset.value;
+    isPanning.value = true;
+  },
+  onMove: (state) => {
+    const dirSign = isRtl.value ? 1 : -1;
+    setOffset(dragStartOffset + (state.total.x / pxPerSecond.value) * dirSign);
+  },
+  onEnd: () => {
+    commitPan();
+  },
+});
+
+// Re-clamp the offset when geometry that bounds it changes (a wider window or a
+// shorter duration can push the current offset out of range).
+watch([width, pxPerSecond, () => duration], () => {
+  setOffset(offset.value);
+});
+
+provideTimeRulerContext({
+  ticks,
+  majorTicks,
+  minorTicks,
+  scale,
+  invert,
+  offset,
+  zoom,
+  duration: computed(() => duration),
+  fps: computed(() => fps),
+  mode: computed(() => mode),
+  formatTime,
+  isPanning,
+  isZooming,
+  disabled: computed(() => disabled),
+});
+
+// `defineExpose` MUST precede `useForwardExpose` so the composable merges these
+// bindings (plus props + `$el`) instead of `expose()` clobbering them.
+defineExpose({
+  ticks,
+  majorTicks,
+  minorTicks,
+  scale,
+  invert,
+  formatTime,
+  offset,
+  zoom,
+});
+
+const { forwardRef } = useForwardExpose();
+
+// Combine `forwardRef` (consumer-facing expose/`$el` forwarding) with our local
+// `rootEl` (measurement / pointer rect) into one `:ref`.
+function setRootRef(el: unknown): void {
+  forwardRef(el as never);
+  rootEl.value = (el && '$el' in (el as object) ? (el as { $el: HTMLElement }).$el : el) as HTMLElement | undefined;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRootRef"
+    :as="as"
+    role="group"
+    aria-orientation="horizontal"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    data-orientation="horizontal"
+    :data-panning="isPanning ? '' : undefined"
+    :data-zooming="isZooming ? '' : undefined"
+    :dir="direction"
+    :tabindex="focusable && !disabled ? 0 : undefined"
+    @keydown="onKeydown"
+    @wheel="onWheel"
+  >
+    <slot
+      :ticks="ticks"
+      :major-ticks="majorTicks"
+      :minor-ticks="minorTicks"
+      :scale="scale"
+      :format-time="formatTime"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/time-ruler/TimeRulerScreenReaderSummary.vue b/vue/primitives/src/canvas/time-ruler/TimeRulerScreenReaderSummary.vue
new file mode 100644
index 0000000..c75f57f
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/TimeRulerScreenReaderSummary.vue
@@ -0,0 +1,134 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A visually-hidden, `aria-live="polite"` region that announces the visible
+ * window after it settles — the accessible alternative to announcing every tick.
+ *
+ * It debounces on every `offset` / `zoom` / `mode` / `fps` change and, once the
+ * viewport stops moving for `settleDelay` ms, writes a single human summary:
+ * the visible time range, the seconds-per-tick (zoom granularity), and the
+ * frame rate (in frame-based modes). Provide `formatMessage` to fully customise
+ * the announcement.
+ */
+export interface TimeRulerScreenReaderSummaryProps extends PrimitiveProps {
+  /** Debounce before announcing, in milliseconds. @default 400 */
+  settleDelay?: number;
+  /**
+   * Build the announcement string. Receives the settled view (visible `start` /
+   * `end` seconds, `secondsPerTick`, `zoom`, `fps`, `mode`) and the bound
+   * `formatTime` helper. Defaults to a `"Showing <a> to <b>, …"` sentence.
+   */
+  formatMessage?: (view: {
+    start: number;
+    end: number;
+    secondsPerTick: number;
+    zoom: number;
+    fps: number;
+    mode: string;
+    formatTime: (seconds: number) => string;
+  }) => string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { useDebounceFn, useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useTimeRulerContext } from './context';
+
+const {
+  settleDelay = 400,
+  formatMessage,
+  as = 'div',
+} = defineProps<TimeRulerScreenReaderSummaryProps>();
+
+const { forwardRef } = useForwardExpose();
+
+const ctx = useTimeRulerContext();
+
+// The visually-hidden style; same recipe as `VisuallyHidden`.
+const visuallyHidden = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  clipPath: 'inset(50%)',
+  whiteSpace: 'nowrap',
+  border: '0',
+} as const;
+
+const message = ref('');
+
+/** Seconds between adjacent ticks — the announced zoom granularity. */
+const secondsPerTick = computed(() => {
+  const t = ctx.ticks.value;
+  if (t.length >= 2) return Math.abs(t[1]!.value - t[0]!.value);
+  return 0;
+});
+
+/** The visible window `[start, end]` in seconds (from the first/last tick spread + offset/zoom). */
+function visibleRange(): [number, number] {
+  const start = ctx.offset.value;
+  // `invert` is unavailable here without width; derive end from the ticks when
+  // possible, else fall back to the offset. The end is best-effort for SR text.
+  const t = ctx.ticks.value;
+  const end = t.length > 0 ? Math.max(start, t[t.length - 1]!.value) : start;
+  return [start, end];
+}
+
+function defaultMessage(view: {
+  start: number;
+  end: number;
+  secondsPerTick: number;
+  zoom: number;
+  fps: number;
+  mode: string;
+  formatTime: (s: number) => string;
+}): string {
+  const range = `Showing ${view.formatTime(view.start)} to ${view.formatTime(view.end)}`;
+  const grain = view.secondsPerTick > 0
+    ? `, ${view.secondsPerTick.toFixed(view.secondsPerTick < 1 ? 2 : 0)} seconds per tick`
+    : '';
+  const rate = view.mode === 'seconds' ? '' : `, ${view.fps} frames per second`;
+  return `${range}${grain}${rate}.`;
+}
+
+function announce(): void {
+  const [start, end] = visibleRange();
+  const view = {
+    start,
+    end,
+    secondsPerTick: secondsPerTick.value,
+    zoom: ctx.zoom.value,
+    fps: ctx.fps.value,
+    mode: ctx.mode.value,
+    formatTime: ctx.formatTime,
+  };
+  message.value = formatMessage ? formatMessage(view) : defaultMessage(view);
+}
+
+const debouncedAnnounce = useDebounceFn(announce, settleDelay);
+
+watch(
+  () => [ctx.offset.value, ctx.zoom.value, ctx.mode.value, ctx.fps.value],
+  () => { void debouncedAnnounce(); },
+  { immediate: true },
+);
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="status"
+    aria-live="polite"
+    aria-atomic="true"
+    :style="visuallyHidden"
+  >
+    <slot :message="message">{{ message }}</slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/time-ruler/TimeRulerTick.vue b/vue/primitives/src/canvas/time-ruler/TimeRulerTick.vue
new file mode 100644
index 0000000..dafaac0
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/TimeRulerTick.vue
@@ -0,0 +1,46 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Tick } from '../../internal/scale';
+
+/**
+ * A single gridline of the ruler. Consumers usually render their own tick layer
+ * by looping the `ticks` exposed on `TimeRulerRoot`'s default slot, but this
+ * part provides a ready-made, positioned element for the common case.
+ *
+ * It is `aria-hidden` by default (the screen-reader summary announces the window
+ * instead of every tick), reflects `tick.major` on `data-major`, and positions
+ * itself at `tick.px` via an inline `left` (overridable through merged styles).
+ */
+export interface TimeRulerTickProps extends PrimitiveProps {
+  /** The tick to render (from `TimeRulerRoot`'s exposed `ticks`). */
+  tick: Tick;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+
+const { tick, as = 'div' } = defineProps<TimeRulerTickProps>();
+
+const { forwardRef } = useForwardExpose();
+
+const style = computed(() => ({
+  position: 'absolute' as const,
+  left: `${tick.px}px`,
+}));
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    :data-major="tick.major ? '' : undefined"
+    :data-value="tick.value"
+    :style="style"
+  >
+    <slot :tick="tick" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/time-ruler/__test__/TimeRuler.test.ts b/vue/primitives/src/canvas/time-ruler/__test__/TimeRuler.test.ts
new file mode 100644
index 0000000..fe74587
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/__test__/TimeRuler.test.ts
@@ -0,0 +1,319 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { provideConfig } from '../../../utilities/config-provider';
+import { TimeRulerCursor, TimeRulerRoot } from '../index';
+
+// Minimal declarative config wrapper (the package ships no ConfigProvider
+// component; config is provided via `provideConfig` inside a setup).
+const ConfigProvider = defineComponent({
+  props: { dir: { type: String, default: undefined } },
+  setup(props, { slots }) {
+    provideConfig({ dir: () => props.dir as 'ltr' | 'rtl' | undefined });
+    return () => slots.default?.();
+  },
+});
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+interface MountOpts {
+  duration?: number;
+  fps?: number;
+  mode?: 'seconds' | 'timecode' | 'frames';
+  zoom?: number;
+  offset?: number;
+  minZoom?: number;
+  maxZoom?: number;
+  focusable?: boolean;
+  disabled?: boolean;
+  width?: number;
+  dir?: 'ltr' | 'rtl';
+}
+
+// Drive the root through a controlled harness so we can read back `offset` /
+// `zoom`, and give the root a fixed CSS width so its measured geometry is real.
+function mountRuler(opts: MountOpts = {}) {
+  const { width = 600, dir, ...rootProps } = opts;
+  const offset = ref(opts.offset ?? 0);
+  const zoom = ref(opts.zoom ?? 100);
+
+  let exposed: any;
+
+  const Harness = defineComponent({
+    setup() {
+      const setExposed = (el: any) => {
+        exposed = el;
+      };
+      return () => h(ConfigProvider, { dir }, {
+        default: () => h(TimeRulerRoot, {
+          ...rootProps,
+          ref: setExposed,
+          style: { display: 'block', width: `${width}px`, position: 'relative' },
+          offset: offset.value,
+          'onUpdate:offset': (v: number) => { offset.value = v; },
+          zoom: zoom.value,
+          'onUpdate:zoom': (v: number) => { zoom.value = v; },
+        }),
+      });
+    },
+  });
+
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, offset, zoom, getExposed: () => exposed };
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean; ctrlKey?: boolean } = {}): void {
+  const event = new KeyboardEvent('keydown', {
+    key,
+    bubbles: true,
+    cancelable: true,
+    shiftKey: opts.shiftKey ?? false,
+    ctrlKey: opts.ctrlKey ?? false,
+  });
+  el.dispatchEvent(event);
+}
+
+/** Wait a frame for ResizeObserver-backed `useElementSize` to flush. */
+async function settle(): Promise<void> {
+  await nextTick();
+  await new Promise(r => requestAnimationFrame(() => r(null)));
+  await nextTick();
+}
+
+describe('timeRulerRoot — rendering & a11y', () => {
+  it('renders role=group with horizontal orientation', () => {
+    const { wrapper } = mountRuler({ duration: 60 });
+    const root = wrapper.find('[role="group"]');
+    expect(root.exists()).toBe(true);
+    expect(root.attributes('aria-orientation')).toBe('horizontal');
+    expect(root.attributes('data-orientation')).toBe('horizontal');
+  });
+
+  it('reflects aria-disabled / data-disabled when disabled', () => {
+    const { wrapper } = mountRuler({ duration: 60, disabled: true });
+    const root = wrapper.find('[role="group"]');
+    expect(root.attributes('aria-disabled')).toBe('true');
+    expect(root.attributes('data-disabled')).toBe('');
+  });
+
+  it('is focusable (tabindex 0) only when focusable and enabled', () => {
+    const { wrapper: a } = mountRuler({ duration: 60, focusable: true });
+    expect(a.find('[role="group"]').attributes('tabindex')).toBe('0');
+    const { wrapper: b } = mountRuler({ duration: 60 });
+    expect(b.find('[role="group"]').attributes('tabindex')).toBeUndefined();
+    const { wrapper: c } = mountRuler({ duration: 60, focusable: true, disabled: true });
+    expect(c.find('[role="group"]').attributes('tabindex')).toBeUndefined();
+  });
+});
+
+describe('timeRulerRoot — scale & ticks', () => {
+  it('exposes scale/invert that round-trip and ticks that are non-empty', async () => {
+    const { getExposed } = mountRuler({ duration: 60, zoom: 100, width: 600 });
+    await settle();
+    const ex = getExposed();
+    expect(ex).toBeTruthy();
+    // scale/invert round-trip (offset 0, zoom 100 → 1s = 100px).
+    expect(ex.scale(0)).toBeCloseTo(0, 3);
+    expect(ex.scale(1)).toBeCloseTo(100, 3);
+    expect(ex.invert(ex.scale(3.5))).toBeCloseTo(3.5, 3);
+    // ticks span the visible window [0, 6s] → non-empty. (Exposed computed refs
+    // are auto-unwrapped on the public instance proxy, so read them directly.)
+    expect(ex.ticks.length).toBeGreaterThan(0);
+  });
+
+  it('formatTime renders clock labels in seconds mode', () => {
+    const { getExposed } = mountRuler({ duration: 600, mode: 'seconds' });
+    const ex = getExposed();
+    expect(ex.formatTime(0)).toBe('0:00');
+    expect(ex.formatTime(75)).toBe('1:15');
+    expect(ex.formatTime(3661)).toBe('1:01:01');
+  });
+
+  it('formatTime renders HH:MM:SS:FF in timecode mode', () => {
+    const { getExposed } = mountRuler({ duration: 600, mode: 'timecode', fps: 30 });
+    const ex = getExposed();
+    expect(ex.formatTime(0)).toBe('00:00:00:00');
+    // 1.5s @30fps → 1 second + 15 frames.
+    expect(ex.formatTime(1.5)).toBe('00:00:01:15');
+    expect(ex.formatTime(61)).toBe('00:01:01:00');
+  });
+
+  it('produces timecode-formatted tick labels in timecode mode', async () => {
+    const { getExposed } = mountRuler({ duration: 60, mode: 'timecode', fps: 30, zoom: 200, width: 600 });
+    await settle();
+    const ex = getExposed();
+    const labelled = ex.majorTicks.filter((t: any) => t.label);
+    expect(labelled.length).toBeGreaterThan(0);
+    for (const t of labelled) {
+      expect(t.label).toMatch(/^\d{2}:\d{2}:\d{2}:\d{2}$/);
+    }
+  });
+
+  it('formatTime renders bare frame numbers in frames mode', () => {
+    const { getExposed } = mountRuler({ duration: 600, mode: 'frames', fps: 30 });
+    const ex = getExposed();
+    expect(ex.formatTime(0)).toBe('0');
+    expect(ex.formatTime(2)).toBe('60');
+  });
+});
+
+describe('timeRulerRoot — keyboard pan & zoom', () => {
+  it('ArrowRight pans the offset forward', async () => {
+    const { wrapper, offset } = mountRuler({ duration: 600, focusable: true, zoom: 100, width: 600 });
+    await settle();
+    const root = wrapper.find('[role="group"]').element;
+    const before = offset.value;
+    keydown(root, 'ArrowRight');
+    await nextTick();
+    expect(offset.value).toBeGreaterThan(before);
+  });
+
+  it('ArrowLeft is clamped at zero (no negative offset)', async () => {
+    const { wrapper, offset } = mountRuler({ duration: 600, focusable: true, zoom: 100, width: 600, offset: 0 });
+    await settle();
+    const root = wrapper.find('[role="group"]').element;
+    keydown(root, 'ArrowLeft');
+    await nextTick();
+    expect(offset.value).toBe(0);
+  });
+
+  it('Shift+ArrowRight pans by a larger (major) interval than ArrowRight', async () => {
+    const a = mountRuler({ duration: 600, focusable: true, zoom: 100, width: 600 });
+    await settle();
+    keydown(a.wrapper.find('[role="group"]').element, 'ArrowRight');
+    await nextTick();
+    const minorDelta = a.offset.value;
+
+    const b = mountRuler({ duration: 600, focusable: true, zoom: 100, width: 600 });
+    await settle();
+    keydown(b.wrapper.find('[role="group"]').element, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    const majorDelta = b.offset.value;
+
+    expect(majorDelta).toBeGreaterThan(minorDelta);
+  });
+
+  it('+ increases zoom and - decreases it, clamped to min/max', async () => {
+    const { wrapper, zoom } = mountRuler({
+      duration: 600, focusable: true, zoom: 100, minZoom: 50, maxZoom: 300, width: 600,
+    });
+    await settle();
+    const root = wrapper.find('[role="group"]').element;
+
+    keydown(root, '+');
+    await nextTick();
+    expect(zoom.value).toBeGreaterThan(100);
+
+    // Zoom in repeatedly → clamps at maxZoom. Await between presses so the
+    // controlled `zoom` prop propagates back before the next keypress reads it.
+    for (let i = 0; i < 20; i++) {
+      keydown(root, '+');
+      await nextTick();
+    }
+    expect(zoom.value).toBe(300);
+
+    // Zoom out repeatedly → clamps at minZoom.
+    for (let i = 0; i < 30; i++) {
+      keydown(root, '-');
+      await nextTick();
+    }
+    expect(zoom.value).toBe(50);
+  });
+
+  it('does not handle keys when not focusable', async () => {
+    const { wrapper, offset } = mountRuler({ duration: 600, zoom: 100, width: 600 });
+    await settle();
+    const root = wrapper.find('[role="group"]').element;
+    keydown(root, 'ArrowRight');
+    await nextTick();
+    expect(offset.value).toBe(0);
+  });
+});
+
+describe('timeRulerRoot — settle events & state flags', () => {
+  it('emits panCommit and rangeChange on keyboard pan', async () => {
+    const onPan = ref<number[]>([]);
+    const onRange = ref<Array<[number, number]>>([]);
+    const Harness = defineComponent({
+      setup() {
+        const offset = ref(0);
+        const zoom = ref(100);
+        return () => h(TimeRulerRoot, {
+          duration: 600,
+          focusable: true,
+          style: { display: 'block', width: '600px', position: 'relative' },
+          offset: offset.value,
+          'onUpdate:offset': (v: number) => { offset.value = v; },
+          zoom: zoom.value,
+          'onUpdate:zoom': (v: number) => { zoom.value = v; },
+          onPanCommit: (o: number) => { onPan.value.push(o); },
+          onRangeChange: (r: [number, number]) => { onRange.value.push(r); },
+        });
+      },
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    await settle();
+    keydown(w.find('[role="group"]').element, 'ArrowRight');
+    await nextTick();
+    expect(onPan.value.length).toBe(1);
+    expect(onRange.value.length).toBe(1);
+  });
+
+  it('emits zoomCommit on + / -', async () => {
+    const onZoom = ref<number[]>([]);
+    const Harness = defineComponent({
+      setup() {
+        const zoom = ref(100);
+        return () => h(TimeRulerRoot, {
+          duration: 600,
+          focusable: true,
+          style: { display: 'block', width: '600px', position: 'relative' },
+          zoom: zoom.value,
+          'onUpdate:zoom': (v: number) => { zoom.value = v; },
+          onZoomCommit: (z: number) => { onZoom.value.push(z); },
+        });
+      },
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    await settle();
+    keydown(w.find('[role="group"]').element, '+');
+    await nextTick();
+    expect(onZoom.value.length).toBe(1);
+  });
+});
+
+describe('timeRulerCursor', () => {
+  it('positions itself via the ruler scale', async () => {
+    const Harness = defineComponent({
+      setup() {
+        return () => h(TimeRulerRoot, {
+          duration: 600,
+          zoom: 100,
+          offset: 0,
+          style: { display: 'block', width: '600px', position: 'relative' },
+        }, {
+          default: () => h(TimeRulerCursor, { time: 2, 'data-testid': 'cursor' }),
+        });
+      },
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    await settle();
+    const cursor = w.find('[data-testid="cursor"]');
+    expect(cursor.exists()).toBe(true);
+    // time 2s * 100px/s = 200px.
+    expect(cursor.attributes('style')).toContain('left: 200px');
+    expect(cursor.attributes('aria-hidden')).toBe('true');
+    expect(cursor.attributes('role')).toBe('presentation');
+  });
+});
diff --git a/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---keyboard-pan---zoom---increases-zoom-and---decreases-it--clamped-to-min-max-1.png b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---keyboard-pan---zoom---increases-zoom-and---decreases-it--clamped-to-min-max-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---keyboard-pan---zoom---increases-zoom-and---decreases-it--clamped-to-min-max-1.png differ
diff --git a/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---scale---ticks-exposes-scale-invert-that-round-trip-and-ticks-that-are-non-empty-1.png b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---scale---ticks-exposes-scale-invert-that-round-trip-and-ticks-that-are-non-empty-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---scale---ticks-exposes-scale-invert-that-round-trip-and-ticks-that-are-non-empty-1.png differ
diff --git a/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---scale---ticks-produces-timecode-formatted-tick-labels-in-timecode-mode-1.png b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---scale---ticks-produces-timecode-formatted-tick-labels-in-timecode-mode-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/TimeRuler.test.ts/timeRulerRoot---scale---ticks-produces-timecode-formatted-tick-labels-in-timecode-mode-1.png differ
diff --git a/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/debug.test.ts/debug-width-and-ticks-1.png b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/debug.test.ts/debug-width-and-ticks-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/time-ruler/__test__/__screenshots__/debug.test.ts/debug-width-and-ticks-1.png differ
diff --git a/vue/primitives/src/canvas/time-ruler/context.ts b/vue/primitives/src/canvas/time-ruler/context.ts
new file mode 100644
index 0000000..7819461
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/context.ts
@@ -0,0 +1,55 @@
+import type { ComputedRef, Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { Tick } from '../../internal/scale';
+
+/** How tick labels are rendered. */
+export type TimeRulerMode = 'seconds' | 'timecode' | 'frames';
+
+/** Writing direction; mirrors the binary contract used across primitives. */
+export type TimeRulerDirection = 'ltr' | 'rtl';
+
+/**
+ * Context shared between `TimeRulerRoot` and its descendants (`TimeRulerTick`,
+ * `TimeRulerLabel`, `TimeRulerCursor`, `TimeRulerScreenReaderSummary`), and the
+ * surface a future `Timeline` reads to embed a ruler.
+ *
+ * Tick collections and the `scale`/`invert` projectors come straight from the
+ * `useScale` instance the root owns; scalar props are exposed as plain `Ref`s
+ * (built with `toRef(() => prop)` for identity passthrough). `scale` / `invert`
+ * are stable closures safe to call on the pointer hot path.
+ */
+export interface TimeRulerContext {
+  /** All ticks for the visible window. */
+  ticks: ComputedRef<Tick[]>;
+  /** Ticks where `major` is true (labelled / emphasised). */
+  majorTicks: ComputedRef<Tick[]>;
+  /** Ticks where `major` is false. */
+  minorTicks: ComputedRef<Tick[]>;
+  /** Project a time (seconds) to a pixel offset within the ruler. Stable identity. */
+  scale: (seconds: number) => number;
+  /** Invert a pixel offset back to a time (seconds). Stable identity. */
+  invert: (px: number) => number;
+  /** Left edge time (seconds) of the visible window. Two-way via `v-model:offset`. */
+  offset: Ref<number>;
+  /** Zoom in pixels-per-second. Two-way via `v-model:zoom`. */
+  zoom: Ref<number>;
+  /** Total content duration in seconds. */
+  duration: Ref<number>;
+  /** Frame rate used for timecode / frame modes. */
+  fps: Ref<number>;
+  /** Active label mode. */
+  mode: Ref<TimeRulerMode>;
+  /** Format a time (seconds) per the active mode. */
+  formatTime: (seconds: number) => string;
+  /** Whether a pan gesture (keyboard, drag, or wheel) is in progress. */
+  isPanning: Ref<boolean>;
+  /** Whether a zoom gesture is in progress. */
+  isZooming: Ref<boolean>;
+  /** Whether the ruler is disabled (non-interactive). */
+  disabled: Ref<boolean>;
+}
+
+const ctx = useContextFactory<TimeRulerContext>('TimeRulerContext');
+
+export const provideTimeRulerContext = ctx.provide;
+export const useTimeRulerContext = ctx.inject;
diff --git a/vue/primitives/src/canvas/time-ruler/demo.vue b/vue/primitives/src/canvas/time-ruler/demo.vue
new file mode 100644
index 0000000..d374346
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/demo.vue
@@ -0,0 +1,171 @@
+<script setup lang="ts">
+import { TimeRulerCursor, TimeRulerRoot } from '@robonen/primitives';
+import type { TimeRulerMode } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const DURATION = 600; // 10 minutes of content
+
+const offset = ref(0);
+const zoom = ref(40); // pixels per second
+const mode = ref<TimeRulerMode>('timecode');
+const playhead = ref(72);
+
+const modes: TimeRulerMode[] = ['seconds', 'timecode', 'frames'];
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-2xl space-y-4 p-6 text-fg">
+    <div class="flex flex-wrap items-center justify-between gap-3">
+      <div class="space-y-0.5">
+        <div class="text-sm font-medium">Time ruler</div>
+        <div class="font-mono text-xs text-fg-muted">
+          offset {{ offset.toFixed(1) }}s · {{ Math.round(zoom) }} px/s
+        </div>
+      </div>
+
+      <div class="flex items-center gap-1 rounded-lg border border-border bg-bg-inset p-0.5">
+        <button
+          v-for="m in modes"
+          :key="m"
+          type="button"
+          class="rounded-md px-2.5 py-1 text-xs font-medium capitalize transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          :class="mode === m ? 'bg-accent text-accent-fg' : 'text-fg-muted hover:text-fg'"
+          @click="mode = m"
+        >
+          {{ m }}
+        </button>
+      </div>
+    </div>
+
+    <!-- The ruler. The default slot exposes the generated tick collections. -->
+    <TimeRulerRoot
+      v-model:offset="offset"
+      v-model:zoom="zoom"
+      :duration="DURATION"
+      :mode="mode"
+      :fps="30"
+      :min-zoom="6"
+      :max-zoom="240"
+      focusable
+      wheel
+      draggable
+      class="ruler relative h-16 w-full overflow-hidden rounded-card border border-border bg-bg-inset focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <template #default="{ ticks, formatTime }">
+        <!-- Tick layer rendered straight from the slot's `ticks`. -->
+        <div
+          v-for="tick in ticks"
+          :key="tick.value"
+          class="ruler-tick"
+          :class="tick.major ? 'ruler-tick--major' : 'ruler-tick--minor'"
+          :style="{ left: `${tick.px}px` }"
+        >
+          <span v-if="tick.major" class="ruler-tick__label">{{ tick.label }}</span>
+        </div>
+
+        <!-- Playhead cursor, positioned through the ruler's own scale. -->
+        <TimeRulerCursor :time="playhead" class="ruler-cursor">
+          <template #default="{ time }">
+            <span class="ruler-cursor__flag">{{ formatTime(time) }}</span>
+          </template>
+        </TimeRulerCursor>
+      </template>
+    </TimeRulerRoot>
+
+    <div class="flex items-center gap-3">
+      <button
+        type="button"
+        class="rounded-lg border border-border bg-bg-elevated px-3 py-1.5 text-sm font-medium text-fg transition hover:border-border-strong hover:bg-bg-inset focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        @click="zoom = Math.min(240, zoom * 1.4)"
+      >
+        Zoom in
+      </button>
+      <button
+        type="button"
+        class="rounded-lg border border-border bg-bg-elevated px-3 py-1.5 text-sm font-medium text-fg transition hover:border-border-strong hover:bg-bg-inset focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        @click="zoom = Math.max(6, zoom / 1.4)"
+      >
+        Zoom out
+      </button>
+      <label class="flex flex-1 items-center gap-2 text-xs text-fg-muted">
+        Playhead
+        <input
+          v-model.number="playhead"
+          type="range"
+          min="0"
+          :max="DURATION"
+          step="1"
+          class="flex-1 accent-(--accent)"
+        >
+      </label>
+    </div>
+
+    <p class="text-xs text-fg-subtle">
+      Drag to pan, scroll to scroll, Ctrl/Cmd + scroll to zoom, or focus the ruler and use Arrow / +/- keys.
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.ruler {
+  cursor: grab;
+  touch-action: none;
+}
+.ruler[data-panning] {
+  cursor: grabbing;
+}
+
+.ruler-tick {
+  position: absolute;
+  bottom: 0;
+  width: 1px;
+  background: var(--border-strong);
+}
+.ruler-tick--minor {
+  height: 0.5rem;
+  opacity: 0.7;
+}
+.ruler-tick--major {
+  height: 1.25rem;
+  background: var(--fg-subtle);
+}
+.ruler-tick__label {
+  position: absolute;
+  top: -1.1rem;
+  left: 0.25rem;
+  font-family: var(--font-mono);
+  font-size: 0.6875rem;
+  white-space: nowrap;
+  color: var(--fg-muted);
+}
+
+/* Playhead cursor. */
+.ruler-cursor {
+  top: 0;
+  bottom: 0;
+  width: 0;
+}
+.ruler-cursor::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  margin-left: -1px;
+  background: var(--accent);
+}
+.ruler-cursor__flag {
+  position: absolute;
+  bottom: 0.25rem;
+  left: 0;
+  transform: translateX(-50%);
+  padding: 1px 6px;
+  border-radius: 9999px;
+  font-family: var(--font-mono);
+  font-size: 0.625rem;
+  font-weight: 600;
+  white-space: nowrap;
+  color: var(--accent-fg);
+  background: var(--accent);
+}
+</style>
diff --git a/vue/primitives/src/canvas/time-ruler/index.ts b/vue/primitives/src/canvas/time-ruler/index.ts
new file mode 100644
index 0000000..353c790
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/index.ts
@@ -0,0 +1,12 @@
+export { default as TimeRulerRoot } from './TimeRulerRoot.vue';
+export type { TimeRulerRootProps, TimeRulerRootEmits } from './TimeRulerRoot.vue';
+export { default as TimeRulerTick } from './TimeRulerTick.vue';
+export type { TimeRulerTickProps } from './TimeRulerTick.vue';
+export { default as TimeRulerLabel } from './TimeRulerLabel.vue';
+export type { TimeRulerLabelProps } from './TimeRulerLabel.vue';
+export { default as TimeRulerCursor } from './TimeRulerCursor.vue';
+export type { TimeRulerCursorProps } from './TimeRulerCursor.vue';
+export { default as TimeRulerScreenReaderSummary } from './TimeRulerScreenReaderSummary.vue';
+export type { TimeRulerScreenReaderSummaryProps } from './TimeRulerScreenReaderSummary.vue';
+export { provideTimeRulerContext, useTimeRulerContext } from './context';
+export type { TimeRulerContext, TimeRulerMode, TimeRulerDirection } from './context';
diff --git a/vue/primitives/src/canvas/time-ruler/utils.ts b/vue/primitives/src/canvas/time-ruler/utils.ts
new file mode 100644
index 0000000..251aa9e
--- /dev/null
+++ b/vue/primitives/src/canvas/time-ruler/utils.ts
@@ -0,0 +1,65 @@
+import type { TickKind } from '../../internal/scale';
+import { formatClock, formatFrames, formatTimecode, secondsToFrames } from '../../internal/scale';
+import type { TimeRulerMode } from './context';
+
+/**
+ * Map a {@link TimeRulerMode} to the {@link TickKind} its `useScale` should use.
+ *
+ * The ruler's scale domain is always in SECONDS, so both frame-based modes route
+ * through the `'timecode'` ticker — which converts the seconds domain to an
+ * integer-frame ladder internally (positions never drift) while keeping
+ * `domain` / `range` in seconds. A `format` override (see {@link tickFormatFor})
+ * then chooses between SMPTE timecode and bare frame numbers.
+ *
+ * - `'seconds'`  → `'time'`     (human time ladder, `M:SS` / `H:MM:SS` labels)
+ * - `'timecode'` → `'timecode'` (SMPTE `HH:MM:SS:FF` labels)
+ * - `'frames'`   → `'timecode'` (frame-aligned ticks, frame-number labels)
+ */
+export function modeToTickKind(mode: TimeRulerMode): TickKind {
+  switch (mode) {
+    case 'timecode':
+    case 'frames':
+      return 'timecode';
+    case 'seconds':
+    default:
+      return 'time';
+  }
+}
+
+/**
+ * A `format` callback (seconds → label) for the active `mode`, or `undefined`
+ * to let the ticker apply its default. Only `'frames'` needs an override (it
+ * borrows the timecode ticker's frame-aligned geometry but labels as frame
+ * numbers); `'seconds'` and `'timecode'` use their generators' defaults.
+ */
+export function tickFormatFor(
+  mode: TimeRulerMode,
+  fps: number,
+): ((seconds: number) => string) | undefined {
+  if (mode !== 'frames') return undefined;
+  return (seconds: number) => formatFrames(secondsToFrames(seconds, fps));
+}
+
+/**
+ * Format a time (in seconds) for display per the active {@link TimeRulerMode}.
+ *
+ * - `'seconds'`  → wall-clock string via {@link formatClock}
+ * - `'timecode'` → SMPTE timecode via {@link formatTimecode} (drop-frame aware)
+ * - `'frames'`   → integer frame number via {@link formatFrames}
+ */
+export function formatTimeForMode(
+  seconds: number,
+  mode: TimeRulerMode,
+  fps: number,
+  dropFrame = false,
+): string {
+  switch (mode) {
+    case 'timecode':
+      return formatTimecode(seconds, fps, dropFrame);
+    case 'frames':
+      return formatFrames(secondsToFrames(seconds, fps));
+    case 'seconds':
+    default:
+      return formatClock(seconds);
+  }
+}
diff --git a/vue/primitives/src/canvas/timeline/TimelineClip.vue b/vue/primitives/src/canvas/timeline/TimelineClip.vue
new file mode 100644
index 0000000..2b81319
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineClip.vue
@@ -0,0 +1,201 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A clip block. Positioned by the shared scale (`left = scale(start)`,
+ * `width = scale(start + duration) - scale(start)` — real layout pixels, never a
+ * CSS transform-scale). It is a roving-focus stop (single Root tab-stop → roving
+ * between clips in time order), `role="group"` / `aria-roledescription="clip"`
+ * with a descriptive label (label + start/duration timecode), `aria-selected`,
+ * and `data-selected` / `data-dragging` / `data-locked`.
+ *
+ * Dragging (via `usePointerDrag`) converts the pointer x-delta to a time delta
+ * (snapped to clip edges / playhead / markers / grid) for a move, and the
+ * y-delta crosses lanes (drop onto another track). Keyboard: Arrow Left/Right
+ * nudge the selected clip(s) by a frame (Shift = 1 s), Arrow Up/Down move across
+ * tracks, Delete removes.
+ */
+export interface TimelineClipProps extends PrimitiveProps {
+  /** Id of the clip this block renders. */
+  clipId: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, shallowRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { getDirectionAwareKey } from '../../utilities/roving-focus/utils';
+import { useTimelineContext } from './context';
+
+const { clipId, as = 'div' } = defineProps<TimelineClipProps>();
+
+const ctx = useTimelineContext();
+const el = shallowRef<HTMLElement | null>(null);
+
+const clip = computed(() => ctx.clipLookup.value.get(clipId));
+const selected = computed(() => ctx.selectedClipIds.value.has(clipId));
+const dragging = computed(() => ctx.draggingClipId.value === clipId);
+const locked = computed(() => !!clip.value?.locked);
+
+// This clip is the roving tab-stop when it is the Root's single tab-stop id (the
+// first selected clip in time order, else the first clip). The id is computed
+// once in the Root, so this is an O(1) equality check (not an O(N) scan per clip).
+const isTabStop = computed(() => ctx.tabStopClipId.value === clipId);
+
+// Pixel geometry from the shared scale (real layout px).
+const left = computed(() => {
+  const c = clip.value;
+  if (!c) return 0;
+  return Math.min(ctx.scale(c.start), ctx.scale(c.start + c.duration));
+});
+const width = computed(() => {
+  const c = clip.value;
+  if (!c) return 0;
+  return Math.abs(ctx.scale(c.start + c.duration) - ctx.scale(c.start));
+});
+
+const ariaLabel = computed(() => {
+  const c = clip.value;
+  if (!c) return 'clip';
+  const name = c.label ?? clipId;
+  return `${name}, start ${ctx.formatTimecode(c.start)}, duration ${ctx.formatTimecode(c.duration)}`;
+});
+
+// ── element registration for roving focus + marquee ──────────────────────────
+watch(el, (node, _prev) => {
+  if (node) ctx.registerClipEl(clipId, node);
+});
+onBeforeUnmount(() => ctx.unregisterClipEl(clipId));
+
+// ── drag (x → time move, y → cross-track) ────────────────────────────────────
+let startStart = 0;
+let startTrackId = '';
+const dragExclude = new Set<string>([clipId]);
+
+/** Which track lane sits under a client-y point (DOM hit-test on `[data-track-id]`). */
+function trackIdAtClientY(clientX: number, clientY: number): string | undefined {
+  const target = document.elementFromPoint(clientX, clientY);
+  const row = target?.closest('[data-track-id]') as HTMLElement | null;
+  return row?.dataset['trackId'];
+}
+
+usePointerDrag(() => (ctx.disabled.value || locked.value ? null : el.value), {
+  axis: 'both',
+  disabled: () => ctx.disabled.value || locked.value,
+  stopPropagation: true,
+  onStart: () => {
+    const c = clip.value;
+    if (!c) return false;
+    startStart = c.start;
+    startTrackId = c.trackId;
+    // Select this clip on grab (non-additive) so the drag affects it.
+    if (!selected.value) ctx.selectClip(clipId, false);
+    return undefined;
+  },
+  onMove: (state) => {
+    const c = clip.value;
+    if (!c) return;
+    // x → time. Convert the cumulative pixel delta to seconds via px-per-second.
+    const dirSign = ctx.direction.value === 'rtl' ? -1 : 1;
+    const deltaSeconds = (state.total.x / ctx.pxPerSecond.value) * dirSign;
+    const rawStart = Math.max(0, startStart + deltaSeconds);
+    const snapped = ctx.snapTime(rawStart, dragExclude);
+    // y → cross-track: hit-test the lane under the pointer.
+    const trackId = trackIdAtClientY(state.point.x, state.point.y) ?? startTrackId;
+    ctx.moveClip(clipId, snapped, trackId, true);
+  },
+  onEnd: () => {
+    ctx.commitMutation();
+  },
+});
+
+// ── keyboard ──────────────────────────────────────────────────────────────────
+function onKeydown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  // Roving navigation between clips (handled here so we control time order).
+  const key = getDirectionAwareKey(event.key, ctx.direction.value);
+
+  switch (key) {
+    case 'ArrowLeft':
+    case 'ArrowRight': {
+      // Shift+Arrow without a clip-move modifier still nudges; we always nudge
+      // the SELECTED clips (this one is selected on focus via roving).
+      event.preventDefault();
+      const sign = key === 'ArrowRight' ? 1 : -1;
+      const step = event.shiftKey ? 1 : (ctx.fps.value > 0 ? 1 / ctx.fps.value : 1);
+      // Ensure this clip is in the selection before nudging.
+      if (!selected.value) ctx.selectClip(clipId, false);
+      ctx.nudgeSelected(sign * step);
+      break;
+    }
+    case 'ArrowUp':
+    case 'ArrowDown': {
+      event.preventDefault();
+      if (!selected.value) ctx.selectClip(clipId, false);
+      ctx.moveSelectedToAdjacentTrack(key === 'ArrowDown' ? 1 : -1);
+      break;
+    }
+    case 'Home':
+    case 'End': {
+      // Move roving focus to the first / last clip in time order.
+      event.preventDefault();
+      const order = ctx.orderedClipIds.value;
+      const targetId = key === 'Home' ? order[0] : order[order.length - 1];
+      if (targetId && targetId !== clipId) ctx.focusClip(targetId);
+      break;
+    }
+    case 'Delete':
+    case 'Backspace': {
+      event.preventDefault();
+      if (!selected.value) ctx.selectClip(clipId, false);
+      ctx.removeSelected();
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+function onPointerDownSelect(event: PointerEvent): void {
+  if (ctx.disabled.value || event.button !== 0) return;
+  // Additive selection with Shift/Meta.
+  if (event.shiftKey || event.metaKey || event.ctrlKey) ctx.selectClip(clipId, true);
+  else if (!selected.value) ctx.selectClip(clipId, false);
+  el.value?.focus();
+}
+
+function setRef(node: unknown): void {
+  el.value = (node && typeof node === 'object' && '$el' in node ? (node as { $el: HTMLElement }).$el : node) as HTMLElement | null;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRef"
+    :as="as"
+    role="group"
+    aria-roledescription="clip"
+    :aria-label="ariaLabel"
+    :aria-selected="selected"
+    :data-clip-id="clipId"
+    :data-selected="selected ? '' : undefined"
+    :data-dragging="dragging ? '' : undefined"
+    :data-locked="locked ? '' : undefined"
+    :tabindex="ctx.disabled.value ? undefined : (isTabStop ? 0 : -1)"
+    :style="{
+      position: 'absolute',
+      left: `${left}px`,
+      width: `${width}px`,
+    }"
+    @keydown="onKeydown"
+    @pointerdown="onPointerDownSelect"
+  >
+    <slot
+      :clip="clip"
+      :selected="selected"
+      :dragging="dragging"
+      :locked="locked"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineClipHandle.vue b/vue/primitives/src/canvas/timeline/TimelineClipHandle.vue
new file mode 100644
index 0000000..9b1b110
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineClipHandle.vue
@@ -0,0 +1,138 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A trim handle on a clip edge. It is `role="slider"` (horizontal) over the
+ * clip's trim range in seconds, with `aria-valuemin` / `aria-valuemax` /
+ * `aria-valuenow` and an `aria-valuetext` timecode — so trims are keyboard
+ * operable AND announced. Dragging trims the start edge (`side: 'start'`) or the
+ * end edge (`side: 'end'`), snapped to clip edges / playhead / markers / grid and
+ * clamped so duration stays `> 0`. Arrow keys trim by one frame (Shift = 1 s).
+ *
+ * Render it inside a `TimelineClip`'s default slot, absolutely positioned at the
+ * clip's left / right edge.
+ */
+export interface TimelineClipHandleProps extends PrimitiveProps {
+  /** Which edge this handle trims. */
+  side: 'start' | 'end';
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { getDirectionAwareKey } from '../../utilities/roving-focus/utils';
+import { useTimelineContext } from './context';
+
+const { side, as = 'span' } = defineProps<TimelineClipHandleProps>();
+
+// A handle must live inside a clip; find its clip id from the data attribute on
+// the nearest clip ancestor at interaction time (kept simple via a prop-less
+// lookup through the DOM is avoided — instead we read the clip from context by
+// the closest `[data-clip-id]`). To stay self-contained the handle accepts the
+// clip via the closest clip element's dataset.
+const ctx = useTimelineContext();
+const el = shallowRef<HTMLElement | null>(null);
+
+/** The owning clip id, resolved from the nearest `[data-clip-id]` ancestor. */
+function ownerClipId(): string | undefined {
+  return (el.value?.closest('[data-clip-id]') as HTMLElement | null)?.dataset['clipId'];
+}
+
+const clip = computed(() => {
+  const id = ownerClipId();
+  return id ? ctx.clipLookup.value.get(id) : undefined;
+});
+
+const locked = computed(() => !!clip.value?.locked);
+
+// Slider value semantics: the handle's value is the edge time it controls.
+const valueNow = computed(() => {
+  const c = clip.value;
+  if (!c) return 0;
+  return side === 'start' ? c.start : c.start + c.duration;
+});
+const valueMin = computed(() => (side === 'start' ? 0 : (clip.value?.start ?? 0)));
+const valueMax = computed(() => {
+  const c = clip.value;
+  if (!c) return ctx.duration.value;
+  return side === 'start' ? c.start + c.duration : ctx.duration.value || Number.MAX_SAFE_INTEGER;
+});
+const valueText = computed(() => ctx.formatTimecode(valueNow.value));
+
+// ── trimming ──────────────────────────────────────────────────────────────────
+function applyTrim(edgeTime: number): void {
+  const c = clip.value;
+  if (!c) return;
+  const exclude = new Set([c.id]);
+  const snapped = ctx.snapTime(edgeTime, exclude);
+  if (side === 'start') {
+    // Trimming the start: keep the end fixed; duration shrinks/grows.
+    const end = c.start + c.duration;
+    const nextStart = Math.min(Math.max(0, snapped), end - 1e-4);
+    ctx.trimClip(c.id, nextStart, end - nextStart, true);
+  }
+  else {
+    // Trimming the end: keep the start fixed.
+    const nextEnd = Math.max(snapped, c.start + 1e-4);
+    ctx.trimClip(c.id, c.start, nextEnd - c.start, true);
+  }
+}
+
+let startEdge = 0;
+
+usePointerDrag(() => (ctx.disabled.value || locked.value ? null : el.value), {
+  axis: 'x',
+  disabled: () => ctx.disabled.value || locked.value,
+  stopPropagation: true,
+  onStart: () => {
+    startEdge = valueNow.value;
+    return undefined;
+  },
+  onMove: (state) => {
+    const dirSign = ctx.direction.value === 'rtl' ? -1 : 1;
+    const deltaSeconds = (state.total.x / ctx.pxPerSecond.value) * dirSign;
+    applyTrim(startEdge + deltaSeconds);
+  },
+  onEnd: () => {
+    ctx.commitMutation();
+  },
+});
+
+function onKeydown(event: KeyboardEvent): void {
+  if (ctx.disabled.value || locked.value) return;
+  const key = getDirectionAwareKey(event.key, ctx.direction.value);
+  if (key !== 'ArrowLeft' && key !== 'ArrowRight') return;
+  event.preventDefault();
+  const sign = key === 'ArrowRight' ? 1 : -1;
+  const step = event.shiftKey ? 1 : (ctx.fps.value > 0 ? 1 / ctx.fps.value : 1);
+  applyTrim(valueNow.value + sign * step);
+  ctx.commitMutation();
+}
+
+function setRef(node: unknown): void {
+  el.value = (node && typeof node === 'object' && '$el' in node ? (node as { $el: HTMLElement }).$el : node) as HTMLElement | null;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRef"
+    :as="as"
+    role="slider"
+    aria-orientation="horizontal"
+    :aria-label="side === 'start' ? 'Trim start' : 'Trim end'"
+    :aria-valuemin="valueMin"
+    :aria-valuemax="valueMax"
+    :aria-valuenow="valueNow"
+    :aria-valuetext="valueText"
+    :data-side="side"
+    :data-locked="locked ? '' : undefined"
+    :aria-disabled="ctx.disabled.value || locked ? true : undefined"
+    :tabindex="ctx.disabled.value || locked ? undefined : 0"
+    @keydown="onKeydown"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineMarker.vue b/vue/primitives/src/canvas/timeline/TimelineMarker.vue
new file mode 100644
index 0000000..2676e02
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineMarker.vue
@@ -0,0 +1,72 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A marker pin at `marker.time`. Positioned at `scale(marker.time)`. It is a
+ * roving-focus stop, `role="button"` with an `aria-label` (label + timecode).
+ */
+export interface TimelineMarkerProps extends PrimitiveProps {
+  /** Id of the marker this pin renders. */
+  markerId: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, shallowRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useTimelineContext } from './context';
+
+const { markerId, as = 'button' } = defineProps<TimelineMarkerProps>();
+
+const ctx = useTimelineContext();
+const el = shallowRef<HTMLElement | null>(null);
+
+const marker = computed(() => ctx.markerLookup.value.get(markerId));
+const left = computed(() => ctx.scale(marker.value?.time ?? 0));
+
+const ariaLabel = computed(() => {
+  const m = marker.value;
+  if (!m) return 'marker';
+  const name = m.label ?? 'Marker';
+  return `${name}, ${ctx.formatTimecode(m.time)}`;
+});
+
+// First marker in time order is the roving tab-stop.
+const isTabStop = computed(() => ctx.orderedMarkerIds.value[0] === markerId);
+
+watch(el, (node) => {
+  if (node) ctx.registerMarkerEl(markerId, node);
+});
+onBeforeUnmount(() => ctx.unregisterMarkerEl(markerId));
+
+function onClick(): void {
+  const m = marker.value;
+  if (!m || ctx.disabled.value) return;
+  ctx.setCurrentTime(m.time, false);
+  ctx.commitScrub();
+}
+
+function setRef(node: unknown): void {
+  el.value = (node && typeof node === 'object' && '$el' in node ? (node as { $el: HTMLElement }).$el : node) as HTMLElement | null;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRef"
+    :as="as"
+    :role="as === 'button' ? undefined : 'button'"
+    :type="as === 'button' ? 'button' : undefined"
+    :aria-label="ariaLabel"
+    :data-marker-id="markerId"
+    :tabindex="ctx.disabled.value ? undefined : (isTabStop ? 0 : -1)"
+    :style="{
+      position: 'absolute',
+      left: `${left}px`,
+      top: '0',
+    }"
+    @click="onClick"
+  >
+    <slot :marker="marker" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelinePlayhead.vue b/vue/primitives/src/canvas/timeline/TimelinePlayhead.vue
new file mode 100644
index 0000000..8003cf7
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelinePlayhead.vue
@@ -0,0 +1,116 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The canonical playhead scrubber. `role="slider"` over `[0, duration]` with
+ * `aria-valuenow` = `currentTime`, an `aria-valuetext` timecode, horizontal
+ * orientation, and the default `aria-label` `'Playhead'`. Positioned at
+ * `scale(currentTime)`. Drag scrubs (snapped to the frame grid); Arrow keys step
+ * one frame (Shift = 1 s), Home / End jump to 0 / duration.
+ *
+ * It is the Root's single keyboard scrub stop — `tabindex` 0 when interactive.
+ */
+export interface TimelinePlayheadProps extends PrimitiveProps {
+  /** Accessible label. @default 'Playhead' */
+  label?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { getDirectionAwareKey } from '../../utilities/roving-focus/utils';
+import { useTimelineContext } from './context';
+
+const { label = 'Playhead', as = 'div' } = defineProps<TimelinePlayheadProps>();
+
+const ctx = useTimelineContext();
+const el = shallowRef<HTMLElement | null>(null);
+
+const left = computed(() => ctx.scale(ctx.currentTime.value));
+const valueText = computed(() => ctx.formatTimecode(ctx.currentTime.value));
+const durationMax = computed(() => ctx.duration.value || Number.MAX_SAFE_INTEGER);
+
+let startTime = 0;
+
+usePointerDrag(() => (ctx.disabled.value ? null : el.value), {
+  axis: 'x',
+  disabled: () => ctx.disabled.value,
+  stopPropagation: true,
+  onStart: () => {
+    startTime = ctx.currentTime.value;
+    return undefined;
+  },
+  onMove: (state) => {
+    const dirSign = ctx.direction.value === 'rtl' ? -1 : 1;
+    const deltaSeconds = (state.total.x / ctx.pxPerSecond.value) * dirSign;
+    ctx.setCurrentTime(ctx.snapToFrame(startTime + deltaSeconds), true);
+  },
+  onEnd: () => {
+    ctx.commitScrub();
+  },
+});
+
+function step(seconds: number): void {
+  ctx.setCurrentTime(ctx.snapToFrame(ctx.currentTime.value + seconds), false);
+  ctx.commitScrub();
+}
+
+function onKeydown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const key = getDirectionAwareKey(event.key, ctx.direction.value);
+  const frame = ctx.fps.value > 0 ? 1 / ctx.fps.value : 1;
+  switch (key) {
+    case 'ArrowLeft':
+      event.preventDefault();
+      step(event.shiftKey ? -1 : -frame);
+      break;
+    case 'ArrowRight':
+      event.preventDefault();
+      step(event.shiftKey ? 1 : frame);
+      break;
+    case 'Home':
+      event.preventDefault();
+      ctx.setCurrentTime(0, false);
+      ctx.commitScrub();
+      break;
+    case 'End':
+      event.preventDefault();
+      ctx.setCurrentTime(ctx.duration.value, false);
+      ctx.commitScrub();
+      break;
+    default:
+      break;
+  }
+}
+
+function setRef(node: unknown): void {
+  el.value = (node && typeof node === 'object' && '$el' in node ? (node as { $el: HTMLElement }).$el : node) as HTMLElement | null;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRef"
+    :as="as"
+    role="slider"
+    aria-orientation="horizontal"
+    :aria-label="label"
+    :aria-valuemin="0"
+    :aria-valuemax="durationMax"
+    :aria-valuenow="ctx.currentTime.value"
+    :aria-valuetext="valueText"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :tabindex="ctx.disabled.value ? undefined : 0"
+    :style="{
+      position: 'absolute',
+      left: `${left}px`,
+      top: '0',
+    }"
+    @keydown="onKeydown"
+  >
+    <slot :current-time="ctx.currentTime.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineRoot.vue b/vue/primitives/src/canvas/timeline/TimelineRoot.vue
new file mode 100644
index 0000000..dba033d
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineRoot.vue
@@ -0,0 +1,738 @@
+<script lang="ts">
+import type { Ref } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Direction } from '../../utilities/config-provider';
+import type { TimelineClip, TimelineMarker, TimelineTrack } from './utils';
+import type { TimelineClipChange, TimelineTrackChange } from './changes';
+
+/**
+ * Root of the headless multi-track timeline (video/audio editor). It owns the
+ * track / clip / marker data plus the playhead (`currentTime`), horizontal scroll
+ * (`offset`), zoom (`pxPerSecond`), and selection — all two-way via `v-model` or
+ * uncontrolled via `default*`. The public arrays are reconciled into internal
+ * `shallowRef` Maps for O(1) reads and identity-stable per-item computeds.
+ *
+ * The COORDINATE MODEL is load-bearing: `pxPerSecond` is applied as real
+ * horizontal LAYOUT pixels (clip widths are genuine px, never a CSS
+ * `scale(zoom)`), so a `useScale` projects the visible window
+ * `[offset, offset + width/pxPerSecond]` → `[0, width]`. The vertical axis is
+ * fixed-height track lanes and is NOT zoomed.
+ *
+ * Transient drag/trim/scrub positions are written to an in-flight overlay and
+ * committed to the model on pointerup (`commitMutation`); an external `v-model`
+ * write during a gesture is ignored (the `isMutating` early-return) so it never
+ * clobbers the live drag. Granular `@clips-change` / `@tracks-change` are emitted
+ * alongside `v-model` so consumers may own their data via `applyClipChanges` /
+ * `applyTrackChanges`.
+ *
+ * Provides `TimelineContext` to every part: the scale, the shared snap engine
+ * (clip edges + playhead + markers + grid), the clip/track/playhead actions, and
+ * the roving-focus registry.
+ */
+export interface TimelineRootProps extends PrimitiveProps {
+  /** Uncontrolled initial tracks (ignored when `v-model:tracks` is bound). */
+  defaultTracks?: TimelineTrack[];
+  /** Uncontrolled initial clips. */
+  defaultClips?: TimelineClip[];
+  /** Uncontrolled initial markers. */
+  defaultMarkers?: TimelineMarker[];
+  /** Uncontrolled initial playhead time (seconds). @default 0 */
+  defaultCurrentTime?: number;
+  /** Uncontrolled initial left-edge time (seconds). @default 0 */
+  defaultOffset?: number;
+  /** Uncontrolled initial zoom in pixels-per-second. @default 100 */
+  defaultPxPerSecond?: number;
+  /** Uncontrolled initial selected clip ids. */
+  defaultSelectedClipIds?: string[];
+  /**
+   * Total content duration in seconds. When omitted it is auto-derived from the
+   * clips (largest `start + duration`).
+   * @default auto
+   */
+  duration?: number;
+  /** Minimum zoom in pixels-per-second; `pxPerSecond` is clamped to this. @default 2 */
+  minPxPerSecond?: number;
+  /** Maximum zoom in pixels-per-second. @default 2000 */
+  maxPxPerSecond?: number;
+  /** Frame rate (timecode + frame snapping + keyboard nudge). @default 30 */
+  fps?: number;
+  /**
+   * Snap step in seconds. When omitted it defaults to one frame (`1 / fps`).
+   * @default 1/fps
+   */
+  snapStep?: number;
+  /** Enable magnetic snapping to clip edges / playhead / markers / grid. @default true */
+  snapping?: boolean;
+  /** Snap radius in pixels. @default 8 */
+  snapThresholdPx?: number;
+  /** Default track-lane height in pixels (fixed; NOT zoomed). @default 64 */
+  trackHeight?: number;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
+  dir?: Direction;
+}
+
+// `update:*` events are declared by their `defineModel`s and must NOT be
+// re-declared here. These are the granular change + settle events.
+export interface TimelineRootEmits {
+  /** Granular clip mutations (move/trim/split/remove/add/select). */
+  clipsChange: [changes: TimelineClipChange[]];
+  /** Granular track mutations (flag toggles / resize / add / remove). */
+  tracksChange: [changes: TimelineTrackChange[]];
+  /** Emitted when a clip drag/trim gesture settles, with the affected ids. */
+  clipCommit: [ids: string[]];
+  /** Emitted when a scrub gesture settles, with the final time (seconds). */
+  scrubCommit: [time: number];
+  /** Emitted when the selected-clip set changes, with the new ids. */
+  selectionChange: [ids: string[]];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, triggerRef, watch } from 'vue';
+import { clamp } from '@robonen/stdlib';
+import { useElementSize, useForwardExpose, useId } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useDirection } from '../../utilities/config-provider';
+import { useScale } from '../../internal/scale';
+import { edgeTargets, gridTargets, pointTargets, useSnapping } from '../../internal/snapping';
+import type { SnapTarget } from '../../internal/snapping';
+import { provideTimelineContext } from './context';
+import type { TimelineContext, TimelineMarqueeRect } from './context';
+import { clipsDuration, snapToFrame, timeToTimecode } from './utils';
+
+const {
+  defaultTracks,
+  defaultClips,
+  defaultMarkers,
+  defaultCurrentTime,
+  defaultOffset,
+  defaultPxPerSecond,
+  defaultSelectedClipIds,
+  duration: durationProp,
+  minPxPerSecond = 2,
+  maxPxPerSecond = 2000,
+  fps = 30,
+  snapStep,
+  snapping = true,
+  snapThresholdPx = 8,
+  trackHeight = 64,
+  disabled = false,
+  dir,
+  as = 'div',
+} = defineProps<TimelineRootProps>();
+
+const emit = defineEmits<TimelineRootEmits>();
+
+const timelineId = useId(undefined, 'timeline').value;
+const direction = useDirection(() => dir);
+
+// ── models (controlled + uncontrolled) ──────────────────────────────────────
+const localTracks = shallowRef<TimelineTrack[]>(defaultTracks ? defaultTracks.slice() : []);
+const tracks = defineModel<TimelineTrack[]>('tracks', {
+  get: external => external ?? localTracks.value,
+  set: (value) => {
+    localTracks.value = value;
+    return value;
+  },
+});
+
+const localClips = shallowRef<TimelineClip[]>(defaultClips ? defaultClips.slice() : []);
+const clips = defineModel<TimelineClip[]>('clips', {
+  get: external => external ?? localClips.value,
+  set: (value) => {
+    localClips.value = value;
+    return value;
+  },
+});
+
+const localMarkers = shallowRef<TimelineMarker[]>(defaultMarkers ? defaultMarkers.slice() : []);
+const markers = defineModel<TimelineMarker[]>('markers', {
+  get: external => external ?? localMarkers.value,
+  set: (value) => {
+    localMarkers.value = value;
+    return value;
+  },
+});
+
+const currentTime = defineModel<number>('currentTime', { default: undefined as unknown as number });
+if (currentTime.value === undefined) currentTime.value = defaultCurrentTime ?? 0;
+
+const offset = defineModel<number>('offset', { default: undefined as unknown as number });
+if (offset.value === undefined) offset.value = defaultOffset ?? 0;
+
+const pxPerSecond = defineModel<number>('pxPerSecond', {
+  default: undefined as unknown as number,
+  // Always present a clamped zoom so an out-of-range controlled value never
+  // leaks into the scale geometry.
+  get: external => clamp(external ?? defaultPxPerSecond ?? 100, minPxPerSecond, maxPxPerSecond),
+});
+if (pxPerSecond.value === undefined) pxPerSecond.value = defaultPxPerSecond ?? 100;
+
+const selectedModel = defineModel<string[]>('selectedClipIds', {
+  default: undefined as unknown as string[],
+});
+if (selectedModel.value === undefined) selectedModel.value = defaultSelectedClipIds ?? [];
+
+// ── element measurement ──────────────────────────────────────────────────────
+const rootEl = shallowRef<HTMLElement>();
+const viewportEl = shallowRef<HTMLElement | null>(null);
+// The tracks viewport reports its width; fall back to the root pre-mount.
+const { width: rootWidth } = useElementSize(rootEl);
+const { width: vpWidth } = useElementSize(viewportEl);
+const viewportWidth = computed(() => vpWidth.value || rootWidth.value);
+
+// ── derived state (immutable shallow Maps) ───────────────────────────────────
+const trackLookup = shallowRef(new Map<string, TimelineTrack>());
+const clipLookup = shallowRef(new Map<string, TimelineClip>());
+const markerLookup = shallowRef(new Map<string, TimelineMarker>());
+const selectedClipIds = shallowRef(new Set<string>(selectedModel.value ?? []));
+const marquee = shallowRef<TimelineMarqueeRect | null>(null);
+
+const isMutating = shallowRef(false);
+const draggingClipId = shallowRef<string | null>(null);
+// Ids touched by the in-flight gesture (committed on pointerup).
+const dirtyClipIds = new Set<string>();
+
+function reconcileTracks(): void {
+  const arr = tracks.value ?? [];
+  const map = trackLookup.value;
+  const seen = new Set<string>();
+  for (const t of arr) {
+    seen.add(t.id);
+    map.set(t.id, t);
+  }
+  for (const id of map.keys()) if (!seen.has(id)) map.delete(id);
+  triggerRef(trackLookup);
+}
+
+function reconcileClips(): void {
+  // During an active gesture the model array is stale on purpose; don't clobber
+  // the live overlay positions until pointerup commits them.
+  if (isMutating.value) return;
+  const arr = clips.value ?? [];
+  const map = clipLookup.value;
+  const seen = new Set<string>();
+  for (const c of arr) {
+    seen.add(c.id);
+    map.set(c.id, c);
+  }
+  for (const id of map.keys()) if (!seen.has(id)) map.delete(id);
+  triggerRef(clipLookup);
+}
+
+function reconcileMarkers(): void {
+  const arr = markers.value ?? [];
+  const map = markerLookup.value;
+  const seen = new Set<string>();
+  for (const m of arr) {
+    seen.add(m.id);
+    map.set(m.id, m);
+  }
+  for (const id of map.keys()) if (!seen.has(id)) map.delete(id);
+  triggerRef(markerLookup);
+}
+
+watch(tracks, reconcileTracks, { immediate: true });
+watch(clips, reconcileClips, { immediate: true });
+watch(markers, reconcileMarkers, { immediate: true });
+
+// External selection writes sync the Set (skip during a gesture).
+watch(selectedModel, (ids) => {
+  if (isMutating.value) return;
+  const next = ids ?? [];
+  // Skip the rebuild when the incoming ids already match the live Set — this
+  // watcher also fires on our own `commitSelection` write, and we don't want a
+  // redundant Set allocation / downstream re-render on the round-trip.
+  const cur = selectedClipIds.value;
+  if (next.length === cur.size && next.every(id => cur.has(id))) return;
+  selectedClipIds.value = new Set(next);
+}, { deep: true });
+
+// ── ordering (for roving focus + duration) ───────────────────────────────────
+const trackIds = computed(() => (tracks.value ?? []).map(t => t.id));
+
+const orderedClipIds = computed(() => {
+  const arr = [...clipLookup.value.values()];
+  arr.sort((a, b) => a.start - b.start || a.id.localeCompare(b.id));
+  return arr.map(c => c.id);
+});
+
+const orderedMarkerIds = computed(() => {
+  const arr = [...markerLookup.value.values()];
+  arr.sort((a, b) => a.time - b.time || a.id.localeCompare(b.id));
+  return arr.map(m => m.id);
+});
+
+// The single roving tab-stop: the first selected clip in time order, else the
+// first clip. Computed once here (O(N)) so each `TimelineClip` does an O(1)
+// equality check instead of scanning `orderedClipIds` itself (which was O(N) per
+// clip → O(N^2) on every selection change).
+const tabStopClipId = computed<string | undefined>(() => {
+  const order = orderedClipIds.value;
+  const sel = selectedClipIds.value;
+  if (sel.size > 0) {
+    for (const id of order) if (sel.has(id)) return id;
+  }
+  return order[0];
+});
+
+const duration = computed(() => {
+  if (durationProp !== undefined && durationProp > 0) return durationProp;
+  const fromClips = clipsDuration(clipLookup.value.values());
+  // Keep markers/playhead within range too.
+  let max = fromClips;
+  for (const m of markerLookup.value.values()) if (m.time > max) max = m.time;
+  if (currentTime.value > max) max = currentTime.value;
+  return max;
+});
+
+// ── coordinate model (zoom = px-per-second; vertical lanes fixed) ────────────
+const effectivePxPerSecond = computed(() => Math.max(pxPerSecond.value, 1e-6));
+const visibleStart = computed(() => offset.value);
+const visibleEnd = computed(() => offset.value + viewportWidth.value / effectivePxPerSecond.value);
+const isRtl = computed(() => direction.value === 'rtl');
+
+const { scale, invert: rawInvert } = useScale({
+  domain: () => [visibleStart.value, visibleEnd.value] as const,
+  range: () => [0, viewportWidth.value] as const,
+  rtl: () => isRtl.value,
+  tickKind: 'none',
+});
+
+// Guard projection until the viewport is measured: a zero-width viewport would
+// invert every pixel to the same time. Return 0 (not NaN) pre-measure.
+function invert(px: number): number {
+  if (viewportWidth.value <= 0) return 0;
+  return rawInvert(px);
+}
+
+const effectiveSnapStep = computed(() => {
+  if (snapStep !== undefined && snapStep > 0) return snapStep;
+  return fps > 0 ? 1 / fps : 1;
+});
+
+function snapFrame(seconds: number): number {
+  return snapToFrame(seconds, fps);
+}
+
+function formatTimecode(seconds: number): string {
+  return timeToTimecode(seconds, fps);
+}
+
+// ── shared snap engine ───────────────────────────────────────────────────────
+// Targets are pre-projected to pixels via `scale`; rebuilt reactively. A dragged
+// clip excludes its own ids at call time via `snapTime`.
+//
+// The pool is split into four independently-memoized parts so a clip-move drag
+// frame (which only mutates `clipLookup`) does NOT rebuild the grid / marker /
+// playhead targets. The grid in particular emits one object per snap step across
+// the visible window (thousands at low zoom); rebuilding it every pointermove was
+// pure churn since `offset`/`pxPerSecond`/window/step are constant during a drag.
+const project = (v: number): number => scale(v);
+
+// Clip edges (left/right/center) — carry the clip id so a clip can skip its own.
+// Only this part re-runs per drag frame (and the dragged clip is excluded at
+// call time, so the change is a same-size reshuffle).
+const clipEdgeTargets = computed<SnapTarget[]>(() => {
+  if (!snapping) return [];
+  const rects = [...clipLookup.value.values()].map(c => ({
+    left: c.start,
+    right: c.start + c.duration,
+    top: 0,
+    bottom: 0,
+    id: c.id,
+  }));
+  return edgeTargets(rects, 'x', project);
+});
+
+// Playhead — depends only on `currentTime` (+ scale).
+const playheadTargets = computed<SnapTarget[]>(() => {
+  if (!snapping) return [];
+  return pointTargets([currentTime.value], 'playhead', 'x', project, ['__playhead__']);
+});
+
+// Markers — depend only on `markerLookup` (+ scale).
+const markerPointTargets = computed<SnapTarget[]>(() => {
+  if (!snapping) return [];
+  const markerVals = [...markerLookup.value.values()];
+  return pointTargets(
+    markerVals.map(m => m.time),
+    'marker',
+    'x',
+    project,
+    markerVals.map(m => m.id),
+  );
+});
+
+// Frame grid across the visible window — the expensive part (one entry per step).
+// Depends only on the window + step (+ scale's window deps), none of which change
+// while a clip is being moved, so it stays cached across the whole gesture.
+const gridSnapTargets = computed<SnapTarget[]>(() => {
+  if (!snapping) return [];
+  return gridTargets(visibleStart.value, visibleEnd.value, effectiveSnapStep.value, project, 'x');
+});
+
+const snapTargets = computed<SnapTarget[]>(() => {
+  if (!snapping) return [];
+  // Concatenate the cached pools. During a drag only `clipEdgeTargets` is dirty,
+  // so this is a reference copy — no per-target object allocation.
+  return [
+    ...clipEdgeTargets.value,
+    ...playheadTargets.value,
+    ...markerPointTargets.value,
+    ...gridSnapTargets.value,
+  ];
+});
+
+const snapEngine = useSnapping({
+  // Snapping is also gated on a measured viewport: pre-measure, `scale` collapses
+  // every value to px 0, so a snap would magnetise everything to one target.
+  enabled: () => snapping && !disabled && viewportWidth.value > 0,
+  thresholdPx: () => snapThresholdPx,
+  axis: 'x',
+  project: (value: number) => scale(value),
+  targets: () => snapTargets.value,
+  // Playhead out-pulls markers out-pull edges out-pull grid.
+  priority: { order: ['playhead', 'marker', 'edge', 'center', 'grid'], relaxPx: 4 },
+});
+
+function snapTime(seconds: number, exclude?: string | Set<string>): number {
+  if (!snapping || disabled || viewportWidth.value <= 0) return seconds;
+  // The engine's `project` maps the candidate value into pixel space, measures
+  // distance there, and returns the matched target's domain value (seconds).
+  return snapEngine.snap1d(seconds, { exclude }).value;
+}
+
+// ── track mutation ────────────────────────────────────────────────────────────
+function patchTrack(id: string, patch: Partial<TimelineTrack>): void {
+  if (disabled) return;
+  const track = trackLookup.value.get(id);
+  if (!track) return;
+  // Update the lookup immutably (new object so the per-track computed re-renders)
+  // and write the public model.
+  trackLookup.value.set(id, { ...track, ...patch });
+  triggerRef(trackLookup);
+  tracks.value = (tracks.value ?? []).map(t => (t.id === id ? { ...t, ...patch } : t));
+  emit('tracksChange', [{ type: 'patch', id, patch }]);
+}
+
+// ── clip mutation ─────────────────────────────────────────────────────────────
+function setClip(id: string, next: TimelineClip): void {
+  // Replace with a NEW object so the per-clip computed sees a new identity.
+  clipLookup.value.set(id, next);
+  triggerRef(clipLookup);
+}
+
+function moveClip(id: string, start: number, trackId: string, mutating: boolean): void {
+  if (disabled) return;
+  const clip = clipLookup.value.get(id);
+  if (!clip || clip.locked) return;
+  isMutating.value = mutating;
+  draggingClipId.value = mutating ? id : draggingClipId.value;
+  const clamped = Math.max(0, start);
+  setClip(id, { ...clip, start: clamped, trackId });
+  dirtyClipIds.add(id);
+}
+
+function trimClip(id: string, start: number, dur: number, mutating: boolean): void {
+  if (disabled) return;
+  const clip = clipLookup.value.get(id);
+  if (!clip || clip.locked) return;
+  if (dur <= 0) return;
+  isMutating.value = mutating;
+  draggingClipId.value = mutating ? id : draggingClipId.value;
+  setClip(id, { ...clip, start: Math.max(0, start), duration: dur });
+  dirtyClipIds.add(id);
+}
+
+function commitMutation(): void {
+  isMutating.value = false;
+  draggingClipId.value = null;
+  if (dirtyClipIds.size === 0) return;
+  const ids = [...dirtyClipIds];
+  dirtyClipIds.clear();
+
+  const changes: TimelineClipChange[] = [];
+  const patchById = new Map<string, TimelineClip>();
+  for (const id of ids) {
+    const clip = clipLookup.value.get(id);
+    if (!clip) continue;
+    patchById.set(id, clip);
+    changes.push({ type: 'move', id, trackId: clip.trackId, start: clip.start });
+  }
+  // Write the model immutably (only touched clips get a new object).
+  clips.value = (clips.value ?? []).map(c => patchById.get(c.id) ?? c);
+  if (changes.length) emit('clipsChange', changes);
+  emit('clipCommit', ids);
+}
+
+function addClip(clip: TimelineClip): void {
+  if (disabled) return;
+  clips.value = [...(clips.value ?? []), clip];
+  emit('clipsChange', [{ type: 'add', clip }]);
+}
+
+function updateClip(id: string, patch: Partial<TimelineClip>): void {
+  if (disabled) return;
+  clips.value = (clips.value ?? []).map(c => (c.id === id ? { ...c, ...patch } : c));
+  const clip = clipLookup.value.get(id);
+  if (!clip) return;
+  const next = { ...clip, ...patch };
+  if (patch.start !== undefined || patch.duration !== undefined)
+    emit('clipsChange', [{ type: 'trim', id, start: next.start, duration: next.duration }]);
+  else if (patch.trackId !== undefined)
+    emit('clipsChange', [{ type: 'move', id, trackId: next.trackId, start: next.start }]);
+}
+
+function removeClip(id: string): void {
+  if (disabled) return;
+  clips.value = (clips.value ?? []).filter(c => c.id !== id);
+  if (selectedClipIds.value.has(id)) {
+    const next = new Set(selectedClipIds.value);
+    next.delete(id);
+    commitSelection(next);
+  }
+  emit('clipsChange', [{ type: 'remove', id }]);
+}
+
+function splitClip(id: string, at: number): void {
+  if (disabled) return;
+  const clip = clipLookup.value.get(id);
+  if (!clip) return;
+  const leftDur = at - clip.start;
+  const rightDur = clip.start + clip.duration - at;
+  if (leftDur <= 0 || rightDur <= 0) return;
+  const left: TimelineClip = { ...clip, id: `${clip.id}-a`, duration: leftDur };
+  const right: TimelineClip = { ...clip, id: `${clip.id}-b`, start: at, duration: rightDur };
+  clips.value = (clips.value ?? []).flatMap(c => (c.id === id ? [left, right] : [c]));
+  emit('clipsChange', [{ type: 'split', id, at }]);
+}
+
+function nudgeSelected(deltaSeconds: number): void {
+  if (disabled || selectedClipIds.value.size === 0) return;
+  const ids = [...selectedClipIds.value];
+  const changes: TimelineClipChange[] = [];
+  const patchById = new Map<string, TimelineClip>();
+  for (const id of ids) {
+    const clip = clipLookup.value.get(id);
+    if (!clip || clip.locked) continue;
+    const start = Math.max(0, snapFrame(clip.start + deltaSeconds));
+    const next = { ...clip, start };
+    patchById.set(id, next);
+    clipLookup.value.set(id, next);
+    changes.push({ type: 'move', id, trackId: clip.trackId, start });
+  }
+  if (patchById.size === 0) return;
+  triggerRef(clipLookup);
+  clips.value = (clips.value ?? []).map(c => patchById.get(c.id) ?? c);
+  emit('clipsChange', changes);
+  emit('clipCommit', [...patchById.keys()]);
+}
+
+function moveSelectedToAdjacentTrack(dirSign: 1 | -1): void {
+  if (disabled || selectedClipIds.value.size === 0) return;
+  const order = trackIds.value;
+  const changes: TimelineClipChange[] = [];
+  const patchById = new Map<string, TimelineClip>();
+  for (const id of selectedClipIds.value) {
+    const clip = clipLookup.value.get(id);
+    if (!clip || clip.locked) continue;
+    const idx = order.indexOf(clip.trackId);
+    const nextIdx = idx + dirSign;
+    if (nextIdx < 0 || nextIdx >= order.length) continue;
+    const trackId = order[nextIdx]!;
+    const next = { ...clip, trackId };
+    patchById.set(id, next);
+    clipLookup.value.set(id, next);
+    changes.push({ type: 'move', id, trackId, start: clip.start });
+  }
+  if (patchById.size === 0) return;
+  triggerRef(clipLookup);
+  clips.value = (clips.value ?? []).map(c => patchById.get(c.id) ?? c);
+  emit('clipsChange', changes);
+  emit('clipCommit', [...patchById.keys()]);
+}
+
+function removeSelected(): void {
+  if (disabled || selectedClipIds.value.size === 0) return;
+  const ids = selectedClipIds.value;
+  const changes: TimelineClipChange[] = [...ids].map(id => ({ type: 'remove' as const, id }));
+  clips.value = (clips.value ?? []).filter(c => !ids.has(c.id));
+  commitSelection(new Set());
+  emit('clipsChange', changes);
+}
+
+// ── playhead ──────────────────────────────────────────────────────────────────
+function setCurrentTime(seconds: number, scrubbing = false): void {
+  if (disabled) return;
+  const clamped = clamp(seconds, 0, duration.value || Number.MAX_SAFE_INTEGER);
+  if (scrubbing) isMutating.value = true;
+  if (clamped !== currentTime.value) currentTime.value = clamped;
+}
+
+function commitScrub(): void {
+  isMutating.value = false;
+  emit('scrubCommit', currentTime.value);
+}
+
+// ── selection ──────────────────────────────────────────────────────────────────
+function commitSelection(next: Set<string>): void {
+  selectedClipIds.value = next;
+  const ids = [...next];
+  selectedModel.value = ids;
+  emit('selectionChange', ids);
+}
+
+function selectClip(id: string, additive = false): void {
+  if (disabled) return;
+  const next = additive ? new Set(selectedClipIds.value) : new Set<string>();
+  if (additive && next.has(id)) next.delete(id);
+  else next.add(id);
+  commitSelection(next);
+}
+
+function setSelection(ids: string[]): void {
+  if (disabled) return;
+  commitSelection(new Set(ids));
+}
+
+function clearSelection(): void {
+  if (selectedClipIds.value.size === 0) return;
+  commitSelection(new Set());
+}
+
+// ── roving-focus registry ──────────────────────────────────────────────────────
+const clipEls = new Map<string, HTMLElement>();
+const markerEls = new Map<string, HTMLElement>();
+function registerClipEl(id: string, el: HTMLElement): void {
+  clipEls.set(id, el);
+}
+function unregisterClipEl(id: string): void {
+  clipEls.delete(id);
+}
+function registerMarkerEl(id: string, el: HTMLElement): void {
+  markerEls.set(id, el);
+}
+function unregisterMarkerEl(id: string): void {
+  markerEls.delete(id);
+}
+
+function focusAdjacentClip(fromId: string, dirSign: 1 | -1): void {
+  const order = orderedClipIds.value;
+  const idx = order.indexOf(fromId);
+  if (idx === -1) return;
+  const nextIdx = idx + dirSign;
+  if (nextIdx < 0 || nextIdx >= order.length) return;
+  clipEls.get(order[nextIdx]!)?.focus();
+}
+
+function focusClip(id: string): void {
+  clipEls.get(id)?.focus();
+}
+
+// ── provide ────────────────────────────────────────────────────────────────────
+const context: TimelineContext = {
+  timelineId,
+  offset: offset as Ref<number>,
+  pxPerSecond: pxPerSecond as Ref<number>,
+  duration,
+  fps: toRef(() => fps),
+  trackHeight: toRef(() => trackHeight),
+  viewportWidth,
+  scale,
+  invert,
+  snapToFrame: snapFrame,
+  formatTimecode,
+  snapping: toRef(() => snapping),
+  disabled: toRef(() => disabled),
+  direction,
+  trackLookup,
+  clipLookup,
+  markerLookup,
+  trackIds,
+  orderedClipIds,
+  orderedMarkerIds,
+  tabStopClipId,
+  selectedClipIds,
+  currentTime: currentTime as Ref<number>,
+  snapEngine,
+  snapTime,
+  isMutating,
+  draggingClipId,
+  patchTrack,
+  addClip,
+  updateClip,
+  removeClip,
+  splitClip,
+  moveClip,
+  trimClip,
+  commitMutation,
+  nudgeSelected,
+  moveSelectedToAdjacentTrack,
+  removeSelected,
+  setCurrentTime,
+  commitScrub,
+  selectClip,
+  setSelection,
+  clearSelection,
+  registerClipEl,
+  unregisterClipEl,
+  registerMarkerEl,
+  unregisterMarkerEl,
+  focusAdjacentClip,
+  focusClip,
+  viewportEl,
+  marquee,
+};
+provideTimelineContext(context);
+
+defineExpose({
+  currentTime,
+  offset,
+  pxPerSecond,
+  selectedClipIds,
+  scale,
+  invert,
+  addClip,
+  updateClip,
+  removeClip,
+  splitClip,
+  selectClip,
+  setSelection,
+  clearSelection,
+  removeSelected,
+});
+
+const { forwardRef } = useForwardExpose();
+
+function setRootRef(el: unknown): void {
+  forwardRef(el as never);
+  rootEl.value = (el && typeof el === 'object' && '$el' in el ? (el as { $el: HTMLElement }).$el : el) as HTMLElement | undefined;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRootRef"
+    :as="as"
+    role="group"
+    aria-roledescription="timeline"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    data-orientation="horizontal"
+    :data-mutating="isMutating ? '' : undefined"
+    :dir="direction"
+  >
+    <slot
+      :scale="scale"
+      :current-time="currentTime"
+      :duration="duration"
+      :px-per-second="pxPerSecond"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineRuler.vue b/vue/primitives/src/canvas/timeline/TimelineRuler.vue
new file mode 100644
index 0000000..1d9c037
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineRuler.vue
@@ -0,0 +1,94 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The time axis sitting above the tracks. It embeds a {@link TimeRulerRoot} bound
+ * to the SAME `offset` / `pxPerSecond` / `fps` as the timeline (so the ruler and
+ * the lanes share one scale), and turns clicks / drags on the axis into playhead
+ * scrubs. The default slot forwards `{ ticks, majorTicks, minorTicks, scale,
+ * formatTime }` from the embedded ruler so consumers render their own tick layer.
+ */
+export interface TimelineRulerProps extends PrimitiveProps {
+  /** Tick label rendering mode. @default 'timecode' */
+  mode?: 'seconds' | 'timecode' | 'frames';
+  /** Target pixel spacing between ticks. @default 80 */
+  targetDensity?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { useEventListener } from '@robonen/vue';
+import { shallowRef } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { TimeRulerRoot } from '../time-ruler';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useTimelineContext } from './context';
+
+const {
+  mode = 'timecode',
+  targetDensity = 80,
+  as = 'div',
+} = defineProps<TimelineRulerProps>();
+
+const ctx = useTimelineContext();
+const rulerEl = shallowRef<HTMLElement | null>(null);
+
+/** Client-x → time (seconds), via the ruler element's rect + the shared invert. */
+function timeFromClientX(clientX: number): number {
+  const el = rulerEl.value;
+  if (!el) return ctx.currentTime.value;
+  const rect = el.getBoundingClientRect();
+  if (rect.width <= 0) return ctx.currentTime.value;
+  const localX = ctx.direction.value === 'rtl' ? rect.right - clientX : clientX - rect.left;
+  return ctx.invert(localX);
+}
+
+// Click + drag on the axis scrubs the playhead (snapped to the frame grid).
+usePointerDrag(() => (ctx.disabled.value ? null : rulerEl.value), {
+  axis: 'x',
+  threshold: 0,
+  disabled: () => ctx.disabled.value,
+  onStart: (state) => {
+    ctx.setCurrentTime(ctx.snapToFrame(timeFromClientX(state.point.x)), true);
+  },
+  onMove: (state) => {
+    ctx.setCurrentTime(ctx.snapToFrame(timeFromClientX(state.point.x)), true);
+  },
+  onEnd: () => {
+    ctx.commitScrub();
+  },
+});
+
+// A bare click without crossing threshold still scrubs.
+useEventListener(rulerEl, 'pointerdown', (event: PointerEvent) => {
+  if (ctx.disabled.value || event.button !== 0) return;
+  ctx.setCurrentTime(ctx.snapToFrame(timeFromClientX(event.clientX)), true);
+});
+
+function setRulerRef(node: unknown): void {
+  rulerEl.value = (node && typeof node === 'object' && '$el' in node ? (node as { $el: HTMLElement }).$el : node) as HTMLElement | null;
+}
+</script>
+
+<template>
+  <Primitive
+    :as="as"
+    data-orientation="horizontal"
+  >
+    <TimeRulerRoot
+      :ref="setRulerRef"
+      v-model:offset="ctx.offset.value"
+      v-model:zoom="ctx.pxPerSecond.value"
+      :duration="ctx.duration.value"
+      :fps="ctx.fps.value"
+      :mode="mode"
+      :target-density="targetDensity"
+      :disabled="ctx.disabled.value"
+      :dir="ctx.direction.value"
+    >
+      <template #default="slotProps">
+        <slot v-bind="slotProps" />
+      </template>
+    </TimeRulerRoot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineSelection.vue b/vue/primitives/src/canvas/timeline/TimelineSelection.vue
new file mode 100644
index 0000000..22bb2f4
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineSelection.vue
@@ -0,0 +1,42 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The marquee selection rectangle overlay. It reads the live marquee geometry
+ * the `TimelineTracks` viewport publishes on the context and renders an
+ * absolutely-positioned box (viewport-relative pixels). It renders nothing when
+ * no marquee is active. The default slot receives the live `rect` so a consumer
+ * can render its own visual; the part also exposes `data-timeline-selection`.
+ */
+export type TimelineSelectionProps = PrimitiveProps;
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useTimelineContext } from './context';
+
+const { as = 'div' } = defineProps<TimelineSelectionProps>();
+
+const ctx = useTimelineContext();
+const rect = computed(() => ctx.marquee.value);
+</script>
+
+<template>
+  <Primitive
+    v-if="rect"
+    :as="as"
+    data-timeline-selection
+    aria-hidden="true"
+    :style="{
+      position: 'absolute',
+      left: `${rect.x}px`,
+      top: `${rect.y}px`,
+      width: `${rect.width}px`,
+      height: `${rect.height}px`,
+      pointerEvents: 'none',
+    }"
+  >
+    <slot :rect="rect" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineTrack.vue b/vue/primitives/src/canvas/timeline/TimelineTrack.vue
new file mode 100644
index 0000000..01738cf
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineTrack.vue
@@ -0,0 +1,65 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * One track lane. Looks its track record up from the Root by `trackId`, applies
+ * the resolved (fixed, non-zoomed) lane height, and provides `TimelineTrackContext`
+ * to its header + clips. `role="row"` within the `TimelineTracks` grid; surfaces
+ * `data-muted` / `data-locked` / `data-soloed`. The default slot receives the
+ * track record + flags.
+ */
+export interface TimelineTrackProps extends PrimitiveProps {
+  /** Id of the track this lane renders. */
+  trackId: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { provideTimelineTrackContext, useTimelineContext } from './context';
+import type { TimelineTrack } from './utils';
+
+const { trackId, as = 'div' } = defineProps<TimelineTrackProps>();
+
+const ctx = useTimelineContext();
+
+const track = computed(() => ctx.trackLookup.value.get(trackId));
+const height = computed(() => track.value?.height ?? ctx.trackHeight.value);
+
+function toggleFlag(flag: 'muted' | 'locked' | 'soloed'): void {
+  const current = track.value;
+  if (!current) return;
+  ctx.patchTrack(trackId, { [flag]: !current[flag] });
+}
+
+function patchTrack(patch: Partial<TimelineTrack>): void {
+  ctx.patchTrack(trackId, patch);
+}
+
+provideTimelineTrackContext({
+  trackId,
+  track,
+  height,
+  toggleFlag,
+  patchTrack,
+});
+</script>
+
+<template>
+  <Primitive
+    :as="as"
+    role="row"
+    :data-track-id="trackId"
+    :data-muted="track?.muted ? '' : undefined"
+    :data-locked="track?.locked ? '' : undefined"
+    :data-soloed="track?.soloed ? '' : undefined"
+    :data-hidden="track?.hidden ? '' : undefined"
+    :style="{ height: `${height}px` }"
+  >
+    <slot
+      :track="track"
+      :height="height"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineTrackHeader.vue b/vue/primitives/src/canvas/timeline/TimelineTrackHeader.vue
new file mode 100644
index 0000000..c26f79e
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineTrackHeader.vue
@@ -0,0 +1,107 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The track gutter: the label plus mute / lock / solo toggle buttons and a
+ * drag-resize affordance for the lane height. The default slot exposes the track
+ * record and ready-made `toggle*` handlers + flag booleans so a consumer can
+ * render its own buttons; the `#resize-handle` slot wires the height drag.
+ *
+ * `role="rowheader"`; `data-muted` / `data-locked` / `data-soloed` mirror the
+ * lane. The toggle buttons are native `<button>`s with `aria-pressed`.
+ */
+export interface TimelineTrackHeaderProps extends PrimitiveProps {
+  /** Minimum lane height (px) the resize drag clamps to. @default 24 */
+  minHeight?: number;
+  /** Maximum lane height (px) the resize drag clamps to. @default 320 */
+  maxHeight?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { shallowRef } from 'vue';
+import { clamp } from '@robonen/stdlib';
+import { Primitive } from '../../internal/primitive';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useTimelineContext, useTimelineTrackContext } from './context';
+
+const {
+  minHeight = 24,
+  maxHeight = 320,
+  as = 'div',
+} = defineProps<TimelineTrackHeaderProps>();
+
+const ctx = useTimelineContext();
+const trackCtx = useTimelineTrackContext();
+
+const resizeHandle = shallowRef<HTMLElement | null>(null);
+let startHeight = 0;
+
+usePointerDrag(() => (ctx.disabled.value ? null : resizeHandle.value), {
+  axis: 'y',
+  disabled: () => ctx.disabled.value,
+  onStart: () => {
+    startHeight = trackCtx.height.value;
+  },
+  onMove: (state) => {
+    const next = clamp(startHeight + state.total.y, minHeight, maxHeight);
+    trackCtx.patchTrack({ height: Math.round(next) });
+  },
+});
+
+function setResizeRef(node: unknown): void {
+  resizeHandle.value = (node && typeof node === 'object' && '$el' in node ? (node as { $el: HTMLElement }).$el : node) as HTMLElement | null;
+}
+</script>
+
+<template>
+  <Primitive
+    :as="as"
+    role="rowheader"
+    :data-track-id="trackCtx.trackId"
+    :data-muted="trackCtx.track.value?.muted ? '' : undefined"
+    :data-locked="trackCtx.track.value?.locked ? '' : undefined"
+    :data-soloed="trackCtx.track.value?.soloed ? '' : undefined"
+  >
+    <slot
+      :track="trackCtx.track.value"
+      :label="trackCtx.track.value?.label"
+      :muted="!!trackCtx.track.value?.muted"
+      :locked="!!trackCtx.track.value?.locked"
+      :soloed="!!trackCtx.track.value?.soloed"
+      :toggle-mute="() => trackCtx.toggleFlag('muted')"
+      :toggle-lock="() => trackCtx.toggleFlag('locked')"
+      :toggle-solo="() => trackCtx.toggleFlag('soloed')"
+      :set-resize-ref="setResizeRef"
+    >
+      <span>{{ trackCtx.track.value?.label }}</span>
+      <button
+        type="button"
+        :aria-pressed="!!trackCtx.track.value?.muted"
+        :aria-label="`Mute ${trackCtx.track.value?.label ?? trackCtx.trackId}`"
+        :disabled="ctx.disabled.value"
+        @click="trackCtx.toggleFlag('muted')"
+      >M</button>
+      <button
+        type="button"
+        :aria-pressed="!!trackCtx.track.value?.soloed"
+        :aria-label="`Solo ${trackCtx.track.value?.label ?? trackCtx.trackId}`"
+        :disabled="ctx.disabled.value"
+        @click="trackCtx.toggleFlag('soloed')"
+      >S</button>
+      <button
+        type="button"
+        :aria-pressed="!!trackCtx.track.value?.locked"
+        :aria-label="`Lock ${trackCtx.track.value?.label ?? trackCtx.trackId}`"
+        :disabled="ctx.disabled.value"
+        @click="trackCtx.toggleFlag('locked')"
+      >L</button>
+      <span
+        :ref="setResizeRef"
+        role="separator"
+        aria-orientation="horizontal"
+        aria-hidden="true"
+      />
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/TimelineTracks.vue b/vue/primitives/src/canvas/timeline/TimelineTracks.vue
new file mode 100644
index 0000000..e374fcd
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/TimelineTracks.vue
@@ -0,0 +1,120 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The scrollable lanes container: a vertical stack of `TimelineTrack`s and the
+ * surface that hosts the marquee selection layer. It registers itself as the
+ * timeline's `viewportEl` (the scale's range origin) and measures its width so
+ * the shared `useScale` projects correctly.
+ *
+ * Shift + drag on empty space (or plain drag, configurable) draws a selection
+ * rectangle and selects every clip whose time span intersects it on release —
+ * ported from the flow `useMarquee` pattern but operating in the timeline's
+ * 1-D-time × track-lane space.
+ */
+export interface TimelineTracksProps extends PrimitiveProps {
+  /**
+   * Whether marquee selection requires holding Shift.
+   * - `true` (default): plain drag on empty space draws a marquee.
+   * - `false`: only Shift+drag draws a marquee.
+   * @default true
+   */
+  marquee?: boolean;
+  /** Require Shift to start a marquee. @default false */
+  requireShift?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { shallowRef } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useTimelineContext } from './context';
+import { clipIntersectsTime } from './utils';
+
+const {
+  marquee = true,
+  requireShift = false,
+  as = 'div',
+} = defineProps<TimelineTracksProps>();
+
+const ctx = useTimelineContext();
+const el = shallowRef<HTMLElement | null>(null);
+
+let pointerId = -1;
+let startClientX = 0;
+let startClientY = 0;
+let startTime = 0;
+
+function viewportRelative(clientX: number, clientY: number): { x: number; y: number } {
+  const rect = el.value?.getBoundingClientRect();
+  if (!rect) return { x: 0, y: 0 };
+  return { x: clientX - rect.left, y: clientY - rect.top };
+}
+
+function localXToTime(clientX: number): number {
+  const rect = el.value?.getBoundingClientRect();
+  if (!rect || rect.width <= 0) return 0;
+  const localX = ctx.direction.value === 'rtl' ? rect.right - clientX : clientX - rect.left;
+  return ctx.invert(localX);
+}
+
+useEventListener(el, 'pointerdown', (event: PointerEvent) => {
+  if (ctx.disabled.value || !marquee || event.button !== 0) return;
+  if (requireShift && !event.shiftKey) return;
+  // Only start a marquee on the viewport background itself — clips stop
+  // propagation, so a press that reaches here is on empty space.
+  if (event.target !== el.value) return;
+  pointerId = event.pointerId;
+  startClientX = event.clientX;
+  startClientY = event.clientY;
+  startTime = localXToTime(event.clientX);
+  ctx.marquee.value = { ...viewportRelative(event.clientX, event.clientY), width: 0, height: 0 };
+  el.value?.setPointerCapture?.(event.pointerId);
+});
+
+useEventListener(el, 'pointermove', (event: PointerEvent) => {
+  if (ctx.marquee.value === null || event.pointerId !== pointerId) return;
+  const start = viewportRelative(startClientX, startClientY);
+  const cur = viewportRelative(event.clientX, event.clientY);
+  ctx.marquee.value = {
+    x: Math.min(start.x, cur.x),
+    y: Math.min(start.y, cur.y),
+    width: Math.abs(cur.x - start.x),
+    height: Math.abs(cur.y - start.y),
+  };
+});
+
+function endMarquee(event: PointerEvent): void {
+  if (ctx.marquee.value === null || event.pointerId !== pointerId) return;
+  const endTime = localXToTime(event.clientX);
+  const ids: string[] = [];
+  for (const clip of ctx.clipLookup.value.values()) {
+    if (clipIntersectsTime(clip, startTime, endTime)) ids.push(clip.id);
+  }
+  ctx.setSelection(ids);
+  ctx.marquee.value = null;
+  pointerId = -1;
+  el.value?.releasePointerCapture?.(event.pointerId);
+}
+
+useEventListener(el, 'pointerup', endMarquee);
+useEventListener(el, 'pointercancel', endMarquee);
+
+function setRef(node: unknown): void {
+  el.value = (node && typeof node === 'object' && '$el' in node ? (node as { $el: HTMLElement }).$el : node) as HTMLElement | null;
+  ctx.viewportEl.value = el.value;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="setRef"
+    :as="as"
+    role="grid"
+    data-orientation="horizontal"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+  >
+    <slot :marquee="ctx.marquee.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/timeline/__test__/Timeline.test.ts b/vue/primitives/src/canvas/timeline/__test__/Timeline.test.ts
new file mode 100644
index 0000000..fca3460
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/__test__/Timeline.test.ts
@@ -0,0 +1,324 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  TimelineClip,
+  TimelineClipHandle,
+  TimelineMarker,
+  TimelinePlayhead,
+  TimelineRoot,
+  TimelineTrack,
+  TimelineTrackHeader,
+  TimelineTracks,
+} from '../index';
+import type { TimelineClipData, TimelineMarkerData, TimelineTrackData } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+const tracks: TimelineTrackData[] = [
+  { id: 't1', label: 'Video' },
+  { id: 't2', label: 'Audio' },
+];
+const clips: TimelineClipData[] = [
+  { id: 'c1', trackId: 't1', start: 1, duration: 2, label: 'Clip 1' },
+  { id: 'c2', trackId: 't2', start: 4, duration: 3, label: 'Clip 2' },
+];
+const markers: TimelineMarkerData[] = [{ id: 'm1', time: 2, label: 'Cue' }];
+
+/**
+ * A full timeline composition with a fixed-width viewport so the scale projects
+ * to real pixels (`pxPerSecond` px/s). Width 1000px, pxPerSecond 100 → 10s window.
+ */
+function mountTimeline(props: Record<string, unknown> = {}, clipChildren?: (id: string) => any) {
+  const Comp = defineComponent({
+    setup() {
+      // Render clips from a LIVE model so add/remove reflect in the DOM (real usage).
+      const clipsRef = ref<TimelineClipData[]>(clips.map(c => ({ ...c })));
+      return () => h(
+        TimelineRoot,
+        {
+          tracks,
+          clips: clipsRef.value,
+          'onUpdate:clips': (v: TimelineClipData[]) => { clipsRef.value = v; },
+          defaultMarkers: markers,
+          defaultPxPerSecond: 100,
+          fps: 30,
+          style: 'width:1000px;display:block;',
+          ...props,
+        } as Record<string, unknown>,
+        {
+          default: () => [
+            h(TimelinePlayhead, {}, { default: () => 'PH' }),
+            ...markers.map(m => h(TimelineMarker, { markerId: m.id })),
+            h(TimelineTracks, { style: 'position:relative;display:block;width:1000px;height:128px;' }, {
+              default: () => tracks.map(t => h(
+                TimelineTrack,
+                { trackId: t.id, key: t.id, style: 'position:relative;display:block;' },
+                {
+                  default: () => [
+                    h(TimelineTrackHeader, {}, {}),
+                    ...clipsRef.value
+                      .filter(c => c.trackId === t.id)
+                      .map(c => h(
+                        TimelineClip,
+                        { clipId: c.id, key: c.id },
+                        { default: () => (clipChildren ? clipChildren(c.id) : c.label) },
+                      )),
+                  ],
+                },
+              )),
+            }),
+          ],
+        },
+      );
+    },
+  });
+  return track(mount(Comp, { attachTo: document.body }));
+}
+
+describe('TimelineRoot', () => {
+  it('renders the root group with timeline roledescription', () => {
+    const w = mountTimeline();
+    const root = w.find('[aria-roledescription="timeline"]');
+    expect(root.exists()).toBe(true);
+    expect(root.attributes('role')).toBe('group');
+  });
+
+  it('renders every track lane and clip', () => {
+    const w = mountTimeline();
+    expect(w.findAll('[data-track-id]').length).toBeGreaterThanOrEqual(2);
+    expect(w.findAll('[data-clip-id]')).toHaveLength(2);
+  });
+});
+
+describe('scale projection', () => {
+  it('positions clips at real px from the scale (start * pxPerSecond)', async () => {
+    const w = mountTimeline();
+    await nextTick();
+    const c1 = w.find('[data-clip-id="c1"]').element as HTMLElement;
+    // start=1s @ 100px/s => left 100px; duration=2s => width 200px.
+    expect(c1.style.left).toBe('100px');
+    expect(c1.style.width).toBe('200px');
+    const c2 = w.find('[data-clip-id="c2"]').element as HTMLElement;
+    expect(c2.style.left).toBe('400px'); // start 4s
+    expect(c2.style.width).toBe('300px'); // duration 3s
+  });
+});
+
+describe('TimelinePlayhead', () => {
+  it('is a horizontal slider with a timecode aria-valuetext', () => {
+    const w = mountTimeline({ defaultCurrentTime: 2 });
+    const ph = w.find('[role="slider"][aria-label="Playhead"]');
+    expect(ph.exists()).toBe(true);
+    expect(ph.attributes('aria-orientation')).toBe('horizontal');
+    expect(ph.attributes('aria-valuenow')).toBe('2');
+    expect(ph.attributes('aria-valuetext')).toBe('00:00:02:00');
+  });
+
+  it('ArrowRight scrubs the playhead by exactly one frame', async () => {
+    const onScrub = ref<number | null>(null);
+    const w = mountTimeline({
+      defaultCurrentTime: 1,
+      onScrubCommit: (t: number) => { onScrub.value = t; },
+    });
+    const ph = w.find('[role="slider"][aria-label="Playhead"]');
+    await ph.trigger('keydown', { key: 'ArrowRight' });
+    await nextTick();
+    // 1s + 1 frame @30fps = 1 + 1/30.
+    expect(onScrub.value).toBeCloseTo(1 + 1 / 30, 5);
+    expect(Number(ph.attributes('aria-valuenow'))).toBeCloseTo(1 + 1 / 30, 5);
+  });
+
+  it('Home jumps to 0 and End to duration', async () => {
+    const w = mountTimeline({ defaultCurrentTime: 3, duration: 10 });
+    const ph = w.find('[role="slider"][aria-label="Playhead"]');
+    await ph.trigger('keydown', { key: 'Home' });
+    await nextTick();
+    expect(ph.attributes('aria-valuenow')).toBe('0');
+    await ph.trigger('keydown', { key: 'End' });
+    await nextTick();
+    expect(ph.attributes('aria-valuenow')).toBe('10');
+  });
+});
+
+describe('TimelineClip roving focus + selection', () => {
+  it('exposes a single tab-stop with aria-selected', async () => {
+    const w = mountTimeline();
+    await nextTick();
+    const stops = w.findAll('[data-clip-id]').filter(c => c.attributes('tabindex') === '0');
+    expect(stops).toHaveLength(1);
+    // The first clip in time order (c1 @1s) is the tab stop.
+    expect(stops[0]!.attributes('data-clip-id')).toBe('c1');
+  });
+
+  it('selects a clip on pointerdown (data-selected + aria-selected)', async () => {
+    const w = mountTimeline();
+    const c1 = w.find('[data-clip-id="c1"]');
+    c1.element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    expect(w.find('[data-clip-id="c1"]').attributes('data-selected')).toBe('');
+    expect(w.find('[data-clip-id="c1"]').attributes('aria-selected')).toBe('true');
+  });
+
+  it('ArrowRight nudges a focused clip by one frame', async () => {
+    const onChange = ref<any>(null);
+    const w = mountTimeline({ onClipsChange: (c: any) => void (onChange.value = c) });
+    const c1 = w.find('[data-clip-id="c1"]');
+    c1.element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    await c1.trigger('keydown', { key: 'ArrowRight' });
+    await nextTick();
+    expect(onChange.value).toBeTruthy();
+    const moved = onChange.value.find((ch: any) => ch.id === 'c1');
+    // start 1s + 1 frame @30fps.
+    expect(moved.start).toBeCloseTo(1 + 1 / 30, 5);
+  });
+
+  it('ArrowDown moves a clip to the track below', async () => {
+    const onChange = ref<any>(null);
+    const w = mountTimeline({ onClipsChange: (c: any) => void (onChange.value = c) });
+    const c1 = w.find('[data-clip-id="c1"]');
+    c1.element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    await c1.trigger('keydown', { key: 'ArrowDown' });
+    await nextTick();
+    const moved = onChange.value.find((ch: any) => ch.id === 'c1');
+    expect(moved.trackId).toBe('t2'); // moved from t1 to the next lane t2
+  });
+
+  it('Delete removes the selected clip', async () => {
+    const onChange = ref<any>(null);
+    const w = mountTimeline({ onClipsChange: (c: any) => void (onChange.value = c) });
+    const c1 = w.find('[data-clip-id="c1"]');
+    c1.element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    await c1.trigger('keydown', { key: 'Delete' });
+    await nextTick();
+    expect(onChange.value.some((ch: any) => ch.type === 'remove' && ch.id === 'c1')).toBe(true);
+    expect(w.find('[data-clip-id="c1"]').exists()).toBe(false);
+  });
+});
+
+describe('TimelineClipHandle (trim)', () => {
+  it('is a slider with valuemin/valuemax/valuenow in seconds + timecode', async () => {
+    const w = mountTimeline({}, () => [
+      h(TimelineClipHandle, { side: 'start', key: 's' }),
+      h(TimelineClipHandle, { side: 'end', key: 'e' }),
+    ]);
+    await nextTick();
+    // Two handles (start + end) per clip; scope to the first clip.
+    const c1 = w.find('[data-clip-id="c1"]');
+    const handles = c1.findAll('[role="slider"][data-side]');
+    expect(handles).toHaveLength(2);
+    const startHandle = handles.find(h => h.attributes('data-side') === 'start')!;
+    expect(startHandle.attributes('aria-orientation')).toBe('horizontal');
+    expect(startHandle.attributes('aria-valuetext')).toMatch(/^\d\d:\d\d:\d\d:\d\d$/);
+  });
+
+  it('ArrowRight on the start handle trims the clip start by a frame', async () => {
+    const onChange = ref<any>(null);
+    const w = mountTimeline(
+      { onClipsChange: (c: any) => void (onChange.value = c) },
+      () => h(TimelineClipHandle, { side: 'start' }),
+    );
+    await nextTick();
+    const handle = w.find('[role="slider"][data-side="start"]');
+    await handle.trigger('keydown', { key: 'ArrowRight' });
+    await nextTick();
+    expect(onChange.value).toBeTruthy();
+    const trimmed = onChange.value.find((ch: any) => ch.type === 'move' || ch.type === 'trim');
+    expect(trimmed).toBeTruthy();
+  });
+});
+
+describe('TimelineMarker', () => {
+  it('renders a marker button with timecode label at its time', async () => {
+    const w = mountTimeline();
+    await nextTick();
+    const marker = w.find('[data-marker-id="m1"]');
+    expect(marker.exists()).toBe(true);
+    expect(marker.attributes('aria-label')).toContain('00:00:02:00');
+    // time=2s @ 100px/s => left 200px.
+    expect((marker.element as HTMLElement).style.left).toBe('200px');
+  });
+});
+
+describe('track header toggles', () => {
+  it('mute/solo/lock buttons set aria-pressed + emit a track patch', async () => {
+    const onTracks = ref<any>(null);
+    const w = mountTimeline({ onTracksChange: (c: any) => void (onTracks.value = c) });
+    const muteBtn = w.findAll('button').find(b => b.attributes('aria-label')?.startsWith('Mute'))!;
+    expect(muteBtn.attributes('aria-pressed')).toBe('false');
+    await muteBtn.trigger('click');
+    await nextTick();
+    expect(onTracks.value[0]).toMatchObject({ type: 'patch', patch: { muted: true } });
+    const after = w.findAll('button').find(b => b.attributes('aria-label')?.startsWith('Mute'))!;
+    expect(after.attributes('aria-pressed')).toBe('true');
+  });
+});
+
+describe('disabled', () => {
+  it('blocks scrubbing and selection', async () => {
+    const onChange = ref<any>(null);
+    const w = mountTimeline({ disabled: true, onClipsChange: (c: any) => void (onChange.value = c) });
+    const root = w.find('[aria-roledescription="timeline"]');
+    expect(root.attributes('data-disabled')).toBe('');
+    const c1 = w.find('[data-clip-id="c1"]');
+    c1.element.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true }));
+    await nextTick();
+    expect(w.find('[data-clip-id="c1"]').attributes('data-selected')).toBeUndefined();
+  });
+});
+
+describe('reconcile does not clobber a mid-mutation clip', () => {
+  it('ignores an external clips write while isMutating', async () => {
+    const model = ref<TimelineClipData[]>([{ id: 'c1', trackId: 't1', start: 1, duration: 2 }]);
+    const Comp = defineComponent({
+      setup(_, { expose }) {
+        const rootRef = ref<any>(null);
+        expose({ rootRef });
+        return () => h(
+          TimelineRoot,
+          {
+            ref: rootRef,
+            tracks: [{ id: 't1' }],
+            clips: model.value,
+            'onUpdate:clips': (v: TimelineClipData[]) => { model.value = v; },
+            defaultPxPerSecond: 100,
+            style: 'width:1000px;display:block;',
+          } as Record<string, unknown>,
+          {
+            default: () => h(TimelineTracks, { style: 'position:relative;width:1000px;height:64px;' }, {
+              default: () => h(TimelineTrack, { trackId: 't1' }, {
+                default: () => h(TimelineClip, { clipId: 'c1' }),
+              }),
+            }),
+          },
+        );
+      },
+    });
+    const w = track(mount(Comp, { attachTo: document.body }));
+    await nextTick();
+    // Begin a drag on the clip so isMutating flips.
+    const c1 = w.find('[data-clip-id="c1"]').element as HTMLElement;
+    c1.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true, clientX: 100, clientY: 10 }));
+    c1.dispatchEvent(new PointerEvent('pointermove', { button: 0, bubbles: true, clientX: 160, clientY: 10 }));
+    await nextTick();
+    // External write during the drag MUST NOT reset the live position.
+    model.value = [{ id: 'c1', trackId: 't1', start: 1, duration: 2 }];
+    await nextTick();
+    c1.dispatchEvent(new PointerEvent('pointerup', { button: 0, bubbles: true, clientX: 160, clientY: 10 }));
+    await nextTick();
+    // After commit the clip reflects the drag, not the clobbering external value.
+    expect(model.value[0]!.start).toBeGreaterThan(1);
+  });
+});
diff --git a/vue/primitives/src/canvas/timeline/__test__/__screenshots__/Timeline.test.ts/TimelineClip-roving-focus---selection-Delete-removes-the-selected-clip-1.png b/vue/primitives/src/canvas/timeline/__test__/__screenshots__/Timeline.test.ts/TimelineClip-roving-focus---selection-Delete-removes-the-selected-clip-1.png
new file mode 100644
index 0000000..205935f
Binary files /dev/null and b/vue/primitives/src/canvas/timeline/__test__/__screenshots__/Timeline.test.ts/TimelineClip-roving-focus---selection-Delete-removes-the-selected-clip-1.png differ
diff --git a/vue/primitives/src/canvas/timeline/__test__/__screenshots__/Timeline.test.ts/TimelineClipHandle--trim--is-a-slider-with-valuemin-valuemax-valuenow-in-seconds---timecode-1.png b/vue/primitives/src/canvas/timeline/__test__/__screenshots__/Timeline.test.ts/TimelineClipHandle--trim--is-a-slider-with-valuemin-valuemax-valuenow-in-seconds---timecode-1.png
new file mode 100644
index 0000000..2ae7cb6
Binary files /dev/null and b/vue/primitives/src/canvas/timeline/__test__/__screenshots__/Timeline.test.ts/TimelineClipHandle--trim--is-a-slider-with-valuemin-valuemax-valuenow-in-seconds---timecode-1.png differ
diff --git a/vue/primitives/src/canvas/timeline/__test__/__screenshots__/changes.test.ts/applyClipChanges-treats-select-changes-as-a-no-op-on-the-clip-array-1.png b/vue/primitives/src/canvas/timeline/__test__/__screenshots__/changes.test.ts/applyClipChanges-treats-select-changes-as-a-no-op-on-the-clip-array-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/timeline/__test__/__screenshots__/changes.test.ts/applyClipChanges-treats-select-changes-as-a-no-op-on-the-clip-array-1.png differ
diff --git a/vue/primitives/src/canvas/timeline/__test__/changes.test.ts b/vue/primitives/src/canvas/timeline/__test__/changes.test.ts
new file mode 100644
index 0000000..f16683b
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/__test__/changes.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import type { TimelineClip, TimelineTrack } from '../utils';
+import { applyClipChanges, applyTrackChanges } from '../changes';
+
+const clips: TimelineClip[] = [
+  { id: 'a', trackId: 't1', start: 0, duration: 2 },
+  { id: 'b', trackId: 't1', start: 5, duration: 3 },
+  { id: 'c', trackId: 't2', start: 1, duration: 4 },
+];
+
+describe('applyClipChanges', () => {
+  it('returns the SAME array reference for an empty batch', () => {
+    expect(applyClipChanges(clips, [])).toBe(clips);
+  });
+
+  it('moves a clip immutably, keeping untouched clips by identity', () => {
+    const out = applyClipChanges(clips, [{ type: 'move', id: 'a', trackId: 't2', start: 10 }]);
+    expect(out).not.toBe(clips);
+    expect(out[0]).not.toBe(clips[0]); // touched clip is a new object
+    expect(out[0]).toMatchObject({ id: 'a', trackId: 't2', start: 10 });
+    expect(out[1]).toBe(clips[1]); // untouched identity preserved
+    expect(out[2]).toBe(clips[2]);
+  });
+
+  it('trims a clip (start + duration)', () => {
+    const out = applyClipChanges(clips, [{ type: 'trim', id: 'b', start: 6, duration: 2 }]);
+    expect(out[1]).toMatchObject({ id: 'b', start: 6, duration: 2 });
+  });
+
+  it('rejects a trim that would make duration non-positive', () => {
+    const out = applyClipChanges(clips, [{ type: 'trim', id: 'b', start: 6, duration: 0 }]);
+    expect(out[1]).toBe(clips[1]); // unchanged
+  });
+
+  it('splits a clip into -a / -b halves at the cut, dropping the source', () => {
+    const out = applyClipChanges(clips, [{ type: 'split', id: 'b', at: 6 }]);
+    const ids = out.map(c => c.id);
+    expect(ids).toEqual(['a', 'b-a', 'b-b', 'c']);
+    const left = out.find(c => c.id === 'b-a')!;
+    const right = out.find(c => c.id === 'b-b')!;
+    expect(left).toMatchObject({ start: 5, duration: 1 });
+    expect(right).toMatchObject({ start: 6, duration: 2 });
+  });
+
+  it('ignores a split outside the clip span', () => {
+    const out = applyClipChanges(clips, [{ type: 'split', id: 'a', at: 9 }]);
+    expect(out.map(c => c.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('removes a clip', () => {
+    const out = applyClipChanges(clips, [{ type: 'remove', id: 'a' }]);
+    expect(out.map(c => c.id)).toEqual(['b', 'c']);
+  });
+
+  it('adds a clip at an index', () => {
+    const out = applyClipChanges(clips, [
+      { type: 'add', clip: { id: 'd', trackId: 't1', start: 9, duration: 1 }, index: 1 },
+    ]);
+    expect(out.map(c => c.id)).toEqual(['a', 'd', 'b', 'c']);
+  });
+
+  it('treats select changes as a no-op on the clip array', () => {
+    const out = applyClipChanges(clips, [{ type: 'select', ids: ['a', 'b'] }]);
+    expect(out).toBe(clips);
+  });
+
+  it('folds a mixed batch (move + remove + add)', () => {
+    const out = applyClipChanges(clips, [
+      { type: 'move', id: 'a', trackId: 't1', start: 1 },
+      { type: 'remove', id: 'c' },
+      { type: 'add', clip: { id: 'z', trackId: 't3', start: 0, duration: 1 } },
+    ]);
+    expect(out.map(c => c.id)).toEqual(['a', 'b', 'z']);
+    expect(out.find(c => c.id === 'a')).toMatchObject({ start: 1 });
+  });
+});
+
+describe('applyTrackChanges', () => {
+  const tracks: TimelineTrack[] = [
+    { id: 't1', label: 'Video' },
+    { id: 't2', label: 'Audio' },
+  ];
+
+  it('returns the SAME reference for an empty batch', () => {
+    expect(applyTrackChanges(tracks, [])).toBe(tracks);
+  });
+
+  it('patches a track flag immutably', () => {
+    const out = applyTrackChanges(tracks, [{ type: 'patch', id: 't1', patch: { muted: true } }]);
+    expect(out[0]).toMatchObject({ id: 't1', muted: true });
+    expect(out[1]).toBe(tracks[1]);
+  });
+
+  it('removes and adds tracks', () => {
+    const removed = applyTrackChanges(tracks, [{ type: 'remove', id: 't1' }]);
+    expect(removed.map(t => t.id)).toEqual(['t2']);
+    const added = applyTrackChanges(tracks, [{ type: 'add', track: { id: 't3' }, index: 0 }]);
+    expect(added.map(t => t.id)).toEqual(['t3', 't1', 't2']);
+  });
+});
diff --git a/vue/primitives/src/canvas/timeline/__test__/utils.test.ts b/vue/primitives/src/canvas/timeline/__test__/utils.test.ts
new file mode 100644
index 0000000..203e5f5
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/__test__/utils.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { clipIntersectsTime, clipsDuration, snapToFrame, timeToTimecode } from '../utils';
+import type { TimelineClip } from '../utils';
+
+describe('timeToTimecode', () => {
+  it('formats seconds as SMPTE HH:MM:SS:FF at fps', () => {
+    expect(timeToTimecode(0, 30)).toBe('00:00:00:00');
+    expect(timeToTimecode(1, 30)).toBe('00:00:01:00');
+    // 1.5s @ 30fps = 45 frames = 1s + 15f.
+    expect(timeToTimecode(1.5, 30)).toBe('00:00:01:15');
+    expect(timeToTimecode(61, 30)).toBe('00:01:01:00');
+  });
+});
+
+describe('snapToFrame', () => {
+  it('snaps a time to the nearest whole frame at fps', () => {
+    // 0.02s @ 30fps -> 0.6 frames -> rounds to 1 frame -> 1/30s.
+    expect(snapToFrame(0.02, 30)).toBeCloseTo(1 / 30, 6);
+    // Exact frame stays put.
+    expect(snapToFrame(2 / 30, 30)).toBeCloseTo(2 / 30, 6);
+  });
+
+  it('is a no-op for fps <= 0', () => {
+    expect(snapToFrame(1.234, 0)).toBe(1.234);
+  });
+});
+
+describe('clipsDuration', () => {
+  it('derives the largest start+duration', () => {
+    const clips: TimelineClip[] = [
+      { id: 'a', trackId: 't', start: 0, duration: 2 },
+      { id: 'b', trackId: 't', start: 5, duration: 3 }, // ends at 8
+      { id: 'c', trackId: 't', start: 1, duration: 4 },
+    ];
+    expect(clipsDuration(clips)).toBe(8);
+  });
+
+  it('is 0 for an empty set', () => {
+    expect(clipsDuration([])).toBe(0);
+  });
+});
+
+describe('clipIntersectsTime', () => {
+  const clip: TimelineClip = { id: 'a', trackId: 't', start: 4, duration: 2 }; // [4, 6]
+
+  it('intersects an overlapping window', () => {
+    expect(clipIntersectsTime(clip, 5, 7)).toBe(true);
+    expect(clipIntersectsTime(clip, 0, 4.5)).toBe(true);
+  });
+
+  it('does not intersect a disjoint window', () => {
+    expect(clipIntersectsTime(clip, 0, 3)).toBe(false);
+    expect(clipIntersectsTime(clip, 7, 9)).toBe(false);
+  });
+
+  it('normalizes a reversed window (to < from)', () => {
+    expect(clipIntersectsTime(clip, 7, 5)).toBe(true);
+  });
+});
diff --git a/vue/primitives/src/canvas/timeline/changes.ts b/vue/primitives/src/canvas/timeline/changes.ts
new file mode 100644
index 0000000..39f05ad
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/changes.ts
@@ -0,0 +1,186 @@
+import type { TimelineClip, TimelineTrack } from './utils';
+
+/**
+ * A granular track mutation, emitted via `@tracks-change` so a controlled
+ * consumer can fold flag toggles (mute/lock/solo) and height resizes into its
+ * own `tracks` array.
+ *
+ * - `patch`  — shallow-merge a partial track (flag toggles + height).
+ * - `remove` — delete the track.
+ * - `add`    — insert a track.
+ */
+export type TimelineTrackChange
+  = | { type: 'patch'; id: string; patch: Partial<TimelineTrack> }
+    | { type: 'remove'; id: string }
+    | { type: 'add'; track: TimelineTrack; index?: number };
+
+/**
+ * Apply a batch of track changes to a tracks array, returning a NEW array (and
+ * new objects only for changed tracks). Returns the SAME reference when empty.
+ */
+export function applyTrackChanges(
+  tracks: TimelineTrack[],
+  changes: TimelineTrackChange[],
+): TimelineTrack[] {
+  if (changes.length === 0) return tracks;
+
+  const byId = new Map(tracks.map(t => [t.id, t]));
+  const removed = new Set<string>();
+  const added: Array<{ item: TimelineTrack; index?: number }> = [];
+
+  for (const change of changes) {
+    switch (change.type) {
+      case 'patch': {
+        const track = byId.get(change.id);
+        if (track) byId.set(change.id, { ...track, ...change.patch });
+        break;
+      }
+      case 'remove':
+        removed.add(change.id);
+        break;
+      case 'add':
+        added.push({ item: change.track, index: change.index });
+        break;
+    }
+  }
+
+  const result = tracks
+    .filter(t => !removed.has(t.id))
+    .map(t => byId.get(t.id) ?? t);
+
+  for (const { item, index } of added) {
+    if (index === undefined || index >= result.length) result.push(item);
+    else result.splice(index, 0, item);
+  }
+
+  return result;
+}
+
+/**
+ * A granular clip mutation. `applyClipChanges` is the controlled-mode reducer:
+ * bind `@clips-change` and fold the batch into your own `clips` array (mirrors
+ * the React-Flow / `applyNodeChanges` pattern). Every variant is immutable —
+ * only the touched clips get a new object so per-clip computeds (and `v-memo`)
+ * stay effective for untouched clips.
+ *
+ * - `move`   — reposition `start` (and optionally cross-track via `trackId`).
+ * - `trim`   — adjust `start` + `duration` (a handle drag).
+ * - `split`  — cut the clip at time `at`, producing two clips (`-a` / `-b` ids).
+ * - `remove` — delete the clip.
+ * - `add`    — insert a clip.
+ * - `select` — replace the selected-clip id set (selection state, not data).
+ */
+export type TimelineClipChange<Data = unknown>
+  = | { type: 'move'; id: string; trackId: string; start: number }
+    | { type: 'trim'; id: string; start: number; duration: number }
+    | { type: 'split'; id: string; at: number }
+    | { type: 'remove'; id: string }
+    | { type: 'add'; clip: TimelineClip<Data>; index?: number }
+    | { type: 'select'; ids: string[] };
+
+/**
+ * Suffix appended to the two halves a split produces. The original id is dropped
+ * and replaced by `${id}-a` (left) and `${id}-b` (right).
+ */
+const SPLIT_LEFT = '-a';
+const SPLIT_RIGHT = '-b';
+
+/**
+ * Apply a batch of clip changes to a clips array, returning a NEW array (and new
+ * objects only for changed clips — untouched clips keep identity). Returns the
+ * SAME array reference when `changes` is empty.
+ *
+ * `select` changes carry no data payload so they are a no-op here (selection is
+ * Root state, not part of the clip model); the reducer accepts them so a mixed
+ * batch can be folded in one call.
+ *
+ * Order of operations within the batch: per-id patches (`move` / `trim`) and
+ * `split` mutate the `byId` map; `remove` collects ids; `add` is appended after
+ * filtering — matching `applyNodeChanges` semantics.
+ */
+export function applyClipChanges<Data = unknown>(
+  clips: Array<TimelineClip<Data>>,
+  changes: Array<TimelineClipChange<Data>>,
+): Array<TimelineClip<Data>> {
+  if (changes.length === 0) return clips;
+
+  const byId = new Map(clips.map(c => [c.id, c]));
+  const removed = new Set<string>();
+  const added: Array<{ item: TimelineClip<Data>; index?: number }> = [];
+  // Splits remove the source clip and insert its two halves where the source was;
+  // tracked here so ordering stays stable rather than appending to the end.
+  const splits = new Map<string, [TimelineClip<Data>, TimelineClip<Data>]>();
+  // Did any data-affecting change land? A batch of only `select` (or no-op) changes
+  // returns the SAME reference so consumers don't re-render the whole list.
+  let mutated = false;
+
+  for (const change of changes) {
+    switch (change.type) {
+      case 'move': {
+        const clip = byId.get(change.id);
+        if (clip) {
+          byId.set(change.id, { ...clip, start: change.start, trackId: change.trackId });
+          mutated = true;
+        }
+        break;
+      }
+      case 'trim': {
+        const clip = byId.get(change.id);
+        // Guard the invariant: duration must stay positive.
+        if (clip && change.duration > 0) {
+          byId.set(change.id, { ...clip, start: change.start, duration: change.duration });
+          mutated = true;
+        }
+        break;
+      }
+      case 'split': {
+        const clip = byId.get(change.id);
+        if (!clip) break;
+        const cut = change.at;
+        const leftDur = cut - clip.start;
+        const rightDur = clip.start + clip.duration - cut;
+        // Only a cut strictly inside the clip produces two clips.
+        if (leftDur <= 0 || rightDur <= 0) break;
+        const left: TimelineClip<Data> = { ...clip, id: `${clip.id}${SPLIT_LEFT}`, start: clip.start, duration: leftDur };
+        const right: TimelineClip<Data> = { ...clip, id: `${clip.id}${SPLIT_RIGHT}`, start: cut, duration: rightDur };
+        splits.set(change.id, [left, right]);
+        mutated = true;
+        break;
+      }
+      case 'remove':
+        if (byId.has(change.id)) {
+          removed.add(change.id);
+          mutated = true;
+        }
+        break;
+      case 'add':
+        added.push({ item: change.clip, index: change.index });
+        mutated = true;
+        break;
+      case 'select':
+        // Selection is Root state; nothing to fold into the clip array.
+        break;
+    }
+  }
+
+  // Only `select` (or fully no-op) changes landed: return the original array.
+  if (!mutated) return clips;
+
+  const result: Array<TimelineClip<Data>> = [];
+  for (const clip of clips) {
+    if (removed.has(clip.id)) continue;
+    const split = splits.get(clip.id);
+    if (split) {
+      result.push(split[0], split[1]);
+      continue;
+    }
+    result.push(byId.get(clip.id) ?? clip);
+  }
+
+  for (const { item, index } of added) {
+    if (index === undefined || index >= result.length) result.push(item);
+    else result.splice(index, 0, item);
+  }
+
+  return result;
+}
diff --git a/vue/primitives/src/canvas/timeline/context.ts b/vue/primitives/src/canvas/timeline/context.ts
new file mode 100644
index 0000000..45d6900
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/context.ts
@@ -0,0 +1,180 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { Direction } from '../../utilities/config-provider';
+import type { UseSnappingReturn } from '../../internal/snapping';
+import type { TimelineClip, TimelineMarker, TimelineTrack } from './utils';
+
+/**
+ * Namespaced roving-focus collection keys. Two pools live under one
+ * `TimelineRoot` — clip blocks and marker pins — so they MUST use distinct keys,
+ * otherwise the inner provider shadows the outer for every descendant (mirrors
+ * `FLOW_NODES_COLLECTION` vs `FLOW_EDGES_COLLECTION`).
+ */
+export const TIMELINE_TRACKS_COLLECTION = 'timeline-tracks';
+export const TIMELINE_CLIPS_COLLECTION = 'timeline-clips';
+
+/** A marquee rectangle in viewport-relative pixels, for rendering the overlay. */
+export interface TimelineMarqueeRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Root context shared by every timeline part. Reactive fields are `Ref` /
+ * `ShallowRef` / `ComputedRef` (never raw values — descendants would lose
+ * reactivity); mutations go through the action functions so behaviour stays in
+ * one place. `scale` / `invert` are stable closures safe on the pointer hot path.
+ */
+export interface TimelineContext {
+  /** Stable id for scoping DOM ids per timeline instance. */
+  timelineId: string;
+
+  // ── coordinate model (zoom = pixels-per-second; vertical lanes fixed) ──────
+  /** Left-edge time (seconds) of the visible window. Two-way via `v-model:offset`. */
+  offset: Ref<number>;
+  /** Zoom in pixels-per-second. Two-way via `v-model:px-per-second`. */
+  pxPerSecond: Ref<number>;
+  /** Total content duration in seconds. */
+  duration: ComputedRef<number>;
+  /** Frame rate (for timecode + frame snapping). */
+  fps: Ref<number>;
+  /** Default track-lane height in pixels (fixed; NOT zoomed). */
+  trackHeight: Ref<number>;
+  /** Live width (px) of the tracks viewport; `scale` range is `[0, width]`. */
+  viewportWidth: Ref<number>;
+  /** Project a time (seconds) to a pixel offset in the viewport. Stable identity. */
+  scale: (seconds: number) => number;
+  /** Invert a pixel offset back to a time (seconds). Stable identity. Returns 0 pre-measure. */
+  invert: (px: number) => number;
+  /** Snap a time to the nearest whole frame at `fps`. */
+  snapToFrame: (seconds: number) => number;
+  /** Format a time (seconds) as `HH:MM:SS:FF` timecode. */
+  formatTimecode: (seconds: number) => string;
+
+  // ── capability flags ──────────────────────────────────────────────────────
+  /** Snapping master enable. */
+  snapping: Ref<boolean>;
+  /** Master interactivity / disabled switch. */
+  disabled: Ref<boolean>;
+  /** Resolved reading direction. */
+  direction: ComputedRef<Direction>;
+
+  // ── data access (immutable shallow Maps — replace items, never mutate) ─────
+  /** Read path for tracks, keyed by id. */
+  trackLookup: ShallowRef<Map<string, TimelineTrack>>;
+  /** Read path for clips, keyed by id. */
+  clipLookup: ShallowRef<Map<string, TimelineClip>>;
+  /** Read path for markers, keyed by id. */
+  markerLookup: ShallowRef<Map<string, TimelineMarker>>;
+  /** Ordered track ids (declaration order). */
+  trackIds: ComputedRef<string[]>;
+  /** Ordered clip ids (sorted by start time, for roving focus). */
+  orderedClipIds: ComputedRef<string[]>;
+  /** Ordered marker ids (sorted by time). */
+  orderedMarkerIds: ComputedRef<string[]>;
+  /**
+   * The single roving tab-stop clip id (first selected clip in time order, else
+   * the first clip). Computed once in the Root so each clip does an O(1) check.
+   */
+  tabStopClipId: ComputedRef<string | undefined>;
+  /** Canonical selected-clip id set (replace wholesale). O(1) membership. */
+  selectedClipIds: ShallowRef<Set<string>>;
+  /** Live current time (playhead) in seconds. Two-way via `v-model:current-time`. */
+  currentTime: Ref<number>;
+
+  // ── shared snap engine ────────────────────────────────────────────────────
+  /** The shared snap engine; targets = clip edges + playhead + markers + grid. */
+  snapEngine: UseSnappingReturn;
+  /** Snap a candidate time, excluding an optional set of ids (a clip's own edges). */
+  snapTime: (seconds: number, exclude?: string | Set<string>) => number;
+
+  // ── mutation state ────────────────────────────────────────────────────────
+  /** True while a clip/playhead/trim gesture is mutating (blocks external sync clobber). */
+  isMutating: Readonly<Ref<boolean>>;
+  /** The id of the clip currently being dragged/trimmed (or null). */
+  draggingClipId: Readonly<Ref<string | null>>;
+
+  // ── track actions ─────────────────────────────────────────────────────────
+  /** Shallow-merge a partial into a track in the model + emit a `patch` change. */
+  patchTrack: (id: string, patch: Partial<TimelineTrack>) => void;
+
+  // ── clip actions ──────────────────────────────────────────────────────────
+  /** Insert a clip + emit an `add` change. */
+  addClip: (clip: TimelineClip) => void;
+  /** Patch a clip in the model + emit the matching change(s). */
+  updateClip: (id: string, patch: Partial<TimelineClip>) => void;
+  /** Remove a clip + emit a `remove` change. */
+  removeClip: (id: string) => void;
+  /** Split a clip at a time + emit a `split` change. */
+  splitClip: (id: string, at: number) => void;
+  /** Move a clip (transient overlay, snapped); commit on pointerup. */
+  moveClip: (id: string, start: number, trackId: string, mutating: boolean) => void;
+  /** Trim a clip start/duration (transient overlay, snapped); commit on pointerup. */
+  trimClip: (id: string, start: number, duration: number, mutating: boolean) => void;
+  /** Commit the in-flight transient mutation into the model (one change batch). */
+  commitMutation: () => void;
+  /** Nudge every selected clip by `deltaSeconds` (keyboard), then commit. */
+  nudgeSelected: (deltaSeconds: number) => void;
+  /** Move every selected clip up/down one track (keyboard), then commit. */
+  moveSelectedToAdjacentTrack: (direction: 1 | -1) => void;
+  /** Remove every selected clip + emit changes. */
+  removeSelected: () => void;
+
+  // ── playhead ──────────────────────────────────────────────────────────────
+  /** Set the playhead time (clamped, optionally snapped). Marks `isMutating` while scrubbing. */
+  setCurrentTime: (seconds: number, scrubbing?: boolean) => void;
+  /** End a scrub gesture (clears `isMutating`, emits the settle). */
+  commitScrub: () => void;
+
+  // ── selection ─────────────────────────────────────────────────────────────
+  /** Replace the selection with one clip (or toggle when `additive`). */
+  selectClip: (id: string, additive?: boolean) => void;
+  /** Replace the entire selected set. */
+  setSelection: (ids: string[]) => void;
+  /** Clear all selection. */
+  clearSelection: () => void;
+
+  // ── roving focus registration ─────────────────────────────────────────────
+  /** Register a clip element for roving focus / marquee hit-testing. */
+  registerClipEl: (id: string, el: HTMLElement) => void;
+  unregisterClipEl: (id: string) => void;
+  /** Register a marker element for roving focus. */
+  registerMarkerEl: (id: string, el: HTMLElement) => void;
+  unregisterMarkerEl: (id: string) => void;
+  /** Focus the next/prev clip in time order from `fromId` (roving). */
+  focusAdjacentClip: (fromId: string, direction: 1 | -1) => void;
+  /** Focus a clip element by id (roving Home/End). */
+  focusClip: (id: string) => void;
+
+  // ── viewport ──────────────────────────────────────────────────────────────
+  /** The tracks viewport element (marquee + scrub rect origin). */
+  viewportEl: ShallowRef<HTMLElement | null>;
+  /** Live marquee rect (viewport-relative px), or null. */
+  marquee: ShallowRef<TimelineMarqueeRect | null>;
+}
+
+const timeline = useContextFactory<TimelineContext>('TimelineContext');
+export const provideTimelineContext = timeline.provide;
+export const useTimelineContext = timeline.inject;
+
+/**
+ * Per-track sub-context. Read by `TimelineTrackHeader` and clips so they never
+ * DOM-walk to find their lane's state.
+ */
+export interface TimelineTrackContext {
+  trackId: string;
+  /** The track record (reactive). */
+  track: ComputedRef<TimelineTrack | undefined>;
+  /** Resolved lane height (px). */
+  height: ComputedRef<number>;
+  /** Toggle a boolean track flag (mute/lock/solo) + emit a track change. */
+  toggleFlag: (flag: 'muted' | 'locked' | 'soloed') => void;
+  /** Patch the track (e.g. height resize) + emit a track change. */
+  patchTrack: (patch: Partial<TimelineTrack>) => void;
+}
+
+const timelineTrack = useContextFactory<TimelineTrackContext>('TimelineTrackContext');
+export const provideTimelineTrackContext = timelineTrack.provide;
+export const useTimelineTrackContext = timelineTrack.inject;
diff --git a/vue/primitives/src/canvas/timeline/demo.vue b/vue/primitives/src/canvas/timeline/demo.vue
new file mode 100644
index 0000000..0fe1777
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/demo.vue
@@ -0,0 +1,368 @@
+<script setup lang="ts">
+import type {
+  TimelineClipData,
+  TimelineMarkerData,
+  TimelineTrackData,
+} from '@robonen/primitives';
+import {
+  TimelineClip,
+  TimelineClipHandle,
+  TimelineMarker,
+  TimelinePlayhead,
+  TimelineRoot,
+  TimelineRuler,
+  TimelineSelection,
+  TimelineTrack,
+  TimelineTrackHeader,
+  TimelineTracks,
+} from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+// ── seed data ────────────────────────────────────────────────────────────────
+const tracks = ref<TimelineTrackData[]>([
+  { id: 'video', label: 'Video', kind: 'video', height: 64 },
+  { id: 'overlay', label: 'Overlay', kind: 'video', height: 56 },
+  { id: 'audio', label: 'Audio', kind: 'audio', height: 52 },
+]);
+
+const clips = ref<TimelineClipData[]>([
+  { id: 'intro', trackId: 'video', start: 0, duration: 3.2, label: 'Intro', color: 'var(--color-accent)' },
+  { id: 'b-roll', trackId: 'video', start: 3.6, duration: 4, label: 'B-roll', color: '#0ea5e9' },
+  { id: 'outro', trackId: 'video', start: 8.2, duration: 2.4, label: 'Outro', color: 'var(--color-accent)', locked: true },
+  { id: 'title', trackId: 'overlay', start: 1, duration: 2.5, label: 'Title card', color: '#8b5cf6' },
+  { id: 'lower-third', trackId: 'overlay', start: 5.5, duration: 2.2, label: 'Lower third', color: '#ec4899' },
+  { id: 'music', trackId: 'audio', start: 0, duration: 7.8, label: 'Music bed', color: '#10b981' },
+  { id: 'vo', trackId: 'audio', start: 8.4, duration: 2.1, label: 'Voiceover', color: '#f59e0b' },
+]);
+
+const markers = ref<TimelineMarkerData[]>([
+  { id: 'm-cut', time: 3.6, label: 'Cut', color: '#f43f5e' },
+  { id: 'm-beat', time: 7, label: 'Beat drop', color: '#f59e0b' },
+]);
+
+const currentTime = ref(2.4);
+const pxPerSecond = ref(90);
+const selectedClipIds = ref<string[]>(['b-roll']);
+
+const fps = 30;
+
+// ── live readout ─────────────────────────────────────────────────────────────
+const root = ref<InstanceType<typeof TimelineRoot> | null>(null);
+
+function timecode(seconds: number): string {
+  const f = Math.max(0, Math.round(seconds * fps));
+  const frames = f % fps;
+  const totalSeconds = Math.floor(f / fps);
+  const secs = totalSeconds % 60;
+  const mins = Math.floor(totalSeconds / 60) % 60;
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${pad(mins)}:${pad(secs)}:${pad(frames)}`;
+}
+
+const selectedClip = computed(() => clips.value.find(c => selectedClipIds.value.includes(c.id)));
+
+function fitZoom(): void {
+  pxPerSecond.value = pxPerSecond.value >= 90 ? 50 : 120;
+}
+
+function splitSelected(): void {
+  const clip = selectedClip.value;
+  if (!clip) return;
+  root.value?.splitClip(clip.id, currentTime.value);
+}
+</script>
+
+<template>
+  <div class="demo-card w-full overflow-hidden rounded-card border border-border bg-bg text-fg shadow-(--shadow-card)">
+    <TimelineRoot
+      ref="root"
+      v-model:tracks="tracks"
+      v-model:clips="clips"
+      v-model:markers="markers"
+      v-model:current-time="currentTime"
+      v-model:px-per-second="pxPerSecond"
+      v-model:selected-clip-ids="selectedClipIds"
+      :fps="fps"
+      :track-height="60"
+      class="flex flex-col"
+    >
+      <!-- ── transport bar ──────────────────────────────────────────────── -->
+      <div class="flex items-center gap-3 border-b border-border bg-bg-elevated px-3 py-2">
+        <div class="flex items-center gap-1.5">
+          <span class="size-2 rounded-full bg-red-500" />
+          <span class="text-xs font-semibold uppercase tracking-wide text-fg-muted">Sequence 01</span>
+        </div>
+
+        <div class="ml-1 flex items-center rounded-md border border-border bg-bg px-2.5 py-1 font-mono text-sm tabular-nums text-fg">
+          {{ timecode(currentTime) }}
+        </div>
+
+        <div class="ml-auto flex items-center gap-2 text-xs">
+          <button
+            type="button"
+            class="rounded-md border border-border bg-bg px-2.5 py-1 font-medium text-fg-muted outline-none transition focus-visible:ring-2 focus-visible:ring-ring hover:bg-bg-inset hover:text-fg disabled:opacity-40"
+            :disabled="!selectedClip || selectedClip.locked"
+            @click="splitSelected()"
+          >
+            Split at playhead
+          </button>
+          <button
+            type="button"
+            class="rounded-md border border-border bg-bg px-2.5 py-1 font-medium text-fg-muted outline-none transition focus-visible:ring-2 focus-visible:ring-ring hover:bg-bg-inset hover:text-fg"
+            @click="fitZoom()"
+          >
+            Zoom {{ pxPerSecond }}px/s
+          </button>
+        </div>
+      </div>
+
+      <!-- ── editor body: gutter column + scale column ──────────────────── -->
+      <div class="flex">
+        <!-- track-header gutter -->
+        <div class="w-40 shrink-0 border-r border-border bg-bg-inset">
+          <!-- spacer aligning with the ruler row -->
+          <div class="h-8 border-b border-border" />
+          <TimelineTrack
+            v-for="track in tracks"
+            :key="track.id"
+            :track-id="track.id"
+            class="border-b border-border last:border-b-0"
+          >
+            <template #default="{ height }">
+              <TimelineTrackHeader
+                v-slot="{ label, muted, locked, soloed, toggleMute, toggleLock, toggleSolo, setResizeRef }"
+                class="relative flex h-full flex-col justify-center gap-1 px-3"
+                :style="{ height: `${height}px` }"
+              >
+                <span class="truncate text-sm font-medium text-fg">{{ label }}</span>
+
+                <div class="flex items-center gap-1">
+                  <button
+                    type="button"
+                    class="track-flag-btn"
+                    :class="muted ? 'is-active' : ''"
+                    :aria-pressed="muted"
+                    @click="toggleMute()"
+                  >M</button>
+                  <button
+                    type="button"
+                    class="track-flag-btn"
+                    :class="soloed ? 'is-active' : ''"
+                    :aria-pressed="soloed"
+                    @click="toggleSolo()"
+                  >S</button>
+                  <button
+                    type="button"
+                    class="track-flag-btn"
+                    :class="locked ? 'is-active' : ''"
+                    :aria-pressed="locked"
+                    @click="toggleLock()"
+                  >L</button>
+                </div>
+
+                <!-- drag-to-resize the lane height -->
+                <span
+                  :ref="setResizeRef"
+                  class="absolute inset-x-0 -bottom-1 h-2 cursor-ns-resize"
+                  aria-hidden="true"
+                />
+              </TimelineTrackHeader>
+            </template>
+          </TimelineTrack>
+        </div>
+
+        <!-- scale column: ruler + lanes share ONE coordinate origin -->
+        <div class="relative min-w-0 flex-1 overflow-hidden bg-bg">
+          <!-- time ruler -->
+          <TimelineRuler
+            v-slot="{ ticks }"
+            mode="timecode"
+            class="relative h-8 cursor-ew-resize border-b border-border bg-bg-elevated select-none"
+          >
+            <div
+              v-for="tick in ticks"
+              :key="tick.value"
+              class="pointer-events-none absolute bottom-0 flex flex-col items-start"
+              :style="{ left: `${tick.px}px` }"
+            >
+              <span
+                class="w-px bg-border-strong"
+                :class="tick.major ? 'h-3' : 'h-1.5'"
+              />
+              <span
+                v-if="tick.major"
+                class="absolute -top-5 left-0 -translate-x-1/2 whitespace-nowrap font-mono text-[10px] tabular-nums text-fg-subtle"
+              >{{ tick.label }}</span>
+            </div>
+          </TimelineRuler>
+
+          <!-- lanes viewport (the scale's range origin lives here) -->
+          <TimelineTracks v-slot="{ marquee }" class="relative">
+            <TimelineTrack
+              v-for="track in tracks"
+              :key="track.id"
+              :track-id="track.id"
+              class="relative border-b border-border last:border-b-0"
+              :class="track.kind === 'audio' ? 'bg-bg-inset/60' : ''"
+            >
+              <!-- clips on this lane. State is read off the component's own
+                   data-attributes (data-selected / data-dragging / data-locked)
+                   via CSS variants, so styling stays decoupled from slot props. -->
+              <template v-for="clip in clips" :key="clip.id">
+                <TimelineClip
+                  v-if="clip.trackId === track.id"
+                  v-slot="{ clip: c }"
+                  :clip-id="clip.id"
+                  class="timeline-clip group absolute inset-y-1 cursor-grab touch-none overflow-hidden rounded-md border border-border-strong shadow-sm outline-none transition-shadow active:cursor-grabbing focus-visible:ring-2 focus-visible:ring-ring data-[dragging]:shadow-lg data-[locked]:cursor-not-allowed data-[selected]:z-10 data-[selected]:border-accent data-[selected]:ring-2 data-[selected]:ring-accent/50"
+                  :style="{ background: `color-mix(in oklch, ${clip.color ?? 'var(--color-accent)'} 22%, var(--color-bg))` }"
+                >
+                  <!-- accent spine -->
+                  <span
+                    class="absolute inset-y-0 left-0 w-1"
+                    :style="{ backgroundColor: clip.color ?? 'var(--color-accent)' }"
+                  />
+
+                  <div class="flex h-full flex-col justify-center gap-0.5 pl-2.5 pr-2">
+                    <span class="flex items-center gap-1 truncate text-xs font-semibold text-fg">
+                      <svg v-if="clip.locked" viewBox="0 0 24 24" class="size-3 shrink-0 text-fg-muted" fill="none" stroke="currentColor" stroke-width="2"><rect x="5" y="11" width="14" height="9" rx="2" /><path d="M8 11V8a4 4 0 0 1 8 0v3" /></svg>
+                      {{ c?.label }}
+                    </span>
+                    <span class="truncate font-mono text-[10px] tabular-nums text-fg-subtle">{{ timecode(c?.duration ?? 0) }}</span>
+                  </div>
+
+                  <!-- waveform-ish hint for audio clips -->
+                  <span
+                    v-if="track.kind === 'audio'"
+                    class="pointer-events-none absolute inset-x-2 bottom-1 flex h-3 items-end gap-px opacity-50"
+                  >
+                    <span
+                      v-for="n in 28"
+                      :key="n"
+                      class="flex-1 rounded-sm"
+                      :style="{ height: `${30 + Math.abs(Math.sin(n * 1.3)) * 70}%`, backgroundColor: clip.color ?? 'var(--color-accent)' }"
+                    />
+                  </span>
+
+                  <!-- trim handles (revealed on hover, or when the clip is selected) -->
+                  <template v-if="!clip.locked">
+                    <TimelineClipHandle side="start" class="trim-handle left-0" />
+                    <TimelineClipHandle side="end" class="trim-handle right-0" />
+                  </template>
+                </TimelineClip>
+              </template>
+            </TimelineTrack>
+
+            <!-- markers (chapter pins) span the full lane stack -->
+            <TimelineMarker
+              v-for="marker in markers"
+              :key="marker.id"
+              v-slot="{ marker: m }"
+              :marker-id="marker.id"
+              as="button"
+              class="absolute z-20 flex -translate-x-1/2 flex-col items-center outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              style="top: 0; bottom: 0"
+            >
+              <span
+                class="flex items-center gap-1 rounded-b-sm px-1.5 py-0.5 text-[10px] font-semibold text-white shadow-sm"
+                :style="{ backgroundColor: m?.color ?? 'var(--color-accent)' }"
+              >{{ m?.label }}</span>
+              <span class="w-px flex-1" :style="{ backgroundColor: m?.color ?? 'var(--color-accent)' }" />
+            </TimelineMarker>
+
+            <!-- playhead -->
+            <TimelinePlayhead
+              v-slot="{ currentTime: t }"
+              class="z-30 cursor-ew-resize outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              style="bottom: 0"
+            >
+              <span class="absolute -left-1.5 -top-0.5 size-3 rounded-sm bg-red-500 shadow-sm" />
+              <span class="absolute inset-y-0 left-0 w-0.5 -translate-x-1/2 bg-red-500" />
+              <span class="sr-only">{{ timecode(t) }}</span>
+            </TimelinePlayhead>
+
+            <!-- marquee selection overlay -->
+            <TimelineSelection
+              v-if="marquee"
+              class="z-40 rounded-sm border border-accent bg-accent/15"
+            />
+          </TimelineTracks>
+        </div>
+      </div>
+
+      <!-- ── status bar ─────────────────────────────────────────────────── -->
+      <div class="flex items-center gap-4 border-t border-border bg-bg-elevated px-3 py-1.5 text-[11px] text-fg-subtle">
+        <span>{{ tracks.length }} tracks</span>
+        <span>{{ clips.length }} clips</span>
+        <span class="flex items-center gap-1">
+          <span class="size-1.5 rounded-full bg-accent" />
+          {{ selectedClip ? selectedClip.label : 'No' }} selected
+        </span>
+        <span class="ml-auto">Drag clips to move · drag edges to trim · drag the ruler to scrub</span>
+      </div>
+    </TimelineRoot>
+  </div>
+</template>
+
+<style scoped>
+.track-flag-btn {
+  display: grid;
+  place-items: center;
+  width: 1.1rem;
+  height: 1.1rem;
+  border-radius: 0.25rem;
+  font-size: 10px;
+  font-weight: 700;
+  line-height: 1;
+  color: var(--color-fg-subtle, #94a3b8);
+  background: var(--color-bg, #fff);
+  border: 1px solid var(--color-border, #e2e8f0);
+  cursor: pointer;
+  transition: all 0.12s;
+}
+.track-flag-btn:hover {
+  color: var(--color-fg, #0f172a);
+}
+.track-flag-btn:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--color-ring, #6366f1);
+}
+.track-flag-btn.is-active {
+  color: #fff;
+  background: var(--color-accent, #6366f1);
+  border-color: var(--color-accent, #6366f1);
+}
+
+.trim-handle {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 8px;
+  cursor: ew-resize;
+  z-index: 5;
+  opacity: 0;
+  transition: opacity 0.12s;
+  touch-action: none;
+}
+.timeline-clip:hover .trim-handle,
+.timeline-clip[data-selected] .trim-handle,
+.trim-handle:focus-visible {
+  opacity: 1;
+}
+.trim-handle::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 2px;
+  height: 40%;
+  transform: translate(-50%, -50%);
+  border-radius: 9999px;
+  background: var(--color-fg, #0f172a);
+  opacity: 0.5;
+}
+.trim-handle:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--color-ring, #6366f1);
+  border-radius: 4px;
+}
+</style>
diff --git a/vue/primitives/src/canvas/timeline/index.ts b/vue/primitives/src/canvas/timeline/index.ts
new file mode 100644
index 0000000..214fa9d
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/index.ts
@@ -0,0 +1,66 @@
+export { default as TimelineRoot } from './TimelineRoot.vue';
+export type { TimelineRootProps, TimelineRootEmits } from './TimelineRoot.vue';
+
+export { default as TimelineRuler } from './TimelineRuler.vue';
+export type { TimelineRulerProps } from './TimelineRuler.vue';
+
+export { default as TimelineTracks } from './TimelineTracks.vue';
+export type { TimelineTracksProps } from './TimelineTracks.vue';
+
+export { default as TimelineTrack } from './TimelineTrack.vue';
+export type { TimelineTrackProps } from './TimelineTrack.vue';
+
+export { default as TimelineTrackHeader } from './TimelineTrackHeader.vue';
+export type { TimelineTrackHeaderProps } from './TimelineTrackHeader.vue';
+
+export { default as TimelineClip } from './TimelineClip.vue';
+export type { TimelineClipProps } from './TimelineClip.vue';
+
+export { default as TimelineClipHandle } from './TimelineClipHandle.vue';
+export type { TimelineClipHandleProps } from './TimelineClipHandle.vue';
+
+export { default as TimelinePlayhead } from './TimelinePlayhead.vue';
+export type { TimelinePlayheadProps } from './TimelinePlayhead.vue';
+
+export { default as TimelineMarker } from './TimelineMarker.vue';
+export type { TimelineMarkerProps } from './TimelineMarker.vue';
+
+export { default as TimelineSelection } from './TimelineSelection.vue';
+export type { TimelineSelectionProps } from './TimelineSelection.vue';
+
+export {
+  TIMELINE_CLIPS_COLLECTION,
+  TIMELINE_TRACKS_COLLECTION,
+  provideTimelineContext,
+  provideTimelineTrackContext,
+  useTimelineContext,
+  useTimelineTrackContext,
+} from './context';
+export type {
+  TimelineContext,
+  TimelineMarqueeRect,
+  TimelineTrackContext,
+} from './context';
+
+export {
+  applyClipChanges,
+  applyTrackChanges,
+} from './changes';
+export type {
+  TimelineClipChange,
+  TimelineTrackChange,
+} from './changes';
+
+export {
+  clipIntersectsTime,
+  clipsDuration,
+  snapToFrame,
+  timeToTimecode,
+} from './utils';
+// Data interfaces are aliased with a `Data` suffix so they do not collide with
+// the same-named part components (`TimelineClip` / `TimelineMarker` / `Track`).
+export type {
+  TimelineClip as TimelineClipData,
+  TimelineMarker as TimelineMarkerData,
+  TimelineTrack as TimelineTrackData,
+} from './utils';
diff --git a/vue/primitives/src/canvas/timeline/utils.ts b/vue/primitives/src/canvas/timeline/utils.ts
new file mode 100644
index 0000000..1cf0dbe
--- /dev/null
+++ b/vue/primitives/src/canvas/timeline/utils.ts
@@ -0,0 +1,104 @@
+import { framesToSeconds, framesToTimecode, secondsToFrames } from '../../internal/scale';
+
+/**
+ * A track lane in the timeline. Tracks stack vertically; their height is fixed
+ * (NOT affected by horizontal zoom) and read from `height` (falling back to the
+ * Root's `trackHeight`).
+ */
+export interface TimelineTrack {
+  /** Stable identity. */
+  id: string;
+  /** Human label rendered in the gutter. */
+  label?: string;
+  /** Lane height in pixels (overrides the Root default). */
+  height?: number;
+  /** Muted state (audio off). */
+  muted?: boolean;
+  /** Locked state (clips not editable). */
+  locked?: boolean;
+  /** Soloed state. */
+  soloed?: boolean;
+  /** Hidden lane (not rendered). */
+  hidden?: boolean;
+  /** Free-form kind tag (`'video'` / `'audio'` / …). */
+  kind?: string;
+}
+
+/**
+ * A clip on a track. `start` / `duration` are in SECONDS (the timeline's domain
+ * unit); pixel geometry is derived via the Root's scale (`pxPerSecond`).
+ */
+export interface TimelineClip<Data = unknown> {
+  /** Stable identity. */
+  id: string;
+  /** Owning track id. */
+  trackId: string;
+  /** Start time in seconds. */
+  start: number;
+  /** Duration in seconds (always `> 0`). */
+  duration: number;
+  /** Human label. */
+  label?: string;
+  /** Display color token. */
+  color?: string;
+  /** Locked clip (not draggable / trimmable). */
+  locked?: boolean;
+  /** Consumer payload. */
+  data?: Data;
+}
+
+/**
+ * A marker pinned to a time on the timeline (chapter / cue point).
+ */
+export interface TimelineMarker {
+  /** Stable identity. */
+  id: string;
+  /** Time in seconds. */
+  time: number;
+  /** Human label. */
+  label?: string;
+  /** Display color token. */
+  color?: string;
+}
+
+/**
+ * Convert a time in seconds to its SMPTE timecode string at `fps`. Thin wrapper
+ * routed through the shared `scale` timecode helpers so the timeline and ruler
+ * format identically.
+ */
+export function timeToTimecode(seconds: number, fps: number, dropFrame = false): string {
+  return framesToTimecode(secondsToFrames(seconds, fps), fps, dropFrame);
+}
+
+/**
+ * Snap a time (seconds) to the nearest whole frame at `fps`. Used as the keyboard
+ * nudge granularity and the default snap grid.
+ */
+export function snapToFrame(seconds: number, fps: number): number {
+  if (fps <= 0) return seconds;
+  return framesToSeconds(secondsToFrames(seconds, fps), fps);
+}
+
+/**
+ * Auto-derive the content duration from a set of clips: the largest
+ * `start + duration`. Returns `0` for an empty set.
+ */
+export function clipsDuration(clips: Iterable<TimelineClip>): number {
+  let max = 0;
+  for (const c of clips) {
+    const end = c.start + c.duration;
+    if (end > max) max = end;
+  }
+  return max;
+}
+
+/**
+ * Test whether a clip's time span `[start, start+duration]` intersects a
+ * time window `[from, to]` (half-open-tolerant; touching edges count as an
+ * intersection so a zero-width marquee on an edge still selects).
+ */
+export function clipIntersectsTime(clip: TimelineClip, from: number, to: number): boolean {
+  const lo = Math.min(from, to);
+  const hi = Math.max(from, to);
+  return clip.start <= hi && clip.start + clip.duration >= lo;
+}
diff --git a/vue/primitives/src/canvas/transform-box/TransformBoxHandle.vue b/vue/primitives/src/canvas/transform-box/TransformBoxHandle.vue
new file mode 100644
index 0000000..ac8efcc
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/TransformBoxHandle.vue
@@ -0,0 +1,148 @@
+<script lang="ts">
+import type { CSSProperties } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { TransformBoxHandlePosition } from './utils';
+
+/**
+ * One of the eight scale handles on a `TransformBoxRoot` (four edges + four
+ * corners). Rendered as a native focusable `<button type="button">` so it is
+ * keyboard-reachable and announced; the default `aria-label` is derived from
+ * `position` (e.g. `"Resize top-left"`).
+ *
+ * Dragging resizes the edge/corner it controls while the OPPOSITE edge stays
+ * anchored in world space — even when the box is rotated, because the root
+ * rotates the screen delta into the box's local axes first. Hold Shift on a
+ * corner to lock the aspect ratio, Alt to resize symmetrically about the pivot.
+ * When `allowFlip` is `false` on the root, pushing past the anchor clamps at the
+ * minimum size instead of flipping.
+ *
+ * Keyboard (when focused): Arrow keys resize by the root's `keyboardStep`,
+ * Shift+Arrow aspect-locks, Alt+Arrow resizes symmetrically about the pivot.
+ */
+export interface TransformBoxHandleProps extends PrimitiveProps {
+  /** Which edge or corner this handle controls. */
+  position: TransformBoxHandlePosition;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, useAttrs, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useTransformBoxContext } from './context';
+import { handleLabel } from './utils';
+
+const { as = 'button', position } = defineProps<TransformBoxHandleProps>();
+const ctx = useTransformBoxContext();
+const attrs = useAttrs();
+
+const handleRef = shallowRef<HTMLElement | null>(null);
+
+// `usePointerDrag.onEnd` fires on BOTH pointerup and pointercancel and clears
+// the gesture state; `onCommit` fires AFTER `onEnd` on a successful pointerup
+// only and emits `transformCommit`. Splitting the two means a cancel tears down
+// without emitting while a real release commits.
+usePointerDrag(handleRef, {
+  threshold: 0,
+  // A press on a handle must NOT bubble to the root's move gesture.
+  stopPropagation: true,
+  disabled: () => ctx.disabled.value,
+  onStart: () => {
+    ctx.beginScale(position);
+  },
+  onMove: (state) => {
+    ctx.updateScale(position, { x: state.total.x, y: state.total.y }, {
+      shift: state.modifiers.shift,
+      alt: state.modifiers.alt,
+    });
+  },
+  onEnd: () => {
+    ctx.endScale(false);
+  },
+  onCommit: () => {
+    ctx.endScale(true);
+  },
+});
+
+// Default aria-label only when the consumer has not supplied one.
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return handleLabel(position);
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const step = ctx.keyboardStep.value;
+  const mods = { shift: event.shiftKey, alt: event.altKey };
+  // Map an arrow to a LOCAL-axis edge delta. The sign already matches the
+  // box's own axes (handle math anchors the opposite edge), so a right-edge
+  // ArrowRight grows width regardless of which edge is dragged.
+  let dx = 0;
+  let dy = 0;
+  switch (event.key) {
+    case 'ArrowLeft':
+      dx = -step;
+      break;
+    case 'ArrowRight':
+      dx = step;
+      break;
+    case 'ArrowUp':
+      dy = -step;
+      break;
+    case 'ArrowDown':
+      dy = step;
+      break;
+    default:
+      return;
+  }
+  event.preventDefault();
+  // Stop the body's arrow-move from also firing.
+  event.stopPropagation();
+  ctx.nudgeScale(position, dx, dy, mods);
+}
+
+const positionStyle = computed<CSSProperties>(() => {
+  // Place the handle at its edge/corner. Corners → exact corners; edges →
+  // edge midpoints. Centered via translate so a non-zero box keeps handles on
+  // the boundary even at w=0/h=0 (they stack at the single point but remain
+  // individually targetable since each is a separate focusable button).
+  const left = position.includes('left') ? '0%' : position.includes('right') ? '100%' : '50%';
+  const top = position.includes('top') ? '0%' : position.includes('bottom') ? '100%' : '50%';
+  return {
+    position: 'absolute',
+    left,
+    top,
+    transform: 'translate(-50%, -50%)',
+    touchAction: 'none',
+  };
+});
+
+defineExpose({ position });
+
+// `useForwardExpose` runs AFTER `defineExpose` so it merges the prior expose
+// bindings; `currentElement` resolves the underlying button for the drag.
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (el) => {
+  handleRef.value = el ?? null;
+}, { immediate: true });
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    :data-position="position"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :aria-label="accessibleLabel"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :position="position" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/transform-box/TransformBoxRoot.vue b/vue/primitives/src/canvas/transform-box/TransformBoxRoot.vue
new file mode 100644
index 0000000..8746d8c
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/TransformBoxRoot.vue
@@ -0,0 +1,458 @@
+<script lang="ts">
+import type { CSSProperties, Ref } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { TransformBoxDirection, TransformBoxModifiers } from './context';
+import type { Point, TransformBoxHandlePosition, TransformBoxPivot, TransformBoxValue } from './utils';
+
+/**
+ * A headless move / scale / rotate bounding box. The root owns the transform
+ * `{ x, y, width, height, rotation }` (controlled via `v-model` or uncontrolled
+ * via `defaultValue`), sizes and rotates itself to it, and provides the gesture
+ * machinery to its handle parts: `TransformBoxHandle` (8 scale handles),
+ * `TransformBoxRotateHandle`, and the optional `TransformBoxStatus` live region.
+ *
+ * All math (rotated-box resize, aspect lock, flip, rotation) lives in pure
+ * helpers in `./utils` so Crop can share `resizeEdge`/`constrainRect`/etc.
+ * without importing any component. The body itself is draggable (move) and
+ * keyboard-focusable (arrow-move); handles delegate their gesture math here.
+ *
+ * Reach for it whenever a user repositions, resizes, or rotates a free object on
+ * a canvas (image, shape, text frame, crop region).
+ */
+export interface TransformBoxRootProps extends PrimitiveProps {
+  /** Controlled transform (`v-model`). `null` resets to `defaultValue`. */
+  modelValue?: TransformBoxValue | null;
+  /**
+   * Uncontrolled initial transform.
+   * @default { x: 0, y: 0, width: 100, height: 100, rotation: 0 }
+   */
+  defaultValue?: TransformBoxValue;
+  /**
+   * Lock the width/height ratio (`width / height`) during scaling. `null`
+   * disables the lock; corners still aspect-lock while Shift is held.
+   * @default null
+   */
+  aspectRatio?: number | null;
+  /**
+   * Snap rotation to multiples of this many degrees while Shift is held during a
+   * rotate drag. `0` disables rotation snapping.
+   * @default 0
+   */
+  rotationSnap?: number;
+  /**
+   * Allow corners/edges to flip past their anchor (negative size, mirrored).
+   * When `false`, an edge clamps at the minimum size instead of flipping.
+   * @default true
+   */
+  allowFlip?: boolean;
+  /** Minimum box width. @default 1 */
+  minWidth?: number;
+  /** Minimum box height. @default 1 */
+  minHeight?: number;
+  /**
+   * Pivot that rotation and symmetric (Alt) resize anchor to: `'center'` or a
+   * fractional `{ x, y }` in `[0, 1]²` of the box.
+   * @default 'center'
+   */
+  pivot?: TransformBoxPivot;
+  /** Per-keystroke move/resize step (Arrow keys). @default 1 */
+  keyboardStep?: number;
+  /** Larger move step (Shift+Arrow when moving the body). @default 10 */
+  keyboardLargeStep?: number;
+  /** Per-keystroke rotation step in degrees (rotate handle). @default 1 */
+  rotationStep?: number;
+  /**
+   * Whether the box is selected/active (`v-model:selected`). A standalone box
+   * defaults to selected; a multi-object editor binds this for click-to-activate.
+   * @default true
+   */
+  selected?: boolean;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /**
+   * Writing direction. Omitted → inherited from the nearest `ConfigProvider`
+   * (falling back to `'ltr'`); affects horizontal keyboard nudge sign.
+   */
+  dir?: TransformBoxDirection;
+}
+
+export interface TransformBoxRootEmits {
+  /** Emitted when a gesture or keypress settles, with the final transform. */
+  transformCommit: [value: TransformBoxValue];
+}
+
+/** Default transform for the uncontrolled box. */
+const DEFAULT_VALUE: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 0 };
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useDirection } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+import { useSnapping } from '../../internal/snapping';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { provideTransformBoxContext } from './context';
+import {
+  boxCenter,
+  constrainRect,
+  moveBox,
+  pointerAngle,
+  resizeEdge,
+  resolvePivot,
+  rotatePoint,
+  rotateVector,
+  shortestAngleDelta,
+  snapRotation,
+} from './utils';
+
+const {
+  defaultValue = DEFAULT_VALUE,
+  aspectRatio = null,
+  rotationSnap = 0,
+  allowFlip = true,
+  minWidth = 1,
+  minHeight = 1,
+  pivot = 'center',
+  keyboardStep = 1,
+  keyboardLargeStep = 10,
+  rotationStep = 1,
+  disabled = false,
+  dir,
+  as = 'div',
+} = defineProps<TransformBoxRootProps>();
+
+const emit = defineEmits<TransformBoxRootEmits>();
+const direction = useDirection(() => dir);
+
+// `defineModel` drives controlled (`v-model`) and uncontrolled modes; in
+// uncontrolled mode it is `undefined` until first write, so `localValue` seeds
+// from `defaultValue`. `null` resets to `defaultValue` for parity with the rest
+// of the package.
+const model = defineModel<TransformBoxValue | null>();
+const selectedModel = defineModel<boolean>('selected', { default: true });
+
+// `shallowRef` — the transform object is always replaced wholesale.
+const localValue = shallowRef<TransformBoxValue>(model.value ? { ...model.value } : { ...defaultValue });
+
+watch(model, (v) => {
+  if (v === null || v === undefined) {
+    localValue.value = { ...defaultValue };
+    return;
+  }
+  if (v === localValue.value) return;
+  localValue.value = { ...v };
+});
+
+const value = computed<TransformBoxValue>({
+  get: () => localValue.value,
+  set: (v) => {
+    localValue.value = v;
+    // `defineModel` emits `update:modelValue` on write — no manual emit needed.
+    model.value = v;
+  },
+});
+
+const flippedX = shallowRef(false);
+const flippedY = shallowRef(false);
+const transforming = shallowRef(false);
+
+/** Normalize (min-size + flip fold) then write a transform, preserving rotation. */
+function setValueRaw(next: TransformBoxValue): void {
+  if (disabled) return;
+  const norm = constrainRect(next, minWidth, minHeight);
+  norm.rotation = next.rotation;
+  value.value = norm;
+}
+
+function commit(): void {
+  emit('transformCommit', { ...localValue.value });
+}
+
+function setSelected(v: boolean): void {
+  if (disabled) return;
+  if (selectedModel.value === v) return;
+  selectedModel.value = v;
+}
+
+// ── snapping engine ───────────────────────────────────────────────────────────
+// The root owns one snap engine; consumers feed it targets via the context.
+// Kept as a 2d point snap so a moved box can snap on either axis. Targets [].
+const snapping = useSnapping({
+  enabled: () => !disabled,
+  axis: '2d',
+});
+
+const rootRef = shallowRef<HTMLElement | null>(null);
+
+/** Client-space center of the current box, derived from the rendered rect. */
+function clientCenter(): Point | null {
+  const el = rootRef.value;
+  if (!el) return null;
+  const rect = el.getBoundingClientRect();
+  if (rect.width === 0 && rect.height === 0) {
+    // Degenerate box (w=0/h=0): the rect still has a position; use its top-left.
+    return { x: rect.left, y: rect.top };
+  }
+  return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+}
+
+// ── scale gesture (math owned here; the handle drives the pointer) ─────────────
+let scaleStartBox: TransformBoxValue | null = null;
+
+function beginScale(_handle: TransformBoxHandlePosition): void {
+  if (disabled) return;
+  scaleStartBox = { ...localValue.value };
+  transforming.value = true;
+  setSelected(true);
+}
+
+function updateScale(handle: TransformBoxHandlePosition, screenDelta: Point, mods: TransformBoxModifiers): void {
+  if (!scaleStartBox) return;
+  // Screen-space cumulative delta → rotate into the box's LOCAL axes. This is
+  // the load-bearing step for rotated boxes: an axis-aligned delta is wrong once
+  // rotation ≠ 0.
+  const local = rotateVector(screenDelta, -scaleStartBox.rotation);
+  // Shift requests an aspect lock at the start box's ratio (corners); the
+  // explicit `aspectRatio` prop always locks regardless of Shift.
+  const ratio = mods.shift && (aspectRatio === null || aspectRatio === undefined)
+    ? (scaleStartBox.height === 0 ? 1 : Math.abs(scaleStartBox.width / scaleStartBox.height))
+    : aspectRatio;
+  const result = resizeEdge(scaleStartBox, handle, local, {
+    minWidth,
+    minHeight,
+    aspectRatio: ratio,
+    symmetric: mods.alt,
+    pivot,
+    allowFlip,
+  });
+  flippedX.value = result.flippedX;
+  flippedY.value = result.flippedY;
+  setValueRaw(result.box);
+}
+
+function endScale(doCommit: boolean): void {
+  transforming.value = false;
+  scaleStartBox = null;
+  if (doCommit) commit();
+}
+
+// ── rotate gesture ─────────────────────────────────────────────────────────────
+let rotStartAngle = 0;
+let rotStartRotation = 0;
+let rotPivotClient: Point | null = null;
+
+function beginRotate(pointer: Point, _handleEl: HTMLElement): void {
+  if (disabled) return;
+  transforming.value = true;
+  setSelected(true);
+  const center = clientCenter();
+  if (!center) {
+    rotPivotClient = null;
+    return;
+  }
+  const box = localValue.value;
+  const localPivot = resolvePivot(box, pivot);
+  const localCenter = boxCenter(box);
+  // Offset of pivot from center in local axes, rotated to client space.
+  const offset = rotatePoint(
+    { x: localPivot.x - localCenter.x, y: localPivot.y - localCenter.y },
+    box.rotation,
+  );
+  rotPivotClient = { x: center.x + offset.x, y: center.y + offset.y };
+  rotStartRotation = box.rotation;
+  rotStartAngle = pointerAngle(pointer, rotPivotClient);
+}
+
+function updateRotate(pointer: Point, mods: TransformBoxModifiers): void {
+  if (!rotPivotClient) return;
+  const current = pointerAngle(pointer, rotPivotClient);
+  let next = rotStartRotation + shortestAngleDelta(rotStartAngle, current);
+  if (mods.shift && rotationSnap > 0) next = snapRotation(next, rotationSnap);
+  setValueRaw({ ...localValue.value, rotation: next });
+}
+
+function endRotate(doCommit: boolean): void {
+  transforming.value = false;
+  rotPivotClient = null;
+  if (doCommit) commit();
+}
+
+// ── move gesture (whole-box drag, owned by the root) ───────────────────────────
+let moveStartBox: TransformBoxValue | null = null;
+
+usePointerDrag(rootRef, {
+  threshold: 3,
+  disabled: () => disabled,
+  buttons: [0],
+  onStart: () => {
+    moveStartBox = { ...localValue.value };
+    transforming.value = true;
+    setSelected(true);
+  },
+  onMove: (state) => {
+    if (!moveStartBox) return;
+    // Move is in WORLD/client space; translation is rotation-invariant. Snap the
+    // moved origin if targets are configured.
+    const moved = moveBox(moveStartBox, { x: state.total.x, y: state.total.y });
+    const snapped = snapping.snap2d({ x: moved.x, y: moved.y });
+    setValueRaw({ ...moved, x: snapped.point.x, y: snapped.point.y });
+  },
+  onEnd: () => {
+    transforming.value = false;
+    moveStartBox = null;
+    snapping.reset();
+  },
+  onCommit: () => commit(),
+});
+
+// ── keyboard ────────────────────────────────────────────────────────────────────
+function dirSign(): number {
+  return direction.value === 'rtl' ? -1 : 1;
+}
+
+function nudgeMove(dx: number, dy: number): void {
+  if (disabled) return;
+  setValueRaw(moveBox(localValue.value, { x: dx, y: dy }));
+  commit();
+}
+
+function nudgeScale(handle: TransformBoxHandlePosition, dx: number, dy: number, mods: TransformBoxModifiers): void {
+  if (disabled) return;
+  const box = localValue.value;
+  // Keyboard deltas are already in the box's LOCAL axes (Arrow keys map to
+  // edges, not screen pixels), so no rotation transform is applied.
+  const ratio = mods.shift
+    ? (box.height === 0 ? 1 : Math.abs(box.width / box.height))
+    : aspectRatio;
+  const result = resizeEdge(box, handle, { x: dx, y: dy }, {
+    minWidth,
+    minHeight,
+    aspectRatio: ratio,
+    symmetric: mods.alt,
+    pivot,
+    allowFlip,
+  });
+  flippedX.value = result.flippedX;
+  flippedY.value = result.flippedY;
+  setValueRaw(result.box);
+  commit();
+}
+
+function nudgeRotate(delta: number): void {
+  if (disabled) return;
+  setValueRaw({ ...localValue.value, rotation: localValue.value.rotation + delta });
+  commit();
+}
+
+function onBodyKeyDown(event: KeyboardEvent): void {
+  if (disabled) return;
+  const step = event.shiftKey ? keyboardLargeStep : keyboardStep;
+  const sign = dirSign();
+  let dx = 0;
+  let dy = 0;
+  switch (event.key) {
+    case 'ArrowLeft':
+      dx = -step * sign;
+      break;
+    case 'ArrowRight':
+      dx = step * sign;
+      break;
+    case 'ArrowUp':
+      dy = -step;
+      break;
+    case 'ArrowDown':
+      dy = step;
+      break;
+    default:
+      return;
+  }
+  event.preventDefault();
+  nudgeMove(dx, dy);
+}
+
+// ── render geometry ─────────────────────────────────────────────────────────────
+const boxStyle = computed<CSSProperties>(() => {
+  const v = localValue.value;
+  // Rotate about the box center so `pivot` stays decoupled from the CSS origin
+  // (pivot only drives symmetric resize/rotation math, not the render box).
+  return {
+    position: 'absolute',
+    left: '0',
+    top: '0',
+    width: `${Math.max(0, v.width)}px`,
+    height: `${Math.max(0, v.height)}px`,
+    transform: `translate(${v.x}px, ${v.y}px) rotate(${v.rotation}deg)`,
+    transformOrigin: 'center center',
+    touchAction: 'none',
+  };
+});
+
+// Keep the box valid if min-size props change.
+watch([() => minWidth, () => minHeight], () => {
+  const norm = constrainRect(localValue.value, minWidth, minHeight);
+  norm.rotation = localValue.value.rotation;
+  if (norm.width !== localValue.value.width || norm.height !== localValue.value.height) {
+    setValueRaw(norm);
+  }
+});
+
+provideTransformBoxContext({
+  value,
+  setValue: setValueRaw,
+  beginScale,
+  updateScale,
+  endScale,
+  beginRotate,
+  updateRotate,
+  endRotate,
+  nudgeScale,
+  nudgeMove,
+  nudgeRotate,
+  snapping,
+  selected: selectedModel as unknown as Ref<boolean>,
+  setSelected,
+  disabled: toRef(() => disabled),
+  transforming,
+  direction,
+  pivot: toRef(() => pivot),
+  keyboardStep: toRef(() => keyboardStep),
+  keyboardLargeStep: toRef(() => keyboardLargeStep),
+  rotationStep: toRef(() => rotationStep),
+  rotationSnap: toRef(() => rotationSnap),
+  flippedX,
+  flippedY,
+});
+
+defineExpose({ value, selected: selectedModel });
+
+// `useForwardExpose` runs AFTER `defineExpose` so it merges the prior expose
+// bindings (plus props + `$el`) instead of clobbering them.
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (el) => {
+  rootRef.value = el ?? null;
+}, { immediate: true });
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    tabindex="0"
+    :dir="direction"
+    :style="boxStyle"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-selected="selectedModel ? '' : undefined"
+    :data-transforming="transforming ? '' : undefined"
+    :data-flipped-x="flippedX ? '' : undefined"
+    :data-flipped-y="flippedY ? '' : undefined"
+    @keydown="onBodyKeyDown"
+  >
+    <slot
+      :value="value"
+      :selected="selectedModel"
+      :transforming="transforming"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/transform-box/TransformBoxRotateHandle.vue b/vue/primitives/src/canvas/transform-box/TransformBoxRotateHandle.vue
new file mode 100644
index 0000000..87ad980
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/TransformBoxRotateHandle.vue
@@ -0,0 +1,114 @@
+<script lang="ts">
+import type { CSSProperties } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The rotate handle of a `TransformBoxRoot`, rendered as a native focusable
+ * `<button type="button">` with a default `aria-label` of `"Rotate"`. Dragging
+ * it rotates the box about the root's `pivot`: the root computes the angle from
+ * the pivot to the pointer with `atan2` and accumulates the signed shortest
+ * delta so dragging across the 0°/360° seam stays smooth. Holding Shift snaps
+ * the rotation to the root's `rotationSnap` increments.
+ *
+ * Keyboard (when focused): Arrow Left/Down rotate by `-rotationStep`, Arrow
+ * Right/Up by `+rotationStep`; Shift+Arrow rotates by `rotationSnap` (when set).
+ *
+ * Position it yourself (commonly a stem above the top edge) via CSS; the default
+ * style centers it on the top-center of the box.
+ */
+export interface TransformBoxRotateHandleProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, useAttrs, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useTransformBoxContext } from './context';
+
+const { as = 'button' } = defineProps<TransformBoxRotateHandleProps>();
+const ctx = useTransformBoxContext();
+const attrs = useAttrs();
+
+const handleRef = shallowRef<HTMLElement | null>(null);
+
+usePointerDrag(handleRef, {
+  threshold: 0,
+  stopPropagation: true,
+  disabled: () => ctx.disabled.value,
+  onStart: (state) => {
+    ctx.beginRotate({ x: state.point.x, y: state.point.y }, handleRef.value!);
+  },
+  onMove: (state) => {
+    ctx.updateRotate({ x: state.point.x, y: state.point.y }, {
+      shift: state.modifiers.shift,
+      alt: state.modifiers.alt,
+    });
+  },
+  onEnd: () => {
+    ctx.endRotate(false);
+  },
+  onCommit: () => {
+    ctx.endRotate(true);
+  },
+});
+
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return 'Rotate';
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const snap = ctx.rotationSnap.value;
+  const unit = event.shiftKey && snap > 0 ? snap : ctx.rotationStep.value;
+  let delta: number;
+  switch (event.key) {
+    case 'ArrowRight':
+    case 'ArrowUp':
+      delta = unit;
+      break;
+    case 'ArrowLeft':
+    case 'ArrowDown':
+      delta = -unit;
+      break;
+    default:
+      return;
+  }
+  event.preventDefault();
+  event.stopPropagation();
+  ctx.nudgeRotate(delta);
+}
+
+const positionStyle = computed<CSSProperties>(() => ({
+  position: 'absolute',
+  left: '50%',
+  top: '0%',
+  transform: 'translate(-50%, -50%)',
+  touchAction: 'none',
+}));
+
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (el) => {
+  handleRef.value = el ?? null;
+}, { immediate: true });
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    data-transform-box-rotate=""
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :aria-label="accessibleLabel"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :rotation="ctx.value.value.rotation" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/transform-box/TransformBoxStatus.vue b/vue/primitives/src/canvas/transform-box/TransformBoxStatus.vue
new file mode 100644
index 0000000..d14f967
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/TransformBoxStatus.vue
@@ -0,0 +1,82 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { TransformBoxValue } from './utils';
+
+/**
+ * An optional visually-hidden `aria-live="polite"` region that announces the
+ * live numeric transform (x / y / width / height / rotation) to assistive
+ * technology when a gesture SETTLES — continuous drag feedback is otherwise
+ * purely visual. It mirrors the standard slider/spinbutton pattern of pairing a
+ * visual control with a text status.
+ *
+ * The announcement is debounced to a settle: it updates on the committed value
+ * (not every drag frame) so screen readers are not flooded. Override the wording
+ * with the `format` prop.
+ */
+export interface TransformBoxStatusProps extends PrimitiveProps {
+  /**
+   * Format the announced string from the current transform. Defaults to a
+   * compact `x, y, width × height, rotation°` summary with rounded values.
+   * @default (v) => `x ${round(v.x)}, y ${round(v.y)}, width ${round(v.width)}, height ${round(v.height)}, rotation ${round(v.rotation)} degrees`
+   */
+  format?: (value: TransformBoxValue) => string;
+}
+
+/** Compact `x, y, width, height, rotation degrees` summary with rounded values. */
+function defaultFormat(v: TransformBoxValue): string {
+  const r = (n: number) => Math.round(n);
+  return `x ${r(v.x)}, y ${r(v.y)}, width ${r(v.width)}, height ${r(v.height)}, rotation ${r(v.rotation)} degrees`;
+}
+</script>
+
+<script setup lang="ts">
+import { shallowRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useTransformBoxContext } from './context';
+
+const { as = 'span', format = defaultFormat } = defineProps<TransformBoxStatusProps>();
+const ctx = useTransformBoxContext();
+
+// Announce only on settle: hold the message blank while a gesture is in flight
+// and publish the committed transform once `transforming` drops to false. This
+// avoids flooding the live region every drag frame.
+const message = shallowRef('');
+
+watch(
+  () => [ctx.transforming.value, ctx.value.value] as const,
+  ([transforming, value]) => {
+    if (transforming) return;
+    message.value = format(value);
+  },
+  { immediate: true, deep: false },
+);
+
+const visuallyHiddenStyle = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  clipPath: 'inset(50%)',
+  whiteSpace: 'nowrap',
+  border: '0',
+} as const;
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="status"
+    aria-live="polite"
+    aria-atomic="true"
+    :style="visuallyHiddenStyle"
+  >
+    <slot :message="message">{{ message }}</slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/transform-box/__test__/TransformBox.test.ts b/vue/primitives/src/canvas/transform-box/__test__/TransformBox.test.ts
new file mode 100644
index 0000000..81b38d2
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/__test__/TransformBox.test.ts
@@ -0,0 +1,479 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  TransformBoxHandle,
+  TransformBoxRoot,
+  TransformBoxRotateHandle,
+  TransformBoxStatus,
+} from '../index';
+import type { TransformBoxHandlePosition, TransformBoxValue } from '../utils';
+import {
+  applyAspectRatio,
+  constrainRect,
+  decomposeTransform,
+  handleAxes,
+  pointerAngle,
+  resizeEdge,
+  rotatePoint,
+  shortestAngleDelta,
+  snapRotation,
+} from '../utils';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+/** One animation-frame tick so the rAF-batched drag flush has run. */
+function raf(): Promise<void> {
+  return new Promise(resolve => requestAnimationFrame(() => resolve()));
+}
+
+function down(el: Element, clientX: number, clientY: number, opts: { shiftKey?: boolean; altKey?: boolean } = {}): void {
+  el.dispatchEvent(new PointerEvent('pointerdown', {
+    pointerId: 1, button: 0, clientX, clientY, bubbles: true, cancelable: true,
+    shiftKey: opts.shiftKey ?? false, altKey: opts.altKey ?? false,
+  }));
+}
+function move(el: Element, clientX: number, clientY: number, opts: { shiftKey?: boolean; altKey?: boolean } = {}): void {
+  el.dispatchEvent(new PointerEvent('pointermove', {
+    pointerId: 1, clientX, clientY, bubbles: true,
+    shiftKey: opts.shiftKey ?? false, altKey: opts.altKey ?? false,
+  }));
+}
+function up(el: Element, clientX: number, clientY: number): void {
+  el.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX, clientY, bubbles: true }));
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean; altKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', {
+    key, bubbles: true, cancelable: true,
+    shiftKey: opts.shiftKey ?? false, altKey: opts.altKey ?? false,
+  }));
+}
+
+interface MountOpts {
+  defaultValue?: TransformBoxValue;
+  aspectRatio?: number | null;
+  allowFlip?: boolean;
+  rotationSnap?: number;
+  rotationStep?: number;
+  keyboardStep?: number;
+  minWidth?: number;
+  minHeight?: number;
+  disabled?: boolean;
+  withRotate?: boolean;
+  withStatus?: boolean;
+}
+
+const POSITIONS: TransformBoxHandlePosition[] = [
+  'top', 'right', 'bottom', 'left', 'top-left', 'top-right', 'bottom-right', 'bottom-left',
+];
+
+function mountBox(opts: MountOpts = {}) {
+  const model = ref<TransformBoxValue | undefined>(undefined);
+  const commits: TransformBoxValue[] = [];
+  const Harness = defineComponent({
+    setup() {
+      return () => h(TransformBoxRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: TransformBoxValue | null | undefined) => { model.value = v ?? undefined; },
+        onTransformCommit: (v: TransformBoxValue) => { commits.push(v); },
+        defaultValue: opts.defaultValue ?? { x: 0, y: 0, width: 100, height: 100, rotation: 0 },
+        aspectRatio: opts.aspectRatio ?? null,
+        allowFlip: opts.allowFlip ?? true,
+        rotationSnap: opts.rotationSnap ?? 0,
+        rotationStep: opts.rotationStep ?? 1,
+        keyboardStep: opts.keyboardStep ?? 1,
+        minWidth: opts.minWidth ?? 1,
+        minHeight: opts.minHeight ?? 1,
+        disabled: opts.disabled ?? false,
+      }, {
+        default: () => [
+          ...POSITIONS.map(p => h(TransformBoxHandle, { key: p, position: p })),
+          opts.withRotate ? h(TransformBoxRotateHandle) : null,
+          opts.withStatus ? h(TransformBoxStatus) : null,
+        ],
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model, commits };
+}
+
+function rootEl(): HTMLElement {
+  return document.querySelector<HTMLElement>('[data-selected], [data-disabled], [tabindex="0"]')!;
+}
+function handleEl(position: TransformBoxHandlePosition): HTMLElement {
+  return document.querySelector<HTMLElement>(`[data-position="${position}"]`)!;
+}
+function rotateEl(): HTMLElement {
+  return document.querySelector<HTMLElement>('[data-transform-box-rotate]')!;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure math (utils.ts) — Crop shares these.
+// ─────────────────────────────────────────────────────────────────────────────
+describe('utils — handleAxes', () => {
+  it('decodes edges and corners with outward signs', () => {
+    expect(handleAxes('left')).toEqual({ x: -1, y: 0 });
+    expect(handleAxes('right')).toEqual({ x: 1, y: 0 });
+    expect(handleAxes('top')).toEqual({ x: 0, y: -1 });
+    expect(handleAxes('bottom')).toEqual({ x: 0, y: 1 });
+    expect(handleAxes('top-left')).toEqual({ x: -1, y: -1 });
+    expect(handleAxes('bottom-right')).toEqual({ x: 1, y: 1 });
+  });
+});
+
+describe('utils — constrainRect', () => {
+  it('folds a negative width/height into the origin (positive size)', () => {
+    const r = constrainRect({ x: 0, y: 0, width: -40, height: -20, rotation: 0 }, 1, 1);
+    expect(r).toEqual({ x: -40, y: -20, width: 40, height: 20, rotation: 0 });
+  });
+  it('clamps below the minimum size', () => {
+    const r = constrainRect({ x: 5, y: 5, width: 0.5, height: 0.2, rotation: 0 }, 1, 1);
+    expect(r.width).toBe(1);
+    expect(r.height).toBe(1);
+  });
+});
+
+describe('utils — applyAspectRatio', () => {
+  it('derives height from width on a horizontal edge', () => {
+    const { width, height } = applyAspectRatio(200, 50, 2, { x: 1, y: 0 });
+    expect(width).toBe(200);
+    expect(height).toBe(100); // 200 / 2
+  });
+  it('keeps the dominant axis on a corner', () => {
+    // width (300) implies a bigger box than height (10) at ratio 2 → keep width.
+    const { width, height } = applyAspectRatio(300, 10, 2, { x: 1, y: 1 });
+    expect(width).toBe(300);
+    expect(height).toBeCloseTo(150);
+  });
+});
+
+describe('utils — resizeEdge (unrotated)', () => {
+  it('right handle grows width with the LEFT edge fixed', () => {
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 0 };
+    const { box } = resizeEdge(start, 'right', { x: 20, y: 0 });
+    expect(box.x).toBe(0); // left edge fixed
+    expect(box.width).toBe(120);
+    expect(box.height).toBe(100);
+  });
+  it('left handle grows width with the RIGHT edge fixed', () => {
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 0 };
+    const { box } = resizeEdge(start, 'left', { x: -20, y: 0 });
+    expect(box.x).toBe(-20); // grew left
+    expect(box.width).toBe(120);
+    // right edge stayed at 100.
+    expect(box.x + box.width).toBe(100);
+  });
+  it('symmetric (Alt) resize grows both sides about the center', () => {
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 0 };
+    const { box } = resizeEdge(start, 'right', { x: 10, y: 0 }, { symmetric: true });
+    // both sides move by 10 → width +20, x shifts -10 to keep center fixed.
+    expect(box.width).toBe(120);
+    expect(box.x).toBe(-10);
+    expect(box.x + box.width / 2).toBe(50); // center unchanged
+  });
+  it('aspect lock keeps the ratio on a corner', () => {
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 0 };
+    const { box } = resizeEdge(start, 'bottom-right', { x: 40, y: 0 }, { aspectRatio: 1 });
+    expect(box.width).toBeCloseTo(box.height);
+  });
+});
+
+describe('utils — resizeEdge (rotated, local-axis delta)', () => {
+  it('a 90° box: a screen-x drag rotated into local axes resizes the right edge', () => {
+    // Box rotated 90°. A pure local-x delta resizes width regardless of rotation,
+    // because resizeEdge receives the delta ALREADY in local axes.
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 90 };
+    const { box } = resizeEdge(start, 'right', { x: 30, y: 0 });
+    expect(box.width).toBeCloseTo(130);
+    expect(box.height).toBeCloseTo(100);
+    expect(box.rotation).toBe(90);
+  });
+  it('preserves the world anchor of the opposite edge under rotation', () => {
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 45 };
+    // World position of the anchored LEFT-edge midpoint before resize.
+    const center0 = { x: start.x + start.width / 2, y: start.y + start.height / 2 };
+    const anchorBefore = rotatePoint({ x: start.x, y: start.y + start.height / 2 }, 45, center0);
+
+    const { box } = resizeEdge(start, 'right', { x: 40, y: 0 });
+    const center1 = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+    const anchorAfter = rotatePoint({ x: box.x, y: box.y + box.height / 2 }, 45, center1);
+
+    expect(anchorAfter.x).toBeCloseTo(anchorBefore.x, 4);
+    expect(anchorAfter.y).toBeCloseTo(anchorBefore.y, 4);
+    expect(box.width).toBeCloseTo(140);
+  });
+});
+
+describe('utils — flip policy', () => {
+  it('allowFlip=false clamps the dragged edge at the minimum size', () => {
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 0 };
+    // Drag the right edge far past the left edge (would flip).
+    const { box, flippedX } = resizeEdge(start, 'right', { x: -200, y: 0 }, {
+      allowFlip: false, minWidth: 5,
+    });
+    expect(box.width).toBe(5);
+    expect(flippedX).toBe(false);
+    expect(box.x).toBe(0); // left edge still anchored
+  });
+  it('allowFlip=true reports a flip and normalizes to a positive box', () => {
+    const start: TransformBoxValue = { x: 0, y: 0, width: 100, height: 100, rotation: 0 };
+    const { box, flippedX } = resizeEdge(start, 'right', { x: -150, y: 0 }, {
+      allowFlip: true, minWidth: 5,
+    });
+    expect(flippedX).toBe(true);
+    expect(box.width).toBeGreaterThan(0); // normalized
+  });
+});
+
+describe('utils — rotation helpers', () => {
+  it('pointerAngle: up=0, right=90, down=180, left=270', () => {
+    const c = { x: 0, y: 0 };
+    expect(pointerAngle({ x: 0, y: -10 }, c)).toBeCloseTo(0);
+    expect(pointerAngle({ x: 10, y: 0 }, c)).toBeCloseTo(90);
+    expect(pointerAngle({ x: 0, y: 10 }, c)).toBeCloseTo(180);
+    expect(pointerAngle({ x: -10, y: 0 }, c)).toBeCloseTo(270);
+  });
+  it('shortestAngleDelta crosses the seam smoothly', () => {
+    expect(shortestAngleDelta(350, 10)).toBeCloseTo(20);
+    expect(shortestAngleDelta(10, 350)).toBeCloseTo(-20);
+  });
+  it('snapRotation snaps to increments', () => {
+    expect(snapRotation(43, 15)).toBe(45);
+    expect(snapRotation(43, 0)).toBe(43); // disabled
+  });
+});
+
+describe('utils — decomposeTransform', () => {
+  it('returns the normalized rect, center, and unrotated corners at rotation 0', () => {
+    const d = decomposeTransform({ x: 10, y: 20, width: 40, height: 60, rotation: 0 });
+    expect(d.rect).toEqual({ x: 10, y: 20, width: 40, height: 60 });
+    expect(d.center).toEqual({ x: 30, y: 50 });
+    expect(d.rotation).toBe(0);
+    expect(d.corners[0]).toEqual({ x: 10, y: 20 }); // top-left
+    expect(d.corners[2]).toEqual({ x: 50, y: 80 }); // bottom-right
+  });
+  it('rotates the corners about the center under rotation', () => {
+    const d = decomposeTransform({ x: 0, y: 0, width: 100, height: 100, rotation: 90 });
+    // 90° about center (50,50): top-left (0,0) → (100,0).
+    expect(d.corners[0].x).toBeCloseTo(100, 4);
+    expect(d.corners[0].y).toBeCloseTo(0, 4);
+    expect(d.rotation).toBe(90);
+  });
+  it('normalizes a negative-size box', () => {
+    const d = decomposeTransform({ x: 50, y: 50, width: -30, height: -20, rotation: 0 });
+    expect(d.rect).toEqual({ x: 20, y: 30, width: 30, height: 20 });
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Components
+// ─────────────────────────────────────────────────────────────────────────────
+describe('TransformBoxHandle — rendering & ARIA', () => {
+  it('renders 8 handles as buttons with derived aria-labels', async () => {
+    mountBox();
+    await nextTick();
+    const buttons = Array.from(document.querySelectorAll<HTMLElement>('[data-position]'));
+    expect(buttons).toHaveLength(8);
+    for (const btn of buttons) {
+      expect(btn.tagName).toBe('BUTTON');
+      expect(btn.getAttribute('type')).toBe('button');
+      const pos = btn.getAttribute('data-position');
+      expect(btn.getAttribute('aria-label')).toBe(`Resize ${pos}`);
+      expect(btn.tabIndex).toBe(0);
+    }
+  });
+
+  it('renders the rotate handle as a button labelled "Rotate"', async () => {
+    mountBox({ withRotate: true });
+    await nextTick();
+    const rot = rotateEl();
+    expect(rot.tagName).toBe('BUTTON');
+    expect(rot.getAttribute('aria-label')).toBe('Rotate');
+  });
+});
+
+describe('TransformBoxRoot — keyboard move', () => {
+  it('ArrowRight on the body moves x by keyboardStep', async () => {
+    const { commits } = mountBox({ keyboardStep: 5 });
+    await nextTick();
+    const root = rootEl();
+    root.focus();
+    keydown(root, 'ArrowRight');
+    await nextTick();
+    expect(commits.at(-1)!.x).toBe(5);
+  });
+
+  it('Shift+ArrowRight uses the large step', async () => {
+    const { commits } = mountBox({ keyboardStep: 1 });
+    await nextTick();
+    const root = rootEl();
+    keydown(root, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(commits.at(-1)!.x).toBe(10); // default keyboardLargeStep
+  });
+});
+
+describe('TransformBoxHandle — keyboard resize', () => {
+  it('ArrowRight on the RIGHT handle increases width with the left edge fixed', async () => {
+    const { commits } = mountBox({ keyboardStep: 4 });
+    await nextTick();
+    const handle = handleEl('right');
+    handle.focus();
+    keydown(handle, 'ArrowRight');
+    await nextTick();
+    const v = commits.at(-1)!;
+    expect(v.width).toBe(104);
+    expect(v.x).toBe(0); // left edge fixed
+  });
+
+  it('Shift+Arrow aspect-locks the resize ratio', async () => {
+    const { commits } = mountBox({ keyboardStep: 10, defaultValue: { x: 0, y: 0, width: 100, height: 100, rotation: 0 } });
+    await nextTick();
+    const handle = handleEl('bottom-right');
+    handle.focus();
+    keydown(handle, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    const v = commits.at(-1)!;
+    // ratio 1 preserved.
+    expect(v.width).toBeCloseTo(v.height);
+  });
+});
+
+describe('TransformBoxHandle — pointer resize', () => {
+  it('dragging the right handle increases width', async () => {
+    const { commits } = mountBox();
+    await nextTick();
+    const handle = handleEl('right');
+    down(handle, 100, 50);
+    await raf();
+    move(handle, 130, 50);
+    await raf();
+    up(handle, 130, 50);
+    await raf();
+    const v = commits.at(-1)!;
+    expect(v.width).toBeGreaterThan(100);
+    expect(v.x).toBe(0); // left edge fixed
+  });
+});
+
+describe('TransformBoxRotateHandle — rotation', () => {
+  it('ArrowRight on the rotate handle changes rotation by rotationStep', async () => {
+    const { commits } = mountBox({ withRotate: true, rotationStep: 3 });
+    await nextTick();
+    const rot = rotateEl();
+    rot.focus();
+    keydown(rot, 'ArrowRight');
+    await nextTick();
+    expect(commits.at(-1)!.rotation).toBe(3);
+    keydown(rot, 'ArrowLeft');
+    await nextTick();
+    expect(commits.at(-1)!.rotation).toBe(0);
+  });
+
+  it('Shift+Arrow on the rotate handle rotates by rotationSnap', async () => {
+    const { commits } = mountBox({ withRotate: true, rotationSnap: 15, rotationStep: 1 });
+    await nextTick();
+    const rot = rotateEl();
+    keydown(rot, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(commits.at(-1)!.rotation).toBe(15);
+  });
+});
+
+describe('TransformBoxRoot — allowFlip clamping (pointer)', () => {
+  it('allowFlip=false clamps at min on a keyboard over-drag', async () => {
+    const { commits } = mountBox({
+      allowFlip: false,
+      minWidth: 5,
+      keyboardStep: 200,
+      defaultValue: { x: 0, y: 0, width: 100, height: 100, rotation: 0 },
+    });
+    await nextTick();
+    const handle = handleEl('right');
+    // Shrink the right edge past the left edge → would flip; clamps to min.
+    keydown(handle, 'ArrowLeft');
+    await nextTick();
+    const v = commits.at(-1)!;
+    expect(v.width).toBe(5);
+    expect(v.x).toBe(0);
+  });
+});
+
+describe('TransformBoxStatus', () => {
+  it('renders an aria-live region announcing the settled transform', async () => {
+    mountBox({ withStatus: true, defaultValue: { x: 12, y: 0, width: 40, height: 20, rotation: 0 } });
+    await nextTick();
+    const status = document.querySelector<HTMLElement>('[aria-live="polite"]')!;
+    expect(status).toBeTruthy();
+    expect(status.getAttribute('role')).toBe('status');
+    expect(status.textContent).toContain('width 40');
+    expect(status.textContent).toContain('height 20');
+  });
+});
+
+describe('TransformBoxRoot — disabled', () => {
+  it('blocks keyboard move when disabled', async () => {
+    const { commits } = mountBox({ disabled: true, keyboardStep: 5 });
+    await nextTick();
+    const root = rootEl();
+    keydown(root, 'ArrowRight');
+    await nextTick();
+    expect(commits).toHaveLength(0);
+  });
+
+  it('blocks handle resize when disabled', async () => {
+    const { commits } = mountBox({ disabled: true });
+    await nextTick();
+    const handle = handleEl('right');
+    keydown(handle, 'ArrowRight');
+    down(handle, 100, 50);
+    await raf();
+    move(handle, 130, 50);
+    await raf();
+    up(handle, 130, 50);
+    await raf();
+    expect(commits).toHaveLength(0);
+  });
+
+  it('sets tabindex -1 on handles when disabled', async () => {
+    mountBox({ disabled: true });
+    await nextTick();
+    const handle = handleEl('right');
+    expect(handle.tabIndex).toBe(-1);
+    expect(handle.getAttribute('data-disabled')).toBe('');
+  });
+});
+
+describe('TransformBoxRoot — selection state', () => {
+  it('exposes data-selected by default and toggles via the model', async () => {
+    const selected = ref(true);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(TransformBoxRoot, {
+          selected: selected.value,
+          'onUpdate:selected': (v: boolean) => { selected.value = v; },
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const root = document.querySelector<HTMLElement>('[data-selected]');
+    expect(root).toBeTruthy();
+    selected.value = false;
+    await nextTick();
+    expect(document.querySelector('[data-selected]')).toBeNull();
+  });
+});
diff --git a/vue/primitives/src/canvas/transform-box/__test__/__screenshots__/TransformBox.test.ts/utils---flip-policy-allowFlip-false-clamps-the-dragged-edge-at-the-minimum-size-1.png b/vue/primitives/src/canvas/transform-box/__test__/__screenshots__/TransformBox.test.ts/utils---flip-policy-allowFlip-false-clamps-the-dragged-edge-at-the-minimum-size-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/transform-box/__test__/__screenshots__/TransformBox.test.ts/utils---flip-policy-allowFlip-false-clamps-the-dragged-edge-at-the-minimum-size-1.png differ
diff --git a/vue/primitives/src/canvas/transform-box/context.ts b/vue/primitives/src/canvas/transform-box/context.ts
new file mode 100644
index 0000000..2bfd08d
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/context.ts
@@ -0,0 +1,101 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { UseSnappingReturn } from '../../internal/snapping';
+import type {
+  Point,
+  TransformBoxHandlePosition,
+  TransformBoxPivot,
+  TransformBoxValue,
+} from './utils';
+
+export type TransformBoxDirection = 'ltr' | 'rtl';
+
+/** Modifier flags read off the live pointer event for a gesture frame. */
+export interface TransformBoxModifiers {
+  /** Aspect-lock (corner) request. */
+  shift: boolean;
+  /** Symmetric-about-pivot request. */
+  alt: boolean;
+}
+
+/**
+ * Context shared between `TransformBoxRoot` and its handle parts.
+ *
+ * Scalar props are exposed as plain `Ref<T>` and built by the root with
+ * `toRef(() => prop)` — a `GetterRefImpl` that is reactive without allocating a
+ * `ReactiveEffect`/cache (the slider/angle-dial identity-passthrough convention).
+ *
+ * The handle parts own their `usePointerDrag` instance (bound to their own
+ * button element, so capture/state never tangles between handles) and call the
+ * root's gesture callbacks per frame: `beginScale`/`updateScale`/`endScale`
+ * (and the rotate equivalents). The root owns ALL transform math; the parts
+ * stay dumb. The body's MOVE gesture is owned wholly by the root.
+ */
+export interface TransformBoxContext {
+  /** Current transform (normalized box + rotation). */
+  value: Ref<TransformBoxValue>;
+  /** Commit a raw transform; the root normalizes (min-size, flip) and emits. */
+  setValue: (next: TransformBoxValue) => void;
+
+  // ── scale gesture (driven by TransformBoxHandle) ───────────────────────────
+  /** Snapshot the start box and mark the gesture active. */
+  beginScale: (handle: TransformBoxHandlePosition) => void;
+  /**
+   * Apply a cumulative SCREEN-space pointer delta for the active scale gesture.
+   * The root rotates it into the box's local axes and resizes the edge(s).
+   */
+  updateScale: (handle: TransformBoxHandlePosition, screenDelta: Point, mods: TransformBoxModifiers) => void;
+  /** End the scale gesture; `commit` true on pointerup (false on cancel). */
+  endScale: (commit: boolean) => void;
+
+  // ── rotate gesture (driven by TransformBoxRotateHandle) ────────────────────
+  /** Snapshot the start rotation and pivot (in client space) from `pointer`. */
+  beginRotate: (pointer: Point, handleEl: HTMLElement) => void;
+  /** Apply the current pointer position; root computes the angle about the pivot. */
+  updateRotate: (pointer: Point, mods: TransformBoxModifiers) => void;
+  /** End the rotate gesture; `commit` true on pointerup. */
+  endRotate: (commit: boolean) => void;
+
+  // ── keyboard nudges ────────────────────────────────────────────────────────
+  /** Resize the handle's edge(s) by a LOCAL-axis step (Arrow on a handle). */
+  nudgeScale: (handle: TransformBoxHandlePosition, dx: number, dy: number, mods: TransformBoxModifiers) => void;
+  /** Move the whole box by a world-space delta (Arrow on the body). */
+  nudgeMove: (dx: number, dy: number) => void;
+  /** Rotate by a signed degree delta (Arrow on the rotate handle). */
+  nudgeRotate: (delta: number) => void;
+
+  /** The root's snap engine. */
+  snapping: UseSnappingReturn;
+  /** Whether the box is currently selected/active. */
+  selected: Ref<boolean>;
+  /** Mark the box selected (click-to-activate). */
+  setSelected: (value: boolean) => void;
+  /** Whether all interaction is disabled. */
+  disabled: Ref<boolean>;
+  /** Whether a move/scale/rotate gesture is in flight. */
+  transforming: Ref<boolean>;
+  /** Resolved reading direction (affects horizontal keyboard nudge). */
+  direction: Ref<TransformBoxDirection>;
+  /** The pivot rotation/symmetric-resize anchor to. */
+  pivot: Ref<TransformBoxPivot>;
+  /** Keyboard step (Arrow). */
+  keyboardStep: Ref<number>;
+  /** Keyboard large step (Shift+Arrow for move). */
+  keyboardLargeStep: Ref<number>;
+  /** Rotation keyboard step (degrees). */
+  rotationStep: Ref<number>;
+  /** Rotation snap increment while Shift is held (degrees, 0 disables). */
+  rotationSnap: Ref<number>;
+  /** Live flip flag for `data-flipped-x` on the root. */
+  flippedX: Ref<boolean>;
+  /** Live flip flag for `data-flipped-y` on the root. */
+  flippedY: Ref<boolean>;
+}
+
+/** Re-export so handle parts can name these without reaching into `utils`. */
+export type { Point, TransformBoxHandlePosition, TransformBoxPivot, TransformBoxValue };
+
+const ctx = useContextFactory<TransformBoxContext>('TransformBoxContext');
+
+export const provideTransformBoxContext = ctx.provide;
+export const useTransformBoxContext = ctx.inject;
diff --git a/vue/primitives/src/canvas/transform-box/demo.vue b/vue/primitives/src/canvas/transform-box/demo.vue
new file mode 100644
index 0000000..08f82ae
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/demo.vue
@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import {
+  TransformBoxHandle,
+  TransformBoxRoot,
+  TransformBoxRotateHandle,
+  TransformBoxStatus,
+} from '@robonen/primitives';
+import type { TransformBoxHandlePosition, TransformBoxValue } from '@robonen/primitives';
+import { ref } from 'vue';
+
+// The eight resize handles, in the package's stable order.
+const HANDLES: TransformBoxHandlePosition[] = [
+  'top-left',
+  'top',
+  'top-right',
+  'right',
+  'bottom-right',
+  'bottom',
+  'bottom-left',
+  'left',
+];
+
+// Controlled transform: x / y are the box origin in stage px, width / height its
+// unrotated size, rotation in degrees. The gradient 'object' fills the box.
+const transform = ref<TransformBoxValue>({
+  x: 96,
+  y: 64,
+  width: 200,
+  height: 130,
+  rotation: -8,
+});
+
+const r = (n: number) => Math.round(n);
+
+function reset() {
+  transform.value = { x: 96, y: 64, width: 200, height: 130, rotation: -8 };
+}
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-xl space-y-4 p-6 text-fg">
+    <div class="flex items-baseline justify-between">
+      <div>
+        <h3 class="text-sm font-semibold">Transform box</h3>
+        <p class="text-xs text-fg-muted">Drag the body to move, the corner/edge squares to scale, the dot above to rotate.</p>
+      </div>
+      <button
+        type="button"
+        class="rounded-md border border-border bg-bg px-2.5 py-1 text-xs font-medium text-fg-muted transition hover:border-border-strong hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        @click="reset"
+      >
+        Reset
+      </button>
+    </div>
+
+    <!-- Stage: positioned ancestor for the absolutely-laid-out box. -->
+    <div
+      class="relative h-80 w-full select-none overflow-hidden rounded-card border border-border bg-bg-inset"
+      style="background-image: linear-gradient(45deg, var(--color-border) 0.5px, transparent 0.5px), linear-gradient(-45deg, var(--color-border) 0.5px, transparent 0.5px); background-size: 16px 16px;"
+    >
+      <TransformBoxRoot
+        v-model="transform"
+        :min-width="40"
+        :min-height="40"
+        :rotation-snap="15"
+        class="group cursor-move outline-none"
+      >
+        <!-- The 'object': a gradient that fills (and therefore scales + rotates with) the box. -->
+        <div
+          class="pointer-events-none absolute inset-0 rounded-sm shadow-(--shadow-card)"
+          style="background: linear-gradient(135deg, oklch(0.72 0.18 28) 0%, oklch(0.68 0.17 330) 50%, oklch(0.74 0.15 250) 100%);"
+        />
+
+        <!-- Selection outline -->
+        <div class="pointer-events-none absolute inset-0 rounded-sm border-2 border-accent ring-1 ring-bg/40" />
+
+        <!-- Rotate stem + handle (positioned above the top edge by the part's default style). -->
+        <div class="pointer-events-none absolute left-1/2 top-0 h-6 w-px -translate-x-1/2 -translate-y-full bg-accent" />
+        <TransformBoxRotateHandle
+          class="-translate-y-6 block h-3.5 w-3.5 cursor-grab rounded-full border-2 border-accent bg-bg shadow-(--shadow-card) outline-none transition active:cursor-grabbing hover:scale-110 focus-visible:ring-2 focus-visible:ring-ring"
+        />
+
+        <!-- Eight scale handles as small accent squares on the corners + edge midpoints. -->
+        <TransformBoxHandle
+          v-for="pos in HANDLES"
+          :key="pos"
+          :position="pos"
+          class="block h-2.5 w-2.5 rounded-[2px] border border-bg bg-accent shadow-sm outline-none transition hover:scale-125 focus-visible:ring-2 focus-visible:ring-ring"
+          :class="pos === 'left' || pos === 'right' ? 'cursor-ew-resize' : pos === 'top' || pos === 'bottom' ? 'cursor-ns-resize' : pos === 'top-left' || pos === 'bottom-right' ? 'cursor-nwse-resize' : 'cursor-nesw-resize'"
+        />
+
+        <!-- Visually-hidden live region for assistive tech. -->
+        <TransformBoxStatus />
+      </TransformBoxRoot>
+    </div>
+
+    <!-- Live geometry readout. -->
+    <dl class="grid grid-cols-5 gap-2 text-center">
+      <div v-for="item in [
+        { label: 'X', value: `${r(transform.x)}` },
+        { label: 'Y', value: `${r(transform.y)}` },
+        { label: 'W', value: `${r(transform.width)}` },
+        { label: 'H', value: `${r(transform.height)}` },
+        { label: 'Rotation', value: `${r(transform.rotation)}°` },
+      ]" :key="item.label" class="rounded-md border border-border bg-bg-inset py-1.5">
+        <dt class="text-[10px] font-medium uppercase tracking-wide text-fg-subtle">{{ item.label }}</dt>
+        <dd class="font-mono text-sm text-fg">{{ item.value }}</dd>
+      </div>
+    </dl>
+
+    <p class="text-xs text-fg-subtle">
+      Hold <kbd class="rounded border border-border bg-bg px-1 font-mono">Shift</kbd> on a corner to lock aspect, on the rotate dot to snap to 15°.
+      Focus the box and use arrow keys to nudge.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/transform-box/index.ts b/vue/primitives/src/canvas/transform-box/index.ts
new file mode 100644
index 0000000..0dd470b
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/index.ts
@@ -0,0 +1,50 @@
+export { default as TransformBoxRoot } from './TransformBoxRoot.vue';
+export type { TransformBoxRootEmits, TransformBoxRootProps } from './TransformBoxRoot.vue';
+
+export { default as TransformBoxHandle } from './TransformBoxHandle.vue';
+export type { TransformBoxHandleProps } from './TransformBoxHandle.vue';
+
+export { default as TransformBoxRotateHandle } from './TransformBoxRotateHandle.vue';
+export type { TransformBoxRotateHandleProps } from './TransformBoxRotateHandle.vue';
+
+export { default as TransformBoxStatus } from './TransformBoxStatus.vue';
+export type { TransformBoxStatusProps } from './TransformBoxStatus.vue';
+
+export {
+  provideTransformBoxContext,
+  useTransformBoxContext,
+} from './context';
+export type {
+  TransformBoxContext,
+  TransformBoxDirection,
+  TransformBoxModifiers,
+} from './context';
+
+export {
+  applyAspectRatio,
+  boxCenter,
+  constrainRect,
+  decomposeTransform,
+  handleAxes,
+  handleLabel,
+  localToWorld,
+  moveBox,
+  normalizeRotation,
+  pointerAngle,
+  resizeEdge,
+  resolvePivot,
+  rotatePoint,
+  rotateVector,
+  rotationFromPointer,
+  shortestAngleDelta,
+  snapRotation,
+  worldToLocal,
+} from './utils';
+export type {
+  Point,
+  ResizeEdgeOptions,
+  ResizeResult,
+  TransformBoxHandlePosition,
+  TransformBoxPivot,
+  TransformBoxValue,
+} from './utils';
diff --git a/vue/primitives/src/canvas/transform-box/utils.ts b/vue/primitives/src/canvas/transform-box/utils.ts
new file mode 100644
index 0000000..544c389
--- /dev/null
+++ b/vue/primitives/src/canvas/transform-box/utils.ts
@@ -0,0 +1,496 @@
+import type { Point } from '../../internal/utils/geometry';
+
+// Reuse the package-canonical 2D point (internal `utils/geometry`, not in the
+// root barrel) so transform-box's `Point` is the SAME symbol as
+// spline/pointer-drag/snapping/angle-dial re-export — keeps the root barrel free
+// of a TS2308 `Point` clash.
+/** A 2D point. Client (screen) pixels unless the call site says otherwise. */
+export type { Point };
+
+const TAU = Math.PI * 2;
+const DEG_TO_RAD = TAU / 360;
+
+/**
+ * The full transform a {@link TransformBoxRoot} owns: an axis-aligned box
+ * `{x, y, width, height}` in the box's UNROTATED local frame plus a `rotation`
+ * (degrees, clockwise-positive to match screen-y-down). The box is drawn by
+ * translating to `(x, y)`, then rotating by `rotation` about the pivot.
+ *
+ * Width/height may be negative mid-gesture when a corner is dragged past its
+ * anchor (a flip); {@link normalizeTransform} folds a negative size back into a
+ * positive one by shifting the origin, which is what the root commits.
+ */
+export interface TransformBoxValue {
+  /** Left edge in the unrotated local frame. */
+  x: number;
+  /** Top edge in the unrotated local frame. */
+  y: number;
+  /** Box width (may be transiently negative during a flip). */
+  width: number;
+  /** Box height (may be transiently negative during a flip). */
+  height: number;
+  /** Rotation in degrees, clockwise-positive (screen y grows downward). */
+  rotation: number;
+}
+
+/** The 8 resize handle positions: 4 edges + 4 corners. */
+export type TransformBoxHandlePosition
+  = | 'top'
+    | 'right'
+    | 'bottom'
+    | 'left'
+    | 'top-left'
+    | 'top-right'
+    | 'bottom-right'
+    | 'bottom-left';
+
+/**
+ * Pivot the box rotates about and that symmetric (Alt) resize anchors to.
+ * `'center'` is the box center; an explicit {@link Point} is a fractional
+ * position in `[0, 1]²` of the box (e.g. `{ x: 0, y: 0 }` is the top-left
+ * corner, `{ x: 0.5, y: 0.5 }` equals `'center'`).
+ */
+export type TransformBoxPivot = 'center' | Point;
+
+/** Whether a handle controls the left/right (x) and top/bottom (y) edges. */
+interface HandleAxes {
+  /** `-1` left edge, `1` right edge, `0` neither (no horizontal resize). */
+  x: -1 | 0 | 1;
+  /** `-1` top edge, `1` bottom edge, `0` neither (no vertical resize). */
+  y: -1 | 0 | 1;
+}
+
+/**
+ * Decode a handle position into which edges it drives. Corners drive both axes;
+ * edge handles drive one. The sign points OUTWARD from the box center toward the
+ * handle (so `right` is `+1`, `left` is `-1`).
+ */
+export function handleAxes(position: TransformBoxHandlePosition): HandleAxes {
+  let x: -1 | 0 | 1 = 0;
+  let y: -1 | 0 | 1 = 0;
+  if (position.includes('left')) x = -1;
+  else if (position.includes('right')) x = 1;
+  if (position.includes('top')) y = -1;
+  else if (position.includes('bottom')) y = 1;
+  return { x, y };
+}
+
+/** Default human-readable `aria-label` for a scale handle (e.g. "Resize top-left"). */
+export function handleLabel(position: TransformBoxHandlePosition): string {
+  return `Resize ${position}`;
+}
+
+/**
+ * Rotate `point` by `angleDeg` (clockwise-positive, screen y down) about
+ * `origin`. Pure; the workhorse for moving between world and the box's local
+ * frame. Rotating by `-rotation` brings a world vector into local axes;
+ * rotating by `+rotation` sends a local point back to world.
+ */
+export function rotatePoint(point: Point, angleDeg: number, origin: Point = { x: 0, y: 0 }): Point {
+  const rad = angleDeg * DEG_TO_RAD;
+  // Screen y grows downward, so a positive (clockwise) rotation uses the
+  // standard matrix with +sin on the y row: [c -s; s c].
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  const dx = point.x - origin.x;
+  const dy = point.y - origin.y;
+  return {
+    x: origin.x + dx * cos - dy * sin,
+    y: origin.y + dx * sin + dy * cos,
+  };
+}
+
+/**
+ * Rotate a free VECTOR (no origin) by `angleDeg`. Equivalent to
+ * `rotatePoint(vec, angleDeg)`; named separately because handle math rotates a
+ * screen-space delta into the box's local axes (`angleDeg = -rotation`) and the
+ * intent reads more clearly as "rotate this delta".
+ */
+export function rotateVector(vec: Point, angleDeg: number): Point {
+  return rotatePoint(vec, angleDeg);
+}
+
+/**
+ * Resolve a {@link TransformBoxPivot} to an absolute point in the box's local
+ * (unrotated) frame, given the box's `x/y/width/height`. `'center'` maps to the
+ * geometric center; a fractional point maps to that fraction of the box.
+ */
+export function resolvePivot(box: TransformBoxValue, pivot: TransformBoxPivot): Point {
+  if (pivot === 'center') {
+    return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+  }
+  return { x: box.x + box.width * pivot.x, y: box.y + box.height * pivot.y };
+}
+
+/**
+ * World-space center of the box (the point the local→world rotation pivots
+ * about for rendering). The CSS `transform: translate(x,y) rotate(r)` rotates
+ * about the element's own center, so the local center maps to itself under the
+ * world rotation and this is simply the local center.
+ */
+export function boxCenter(box: TransformBoxValue): Point {
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+}
+
+/**
+ * Map a point given in the box's LOCAL (unrotated) frame to WORLD space, where
+ * the box is rotated by `box.rotation` about its center. Used to find the
+ * fixed-world position of an anchor corner before a resize.
+ */
+export function localToWorld(box: TransformBoxValue, local: Point): Point {
+  return rotatePoint(local, box.rotation, boxCenter(box));
+}
+
+/** Inverse of {@link localToWorld}: a world point into the box's local frame. */
+export function worldToLocal(box: TransformBoxValue, world: Point): Point {
+  return rotatePoint(world, -box.rotation, boxCenter(box));
+}
+
+/**
+ * Options controlling a single resize step. All optional; sensible defaults
+ * keep an axis-aligned, anchor-the-opposite-edge resize.
+ */
+export interface ResizeEdgeOptions {
+  /** Smallest allowed width. @default 1 */
+  minWidth?: number;
+  /** Smallest allowed height. @default 1 */
+  minHeight?: number;
+  /**
+   * Lock the width/height ratio to this value (`width / height`). `null`
+   * disables the lock. When set, the dominant dragged axis drives the other.
+   * @default null
+   */
+  aspectRatio?: number | null;
+  /**
+   * Anchor symmetrically about the pivot instead of the opposite edge — the
+   * box grows/shrinks equally on both sides (the Alt gesture). @default false
+   */
+  symmetric?: boolean;
+  /**
+   * Pivot used when `symmetric` is true (fractional point or `'center'`).
+   * @default 'center'
+   */
+  pivot?: TransformBoxPivot;
+  /**
+   * Allow the box to flip through zero (negative size) instead of clamping at
+   * the minimum. @default true
+   */
+  allowFlip?: boolean;
+}
+
+/**
+ * Apply an aspect ratio to a width/height pair, keeping whichever axis the
+ * handle primarily drives and deriving the other.
+ *
+ * - A corner (`axes.x !== 0 && axes.y !== 0`) uses the axis with the larger
+ *   absolute size so the box tracks the dominant drag direction.
+ * - A horizontal edge derives height from width; a vertical edge derives width
+ *   from height.
+ *
+ * Signs are preserved (so a flipped, negative size stays negative). Pure.
+ */
+export function applyAspectRatio(
+  width: number,
+  height: number,
+  ratio: number,
+  axes: HandleAxes,
+): { width: number; height: number } {
+  if (!(ratio > 0) || !Number.isFinite(ratio)) return { width, height };
+
+  const horizontal = axes.x !== 0;
+  const vertical = axes.y !== 0;
+
+  // Corner: pick the axis whose magnitude implies the larger box and derive the
+  // other from it. This makes diagonal drags feel like they track the pointer.
+  if (horizontal && vertical) {
+    const wFromH = Math.abs(height) * ratio;
+    if (Math.abs(width) >= wFromH) {
+      const h = (Math.abs(width) / ratio) * Math.sign(height || 1);
+      return { width, height: h };
+    }
+    const w = (Math.abs(height) * ratio) * Math.sign(width || 1);
+    return { width: w, height };
+  }
+
+  // Horizontal edge: width is authoritative.
+  if (horizontal) {
+    return { width, height: (Math.abs(width) / ratio) * Math.sign(height || 1) };
+  }
+  // Vertical edge: height is authoritative.
+  return { width: (Math.abs(height) * ratio) * Math.sign(width || 1), height };
+}
+
+/**
+ * Clamp / normalize a box to satisfy the min-size and flip policy, returning a
+ * box with NON-negative width/height (a flip is folded into the origin).
+ *
+ * - When `allowFlip` is false a size below its minimum is clamped to the
+ *   minimum (the edge cannot cross its anchor).
+ * - When `allowFlip` is true a negative size is allowed but normalized: the
+ *   origin shifts and the size is made positive, so the committed box is always
+ *   well-formed. The caller reads {@link TransformBoxValue} flip flags from the
+ *   sign BEFORE normalization (see `resizeEdge`'s return).
+ *
+ * Pure.
+ */
+export function constrainRect(
+  box: TransformBoxValue,
+  minWidth = 1,
+  minHeight = 1,
+): TransformBoxValue {
+  let { x, y, width, height } = box;
+
+  if (width < 0) {
+    x += width;
+    width = -width;
+  }
+  if (height < 0) {
+    y += height;
+    height = -height;
+  }
+  if (width < minWidth) width = minWidth;
+  if (height < minHeight) height = minHeight;
+
+  return { x, y, width, height, rotation: box.rotation };
+}
+
+/** Result of a resize step, carrying the new box plus the flip flags it crossed. */
+export interface ResizeResult {
+  /** The resized box (already constrained / normalized). */
+  box: TransformBoxValue;
+  /** Whether the box is mirrored on x relative to the gesture start. */
+  flippedX: boolean;
+  /** Whether the box is mirrored on y relative to the gesture start. */
+  flippedY: boolean;
+}
+
+/**
+ * Resize `box` by moving the edge(s) a `handle` controls by `deltaLocal` — a
+ * delta already expressed in the box's LOCAL (unrotated) axes.
+ *
+ * CRITICAL (rotated boxes): the caller MUST rotate the raw screen-space pointer
+ * delta into local axes first (`rotateVector(screenDelta, -box.rotation)`)
+ * before calling this. A naive axis-aligned delta is wrong once `rotation ≠ 0`
+ * because the box's "width" axis no longer aligns with screen x.
+ *
+ * The opposite edge/corner stays fixed in WORLD space (or the pivot stays fixed
+ * when `symmetric`). To keep the world anchor fixed we:
+ *   1. record the anchor's world position from the original box,
+ *   2. mutate the dragged edges in local space (so width/height/x/y change),
+ *   3. re-place the box so the anchor's local position maps back to the same
+ *      world point under the (unchanged) rotation.
+ *
+ * Aspect lock, min-size, and flip policy are applied between (2) and (3).
+ * Returns the new box and the flip flags. Pure.
+ */
+export function resizeEdge(
+  box: TransformBoxValue,
+  handle: TransformBoxHandlePosition,
+  deltaLocal: Point,
+  options: ResizeEdgeOptions = {},
+): ResizeResult {
+  const {
+    minWidth = 1,
+    minHeight = 1,
+    aspectRatio = null,
+    symmetric = false,
+    pivot = 'center',
+    allowFlip = true,
+  } = options;
+
+  const axes = handleAxes(handle);
+
+  // ── 1. world anchor ────────────────────────────────────────────────────────
+  // The anchor is the opposite corner/edge midpoint that must stay put. For a
+  // symmetric resize the anchor is the pivot itself. We capture it in world
+  // space so rotation is accounted for.
+  const startCenter = boxCenter(box);
+  const anchorLocal = symmetric
+    ? resolvePivot(box, pivot)
+    : {
+        // Opposite edge: flip the handle's outward sign. `0` axis → box center
+        // coordinate (that edge is not being moved).
+        x: box.x + (axes.x === 0 ? box.width / 2 : axes.x < 0 ? box.width : 0),
+        y: box.y + (axes.y === 0 ? box.height / 2 : axes.y < 0 ? box.height : 0),
+      };
+  const anchorWorld = rotatePoint(anchorLocal, box.rotation, startCenter);
+
+  // ── 2. apply the local delta to the dragged edges ──────────────────────────
+  // Symmetric doubles the delta (both sides move). `axes.* === 0` → that axis is
+  // untouched.
+  const scale = symmetric ? 2 : 1;
+  let newWidth = box.width + axes.x * deltaLocal.x * scale;
+  let newHeight = box.height + axes.y * deltaLocal.y * scale;
+
+  // ── 3. aspect lock ─────────────────────────────────────────────────────────
+  if (aspectRatio !== null && aspectRatio !== undefined) {
+    const applied = applyAspectRatio(newWidth, newHeight, aspectRatio, axes);
+    newWidth = applied.width;
+    newHeight = applied.height;
+  }
+
+  // Flip flags are read from the sign BEFORE we clamp/normalize. When flips are
+  // disallowed the size is clamped to the minimum (never crosses zero), so the
+  // box is never reported as flipped.
+  const flippedX = allowFlip && axes.x !== 0 && newWidth < 0;
+  const flippedY = allowFlip && axes.y !== 0 && newHeight < 0;
+
+  // ── 4. min size / flip policy ──────────────────────────────────────────────
+  if (!allowFlip) {
+    if (newWidth < minWidth) newWidth = minWidth;
+    if (newHeight < minHeight) newHeight = minHeight;
+  }
+  else {
+    // Allow negative size but keep |size| above the minimum so a flipped box is
+    // still grabbable.
+    if (Math.abs(newWidth) < minWidth) newWidth = minWidth * Math.sign(newWidth || 1);
+    if (Math.abs(newHeight) < minHeight) newHeight = minHeight * Math.sign(newHeight || 1);
+  }
+
+  // ── 5. re-place so the world anchor is preserved ───────────────────────────
+  // Build a provisional box whose anchor sits at the SAME LOCAL position
+  // (relative to the new size) as before, then translate it so that local
+  // anchor maps back to `anchorWorld`.
+  //
+  // Local anchor fraction (0..1) is constant across the resize because the
+  // anchor is the opposite edge/pivot. We compute the anchor's local position in
+  // the resized box, rotate it about the resized center, and shift.
+  const anchorFracX = symmetric
+    ? pivotFrac(pivot, 'x')
+    : axes.x === 0 ? 0.5 : axes.x < 0 ? 1 : 0;
+  const anchorFracY = symmetric
+    ? pivotFrac(pivot, 'y')
+    : axes.y === 0 ? 0.5 : axes.y < 0 ? 1 : 0;
+
+  // Provisional origin at (0,0); we only need it to compute the rotated offset of
+  // the anchor from the center, which is translation-invariant.
+  const provisional: TransformBoxValue = { x: 0, y: 0, width: newWidth, height: newHeight, rotation: box.rotation };
+  const provCenter = boxCenter(provisional);
+  const provAnchorLocal = { x: newWidth * anchorFracX, y: newHeight * anchorFracY };
+  const provAnchorWorld = rotatePoint(provAnchorLocal, box.rotation, provCenter);
+
+  // Shift the provisional box so its anchor lands on the recorded world anchor.
+  const placed: TransformBoxValue = {
+    x: anchorWorld.x - provAnchorWorld.x,
+    y: anchorWorld.y - provAnchorWorld.y,
+    width: newWidth,
+    height: newHeight,
+    rotation: box.rotation,
+  };
+
+  // Normalize negative sizes into a positive, well-formed box (flip folded into
+  // the origin). When flips are disallowed sizes are already positive.
+  const box2 = constrainRect(placed, minWidth, minHeight);
+
+  return { box: box2, flippedX, flippedY };
+}
+
+/** Fractional anchor position for a pivot on one axis (0..1). */
+function pivotFrac(pivot: TransformBoxPivot, axis: 'x' | 'y'): number {
+  if (pivot === 'center') return 0.5;
+  return axis === 'x' ? pivot.x : pivot.y;
+}
+
+/**
+ * Move the box by a WORLD-space translation `delta`. Rotation does not change
+ * the world-space translate, so this just shifts `x/y` (the box's local origin
+ * lives in the same space its center renders in). Pure.
+ */
+export function moveBox(box: TransformBoxValue, delta: Point): TransformBoxValue {
+  return { ...box, x: box.x + delta.x, y: box.y + delta.y };
+}
+
+/**
+ * Compute a rotation (degrees) from a pointer at `point` about `pivotWorld`,
+ * carrying a `start` reference so the seam (the ±180° wrap) is crossed smoothly:
+ * the returned angle is `startRotation + signedDelta(startAngle → currentAngle)`.
+ *
+ * Convention matches the rest of the editor: 0° up, clockwise-positive.
+ */
+export function rotationFromPointer(
+  point: Point,
+  pivotWorld: Point,
+  startPointerAngle: number,
+  startRotation: number,
+): number {
+  const current = pointerAngle(point, pivotWorld);
+  return startRotation + shortestAngleDelta(startPointerAngle, current);
+}
+
+/**
+ * Raw angle (degrees) of `point` about `center`: 0° up, clockwise-positive,
+ * range `[0, 360)`. Mirrors angle-dial's convention so rotation handles read the
+ * same way. A point exactly at the center returns `0`.
+ */
+export function pointerAngle(point: Point, center: Point): number {
+  const dx = point.x - center.x;
+  const dy = point.y - center.y;
+  if (dx === 0 && dy === 0) return 0;
+  const rad = Math.atan2(dx, -dy);
+  let deg = rad * (360 / TAU);
+  if (deg < 0) deg += 360;
+  return deg;
+}
+
+/**
+ * Signed shortest step (degrees) from `from` to `to`, in `(-180, 180]`. Positive
+ * is clockwise. Lets a rotate drag accumulate across the 0/360 seam instead of
+ * snapping backwards.
+ */
+export function shortestAngleDelta(from: number, to: number): number {
+  let d = (to - from) % 360;
+  if (d > 180) d -= 360;
+  else if (d <= -180) d += 360;
+  return d;
+}
+
+/** Wrap an angle (degrees) into `[0, 360)`. */
+export function normalizeRotation(deg: number): number {
+  const r = deg % 360;
+  return r < 0 ? r + 360 : r;
+}
+
+/**
+ * Snap a rotation to the nearest multiple of `increment` degrees. `increment <=
+ * 0` returns the value unchanged. Anchored at 0. Pure.
+ */
+export function snapRotation(deg: number, increment: number): number {
+  if (!(increment > 0)) return deg;
+  return Math.round(deg / increment) * increment;
+}
+
+/**
+ * Decompose a transform into its readable parts. Given a box, returns the
+ * normalized box dimensions, the world-space center, the four corner points in
+ * WORLD space (top-left, top-right, bottom-right, bottom-left, in that order,
+ * rotation applied), and the normalized rotation in `[0, 360)`.
+ *
+ * Shared with Crop (which needs corner world positions to draw the crop overlay
+ * and to hit-test handles) so the corner math lives in ONE pure place.
+ */
+export function decomposeTransform(box: TransformBoxValue): {
+  /** Normalized box (positive width/height, flip folded into origin). */
+  rect: { x: number; y: number; width: number; height: number };
+  /** World-space center the box rotates about. */
+  center: Point;
+  /** Rotation folded into `[0, 360)`. */
+  rotation: number;
+  /** World-space corners: [top-left, top-right, bottom-right, bottom-left]. */
+  corners: [Point, Point, Point, Point];
+} {
+  const norm = constrainRect(box, 0, 0);
+  const center = { x: norm.x + norm.width / 2, y: norm.y + norm.height / 2 };
+  const rotation = normalizeRotation(box.rotation);
+
+  const tl = rotatePoint({ x: norm.x, y: norm.y }, box.rotation, center);
+  const tr = rotatePoint({ x: norm.x + norm.width, y: norm.y }, box.rotation, center);
+  const br = rotatePoint({ x: norm.x + norm.width, y: norm.y + norm.height }, box.rotation, center);
+  const bl = rotatePoint({ x: norm.x, y: norm.y + norm.height }, box.rotation, center);
+
+  return {
+    rect: { x: norm.x, y: norm.y, width: norm.width, height: norm.height },
+    center,
+    rotation,
+    corners: [tl, tr, br, bl],
+  };
+}
diff --git a/vue/primitives/src/canvas/waveform/WaveformBars.vue b/vue/primitives/src/canvas/waveform/WaveformBars.vue
new file mode 100644
index 0000000..0c94b73
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformBars.vue
@@ -0,0 +1,63 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Renders the resampled bar geometry from `WaveformRoot` as a row of elements,
+ * one per bucket, each positioned and sized from the computed `buckets`. Purely
+ * presentational (`role="presentation"`, `aria-hidden`) — the accessible model
+ * lives on `WaveformCursor` and `WaveformRegion`. Bar heights are exposed as a
+ * `0..1` fraction (via CSS custom prop `--waveform-bar`) and as an explicit
+ * height percentage so consumers can style freely. Render this OR
+ * `WaveformPath`, per the root's `mode`.
+ */
+export interface WaveformBarsProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import type { CSSProperties } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useWaveformContext } from './context';
+import type { WaveformBar } from './utils';
+
+const { as = 'div' } = defineProps<WaveformBarsProps>();
+const ctx = useWaveformContext();
+const { forwardRef } = useForwardExpose();
+
+// `--waveform-bar` (a `0..1` magnitude) is exposed so consumers can style by
+// amplitude. CSS custom props aren't in Vue's typed `CSSProperties`, so the
+// record is assembled and cast here rather than inline in the template.
+function barStyle(bar: WaveformBar): CSSProperties {
+  const style = {
+    position: 'absolute',
+    left: `${bar.x}px`,
+    width: `${bar.width}px`,
+    height: `${bar.height * 100}%`,
+    top: '50%',
+    transform: 'translateY(-50%)',
+    '--waveform-bar': String(bar.height),
+  } satisfies Record<string, string>;
+  return style as unknown as CSSProperties;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="presentation"
+    aria-hidden="true"
+    data-waveform-bars=""
+    style="position: relative;"
+  >
+    <slot :bars="ctx.buckets.value">
+      <Primitive
+        v-for="(bar, i) in ctx.buckets.value"
+        :key="i"
+        as="span"
+        data-waveform-bar=""
+        :style="barStyle(bar)"
+      />
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/WaveformCursor.vue b/vue/primitives/src/canvas/waveform/WaveformCursor.vue
new file mode 100644
index 0000000..4d20967
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformCursor.vue
@@ -0,0 +1,132 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { WaveformTimeFormatter } from './context';
+
+/**
+ * The playback cursor, rendered as `role="slider"` over `[0, duration]` with
+ * `aria-valuenow` = the current time. It positions itself at
+ * `projection(currentTime)` and is fully keyboard-driven: Arrow Left/Right scrub
+ * by `step` seconds (Shift by `largeStep`), Home/End jump to `0`/`duration`,
+ * PageUp/PageDown seek by one visible window. Give it an `aria-label` (defaults
+ * to "Playback position"). `aria-valuetext` comes from `timeFormatter` (falling
+ * back to the root's, then `formatClock`).
+ */
+export interface WaveformCursorProps extends PrimitiveProps {
+  /**
+   * Formatter for `aria-valuetext`. Overrides the root's formatter for this
+   * cursor only. @default the root's `timeFormatter` (`formatClock`)
+   */
+  timeFormatter?: WaveformTimeFormatter;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, useAttrs, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useWaveformContext } from './context';
+
+const { as = 'div', timeFormatter } = defineProps<WaveformCursorProps>();
+const ctx = useWaveformContext();
+const attrs = useAttrs();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+watch(currentElement, (el) => {
+  ctx.registerCursor((el ?? null) as HTMLElement | null);
+});
+onBeforeUnmount(() => ctx.registerCursor(null));
+
+const time = computed(() => ctx.currentTime.value);
+const duration = computed(() => (ctx.duration.value > 0 ? ctx.duration.value : 0));
+
+// Pixel x within the body. Pinned to 0 when empty / unmeasured.
+const offsetPx = computed(() => {
+  if (ctx.isEmpty.value || ctx.width.value <= 0) return 0;
+  return ctx.projection.scale(time.value);
+});
+
+const positionStyle = computed<{
+  left: string | undefined;
+  right: string | undefined;
+}>(() => {
+  const px = `${offsetPx.value}px`;
+  if (ctx.direction.value === 'rtl') return { left: undefined, right: px };
+  return { left: px, right: undefined };
+});
+
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return 'Playback position';
+});
+
+const valueText = computed<string | undefined>(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  const fmt = timeFormatter ?? ctx.timeFormatter.value;
+  return fmt(time.value);
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const rtl = ctx.direction.value === 'rtl';
+  const stepS = event.shiftKey ? ctx.largeStep.value : ctx.step.value;
+  let delta: number;
+  switch (event.key) {
+    case 'ArrowRight':
+      delta = rtl ? -stepS : stepS;
+      break;
+    case 'ArrowLeft':
+      delta = rtl ? stepS : -stepS;
+      break;
+    case 'Home':
+      event.preventDefault();
+      ctx.seek(0, true);
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.seek(duration.value, true);
+      return;
+    case 'PageUp': {
+      event.preventDefault();
+      const [ws, we] = ctx.window.value;
+      ctx.seek(time.value + (we - ws), true);
+      return;
+    }
+    case 'PageDown': {
+      event.preventDefault();
+      const [ws, we] = ctx.window.value;
+      ctx.seek(time.value - (we - ws), true);
+      return;
+    }
+    default:
+      return;
+  }
+  if (delta === 0) return;
+  event.preventDefault();
+  ctx.seek(time.value + delta, true);
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
+    :aria-valuemin="0"
+    :aria-valuemax="duration"
+    :aria-valuenow="time"
+    :aria-valuetext="valueText"
+    aria-orientation="horizontal"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-empty="ctx.isEmpty.value ? '' : undefined"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :time="time" :offset="offsetPx" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/WaveformEmpty.vue b/vue/primitives/src/canvas/waveform/WaveformEmpty.vue
new file mode 100644
index 0000000..4cf4941
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformEmpty.vue
@@ -0,0 +1,44 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Placeholder shown when there is nothing to render — `duration === 0` or the
+ * peaks array is empty (the same condition that puts `data-empty` on the root),
+ * or while `loading` async peaks. Renders only in those states; the default slot
+ * receives `isEmpty` / `loading` so a consumer can show a spinner vs. a "no
+ * audio" message. Use this OR rely on the root's `data-empty` / `data-loading`.
+ */
+export interface WaveformEmptyProps extends PrimitiveProps {
+  /**
+   * Also render while the root is `loading`. When `false`, only renders for the
+   * empty (no peaks / zero duration) state. @default true
+   */
+  whileLoading?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useWaveformContext } from './context';
+
+const { as = 'div', whileLoading = true } = defineProps<WaveformEmptyProps>();
+const ctx = useWaveformContext();
+const { forwardRef } = useForwardExpose();
+
+const visible = computed(() => ctx.isEmpty.value || (whileLoading && ctx.loading.value));
+</script>
+
+<template>
+  <Primitive
+    v-if="visible"
+    :ref="forwardRef"
+    :as="as"
+    data-waveform-empty=""
+    :data-loading="ctx.loading.value ? '' : undefined"
+    :aria-busy="ctx.loading.value || undefined"
+  >
+    <slot :is-empty="ctx.isEmpty.value" :loading="ctx.loading.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/WaveformPath.vue b/vue/primitives/src/canvas/waveform/WaveformPath.vue
new file mode 100644
index 0000000..04b4b0d
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformPath.vue
@@ -0,0 +1,80 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Alternative SVG rendering of the waveform: a single smoothed `<path>` through
+ * the resampled peaks (mirrored top/bottom for a filled silhouette). Smoothing
+ * is Catmull-Rom (`buildSmoothPath`) at the supplied `tension`. Purely
+ * presentational (`aria-hidden`). Render this OR `WaveformBars`, per the root's
+ * `mode`. The `<svg>` stretches to the part's box; size it via CSS.
+ */
+export interface WaveformPathProps extends PrimitiveProps {
+  /**
+   * Number of points sampled across the body. Higher is smoother but costlier.
+   * @default 256
+   */
+  samples?: number;
+  /**
+   * Catmull-Rom tension forwarded to `buildSmoothPath` (`0` = uniform). Higher
+   * flattens the curve. @default 0
+   */
+  tension?: number;
+  /** Fill the area under the silhouette (mirrored) instead of stroking a line. @default true */
+  filled?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useElementSize, useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { buildSmoothPath } from '../../internal/spline';
+import { useWaveformContext } from './context';
+import { buildPathPoints } from './utils';
+
+const { as = 'svg', samples = 256, tension = 0, filled = true } = defineProps<WaveformPathProps>();
+const ctx = useWaveformContext();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const { width, height } = useElementSize(currentElement);
+
+const d = computed(() => {
+  const w = width.value;
+  const h = height.value;
+  if (w <= 0 || h <= 0 || ctx.isEmpty.value) return '';
+  const [ws, we] = ctx.window.value;
+  const dur = ctx.duration.value;
+  const len = ctx.peaks.value.length;
+  const sampleStart = dur > 0 ? Math.floor((ws / dur) * len) : 0;
+  const sampleEnd = dur > 0 ? Math.ceil((we / dur) * len) : len;
+  const top = buildPathPoints(ctx.peaks.value, w, h, samples, ctx.signed.value, sampleStart, sampleEnd);
+  if (top.length === 0) return '';
+  if (!filled) return buildSmoothPath(top, tension);
+  // Filled: top silhouette, then back along the mirrored bottom, closed. Build
+  // each smoothed segment from points, then stitch (drop the trailing `M` of the
+  // lower segment so it continues the same subpath) and close.
+  const mid = h / 2;
+  const bottom = top.map(p => ({ x: p.x, y: mid + (mid - p.y) })).reverse();
+  const upper = buildSmoothPath(top, tension);
+  const lowerFull = buildSmoothPath(bottom, tension);
+  // `buildSmoothPath` always starts with `M x,y` — replace it with a line-to so
+  // the bottom continues the upper subpath instead of starting a new one.
+  const lower = lowerFull.replace(/^M\s*([-\d.]+),([-\d.]+)/, 'L $1,$2');
+  return `${upper} ${lower} Z`;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    data-waveform-path=""
+    preserveAspectRatio="none"
+    style="display: block;"
+  >
+    <slot :d="d">
+      <path :d="d" />
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/WaveformRegion.vue b/vue/primitives/src/canvas/waveform/WaveformRegion.vue
new file mode 100644
index 0000000..625606b
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformRegion.vue
@@ -0,0 +1,151 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A single audio region (selection), rendered as `role="group"` whose
+ * `aria-label` is the formatted `start–end` range (plus the region `label` when
+ * set). It positions and sizes itself from `projection(start)..projection(end)`
+ * and hosts two `WaveformRegionHandle` children (one per edge) so trimming is
+ * keyboard-driven like a two-thumb range slider. The group itself can be moved
+ * by dragging its body; Enter/Space select it, Delete/Backspace remove it.
+ * Exposes `data-selected` / `data-active`.
+ */
+export interface WaveformRegionProps extends PrimitiveProps {
+  /** The id of the region (in the root's `regions`) this part renders. */
+  regionId: string;
+  /** Whether the group body can be dragged to move the whole region. @default true */
+  draggable?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { provideWaveformRegionContext, useWaveformContext } from './context';
+import type { WaveformRegionEdge } from './context';
+
+const { as = 'div', regionId, draggable = true } = defineProps<WaveformRegionProps>();
+const ctx = useWaveformContext();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+const region = computed(() => ctx.regions.value.find(r => r.id === regionId));
+const start = computed(() => region.value?.start ?? 0);
+const end = computed(() => region.value?.end ?? 0);
+
+const selected = shallowRef(false);
+
+const leftPx = computed(() => (ctx.isEmpty.value ? 0 : ctx.projection.scale(start.value)));
+const rightPx = computed(() => (ctx.isEmpty.value ? 0 : ctx.projection.scale(end.value)));
+const sizePx = computed(() => Math.abs(rightPx.value - leftPx.value));
+
+const positionStyle = computed<{ left: string | undefined; right: string | undefined; width: string }>(() => {
+  const w = `${sizePx.value}px`;
+  const near = `${Math.min(leftPx.value, rightPx.value)}px`;
+  if (ctx.direction.value === 'rtl') return { left: undefined, right: near, width: w };
+  return { left: near, right: undefined, width: w };
+});
+
+const ariaLabel = computed(() => {
+  const fmt = ctx.timeFormatter.value;
+  const range = `${fmt(start.value)}–${fmt(end.value)}`;
+  return region.value?.label ? `${region.value.label}, ${range}` : range;
+});
+
+function trim(edge: WaveformRegionEdge, seconds: number, commit = false): void {
+  if (edge === 'start') ctx.updateRegion(regionId, { start: seconds }, commit);
+  else ctx.updateRegion(regionId, { end: seconds }, commit);
+}
+
+provideWaveformRegionContext({
+  id: toRef(() => regionId),
+  start,
+  end,
+  selected,
+  trim,
+});
+
+// ── move the whole region by dragging its body ──────────────────────────────
+let dragStart = 0;
+let dragEnd = 0;
+usePointerDrag(currentElement, {
+  axis: 'x',
+  threshold: 3,
+  disabled: () => ctx.disabled.value || !draggable,
+  onStart: () => {
+    if (ctx.disabled.value || !draggable) return false;
+    // Edge handles `stopPropagation()` on pointerdown so their press never
+    // reaches this body drag — a press here always means "move the region".
+    dragStart = start.value;
+    dragEnd = end.value;
+    selected.value = true;
+    return undefined;
+  },
+  onMove: (state) => {
+    const ppu = pxPerSecond();
+    if (ppu === 0) return;
+    const dt = (ctx.direction.value === 'rtl' ? -state.total.x : state.total.x) / ppu;
+    const dur = ctx.duration.value;
+    const span = dragEnd - dragStart;
+    let ns = dragStart + dt;
+    // Clamp the whole region within [0, duration] preserving its span.
+    if (ns < 0) ns = 0;
+    if (ns + span > dur) ns = dur - span;
+    ctx.updateRegion(regionId, { start: ns, end: ns + span });
+  },
+  onCommit: () => {
+    const r = ctx.regions.value.find(x => x.id === regionId);
+    if (r) ctx.updateRegion(regionId, { start: r.start, end: r.end }, true);
+  },
+});
+
+function pxPerSecond(): number {
+  // Derive from the projection over a 1-second probe (robust to zoom/fit).
+  const a = ctx.projection.scale(0);
+  const b = ctx.projection.scale(1);
+  return Math.abs(b - a);
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  switch (event.key) {
+    case 'Enter':
+    case ' ':
+      event.preventDefault();
+      selected.value = !selected.value;
+      break;
+    case 'Delete':
+    case 'Backspace':
+      event.preventDefault();
+      ctx.removeRegion(regionId);
+      break;
+    default:
+      break;
+  }
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="group"
+    :aria-label="ariaLabel"
+    :data-selected="selected ? '' : undefined"
+    :data-active="selected ? '' : undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :style="{ position: 'absolute', top: '0', bottom: '0', ...positionStyle }"
+    tabindex="0"
+    @keydown="onKeyDown"
+    @focus="selected = true"
+  >
+    <slot
+      :region="region"
+      :start="start"
+      :end="end"
+      :selected="selected"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/WaveformRegionHandle.vue b/vue/primitives/src/canvas/waveform/WaveformRegionHandle.vue
new file mode 100644
index 0000000..2fafc67
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformRegionHandle.vue
@@ -0,0 +1,133 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { WaveformRegionEdge } from './context';
+
+/**
+ * One trim handle of a `WaveformRegion`, rendered as `role="slider"` over
+ * `[0, duration]` with `aria-valuenow` = its edge's time. Pass `edge="start"`
+ * or `edge="end"`. Dragging trims that edge; Arrow Left/Right move it by `step`
+ * (Shift by `largeStep`), Home/End jump the edge to `0` / `duration`. Together
+ * the two handles behave like a two-thumb range slider over the region. Default
+ * `aria-label` is "Region start" / "Region end".
+ */
+export interface WaveformRegionHandleProps extends PrimitiveProps {
+  /** Which edge of the parent region this handle trims. */
+  edge: WaveformRegionEdge;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useAttrs } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useWaveformContext, useWaveformRegionContext } from './context';
+
+const { as = 'div', edge } = defineProps<WaveformRegionHandleProps>();
+const ctx = useWaveformContext();
+const region = useWaveformRegionContext();
+const attrs = useAttrs();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+const value = computed(() => (edge === 'start' ? region.start.value : region.end.value));
+const duration = computed(() => (ctx.duration.value > 0 ? ctx.duration.value : 0));
+
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return edge === 'start' ? 'Region start' : 'Region end';
+});
+
+const valueText = computed<string | undefined>(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  return ctx.timeFormatter.value(value.value);
+});
+
+function timeFromClientX(clientX: number): number {
+  // The projection's pixel 0 is the left edge of the root body. Resolve that
+  // origin by walking up to the root primitive (it carries `data-waveform-root`)
+  // and convert the client x into a body-relative x for `projection.invert`.
+  const origin = bodyRect();
+  if (!origin) return value.value;
+  return ctx.projection.invert(clientX - origin.left);
+}
+
+function bodyRect(): DOMRect | undefined {
+  let el: HTMLElement | null = currentElement.value ?? null;
+  while (el) {
+    if (el.hasAttribute('data-waveform-root')) return el.getBoundingClientRect();
+    el = el.parentElement;
+  }
+  return currentElement.value?.offsetParent instanceof HTMLElement
+    ? currentElement.value.offsetParent.getBoundingClientRect()
+    : undefined;
+}
+
+usePointerDrag(currentElement, {
+  axis: 'x',
+  threshold: 0,
+  disabled: () => ctx.disabled.value,
+  stopPropagation: true,
+  onStart: () => {
+    if (ctx.disabled.value) return false;
+    return undefined;
+  },
+  onMove: (state) => {
+    region.trim(edge, timeFromClientX(state.point.x));
+  },
+  onCommit: () => {
+    region.trim(edge, value.value, true);
+  },
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const rtl = ctx.direction.value === 'rtl';
+  const stepS = event.shiftKey ? ctx.largeStep.value : ctx.step.value;
+  let delta: number;
+  switch (event.key) {
+    case 'ArrowRight':
+      delta = rtl ? -stepS : stepS;
+      break;
+    case 'ArrowLeft':
+      delta = rtl ? stepS : -stepS;
+      break;
+    case 'Home':
+      event.preventDefault();
+      region.trim(edge, 0, true);
+      return;
+    case 'End':
+      event.preventDefault();
+      region.trim(edge, duration.value, true);
+      return;
+    default:
+      return;
+  }
+  if (delta === 0) return;
+  event.preventDefault();
+  region.trim(edge, value.value + delta, true);
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :data-edge="edge"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
+    :aria-valuemin="0"
+    :aria-valuemax="duration"
+    :aria-valuenow="value"
+    :aria-valuetext="valueText"
+    aria-orientation="horizontal"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    @keydown="onKeyDown"
+  >
+    <slot :edge="edge" :value="value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/WaveformRoot.vue b/vue/primitives/src/canvas/waveform/WaveformRoot.vue
new file mode 100644
index 0000000..3a2026d
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformRoot.vue
@@ -0,0 +1,437 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { WaveformDirection, WaveformProjection, WaveformTimeFormatter } from './context';
+import type { WaveformMode, WaveformPeaksRange, WaveformRegionData } from './utils';
+
+/**
+ * A headless audio waveform: it renders amplitude peaks as bars (or a smoothed
+ * path), overlays a draggable playback cursor, and hosts zero or more draggable
+ * regions (selections). The root owns the peaks, the `currentTime` model, and
+ * the `regions` model; it measures its own width, builds a time↔pixel
+ * projection over the visible window (`offset` + `zoom` for timeline sync), and
+ * resamples `peaks` to the available bar count by ratio (never assuming one peak
+ * per pixel). Pointer-down on the body scrubs the cursor; with
+ * `createRegionOnDrag` a press-drag marquees out a new region. It provides
+ * context to `WaveformBars`/`WaveformPath`, `WaveformCursor`, `WaveformRegion`,
+ * `WaveformSelectionPreview`, and `WaveformEmpty`. Reach for it to visualize and
+ * navigate audio (players, trimmers, transcript editors).
+ */
+export interface WaveformRootProps extends PrimitiveProps {
+  /**
+   * Per-sample amplitudes. Either normalized `0..1` magnitudes or signed
+   * `-1..1` PCM-style samples — select which via `peaksRange`. Length is
+   * decoupled from `duration`: the root resamples by ratio to the bar count.
+   * @default []
+   */
+  peaks?: number[] | Float32Array;
+  /**
+   * The amplitude convention of `peaks`. `'-1..1'` (signed) is rectified via
+   * absolute value; `'0..1'` is passed through.
+   * @default '-1..1'
+   */
+  peaksRange?: WaveformPeaksRange;
+  /** Total media duration, in seconds. @default 0 */
+  duration?: number;
+  /** Current playback position in seconds (`v-model:current-time`). @default 0 */
+  currentTime?: number;
+  /** The set of regions (`v-model:regions`). @default [] */
+  regions?: WaveformRegionData[];
+  /**
+   * Left edge of the visible window, in seconds (for timeline sync). @default 0
+   */
+  offset?: number;
+  /**
+   * Horizontal zoom in pixels-per-second. `0` means "fit": the whole
+   * `[offset, duration]` span fills the measured width. @default 0
+   */
+  zoom?: number;
+  /** Bar thickness in pixels (bars mode). @default 2 */
+  barWidth?: number;
+  /** Gap between bars in pixels (bars mode). @default 1 */
+  barGap?: number;
+  /** Body render strategy. @default 'bars' */
+  mode?: WaveformMode;
+  /** A press-drag on the body marquees out a new region instead of seeking. @default false */
+  createRegionOnDrag?: boolean;
+  /**
+   * Keyboard step for the cursor / region edges, in seconds. `0` means "1 pixel
+   * of time" — resolved from the current projection. @default 0
+   */
+  step?: number;
+  /** Large keyboard step (Shift+Arrow), in seconds. @default step × 10 (or 1px×10) */
+  largeStep?: number;
+  /** Default formatter for the cursor's `aria-valuetext`. @default formatClock */
+  timeFormatter?: WaveformTimeFormatter;
+  /** Mark the waveform as loading async peaks (sets `data-loading`). @default false */
+  loading?: boolean;
+  /** Disable all interaction. @default false */
+  disabled?: boolean;
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
+  dir?: WaveformDirection;
+}
+
+export interface WaveformRootEmits {
+  /** A scrub / keyboard seek settled. */
+  seekCommit: [time: number];
+  /** A new region was created (via `createRegionOnDrag`). */
+  regionCreate: [region: WaveformRegionData];
+  /** A region's bounds changed (drag/keyboard) and settled. */
+  regionUpdate: [region: WaveformRegionData];
+  /** A region was removed. */
+  regionRemove: [id: string];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { useElementSize } from '@robonen/vue';
+import { clamp } from '@robonen/stdlib';
+import { Primitive } from '../../internal/primitive';
+import { formatClock, useScale } from '../../internal/scale';
+import { useDirection } from '../../utilities/config-provider';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { provideWaveformContext } from './context';
+import { buildBars } from './utils';
+
+const {
+  peaks = [],
+  peaksRange = '-1..1',
+  duration = 0,
+  offset = 0,
+  zoom = 0,
+  barWidth = 2,
+  barGap = 1,
+  mode = 'bars',
+  createRegionOnDrag = false,
+  step = 0,
+  largeStep,
+  timeFormatter = formatClock,
+  loading = false,
+  disabled = false,
+  dir,
+  as = 'div',
+} = defineProps<WaveformRootProps>();
+
+const emit = defineEmits<WaveformRootEmits>();
+
+const currentTimeModel = defineModel<number>('currentTime', { default: 0 });
+const regionsModel = defineModel<WaveformRegionData[]>('regions', { default: () => [] });
+
+// Internal local mirrors of the models. `defineModel` in fully-controlled mode
+// returns the incoming PROP from its getter until the parent re-renders, so two
+// synchronous writes (e.g. rapid key presses or a pointer drag) would both read
+// the stale value. The locals are written immediately and pushed to the model;
+// a watch keeps them in sync when the parent drives the value. (Same pattern as
+// SliderRoot's `localValues`.)
+const localTime = shallowRef<number>(currentTimeModel.value ?? 0);
+watch(currentTimeModel, (v) => {
+  if (v !== null && v !== undefined && v !== localTime.value) localTime.value = v;
+});
+
+const localRegions = shallowRef<WaveformRegionData[]>(regionsModel.value ?? []);
+watch(regionsModel, (v) => {
+  if (v && v !== localRegions.value) localRegions.value = v;
+});
+
+const direction = useDirection(() => dir);
+const signed = computed(() => peaksRange === '-1..1');
+
+// ── width measurement ────────────────────────────────────────────────────
+// Manual element ref (no `useForwardExpose`): the root owns its own element and
+// exposes a custom imperative API via a single `defineExpose` below, so a manual
+// ref avoids the double-`expose()` warning `useForwardExpose` would cause when
+// paired with `defineExpose`. `Primitive`'s `:ref` resolves to the DOM node (or
+// a component instance whose `$el` we read).
+const bodyEl = shallowRef<HTMLElement | null>(null);
+function setRootRef(el: unknown): void {
+  if (el === null || el === undefined) {
+    bodyEl.value = null;
+    return;
+  }
+  if (el instanceof HTMLElement) {
+    bodyEl.value = el;
+    return;
+  }
+  const inst = el as { $el?: unknown };
+  bodyEl.value = inst.$el instanceof HTMLElement ? inst.$el : null;
+}
+
+const { width } = useElementSize(bodyEl);
+
+// ── visible window + projection ──────────────────────────────────────────
+const isEmpty = computed(() => duration <= 0 || peaks.length === 0);
+
+// `zoom` (px/sec) sets the window width; `0` → fit the remaining duration.
+const windowRange = computed<readonly [number, number]>(() => {
+  const start = offset > 0 ? offset : 0;
+  if (duration <= 0) return [0, 0];
+  if (zoom > 0) {
+    const w = width.value;
+    const span = w > 0 ? w / zoom : duration - start;
+    const end = Math.min(start + span, duration);
+    return [start, end > start ? end : start];
+  }
+  return [start, duration];
+});
+
+const scale = useScale({
+  domain: windowRange,
+  range: () => [0, width.value],
+  // ltr → start at left; rtl flips horizontally.
+  rtl: () => direction.value === 'rtl',
+  clamp: true,
+});
+
+const projection: WaveformProjection = {
+  scale: scale.scale,
+  invert: scale.invert,
+};
+
+// One pixel of time, for `step: 0` resolution and PageUp/Down windows.
+const pxToTime = computed(() => {
+  const ppu = scale.pxPerUnit.value;
+  return ppu > 0 ? 1 / ppu : 0;
+});
+const resolvedStep = computed(() => (step > 0 ? step : pxToTime.value || 0.01));
+const resolvedLargeStep = computed(() => (largeStep !== undefined && largeStep > 0 ? largeStep : resolvedStep.value * 10));
+
+// ── buckets (bar geometry) ───────────────────────────────────────────────
+// Resampled BY RATIO across the visible window's sample slice. When peaks map
+// to the whole duration, the window's sample slice is its time fraction.
+const buckets = computed(() => {
+  if (mode !== 'bars') return [];
+  const w = width.value;
+  if (w <= 0 || isEmpty.value) return [];
+  const len = peaks.length;
+  const [ws, we] = windowRange.value;
+  const dur = duration;
+  // Map the visible time window onto the peaks index window by ratio.
+  const sampleStart = dur > 0 ? Math.floor((ws / dur) * len) : 0;
+  const sampleEnd = dur > 0 ? Math.ceil((we / dur) * len) : len;
+  return buildBars(peaks, w, barWidth, barGap, signed.value, sampleStart, sampleEnd);
+});
+
+// ── currentTime ──────────────────────────────────────────────────────────
+const currentTime = computed(() => clamp(localTime.value ?? 0, 0, duration > 0 ? duration : 0));
+
+function seek(seconds: number, commit = false): void {
+  if (disabled) return;
+  const next = clamp(Number.isFinite(seconds) ? seconds : 0, 0, duration > 0 ? duration : 0);
+  if (next !== localTime.value) {
+    localTime.value = next;
+    currentTimeModel.value = next;
+  }
+  if (commit) emit('seekCommit', next);
+}
+
+// ── regions ──────────────────────────────────────────────────────────────
+// Named `regionList` (not `regions`) to avoid colliding with the `regions`
+// prop/model name (`vue/no-dupe-keys`).
+const regionList = computed(() => localRegions.value ?? []);
+
+function setRegions(next: WaveformRegionData[]): void {
+  localRegions.value = next;
+  regionsModel.value = next;
+}
+
+let regionSeq = 0;
+function nextId(): string {
+  regionSeq += 1;
+  return `waveform-region-${Date.now().toString(36)}-${regionSeq}`;
+}
+
+function clampTime(t: number): number {
+  return clamp(Number.isFinite(t) ? t : 0, 0, duration > 0 ? duration : 0);
+}
+
+function addRegion(region: Partial<WaveformRegionData> & { start: number; end: number }): string {
+  const id = region.id ?? nextId();
+  let start = clampTime(region.start);
+  let end = clampTime(region.end);
+  if (end < start) [start, end] = [end, start];
+  const created: WaveformRegionData = { id, start, end, label: region.label, color: region.color };
+  setRegions([...regionList.value, created]);
+  emit('regionCreate', created);
+  return id;
+}
+
+function updateRegion(id: string, patch: Partial<Omit<WaveformRegionData, 'id'>>, commit = false): void {
+  if (disabled) return;
+  const list = regionList.value;
+  const idx = list.findIndex(r => r.id === id);
+  if (idx === -1) return;
+  const prev = list[idx]!;
+  let start = patch.start !== undefined && patch.start !== null ? clampTime(patch.start) : prev.start;
+  let end = patch.end !== undefined && patch.end !== null ? clampTime(patch.end) : prev.end;
+  if (end < start) [start, end] = [end, start];
+  const merged: WaveformRegionData = {
+    ...prev,
+    start,
+    end,
+    label: patch.label !== undefined ? patch.label : prev.label,
+    color: patch.color !== undefined ? patch.color : prev.color,
+  };
+  if (merged.start === prev.start && merged.end === prev.end && merged.label === prev.label && merged.color === prev.color) {
+    if (commit) emit('regionUpdate', merged);
+    return;
+  }
+  const next = list.slice();
+  next[idx] = merged;
+  setRegions(next);
+  if (commit) emit('regionUpdate', merged);
+}
+
+function removeRegion(id: string): void {
+  if (disabled) return;
+  const list = regionList.value;
+  if (!list.some(r => r.id === id)) return;
+  setRegions(list.filter(r => r.id !== id));
+  emit('regionRemove', id);
+}
+
+// ── cursor registration (so the root can drive focus / window paging) ──────
+const cursorEl = shallowRef<HTMLElement | null>(null);
+function registerCursor(el: HTMLElement | null): void {
+  cursorEl.value = el;
+}
+
+// ── pointer interaction on the body ────────────────────────────────────────
+// Selection preview state (create-region marquee in flight).
+const previewActive = shallowRef(false);
+const previewStart = shallowRef(0);
+const previewEnd = shallowRef(0);
+let pendingRegion = false;
+
+function timeFromClientX(clientX: number, rect?: DOMRect): number {
+  const r = rect ?? bodyEl.value?.getBoundingClientRect();
+  if (!r || r.width === 0) return 0;
+  return projection.invert(clientX - r.left);
+}
+
+// Body rect snapshotted at gesture start: it cannot change mid-drag, so caching
+// it removes a getBoundingClientRect reflow on every scrub/region onMove frame.
+let gestureRect: DOMRect | undefined;
+
+usePointerDrag(bodyEl, {
+  axis: 'x',
+  threshold: createRegionOnDrag ? 3 : 0,
+  disabled: () => disabled || isEmpty.value,
+  preventDefault: true,
+  onStart: (state) => {
+    if (disabled || isEmpty.value) return false;
+    gestureRect = bodyEl.value?.getBoundingClientRect();
+    if (createRegionOnDrag) {
+      const t = timeFromClientX(state.startPoint.x, gestureRect);
+      previewStart.value = t;
+      previewEnd.value = t;
+      previewActive.value = true;
+      pendingRegion = true;
+    }
+    else {
+      // Immediate scrub: seek to the press point.
+      seek(timeFromClientX(state.startPoint.x, gestureRect));
+    }
+    return undefined;
+  },
+  onMove: (state) => {
+    const t = timeFromClientX(state.point.x, gestureRect);
+    if (pendingRegion) previewEnd.value = t;
+    else seek(t);
+  },
+  onEnd: () => {
+    gestureRect = undefined;
+    if (pendingRegion) {
+      previewActive.value = false;
+      pendingRegion = false;
+    }
+  },
+  onCommit: () => {
+    if (createRegionOnDrag) {
+      const a = previewStart.value;
+      const b = previewEnd.value;
+      if (Math.abs(b - a) > 0) addRegion({ start: Math.min(a, b), end: Math.max(a, b) });
+    }
+    else {
+      emit('seekCommit', currentTime.value);
+    }
+  },
+});
+
+// ── keyboard window paging (PageUp/PageDown seek by one visible window) ─────
+function pageSeconds(): number {
+  const [ws, we] = windowRange.value;
+  const span = we - ws;
+  return span > 0 ? span : duration;
+}
+
+// expose helpers consumed by the cursor for window-based paging
+const windowSpan = computed(() => pageSeconds());
+
+const preview = computed(() => ({
+  active: previewActive.value,
+  start: previewStart.value,
+  end: previewEnd.value,
+}));
+
+provideWaveformContext({
+  peaks: toRef(() => peaks as ArrayLike<number>),
+  signed,
+  duration: toRef(() => duration),
+  currentTime,
+  regions: regionList,
+  width,
+  direction,
+  disabled: toRef(() => disabled),
+  step: resolvedStep,
+  largeStep: resolvedLargeStep,
+  timeFormatter: toRef(() => timeFormatter),
+  window: windowRange,
+  projection,
+  buckets,
+  isEmpty,
+  loading: toRef(() => loading),
+  preview,
+  seek,
+  addRegion,
+  updateRegion,
+  removeRegion,
+  registerCursor,
+});
+
+defineExpose({
+  currentTime,
+  regions: regionList,
+  seek,
+  addRegion,
+  updateRegion,
+  removeRegion,
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="setRootRef"
+    :as="as"
+    :dir="direction"
+    data-waveform-root=""
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-empty="isEmpty ? '' : undefined"
+    :data-loading="loading ? '' : undefined"
+    :data-creating="previewActive ? '' : undefined"
+  >
+    <slot
+      :current-time="currentTime"
+      :regions="regionList"
+      :duration="duration"
+      :is-empty="isEmpty"
+      :loading="loading"
+      :width="width"
+      :preview="{ active: previewActive, start: previewStart, end: previewEnd }"
+      :window-span="windowSpan"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/WaveformSelectionPreview.vue b/vue/primitives/src/canvas/waveform/WaveformSelectionPreview.vue
new file mode 100644
index 0000000..fb03c2d
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/WaveformSelectionPreview.vue
@@ -0,0 +1,59 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The transient marquee shown while a new region is being dragged out
+ * (`createRegionOnDrag`). Renders nothing until a create gesture is in flight,
+ * then positions/sizes itself from the in-progress selection. The pixel
+ * geometry is also exposed via the default slot so a consumer can render their
+ * own preview surface. `aria-hidden` (it has no committed value yet).
+ */
+export interface WaveformSelectionPreviewProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useWaveformContext } from './context';
+
+const { as = 'div' } = defineProps<WaveformSelectionPreviewProps>();
+const ctx = useWaveformContext();
+const { forwardRef } = useForwardExpose();
+
+const active = computed(() => ctx.preview.value.active);
+
+const geometry = computed(() => {
+  const { start, end } = ctx.preview.value;
+  const a = ctx.projection.scale(start);
+  const b = ctx.projection.scale(end);
+  const left = Math.min(a, b);
+  const width = Math.abs(b - a);
+  return { left, width, start: Math.min(start, end), end: Math.max(start, end) };
+});
+
+const positionStyle = computed<{ left: string | undefined; right: string | undefined; width: string }>(() => {
+  const g = geometry.value;
+  const w = `${g.width}px`;
+  if (ctx.direction.value === 'rtl') return { left: undefined, right: `${g.left}px`, width: w };
+  return { left: `${g.left}px`, right: undefined, width: w };
+});
+</script>
+
+<template>
+  <Primitive
+    v-if="active"
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    data-waveform-selection-preview=""
+    :style="{ position: 'absolute', top: '0', bottom: '0', ...positionStyle }"
+  >
+    <slot
+      :left="geometry.left"
+      :width="geometry.width"
+      :start="geometry.start"
+      :end="geometry.end"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/__test__/Waveform.test.ts b/vue/primitives/src/canvas/waveform/__test__/Waveform.test.ts
new file mode 100644
index 0000000..238c008
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/__test__/Waveform.test.ts
@@ -0,0 +1,298 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { WaveformRegionData } from '../utils';
+import {
+  WaveformBars,
+  WaveformCursor,
+  WaveformEmpty,
+  WaveformRegion,
+  WaveformRegionHandle,
+  WaveformRoot,
+} from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function makePeaks(n: number): number[] {
+  return Array.from({ length: n }, (_, i) => Math.sin((i / n) * Math.PI * 8));
+}
+
+const ROOT_STYLE = 'position: relative; width: 300px; height: 60px; display: block;';
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false }));
+}
+
+// Wait for the ResizeObserver-backed width to settle.
+async function settle(): Promise<void> {
+  await nextTick();
+  await new Promise(r => requestAnimationFrame(() => r(null)));
+  await nextTick();
+}
+
+interface RootOpts {
+  peaks?: number[];
+  duration?: number;
+  currentTime?: number;
+  regions?: WaveformRegionData[];
+  createRegionOnDrag?: boolean;
+  disabled?: boolean;
+  step?: number;
+}
+
+function mountRoot(opts: RootOpts = {}, children?: (props: any) => any) {
+  const currentTime = ref(opts.currentTime ?? 0);
+  const regions = ref<WaveformRegionData[]>(opts.regions ?? []);
+  const events = {
+    seekCommit: [] as number[],
+    regionCreate: [] as WaveformRegionData[],
+    regionUpdate: [] as WaveformRegionData[],
+    regionRemove: [] as string[],
+  };
+  const Harness = defineComponent({
+    setup() {
+      return () => h(WaveformRoot, {
+        peaks: opts.peaks ?? makePeaks(200),
+        peaksRange: '-1..1',
+        duration: opts.duration ?? 100,
+        currentTime: currentTime.value,
+        'onUpdate:currentTime': (v: number) => { currentTime.value = v; },
+        regions: regions.value,
+        'onUpdate:regions': (v: WaveformRegionData[]) => { regions.value = v; },
+        createRegionOnDrag: opts.createRegionOnDrag,
+        disabled: opts.disabled,
+        step: opts.step,
+        style: ROOT_STYLE,
+        onSeekCommit: (t: number) => events.seekCommit.push(t),
+        onRegionCreate: (r: WaveformRegionData) => events.regionCreate.push(r),
+        onRegionUpdate: (r: WaveformRegionData) => events.regionUpdate.push(r),
+        onRegionRemove: (id: string) => events.regionRemove.push(id),
+      }, {
+        default: (slotProps: any) => children
+          ? children(slotProps)
+          : [
+              h(WaveformBars),
+              h(WaveformCursor, { 'aria-label': 'Playback position' }),
+            ],
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, currentTime, regions, events };
+}
+
+describe('Waveform — cursor', () => {
+  it('renders the cursor as role="slider" with aria-value* attrs', async () => {
+    mountRoot({ duration: 100, currentTime: 25 });
+    await settle();
+    const cursor = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(cursor).toBeTruthy();
+    expect(cursor.getAttribute('aria-valuemin')).toBe('0');
+    expect(cursor.getAttribute('aria-valuemax')).toBe('100');
+    expect(cursor.getAttribute('aria-valuenow')).toBe('25');
+    expect(cursor.getAttribute('aria-orientation')).toBe('horizontal');
+    expect(cursor.getAttribute('aria-label')).toBe('Playback position');
+    expect(cursor.tabIndex).toBe(0);
+  });
+
+  it('Arrow Right/Left scrub by step seconds', async () => {
+    const { currentTime } = mountRoot({ duration: 100, currentTime: 50, step: 5 });
+    await settle();
+    const cursor = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(cursor, 'ArrowRight');
+    await nextTick();
+    expect(currentTime.value).toBe(55);
+    keydown(cursor, 'ArrowLeft');
+    keydown(cursor, 'ArrowLeft');
+    await nextTick();
+    expect(currentTime.value).toBe(45);
+  });
+
+  it('Home/End seek to 0 / duration', async () => {
+    const { currentTime } = mountRoot({ duration: 100, currentTime: 30, step: 1 });
+    await settle();
+    const cursor = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(cursor, 'End');
+    await nextTick();
+    expect(currentTime.value).toBe(100);
+    keydown(cursor, 'Home');
+    await nextTick();
+    expect(currentTime.value).toBe(0);
+  });
+
+  it('clamps seeks to [0, duration] (no NaN, no overflow)', async () => {
+    const { currentTime } = mountRoot({ duration: 10, currentTime: 9, step: 5 });
+    await settle();
+    const cursor = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(cursor, 'ArrowRight');
+    keydown(cursor, 'ArrowRight');
+    await nextTick();
+    expect(currentTime.value).toBe(10);
+    expect(Number.isNaN(currentTime.value)).toBe(false);
+  });
+
+  it('is positioned via the projection (left grows with time)', async () => {
+    const { currentTime, wrapper } = mountRoot({ duration: 100, currentTime: 0, step: 10 });
+    await settle();
+    const cursor = document.querySelector<HTMLElement>('[role="slider"]')!;
+    const at0 = cursor.style.left;
+    currentTime.value = 50;
+    await wrapper.setProps({});
+    await nextTick();
+    const at50 = cursor.style.left;
+    expect(at0).toBe('0px');
+    expect(Number.parseFloat(at50)).toBeGreaterThan(0);
+  });
+});
+
+describe('Waveform — bars', () => {
+  it('resamples to the expected bar count for the width / barWidth / barGap', async () => {
+    // width 300, barWidth 2, barGap 1 → 100 bars regardless of peaks length.
+    mountRoot({ peaks: makePeaks(777), duration: 100 });
+    await settle();
+    const bars = document.querySelectorAll('[data-waveform-bar]');
+    expect(bars.length).toBe(100);
+  });
+
+  it('renders nothing meaningful when peaks are empty', async () => {
+    mountRoot({ peaks: [], duration: 100 });
+    await settle();
+    const bars = document.querySelectorAll('[data-waveform-bar]');
+    expect(bars.length).toBe(0);
+  });
+});
+
+describe('Waveform — empty state', () => {
+  it('sets data-empty on the root when duration is 0', async () => {
+    mountRoot({ duration: 0 }, () => [h(WaveformEmpty, null, { default: () => 'No audio' })]);
+    await settle();
+    const root = document.querySelector<HTMLElement>('[data-waveform-root]')!;
+    expect(root.hasAttribute('data-empty')).toBe(true);
+    expect(document.querySelector('[data-waveform-empty]')).toBeTruthy();
+  });
+
+  it('no data-empty when there is audio', async () => {
+    mountRoot({ duration: 100, peaks: makePeaks(100) });
+    await settle();
+    const root = document.querySelector<HTMLElement>('[data-waveform-root]')!;
+    expect(root.hasAttribute('data-empty')).toBe(false);
+  });
+
+  it('pins the cursor at 0 with no NaN when duration is 0', async () => {
+    mountRoot({ duration: 0 });
+    await settle();
+    const cursor = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(cursor.getAttribute('aria-valuenow')).toBe('0');
+    expect(cursor.style.left).toBe('0px');
+  });
+});
+
+describe('Waveform — regions', () => {
+  function mountWithRegion(region: WaveformRegionData, opts: RootOpts = {}) {
+    return mountRoot({ ...opts, regions: [region] }, () => [
+      h(WaveformBars),
+      h(WaveformRegion, { regionId: region.id }, {
+        default: () => [
+          h(WaveformRegionHandle, { edge: 'start' }),
+          h(WaveformRegionHandle, { edge: 'end' }),
+        ],
+      }),
+    ]);
+  }
+
+  it('renders the region as role="group" with formatted aria-label', async () => {
+    mountWithRegion({ id: 'r1', start: 20, end: 40, label: 'Intro' });
+    await settle();
+    const group = document.querySelector<HTMLElement>('[role="group"]')!;
+    expect(group).toBeTruthy();
+    expect(group.getAttribute('aria-label')).toContain('Intro');
+  });
+
+  it('renders two handles as role="slider" (Region start / Region end)', async () => {
+    mountWithRegion({ id: 'r1', start: 20, end: 40 });
+    await settle();
+    const handles = document.querySelectorAll<HTMLElement>('[role="group"] [role="slider"]');
+    expect(handles).toHaveLength(2);
+    expect(handles[0]!.getAttribute('aria-label')).toBe('Region start');
+    expect(handles[1]!.getAttribute('aria-label')).toBe('Region end');
+    expect(handles[0]!.getAttribute('aria-valuenow')).toBe('20');
+    expect(handles[1]!.getAttribute('aria-valuenow')).toBe('40');
+  });
+
+  it('keyboard trims the start handle by step', async () => {
+    const { regions } = mountWithRegion({ id: 'r1', start: 20, end: 40 }, { step: 5 });
+    await settle();
+    const startHandle = document.querySelector<HTMLElement>('[role="slider"][data-edge="start"]')!;
+    keydown(startHandle, 'ArrowRight');
+    await nextTick();
+    expect(regions.value[0]!.start).toBe(25);
+  });
+
+  it('Home moves the start handle to 0; End moves end to duration', async () => {
+    const { regions } = mountWithRegion({ id: 'r1', start: 20, end: 40 }, { duration: 100, step: 1 });
+    await settle();
+    const startHandle = document.querySelector<HTMLElement>('[data-edge="start"]')!;
+    const endHandle = document.querySelector<HTMLElement>('[data-edge="end"]')!;
+    keydown(startHandle, 'Home');
+    await nextTick();
+    expect(regions.value[0]!.start).toBe(0);
+    keydown(endHandle, 'End');
+    await nextTick();
+    expect(regions.value[0]!.end).toBe(100);
+  });
+
+  it('Delete on the region removes it and emits regionRemove', async () => {
+    const { regions, events } = mountWithRegion({ id: 'r1', start: 20, end: 40 });
+    await settle();
+    const group = document.querySelector<HTMLElement>('[role="group"]')!;
+    keydown(group, 'Delete');
+    await nextTick();
+    expect(regions.value).toHaveLength(0);
+    expect(events.regionRemove).toContain('r1');
+  });
+});
+
+describe('Waveform — disabled', () => {
+  it('blocks keyboard seeks and sets aria/data-disabled', async () => {
+    const { currentTime } = mountRoot({ duration: 100, currentTime: 50, step: 5, disabled: true });
+    await settle();
+    const cursor = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(cursor.tabIndex).toBe(-1);
+    expect(cursor.getAttribute('aria-disabled')).toBe('true');
+    keydown(cursor, 'ArrowRight');
+    await nextTick();
+    expect(currentTime.value).toBe(50);
+    const root = document.querySelector<HTMLElement>('[data-waveform-root]')!;
+    expect(root.hasAttribute('data-disabled')).toBe(true);
+  });
+});
+
+describe('Waveform — createRegionOnDrag', () => {
+  it('emits a new region when a marquee drag commits', async () => {
+    const { regions, events } = mountRoot({ duration: 100, createRegionOnDrag: true }, () => [h(WaveformBars)]);
+    await settle();
+    const root = document.querySelector<HTMLElement>('[data-waveform-root]')!;
+    const rect = root.getBoundingClientRect();
+    const id = 1;
+    const opts = (x: number) => ({ pointerId: id, clientX: rect.left + x, clientY: rect.top + 10, button: 0, bubbles: true, cancelable: true });
+    root.dispatchEvent(new PointerEvent('pointerdown', opts(30)));
+    root.dispatchEvent(new PointerEvent('pointermove', opts(150)));
+    await new Promise(r => requestAnimationFrame(() => r(null)));
+    root.dispatchEvent(new PointerEvent('pointerup', opts(150)));
+    await nextTick();
+    expect(events.regionCreate.length).toBeGreaterThan(0);
+    expect(regions.value.length).toBe(1);
+    expect(regions.value[0]!.end).toBeGreaterThan(regions.value[0]!.start);
+  });
+});
diff --git a/vue/primitives/src/canvas/waveform/__test__/utils.test.ts b/vue/primitives/src/canvas/waveform/__test__/utils.test.ts
new file mode 100644
index 0000000..4050759
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/__test__/utils.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import { buildBars, buildPathPoints, countBars, resamplePeaks } from '../utils';
+
+describe('countBars', () => {
+  it('counts bars by pitch (barWidth + barGap), no trailing gap', () => {
+    // pitch = 2 + 1 = 3; (300 + 1) / 3 = 100.33 → 100
+    expect(countBars(300, 2, 1)).toBe(100);
+    // pitch = 4 + 2 = 6; (120 + 2) / 6 = 20.33 → 20
+    expect(countBars(120, 4, 2)).toBe(20);
+    // no gap: pitch = barWidth
+    expect(countBars(100, 2, 0)).toBe(50);
+  });
+
+  it('returns 0 for degenerate widths (no divide-by-zero)', () => {
+    expect(countBars(0, 2, 1)).toBe(0);
+    expect(countBars(-10, 2, 1)).toBe(0);
+  });
+
+  it('treats non-positive barWidth as 1px and non-positive gap as 0', () => {
+    expect(countBars(10, 0, 0)).toBe(10);
+    expect(countBars(10, -5, -5)).toBe(10);
+  });
+});
+
+describe('resamplePeaks', () => {
+  it('produces exactly bucketCount values regardless of peaks length', () => {
+    expect(resamplePeaks([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 4, false)).toHaveLength(4);
+    expect(resamplePeaks([0.5], 8, false)).toHaveLength(8);
+    expect(resamplePeaks(Array.from({ length: 1000 }, () => 0.3), 37, false)).toHaveLength(37);
+  });
+
+  it('takes the MAX magnitude within each bucket slice', () => {
+    // 8 samples → 2 buckets → slice [0,4) and [4,8)
+    const peaks = [0.1, 0.9, 0.2, 0.3, 0.4, 0.5, 0.1, 0.2];
+    expect(resamplePeaks(peaks, 2, false)).toEqual([0.9, 0.5]);
+  });
+
+  it('rectifies signed peaks via absolute value', () => {
+    const peaks = [-0.8, 0.2, -0.1, 0.3];
+    // signed → |−0.8| = 0.8 max in first slice
+    expect(resamplePeaks(peaks, 2, true)).toEqual([0.8, 0.3]);
+  });
+
+  it('passes through 0..1 peaks unchanged (clamped to 1)', () => {
+    expect(resamplePeaks([0.4, 1.5, 0.2, 0.6], 2, false)).toEqual([1, 0.6]);
+  });
+
+  it('resamples a window slice by ratio', () => {
+    const peaks = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8];
+    // window [4, 8) → 2 buckets → [0.5, 0.6] and [0.7, 0.8]
+    expect(resamplePeaks(peaks, 2, false, 4, 8)).toEqual([0.6, 0.8]);
+  });
+
+  it('returns [] for empty peaks or non-positive bucket count', () => {
+    expect(resamplePeaks([], 4, false)).toEqual([]);
+    expect(resamplePeaks([1, 2, 3], 0, false)).toEqual([]);
+  });
+
+  it('yields flat zero buckets for a degenerate window (no NaN)', () => {
+    const out = resamplePeaks([1, 2, 3], 3, false, 2, 2);
+    expect(out).toEqual([0, 0, 0]);
+    expect(out.some(Number.isNaN)).toBe(false);
+  });
+
+  it('upsamples (more buckets than samples) without NaN', () => {
+    const out = resamplePeaks([0.2, 0.8], 6, false);
+    expect(out).toHaveLength(6);
+    expect(out.some(Number.isNaN)).toBe(false);
+    // every bucket samples at least one source value
+    expect(out.every(v => v >= 0)).toBe(true);
+  });
+});
+
+describe('buildBars', () => {
+  it('returns one bar per fitted bucket with correct width', () => {
+    const peaks = Array.from({ length: 50 }, (_, i) => i / 50);
+    const bars = buildBars(peaks, 300, 2, 1, false);
+    expect(bars).toHaveLength(100); // countBars(300,2,1)
+    expect(bars.every(b => b.width === 2)).toBe(true);
+  });
+
+  it('respects an arbitrary peaks length (more or fewer than bars)', () => {
+    expect(buildBars([0.5], 100, 2, 0, false)).toHaveLength(50);
+    expect(buildBars(Array.from({ length: 9999 }, () => 0.5), 100, 2, 0, false)).toHaveLength(50);
+  });
+
+  it('places bars on a pitch and centers leftover space', () => {
+    // width 10, barWidth 2, gap 0 → 5 bars at x = 0,2,4,6,8 (no leftover)
+    const bars = buildBars([1, 1, 1, 1, 1], 10, 2, 0, false);
+    expect(bars.map(b => b.x)).toEqual([0, 2, 4, 6, 8]);
+  });
+
+  it('returns [] when width is 0 (renders nothing)', () => {
+    expect(buildBars([0.5, 0.6], 0, 2, 1, false)).toEqual([]);
+  });
+
+  it('heights are 0..1 fractions', () => {
+    const bars = buildBars([0.25, 1, 0.5], 6, 2, 0, false);
+    expect(bars.every(b => b.height >= 0 && b.height <= 1)).toBe(true);
+  });
+});
+
+describe('buildPathPoints', () => {
+  it('returns `samples` points spanning the width', () => {
+    const pts = buildPathPoints([0, 0.5, 1, 0.5], 100, 40, 4, false);
+    expect(pts).toHaveLength(4);
+    expect(pts[0]!.x).toBe(0);
+    expect(pts[3]!.x).toBeCloseTo(100);
+  });
+
+  it('maps magnitude onto the vertical center', () => {
+    // height 40 → mid 20; magnitude 1 → y = 0 (top), magnitude 0 → y = 20 (mid)
+    const pts = buildPathPoints([1, 0], 100, 40, 2, false);
+    expect(pts[0]!.y).toBeCloseTo(0);
+    expect(pts[1]!.y).toBeCloseTo(20);
+  });
+
+  it('returns [] for degenerate geometry', () => {
+    expect(buildPathPoints([0.5], 0, 40, 8, false)).toEqual([]);
+    expect(buildPathPoints([0.5], 100, 0, 8, false)).toEqual([]);
+    expect(buildPathPoints([0.5], 100, 40, 0, false)).toEqual([]);
+  });
+});
diff --git a/vue/primitives/src/canvas/waveform/context.ts b/vue/primitives/src/canvas/waveform/context.ts
new file mode 100644
index 0000000..90ad54f
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/context.ts
@@ -0,0 +1,108 @@
+import type { ComputedRef, Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { WaveformBar, WaveformRegionData } from './utils';
+
+/** Writing direction for the waveform body. */
+export type WaveformDirection = 'ltr' | 'rtl';
+
+/** Formats a time (seconds) into a human string for `aria-valuetext`. */
+export type WaveformTimeFormatter = (seconds: number) => string;
+
+/**
+ * The value↔pixel projection exposed to descendants: `scale` maps a time (s) to
+ * a pixel x within the body, `invert` maps a pixel x back to a time. Mirrors the
+ * subset of {@link import('../../internal/scale').useScale} that parts consume.
+ */
+export interface WaveformProjection {
+  /** Project a time (seconds) to a pixel x within the body. */
+  scale: (seconds: number) => number;
+  /** Invert a pixel x within the body back to a time (seconds). */
+  invert: (px: number) => number;
+}
+
+/**
+ * Context shared between `WaveformRoot` and its descendants.
+ *
+ * Scalar props are plain `Ref<T>` (built with `toRef(() => prop)` in the root —
+ * a `GetterRefImpl` that is reactive without allocating an effect). `buckets`
+ * and `projection` are derived and read on every render of the body.
+ */
+export interface WaveformContext {
+  /** Source per-sample amplitudes (passthrough of the `peaks` prop). */
+  peaks: Ref<ArrayLike<number>>;
+  /** Whether `peaks` are signed (`'-1..1'`) and must be rectified. */
+  signed: Ref<boolean>;
+  /** Total media duration, in seconds. */
+  duration: Ref<number>;
+  /** Current playback position (seconds), clamped to `[0, duration]`. */
+  currentTime: Ref<number>;
+  /** The current set of regions. */
+  regions: Ref<WaveformRegionData[]>;
+  /** Measured body width, in pixels. */
+  width: Ref<number>;
+  /** Effective writing direction. */
+  direction: Ref<WaveformDirection>;
+  /** Whether interaction is disabled. */
+  disabled: Ref<boolean>;
+  /** Keyboard step for the cursor / region edges, in seconds. */
+  step: Ref<number>;
+  /** Large keyboard step (Shift+Arrow), in seconds. */
+  largeStep: Ref<number>;
+  /** Default formatter for cursor `aria-valuetext`. */
+  timeFormatter: Ref<WaveformTimeFormatter>;
+
+  /** The visible time window `[start, end]` (seconds). */
+  window: ComputedRef<readonly [number, number]>;
+  /** Time↔pixel projection over the visible window → `[0, width]`. */
+  projection: WaveformProjection;
+  /** Computed bar geometry, resampled by ratio for the current width. */
+  buckets: ComputedRef<WaveformBar[]>;
+  /** `true` when duration is 0 or there are no peaks. */
+  isEmpty: ComputedRef<boolean>;
+  /** `true` while peaks are loading (async fetch). */
+  loading: Ref<boolean>;
+  /** The transient create-region marquee (only meaningful while `active`). */
+  preview: ComputedRef<{ active: boolean; start: number; end: number }>;
+
+  /** Seek to a time (seconds); clamps to bounds and emits a commit. */
+  seek: (seconds: number, commit?: boolean) => void;
+  /** Append a new region (id auto-generated when omitted); returns its id. */
+  addRegion: (region: Partial<WaveformRegionData> & { start: number; end: number }) => string;
+  /** Patch an existing region by id (start/end re-ordered & clamped). */
+  updateRegion: (id: string, patch: Partial<Omit<WaveformRegionData, 'id'>>, commit?: boolean) => void;
+  /** Remove a region by id. */
+  removeRegion: (id: string) => void;
+
+  /** Register the cursor element so the root can drive focus/keyboard. */
+  registerCursor: (el: HTMLElement | null) => void;
+}
+
+const ctx = useContextFactory<WaveformContext>('WaveformContext');
+
+export const provideWaveformContext = ctx.provide;
+export const useWaveformContext = ctx.inject;
+
+/** Which edge of a region a `WaveformRegionHandle` trims. */
+export type WaveformRegionEdge = 'start' | 'end';
+
+/**
+ * Context provided by `WaveformRegion` to its two `WaveformRegionHandle`
+ * children so each handle knows the region's id and current bounds and can trim
+ * the correct edge.
+ */
+export interface WaveformRegionContext {
+  /** The region's stable id. */
+  id: Ref<string>;
+  /** Live region bounds `{ start, end }` in seconds. */
+  start: Ref<number>;
+  end: Ref<number>;
+  /** Whether this region is the selected/active one. */
+  selected: Ref<boolean>;
+  /** Trim one edge to `seconds`; the root re-orders & clamps. */
+  trim: (edge: WaveformRegionEdge, seconds: number, commit?: boolean) => void;
+}
+
+const regionCtx = useContextFactory<WaveformRegionContext>('WaveformRegionContext');
+
+export const provideWaveformRegionContext = regionCtx.provide;
+export const useWaveformRegionContext = regionCtx.inject;
diff --git a/vue/primitives/src/canvas/waveform/demo-audio.ts b/vue/primitives/src/canvas/waveform/demo-audio.ts
new file mode 100644
index 0000000..f556a4b
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/demo-audio.ts
@@ -0,0 +1,60 @@
+// AUTO-GENERATED demo data — real peaks of the "Healing 01" track (sousound.com),
+// decoded offline (the source has no CORS, so peaks can't be computed at runtime;
+// the audio still plays cross-origin via a plain <audio> element). 800 peaks,
+// magnitude 0..1, normalized. Duration 45.01s.
+/** Pre-computed, normalized waveform peaks (0..1 magnitude) for the demo track. */
+export const HEALING_PEAKS: number[] = [
+  0.002, 0.053, 0.42, 0.497, 0.614, 0.502, 0.489, 0.46, 0.358, 0.31, 0.335, 0.352, 0.337, 0.314, 0.318, 0.311, 0.262,
+  0.285, 0.265, 0.348, 0.361, 0.263, 0.256, 0.268, 0.25, 0.464, 0.452, 0.371, 0.435, 0.332, 0.517, 0.448, 0.342, 0.35,
+  0.365, 0.447, 0.441, 0.374, 0.398, 0.327, 0.476, 0.484, 0.431, 0.458, 0.569, 0.305, 0.691, 0.562, 0.489, 0.568, 0.523,
+  0.47, 0.41, 0.385, 0.442, 0.412, 0.466, 0.471, 0.421, 0.418, 0.378, 0.576, 0.33, 0.363, 0.397, 0.351, 0.326, 0.455,
+  0.325, 0.315, 0.298, 0.3, 0.296, 0.356, 0.388, 0.259, 0.279, 0.251, 0.226, 0.995, 0.996, 0.975, 0.912, 0.858, 0.839,
+  0.836, 0.876, 0.945, 0.818, 0.898, 0.885, 0.801, 0.807, 0.825, 0.872, 0.763, 0.828, 0.707, 0.729, 0.721, 0.834, 0.727,
+  0.744, 0.75, 0.706, 0.738, 0.742, 0.627, 0.627, 0.595, 0.735, 0.621, 0.541, 0.489, 0.527, 0.513, 0.492, 0.567, 0.51,
+  0.476, 0.448, 0.416, 0.553, 0.495, 0.597, 0.529, 0.491, 0.707, 0.576, 0.495, 0.488, 0.544, 0.71, 0.757, 0.57, 0.478,
+  0.517, 0.494, 0.844, 0.7, 0.698, 0.641, 0.663, 0.485, 0.455, 0.493, 0.583, 0.534, 0.57, 0.364, 0.31, 0.519, 0.515,
+  0.568, 0.641, 0.627, 0.578, 0.589, 0.561, 0.62, 0.549, 0.546, 0.486, 0.503, 0.378, 0.36, 0.364, 0.301, 0.858, 0.572,
+  0.646, 0.561, 0.597, 0.759, 0.587, 0.615, 0.768, 0.583, 0.718, 0.567, 0.702, 0.979, 0.941, 0.906, 0.862, 0.822, 0.862,
+  0.734, 0.653, 0.642, 0.609, 0.623, 0.63, 0.648, 0.721, 0.716, 0.602, 0.604, 0.71, 0.789, 0.761, 0.837, 0.802, 0.706,
+  0.694, 0.663, 0.766, 0.692, 0.71, 0.645, 0.579, 0.965, 0.921, 0.765, 0.806, 0.706, 0.885, 0.653, 0.629, 0.722, 0.528,
+  0.482, 0.896, 0.832, 0.752, 0.772, 0.771, 0.615, 0.645, 0.56, 0.665, 0.687, 0.597, 0.563, 0.545, 0.6, 0.589, 0.619,
+  0.823, 0.84, 0.762, 0.61, 0.71, 0.643, 0.532, 0.6, 0.672, 0.707, 0.57, 0.587, 0.464, 0.462, 0.578, 0.512, 0.825, 0.71,
+  0.666, 0.522, 0.659, 0.824, 0.667, 0.825, 0.616, 0.795, 0.51, 0.862, 0.991, 0.959, 0.91, 0.961, 0.875, 0.795, 0.842,
+  0.816, 0.908, 0.849, 0.798, 0.898, 0.915, 0.836, 0.819, 0.739, 0.5, 0.874, 0.831, 0.863, 0.815, 0.856, 0.732, 0.707,
+  0.686, 0.711, 0.692, 0.605, 0.929, 0.832, 0.726, 0.63, 0.551, 0.592, 0.605, 0.687, 0.7, 0.711, 0.638, 0.716, 0.589,
+  0.759, 0.585, 0.599, 0.572, 0.622, 0.99, 0.937, 0.833, 0.859, 0.865, 0.692, 0.77, 0.825, 0.653, 0.672, 0.706, 0.561,
+  0.633, 0.718, 0.636, 0.596, 0.585, 0.478, 0.411, 0.505, 0.434, 0.487, 0.449, 0.362, 0.319, 0.627, 0.952, 0.96, 0.687,
+  0.681, 0.719, 0.676, 0.585, 0.414, 0.639, 0.654, 0.686, 0.525, 0.523, 0.44, 0.95, 0.971, 0.929, 0.852, 0.798, 0.721,
+  0.725, 0.755, 0.753, 0.775, 0.73, 0.716, 0.606, 0.599, 0.616, 0.718, 0.735, 0.722, 0.695, 0.681, 0.669, 0.629, 0.622,
+  0.585, 0.57, 0.547, 0.532, 0.502, 0.469, 0.442, 0.392, 0.391, 0.433, 0.465, 0.452, 0.449, 0.434, 0.395, 0.383, 0.387,
+  0.399, 0.389, 0.387, 0.369, 0.478, 0.343, 0.281, 0.192, 0.065, 0.042, 0.024, 0.02, 0.013, 0.025, 0.024, 0.055, 0.619,
+  0.967, 0.848, 0.785, 0.793, 0.742, 0.754, 0.791, 0.706, 0.742, 0.695, 0.62, 0.933, 0.813, 0.751, 0.706, 0.694, 0.586,
+  0.965, 0.719, 0.844, 0.723, 0.715, 0.672, 0.732, 0.846, 0.803, 0.702, 0.597, 0.716, 0.749, 0.694, 0.901, 0.811, 0.815,
+  0.909, 0.83, 0.631, 0.582, 0.601, 0.607, 0.926, 0.931, 0.917, 0.816, 0.896, 0.931, 0.929, 0.764, 0.716, 0.72, 0.724,
+  0.738, 0.779, 0.816, 0.754, 0.735, 0.717, 0.705, 0.776, 0.651, 0.823, 0.685, 0.63, 0.596, 0.987, 0.78, 0.8, 0.732,
+  0.645, 0.604, 0.67, 0.647, 0.611, 0.592, 0.607, 0.604, 0.652, 0.603, 0.87, 0.818, 0.719, 0.882, 0.877, 0.853, 0.811,
+  0.807, 0.796, 0.753, 0.803, 0.725, 0.708, 0.73, 0.761, 0.991, 0.97, 0.877, 0.811, 0.768, 0.813, 0.729, 0.887, 0.679,
+  0.793, 0.574, 0.766, 0.945, 0.804, 0.775, 0.722, 0.619, 0.687, 0.941, 0.886, 0.863, 0.774, 0.821, 0.602, 0.826, 0.816,
+  0.78, 0.745, 0.759, 0.654, 0.633, 0.663, 0.535, 0.67, 0.801, 0.809, 0.823, 0.757, 0.677, 0.618, 0.555, 0.574, 0.903,
+  0.762, 0.811, 0.82, 0.835, 0.801, 0.9, 0.74, 0.859, 0.706, 0.642, 0.598, 0.727, 0.655, 0.619, 0.891, 0.702, 0.749,
+  0.736, 0.59, 0.576, 0.615, 0.746, 0.873, 0.89, 0.887, 0.826, 0.834, 0.842, 0.822, 0.714, 0.673, 0.712, 0.629, 0.712,
+  0.76, 0.693, 0.663, 0.732, 0.759, 0.707, 0.809, 0.745, 0.557, 0.662, 0.685, 0.596, 0.622, 0.639, 0.503, 0.309, 0.586,
+  0.989, 0.807, 0.891, 0.83, 0.867, 0.847, 0.645, 0.767, 0.868, 0.828, 0.703, 0.569, 0.598, 0.675, 0.898, 0.673, 0.796,
+  0.789, 0.861, 0.888, 0.761, 0.823, 0.653, 0.777, 0.665, 0.759, 0.511, 0.841, 0.698, 0.771, 0.776, 0.69, 0.684, 0.77,
+  0.668, 0.584, 0.661, 0.62, 0.741, 0.648, 0.695, 0.773, 0.668, 0.816, 0.634, 0.894, 0.682, 0.626, 0.634, 0.914, 0.789,
+  0.786, 0.819, 0.867, 0.786, 0.763, 0.735, 0.692, 0.785, 0.649, 0.7, 0.664, 0.768, 0.83, 0.864, 0.637, 0.909, 0.757,
+  0.951, 0.929, 0.792, 0.782, 0.761, 0.757, 0.722, 0.624, 0.624, 0.886, 0.868, 0.762, 0.752, 0.576, 0.809, 0.932, 0.625,
+  0.863, 0.725, 0.544, 0.996, 0.797, 0.746, 0.656, 0.78, 0.84, 0.722, 0.6, 0.747, 0.719, 0.801, 0.729, 0.776, 0.709,
+  0.87, 0.664, 0.97, 0.663, 0.949, 0.866, 0.786, 0.794, 0.926, 0.907, 0.878, 0.85, 0.733, 0.703, 0.831, 0.782, 0.603,
+  0.493, 0.379, 1, 0.66, 0.648, 0.624, 0.652, 0.746, 0.888, 0.894, 0.842, 0.676, 0.589, 0.732, 0.674, 0.565, 0.591,
+  0.541, 0.53, 0.537, 0.469, 0.802, 0.545, 0.5, 0.384, 0.418, 0.786, 0.781, 0.721, 0.81, 0.752, 0.622, 0.59, 0.772,
+  0.709, 0.588, 0.653, 0.65, 0.626, 0.667, 0.689, 0.737, 0.764, 0.695, 0.437, 0.413, 0.577, 0.494, 0.398, 0.331, 0.259,
+  0.244, 0.321, 0.268, 0.231, 0.231, 0.47, 0.694, 0.501, 0.336, 0.584, 0.516, 0.249, 0.291, 0.28, 0.325, 0.227, 0.181,
+  0.191, 0.114, 0.171, 0.162, 0.131, 0.097, 0.109, 0.083, 0.072, 0.051, 0.042, 0.04, 0.022, 0.009, 0.005, 0.003, 0.001,
+];
+
+/** Duration of the demo track in seconds. */
+export const HEALING_DURATION = 45.009;
+
+/** Streamable (cross-origin playable) source — https avoids mixed-content. */
+export const HEALING_SRC = 'https://www.sousound.com/music/healing/healing_01.mp3';
diff --git a/vue/primitives/src/canvas/waveform/demo.vue b/vue/primitives/src/canvas/waveform/demo.vue
new file mode 100644
index 0000000..4b6c580
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/demo.vue
@@ -0,0 +1,261 @@
+<script setup lang="ts">
+import type { WaveformRegionData } from '@robonen/primitives';
+import {
+  WaveformBars,
+  WaveformCursor,
+  WaveformRegion,
+  WaveformRegionHandle,
+  WaveformRoot,
+} from '@robonen/primitives';
+import { computed, onBeforeUnmount, onMounted, ref, useTemplateRef, watch } from 'vue';
+import { HEALING_DURATION, HEALING_PEAKS, HEALING_SRC } from './demo-audio';
+
+// ── Peaks: generated in the browser when possible ───────────────────────────
+// The waveform shape is just the max amplitude per slice of the decoded audio.
+// `generatePeaks` does exactly that in JS — fetch the bytes, decode them with
+// the Web Audio API, and reduce each block to its peak. It works for any
+// CORS-enabled audio URL. THIS track sends no CORS header, so the fetch is
+// blocked and we fall back to peaks decoded offline (bundled in ./demo-audio).
+async function generatePeaks(url: string, count = 800): Promise<{ peaks: number[]; duration: number }> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const bytes = await res.arrayBuffer();
+  const Ctx: typeof AudioContext = window.AudioContext
+    ?? (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext;
+  const ctx = new Ctx();
+  try {
+    const buffer = await ctx.decodeAudioData(bytes);
+    const data = buffer.getChannelData(0); // first channel is enough for a mono shape
+    const block = Math.max(1, Math.floor(data.length / count));
+    const peaks = Array.from<number>({ length: count });
+    let gmax = 0;
+    for (let i = 0; i < count; i++) {
+      let m = 0;
+      const s = i * block;
+      for (let j = 0; j < block; j++) {
+        const v = Math.abs(data[s + j] ?? 0);
+        if (v > m) m = v;
+      }
+      peaks[i] = m;
+      if (m > gmax) gmax = m;
+    }
+    return {
+      peaks: gmax > 0 ? peaks.map(p => p / gmax) : peaks, // normalize to fill height
+      duration: buffer.duration,
+    };
+  }
+  finally {
+    void ctx.close();
+  }
+}
+
+const peaks = ref<readonly number[]>(HEALING_PEAKS); // real peaks, shown instantly
+const duration = ref(HEALING_DURATION);
+const decoding = ref(false);
+const source = ref<'live' | 'bundled'>('bundled');
+
+onMounted(async () => {
+  decoding.value = true;
+  try {
+    const r = await generatePeaks(HEALING_SRC);
+    peaks.value = r.peaks;
+    duration.value = r.duration;
+    source.value = 'live';
+  }
+  catch {
+    source.value = 'bundled'; // CORS/offline → keep the bundled peaks
+  }
+  finally {
+    decoding.value = false;
+  }
+});
+
+// ── Playback: a plain <audio> element (cross-origin playback needs no CORS) ──
+const audio = useTemplateRef<HTMLAudioElement>('audio');
+const currentTime = ref(0);
+const playing = ref(false);
+
+const regions = ref<WaveformRegionData[]>([
+  { id: 'phrase', start: 14, end: 26, label: 'Phrase' },
+]);
+
+// Two-way sync: the audio clock drives the cursor during playback (an rAF loop);
+// a user scrub writes `currentTime` and we seek the audio. `fromAudio` guards
+// the two from fighting.
+let raf = 0;
+let fromAudio = false;
+
+function frame(): void {
+  const el = audio.value;
+  if (!el) return;
+  fromAudio = true;
+  currentTime.value = el.currentTime;
+  fromAudio = false;
+  if (!el.paused && !el.ended) raf = requestAnimationFrame(frame);
+}
+
+watch(currentTime, (t) => {
+  const el = audio.value;
+  if (!el || fromAudio) return;
+  if (Math.abs(el.currentTime - t) > 0.05) el.currentTime = t;
+});
+
+function toggle(): void {
+  const el = audio.value;
+  if (!el) return;
+  if (el.paused) void el.play().catch(() => { /* autoplay blocked / offline */ });
+  else el.pause();
+}
+function rewind(): void {
+  currentTime.value = 0;
+  if (audio.value) audio.value.currentTime = 0;
+}
+function onPlay(): void {
+  playing.value = true;
+  cancelAnimationFrame(raf);
+  raf = requestAnimationFrame(frame);
+}
+function onPause(): void {
+  playing.value = false;
+  cancelAnimationFrame(raf);
+}
+function onEnded(): void {
+  playing.value = false;
+  cancelAnimationFrame(raf);
+  currentTime.value = 0;
+}
+
+onBeforeUnmount(() => {
+  cancelAnimationFrame(raf);
+  audio.value?.pause();
+});
+
+function fmt(seconds: number): string {
+  const s = Math.max(0, seconds);
+  const m = Math.floor(s / 60);
+  const r = Math.floor(s % 60);
+  return `${m}:${r.toString().padStart(2, '0')}`;
+}
+
+const progress = computed(() => Math.round((currentTime.value / duration.value) * 100));
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-lg space-y-4 bg-bg p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <div class="min-w-0">
+        <span class="font-medium">Healing 01</span>
+        <span class="ml-2 font-mono text-[11px] text-fg-subtle">
+          {{ decoding ? 'decoding…' : source === 'live' ? 'peaks decoded in-browser' : 'bundled peaks (no CORS)' }}
+        </span>
+      </div>
+      <span class="font-mono tabular-nums text-fg-muted">
+        {{ fmt(currentTime) }} / {{ fmt(duration) }}
+      </span>
+    </div>
+
+    <!-- The Root measures its own width; the fixed height gives the bars (sized
+         as a % of their container) and the absolute cursor something to fill. -->
+    <WaveformRoot
+      v-model:current-time="currentTime"
+      v-model:regions="regions"
+      :peaks="peaks"
+      peaks-range="0..1"
+      :duration="duration"
+      :bar-width="2"
+      :bar-gap="1"
+      class="relative h-28 w-full cursor-pointer touch-none select-none overflow-hidden rounded-card border border-border bg-bg-inset"
+    >
+      <!-- Amplitude bars. WaveformBars hardcodes `position: relative`, so it must
+           be SIZED (size-full) rather than positioned `absolute inset-0` — an
+           inline style can't be overridden by a class, and an auto-height
+           container would collapse its percentage-height bars to 0. -->
+      <WaveformBars
+        class="pointer-events-none size-full [&_[data-waveform-bar]]:rounded-full [&_[data-waveform-bar]]:bg-fg-subtle"
+      />
+
+      <!-- Played-portion tint, over the bars, clipped to the cursor position. -->
+      <div
+        class="pointer-events-none absolute inset-y-0 left-0 z-0 bg-accent/15"
+        :style="{ width: `${progress}%` }"
+      />
+
+      <!-- Region: a labelled selection with two draggable trim handles. -->
+      <WaveformRegion
+        v-for="r in regions"
+        :key="r.id"
+        v-slot="{ start, end }"
+        :region-id="r.id"
+        class="z-10 border-x border-accent bg-accent/15 outline-none transition-colors focus-visible:bg-accent/25 data-[selected]:bg-accent/25"
+      >
+        <span class="absolute -top-px left-1 truncate text-[10px] font-medium text-accent-text/90">
+          {{ r.label }}
+        </span>
+        <WaveformRegionHandle
+          edge="start"
+          aria-label="Region start"
+          class="absolute inset-y-0 left-0 z-20 w-2 -translate-x-1/2 cursor-ew-resize outline-none before:absolute before:inset-y-2 before:left-1/2 before:w-0.5 before:-translate-x-1/2 before:rounded-full before:bg-accent focus-visible:before:ring-2 focus-visible:before:ring-ring"
+        />
+        <WaveformRegionHandle
+          edge="end"
+          aria-label="Region end"
+          class="absolute inset-y-0 right-0 z-20 w-2 translate-x-1/2 cursor-ew-resize outline-none before:absolute before:inset-y-2 before:left-1/2 before:w-0.5 before:-translate-x-1/2 before:rounded-full before:bg-accent focus-visible:before:ring-2 focus-visible:before:ring-ring"
+        />
+        <span class="sr-only">{{ fmt(start) }} to {{ fmt(end) }}</span>
+      </WaveformRegion>
+
+      <!-- Playback cursor (draggable + keyboard seekable). -->
+      <WaveformCursor
+        aria-label="Playback position"
+        class="absolute inset-y-0 z-30 w-px -translate-x-1/2 cursor-ew-resize bg-accent outline-none after:absolute after:left-1/2 after:top-0 after:h-3 after:w-3 after:-translate-x-1/2 after:rounded-full after:border-2 after:border-accent after:bg-bg after:shadow-sm focus-visible:after:ring-2 focus-visible:after:ring-ring"
+      />
+    </WaveformRoot>
+
+    <!-- Transport row. -->
+    <div class="flex items-center gap-3 text-sm">
+      <button
+        type="button"
+        :aria-label="playing ? 'Pause' : 'Play'"
+        class="grid size-9 shrink-0 place-items-center rounded-full bg-accent text-accent-fg outline-none transition hover:opacity-90 focus-visible:ring-2 focus-visible:ring-ring"
+        @click="toggle"
+      >
+        <svg v-if="playing" width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+          <rect x="6" y="5" width="4" height="14" rx="1" /><rect x="14" y="5" width="4" height="14" rx="1" />
+        </svg>
+        <svg v-else width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+          <path d="M8 5.14v13.72a1 1 0 0 0 1.5.86l11-6.86a1 1 0 0 0 0-1.72l-11-6.86A1 1 0 0 0 8 5.14Z" />
+        </svg>
+      </button>
+
+      <button
+        type="button"
+        class="rounded-md bg-bg-inset px-3 py-1.5 text-xs font-medium text-fg-muted outline-none transition hover:text-fg focus-visible:ring-2 focus-visible:ring-ring"
+        @click="rewind"
+      >
+        Rewind
+      </button>
+
+      <div class="relative h-1.5 flex-1 overflow-hidden rounded-full bg-bg-inset">
+        <div class="absolute inset-y-0 left-0 rounded-full bg-accent" :style="{ width: `${progress}%` }" />
+      </div>
+      <span class="w-10 text-right font-mono text-xs tabular-nums text-fg-muted">{{ progress }}%</span>
+    </div>
+
+    <p class="text-xs text-fg-subtle">
+      Peaks are generated in-browser (Web Audio decode) when the source allows
+      CORS; this track doesn't, so it falls back to peaks decoded offline. The
+      audio streams from sousound.com on play — click or drag to scrub.
+    </p>
+
+    <!-- Plain <audio> (no `crossorigin`): cross-origin playback needs no CORS,
+         and `preload="none"` keeps the 1.4 MB track off the wire until play. -->
+    <audio
+      ref="audio"
+      :src="HEALING_SRC"
+      preload="none"
+      @play="onPlay"
+      @pause="onPause"
+      @ended="onEnded"
+    />
+  </div>
+</template>
diff --git a/vue/primitives/src/canvas/waveform/index.ts b/vue/primitives/src/canvas/waveform/index.ts
new file mode 100644
index 0000000..50c2dca
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/index.ts
@@ -0,0 +1,31 @@
+export { default as WaveformRoot } from './WaveformRoot.vue';
+export { default as WaveformBars } from './WaveformBars.vue';
+export { default as WaveformCursor } from './WaveformCursor.vue';
+export { default as WaveformEmpty } from './WaveformEmpty.vue';
+export { default as WaveformPath } from './WaveformPath.vue';
+export { default as WaveformRegion } from './WaveformRegion.vue';
+export { default as WaveformRegionHandle } from './WaveformRegionHandle.vue';
+export { default as WaveformSelectionPreview } from './WaveformSelectionPreview.vue';
+
+export type {
+  WaveformDirection,
+  WaveformProjection,
+  WaveformRegionContext,
+  WaveformRegionEdge,
+  WaveformTimeFormatter,
+} from './context';
+export type {
+  WaveformBar,
+  WaveformMode,
+  WaveformPeaksRange,
+  WaveformRegionData,
+} from './utils';
+
+export type { WaveformRootEmits, WaveformRootProps } from './WaveformRoot.vue';
+export type { WaveformBarsProps } from './WaveformBars.vue';
+export type { WaveformCursorProps } from './WaveformCursor.vue';
+export type { WaveformEmptyProps } from './WaveformEmpty.vue';
+export type { WaveformPathProps } from './WaveformPath.vue';
+export type { WaveformRegionProps } from './WaveformRegion.vue';
+export type { WaveformRegionHandleProps } from './WaveformRegionHandle.vue';
+export type { WaveformSelectionPreviewProps } from './WaveformSelectionPreview.vue';
diff --git a/vue/primitives/src/canvas/waveform/utils.ts b/vue/primitives/src/canvas/waveform/utils.ts
new file mode 100644
index 0000000..bf2c046
--- /dev/null
+++ b/vue/primitives/src/canvas/waveform/utils.ts
@@ -0,0 +1,183 @@
+import type { Point } from '../../internal/utils/geometry';
+
+/** The amplitude range the supplied `peaks` are normalized to. */
+export type WaveformPeaksRange = '0..1' | '-1..1';
+
+/** Render strategy for the waveform body. */
+export type WaveformMode = 'bars' | 'path';
+
+/** A single audio region (selection) owned by the root. */
+export interface WaveformRegionData {
+  /** Stable identity used for `v-for` keys and update/remove targeting. */
+  id: string;
+  /** Region start, in seconds. */
+  start: number;
+  /** Region end, in seconds. */
+  end: number;
+  /** Optional human-readable label (folded into the group's `aria-label`). */
+  label?: string;
+  /** Optional CSS color the consumer may bind to the region surface. */
+  color?: string;
+}
+
+/**
+ * Geometry of one rendered bar: its `x` offset (px, left edge), drawn `width`
+ * (px), and `height` as a `0..1` fraction of the available vertical space (the
+ * consumer maps this onto its own pixel height).
+ */
+export interface WaveformBar {
+  /** Left edge of the bar, in pixels from the start of the body. */
+  x: number;
+  /** Drawn width of the bar, in pixels (`barWidth`). */
+  width: number;
+  /** Peak magnitude for this bar as a `0..1` fraction of full height. */
+  height: number;
+}
+
+/**
+ * Number of bars that fit across `width` px given `barWidth` + `barGap`.
+ *
+ * The trailing bar needs no gap, so the count is
+ * `floor((width + barGap) / (barWidth + barGap))`. Guards every degenerate
+ * input (non-positive width, non-positive pitch) by returning `0` — callers
+ * then render nothing rather than dividing by zero.
+ */
+export function countBars(width: number, barWidth: number, barGap: number): number {
+  if (width <= 0) return 0;
+  const w = barWidth > 0 ? barWidth : 1;
+  const gap = barGap > 0 ? barGap : 0;
+  const pitch = w + gap;
+  if (pitch <= 0) return 0;
+  const n = Math.floor((width + gap) / pitch);
+  return n > 0 ? n : 0;
+}
+
+/**
+ * Read amplitude `i` of `peaks` as a non-negative `0..1` magnitude.
+ *
+ * `peaksRange` selects the source convention: `'-1..1'` (the default — signed
+ * PCM-style samples) takes the absolute value; `'0..1'` (pre-rectified
+ * magnitudes) is passed through. The result is always clamped to `0..1`.
+ */
+function magnitudeAt(peaks: ArrayLike<number>, i: number, signed: boolean): number {
+  const v = peaks[i] ?? 0;
+  const m = signed ? (v < 0 ? -v : v) : v;
+  if (m <= 0) return 0;
+  return m > 1 ? 1 : m;
+}
+
+/**
+ * Resample `peaks` (any length) into `bucketCount` peak magnitudes by RATIO.
+ *
+ * The window `[sampleStart, sampleEnd)` of the source is divided into
+ * `bucketCount` equal slices; each bucket takes the **max** magnitude of the
+ * samples that land in its slice (max, not mean — peak meters must not wash out
+ * transients). `peaks.length` is decoupled from the bar count: the slice width
+ * is `(sampleEnd - sampleStart) / bucketCount`, never assumed to be 1.
+ *
+ * Empty input, a zero-or-negative bucket count, or a degenerate window all
+ * yield an empty array (no divide-by-zero).
+ *
+ * @param peaks Source per-sample amplitudes.
+ * @param bucketCount How many output buckets (bars) to produce.
+ * @param signed Whether `peaks` are signed (`'-1..1'`) and must be rectified.
+ * @param sampleStart First source index of the visible window (inclusive). @default 0
+ * @param sampleEnd Last source index of the visible window (exclusive). @default peaks.length
+ */
+export function resamplePeaks(
+  peaks: ArrayLike<number>,
+  bucketCount: number,
+  signed: boolean,
+  sampleStart = 0,
+  sampleEnd = peaks.length,
+): number[] {
+  const len = peaks.length;
+  if (len === 0 || bucketCount <= 0) return [];
+
+  const lo = sampleStart < 0 ? 0 : sampleStart > len ? len : sampleStart;
+  const hi = sampleEnd < lo ? lo : sampleEnd > len ? len : sampleEnd;
+  const span = hi - lo;
+  // Degenerate window → flat (zero-height) buckets rather than NaN.
+  if (span <= 0) {
+    const flat: number[] = [];
+    for (let b = 0; b < bucketCount; b++) flat.push(0);
+    return flat;
+  }
+
+  const out: number[] = [];
+  const slice = span / bucketCount;
+  for (let b = 0; b < bucketCount; b++) {
+    let from = Math.floor(lo + b * slice);
+    let to = Math.floor(lo + (b + 1) * slice);
+    if (to <= from) to = from + 1; // ensure each bucket samples at least once
+    if (from < lo) from = lo;
+    if (to > hi) to = hi;
+    let peak = 0;
+    for (let i = from; i < to; i++) {
+      const m = magnitudeAt(peaks, i, signed);
+      if (m > peak) peak = m;
+    }
+    out.push(peak);
+  }
+  return out;
+}
+
+/**
+ * Build the full bar geometry for a body of `width` px.
+ *
+ * Bars are centered as a group: the leftover after `count` bars + gaps is split
+ * so the row sits flush-centered. Each entry carries its pixel `x`, its drawn
+ * `width` (px), and its `height` as a `0..1` fraction.
+ */
+export function buildBars(
+  peaks: ArrayLike<number>,
+  width: number,
+  barWidth: number,
+  barGap: number,
+  signed: boolean,
+  sampleStart = 0,
+  sampleEnd = peaks.length,
+): WaveformBar[] {
+  const count = countBars(width, barWidth, barGap);
+  if (count === 0) return [];
+  const w = barWidth > 0 ? barWidth : 1;
+  const gap = barGap > 0 ? barGap : 0;
+  const pitch = w + gap;
+  const used = count * pitch - gap;
+  const leftPad = (width - used) / 2;
+  const heights = resamplePeaks(peaks, count, signed, sampleStart, sampleEnd);
+  const bars: WaveformBar[] = [];
+  for (let i = 0; i < count; i++) {
+    bars.push({ x: leftPad + i * pitch, width: w, height: heights[i] ?? 0 });
+  }
+  return bars;
+}
+
+/**
+ * Build the polyline points for path mode: `samples + 1` points across the body
+ * width, y mapped so `0` magnitude sits on the vertical center and full
+ * magnitude reaches top/bottom. Returns the upper silhouette (consumers mirror
+ * it for a filled shape, or stroke it directly).
+ *
+ * `height` is the body's pixel height; `samples` the resample resolution.
+ */
+export function buildPathPoints(
+  peaks: ArrayLike<number>,
+  width: number,
+  height: number,
+  samples: number,
+  signed: boolean,
+  sampleStart = 0,
+  sampleEnd = peaks.length,
+): Point[] {
+  if (width <= 0 || height <= 0 || samples <= 0) return [];
+  const mags = resamplePeaks(peaks, samples, signed, sampleStart, sampleEnd);
+  const mid = height / 2;
+  const points: Point[] = [];
+  const step = samples > 1 ? width / (samples - 1) : 0;
+  for (let i = 0; i < samples; i++) {
+    const m = mags[i] ?? 0;
+    points.push({ x: i * step, y: mid - m * mid });
+  }
+  return points;
+}
diff --git a/vue/primitives/src/canvas/zoom-pan/ViewportContent.vue b/vue/primitives/src/canvas/zoom-pan/ViewportContent.vue
new file mode 100644
index 0000000..413e7cc
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/ViewportContent.vue
@@ -0,0 +1,58 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The single transformed layer. Everything a consumer renders inside the
+ * viewport lives here, so pan/zoom is one GPU-composited `transform` rather than
+ * a per-element restyle. `transform-origin: 0 0` is required — the coordinate
+ * formulas in `utils.ts` assume top-left scaling. `will-change: transform` is
+ * toggled on ONLY while interacting (never permanently): a pinned hint locks the
+ * compositor's raster scale, so the cached texture is GPU-upscaled and the
+ * content blurs at high zoom — toggling it lets the layer re-rasterise crisply
+ * once motion settles (see `useInteractionState`). Pure presentational; renders
+ * the default slot.
+ */
+export interface ViewportContentProps extends PrimitiveProps {}
+
+/**
+ * Static style shared by every transformed layer. Frozen and hoisted to module
+ * scope so the per-frame re-render only allocates/diffs the dynamic
+ * `transform`/`willChange` keys (see `dynamicStyle`), never these three.
+ */
+const BASE_STYLE = Object.freeze({
+  position: 'absolute',
+  inset: '0',
+  transformOrigin: '0 0',
+});
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useViewportContext } from './context';
+
+const { as = 'div' } = defineProps<ViewportContentProps>();
+
+const ctx = useViewportContext();
+const { forwardRef } = useForwardExpose();
+
+const dynamicStyle = computed(() => {
+  const vp = ctx.viewport.value;
+  return {
+    transform: `translate(${vp.x}px, ${vp.y}px) scale(${vp.zoom})`,
+    willChange: ctx.isInteracting.value ? 'transform' : undefined,
+  };
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    data-viewport-content=""
+    :style="[BASE_STYLE, dynamicStyle]"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/zoom-pan/ViewportRoot.vue b/vue/primitives/src/canvas/zoom-pan/ViewportRoot.vue
new file mode 100644
index 0000000..3d49a8c
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/ViewportRoot.vue
@@ -0,0 +1,195 @@
+<script lang="ts">
+import type { SurfaceRect, Viewport, ViewportApi, ViewportContext, ViewportRootProps, XYPosition, ZoomPanOptions } from './types';
+
+/**
+ * Root of a headless zoom-pan surface. Owns the master `Viewport` (two-way via
+ * `v-model:viewport`, or uncontrolled via `defaultViewport`), holds the
+ * interaction configuration (`minZoom`/`maxZoom`/`axis`/extents/gesture
+ * toggles), builds the {@link ViewportContext}, and provides it to
+ * `ViewportSurface` / `ViewportContent`. By default it renders the standard
+ * `ViewportSurface → ViewportContent` subtree and exposes the default slot as
+ * the viewport content; pass `#surface` to compose the parts manually. The
+ * imperative {@link ViewportApi} is also `defineExpose`d so consumers can drive
+ * pan/zoom via a template ref.
+ *
+ * The generalised substrate the flow canvas, a crop tool, an image stage, or a
+ * transform box all mount their content inside.
+ */
+export type { ViewportRootProps };
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, useSlots, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import ViewportSurface from './ViewportSurface.vue';
+import ViewportContent from './ViewportContent.vue';
+import { provideViewportContext } from './context';
+import { useViewportApi } from './useViewportApi';
+import { useInteractionState } from './useInteractionState';
+import { clampViewport as clampViewportFn, contentToScreen as contentToScreenFn, measureContentRect as measureContentRectFn, screenToContent as screenToContentFn } from './utils';
+
+const {
+  defaultViewport = { x: 0, y: 0, zoom: 1 },
+  minZoom = 0.5,
+  maxZoom = 2,
+  axis = 'xy',
+  panOnDrag = true,
+  zoomOnScroll = true,
+  zoomOnPinch = true,
+  panOnScroll = false,
+  zoomOnDoubleClick = true,
+  translateExtent = null,
+  contentExtent = null,
+  fitPadding = 0.1,
+  fitView = false,
+  zoomActivationKey = null,
+  disabled = false,
+  disableKeyboard = false,
+  as = 'div',
+} = defineProps<ViewportRootProps>();
+
+const slots = useSlots();
+
+// ── viewport model (controlled + uncontrolled), mirroring SliderRoot ─────────
+// In uncontrolled mode `model.value` is `undefined` until the first write, so a
+// local `shallowRef` seeded from `defaultViewport` is the source of truth and is
+// kept in sync with any external bind by the watch below.
+const model = defineModel<Viewport | undefined>('viewport');
+const localViewport = shallowRef<Viewport>(model.value ?? { ...defaultViewport });
+
+watch(model, (v) => {
+  if (v === undefined || v === null) return;
+  if (v === localViewport.value) return;
+  localViewport.value = v;
+});
+
+const viewport = computed<Viewport>({
+  get: () => localViewport.value,
+  set: (v) => {
+    localViewport.value = v;
+    // `defineModel` emits `update:viewport` on write — no manual emit needed.
+    model.value = v;
+  },
+});
+
+// ── surface measurement ──────────────────────────────────────────────────────
+const surfaceRect = shallowRef<SurfaceRect>({ left: 0, top: 0, width: 0, height: 0 });
+const measured = shallowRef(false);
+function setSurfaceRect(rect: SurfaceRect): void {
+  surfaceRect.value = rect;
+  if (!measured.value && rect.width > 0 && rect.height > 0) measured.value = true;
+}
+
+// ── reactive config refs (GetterRefImpl passthroughs) ────────────────────────
+const minZoomRef = toRef(() => minZoom);
+const maxZoomRef = toRef(() => maxZoom);
+const axisRef = toRef(() => axis);
+const translateExtentRef = toRef(() => translateExtent);
+const contentExtentRef = toRef(() => contentExtent);
+const fitPaddingRef = toRef(() => fitPadding);
+const interactiveRef = toRef(() => !disabled);
+
+const options = computed<ZoomPanOptions>(() => ({
+  axis,
+  panOnDrag,
+  zoomOnScroll,
+  zoomOnPinch,
+  panOnScroll,
+  zoomOnDoubleClick,
+  zoomActivationKey,
+  disabled,
+  disableKeyboard,
+}));
+
+// ── coordinate bindings (live viewport + surface origin) ─────────────────────
+function screenToContent(point: XYPosition): XYPosition {
+  return screenToContentFn(point, viewport.value, surfaceRect.value);
+}
+function contentToScreen(point: XYPosition): XYPosition {
+  return contentToScreenFn(point, viewport.value, surfaceRect.value);
+}
+function measureContentRect(el: HTMLElement) {
+  return measureContentRectFn(el, viewport.value, surfaceRect.value);
+}
+function clampViewport(vp: Viewport): Viewport {
+  return clampViewportFn(vp, {
+    minZoom: minZoomRef.value,
+    maxZoom: maxZoomRef.value,
+    translateExtent: translateExtentRef.value,
+  });
+}
+
+const isInteracting = useInteractionState(() => viewport.value);
+
+// ── build + provide context ──────────────────────────────────────────────────
+const context: ViewportContext = {
+  viewport,
+  surfaceRect,
+  setSurfaceRect,
+  minZoom: minZoomRef,
+  maxZoom: maxZoomRef,
+  axis: axisRef,
+  translateExtent: translateExtentRef,
+  contentExtent: contentExtentRef,
+  fitPadding: fitPaddingRef,
+  interactive: interactiveRef,
+  measured,
+  options,
+  isInteracting,
+  // `isPanning` / `isZooming` are surfaced from `useZoomPan` (run inside
+  // `ViewportSurface`) via these proxy refs; `ViewportSurface` writes into them.
+  isPanning: shallowRef(false),
+  isZooming: shallowRef(false),
+  screenToContent,
+  contentToScreen,
+  measureContentRect,
+  clampViewport,
+  // `api` is assigned right after construction (it closes over `context`).
+  api: undefined as unknown as ViewportApi,
+};
+
+const api = useViewportApi(context);
+context.api = api;
+
+provideViewportContext(context);
+
+// `fitView`: fit `contentExtent` into view once the surface is first measured.
+if (fitView) {
+  watch(measured, (m) => {
+    if (m) api.fit();
+  });
+}
+
+const hasSurfaceSlot = computed(() => !!slots.surface);
+
+// `defineExpose` runs BEFORE `useForwardExpose` so the composable merges these
+// bindings (plus props + `$el`) instead of `defineExpose`'s `expose()`
+// clobbering them and warning "expose() should be called only once". ORDER IS
+// LOAD-BEARING.
+defineExpose({
+  ...api,
+  viewport,
+});
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    data-viewport-root=""
+  >
+    <slot
+      v-if="hasSurfaceSlot"
+      name="surface"
+      :api="api"
+    />
+    <ViewportSurface v-else>
+      <ViewportContent>
+        <slot :api="api" />
+      </ViewportContent>
+    </ViewportSurface>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/zoom-pan/ViewportSurface.vue b/vue/primitives/src/canvas/zoom-pan/ViewportSurface.vue
new file mode 100644
index 0000000..6062f00
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/ViewportSurface.vue
@@ -0,0 +1,59 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The clipping / interaction pane. Clips the content (`overflow: hidden`),
+ * disables native touch gestures (`touch-action: none`), reports its live
+ * bounding rect into the context as the screen origin for coordinate math, and
+ * hosts the wheel / pinch / drag / dblclick / keyboard pan-zoom layer
+ * (`useZoomPan`). Carries `role` / `tabindex` for the a11y keyboard layer and
+ * reflects gesture state via `data-panning` / `data-zooming` / `data-measured`.
+ * Rendered by `ViewportRoot` by default; place directly only when composing the
+ * parts manually.
+ */
+export interface ViewportSurfaceProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import type { Ref } from 'vue';
+import { watchEffect } from 'vue';
+import { useElementBounding, useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useViewportContext } from './context';
+import { useZoomPan } from './useZoomPan';
+
+const { as = 'div' } = defineProps<ViewportSurfaceProps>();
+
+const ctx = useViewportContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const { left, top, width, height } = useElementBounding(currentElement);
+watchEffect(() => {
+  ctx.setSurfaceRect({ left: left.value, top: top.value, width: width.value, height: height.value });
+});
+
+// `useZoomPan` owns the live gesture flags; mirror them onto the context refs so
+// `ViewportContent` / consumers (and the `data-*` attributes below) observe them.
+const { isPanning, isZooming } = useZoomPan(currentElement, ctx, ctx.options.value);
+watchEffect(() => {
+  (ctx.isPanning as Ref<boolean>).value = isPanning.value;
+  (ctx.isZooming as Ref<boolean>).value = isZooming.value;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    data-viewport-surface=""
+    :data-panning="ctx.isPanning.value ? '' : undefined"
+    :data-zooming="ctx.isZooming.value ? '' : undefined"
+    :data-measured="ctx.measured.value ? '' : undefined"
+    :data-interactive="ctx.interactive.value ? '' : undefined"
+    :role="ctx.options.value.disableKeyboard ? undefined : 'application'"
+    :tabindex="ctx.options.value.disableKeyboard ? undefined : 0"
+    :style="{ position: 'relative', overflow: 'hidden', touchAction: 'none', width: '100%', height: '100%' }"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/canvas/zoom-pan/__test__/__screenshots__/zoom-pan.test.ts/ViewportRoot---Surface---Content--mount--flags-the-surface-as-measured-once-it-has-a-non-zero-rect-1.png b/vue/primitives/src/canvas/zoom-pan/__test__/__screenshots__/zoom-pan.test.ts/ViewportRoot---Surface---Content--mount--flags-the-surface-as-measured-once-it-has-a-non-zero-rect-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/canvas/zoom-pan/__test__/__screenshots__/zoom-pan.test.ts/ViewportRoot---Surface---Content--mount--flags-the-surface-as-measured-once-it-has-a-non-zero-rect-1.png differ
diff --git a/vue/primitives/src/canvas/zoom-pan/__test__/zoom-pan.test.ts b/vue/primitives/src/canvas/zoom-pan/__test__/zoom-pan.test.ts
new file mode 100644
index 0000000..a78b308
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/__test__/zoom-pan.test.ts
@@ -0,0 +1,295 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { Viewport } from '../types';
+import {
+  clampViewport,
+  clampZoom,
+  contentToScreen,
+  fitViewTransform,
+  screenToContent,
+  zoomAtPointer,
+} from '../utils';
+import { ViewportRoot } from '../index';
+
+const ORIGIN = { left: 0, top: 0 };
+
+// ── pure-math (no DOM) ───────────────────────────────────────────────────────
+
+describe('screenToContent / contentToScreen', () => {
+  it('are exact inverses at zoom 1', () => {
+    const vp: Viewport = { x: 30, y: -10, zoom: 1 };
+    const p = { x: 123, y: 456 };
+    const content = screenToContent(p, vp, ORIGIN);
+    expect(contentToScreen(content, vp, ORIGIN)).toEqual(p);
+  });
+
+  it('are exact inverses at several zooms (!= 1) and offsets', () => {
+    const cases: Array<{ vp: Viewport; origin: { left: number; top: number }; p: { x: number; y: number } }> = [
+      { vp: { x: 200, y: 80, zoom: 1.5 }, origin: { left: 64, top: 40 }, p: { x: 512, y: 300 } },
+      { vp: { x: -120, y: 33, zoom: 0.5 }, origin: { left: 10, top: 5 }, p: { x: 47, y: 900 } },
+      { vp: { x: 7, y: -7, zoom: 2.75 }, origin: { left: 100, top: 200 }, p: { x: 333, y: 12 } },
+      { vp: { x: 0, y: 0, zoom: 0.137 }, origin: { left: 0, top: 0 }, p: { x: 1000, y: -500 } },
+    ];
+    for (const { vp, origin, p } of cases) {
+      const content = screenToContent(p, vp, origin);
+      const back = contentToScreen(content, vp, origin);
+      expect(back.x).toBeCloseTo(p.x, 6);
+      expect(back.y).toBeCloseTo(p.y, 6);
+    }
+  });
+
+  it('divides out zoom and translation', () => {
+    const vp: Viewport = { x: 100, y: 50, zoom: 2 };
+    expect(screenToContent({ x: 100, y: 50 }, vp, ORIGIN)).toEqual({ x: 0, y: 0 });
+    expect(screenToContent({ x: 300, y: 250 }, vp, ORIGIN)).toEqual({ x: 100, y: 100 });
+  });
+
+  it('subtracts the surface origin', () => {
+    const vp: Viewport = { x: 0, y: 0, zoom: 1 };
+    const origin = { left: 50, top: 20 };
+    expect(screenToContent({ x: 50, y: 20 }, vp, origin)).toEqual({ x: 0, y: 0 });
+    expect(screenToContent({ x: 150, y: 120 }, vp, origin)).toEqual({ x: 100, y: 100 });
+  });
+});
+
+describe('zoomAtPointer', () => {
+  it('keeps the content point under the cursor fixed', () => {
+    const vp: Viewport = { x: 0, y: 0, zoom: 1 };
+    const pointer = { x: 400, y: 300 };
+    const next = zoomAtPointer(vp, 2, pointer);
+    const before = screenToContent(pointer, vp, ORIGIN);
+    const after = screenToContent(pointer, next, ORIGIN);
+    expect(after.x).toBeCloseTo(before.x, 6);
+    expect(after.y).toBeCloseTo(before.y, 6);
+    expect(next.zoom).toBe(2);
+  });
+
+  it('keeps the anchor fixed across multiple zoom levels and a translated viewport', () => {
+    const vp: Viewport = { x: 120, y: -45, zoom: 0.8 };
+    const pointer = { x: 250, y: 175 };
+    for (const z of [0.4, 1, 1.6, 3.2]) {
+      const next = zoomAtPointer(vp, z, pointer);
+      const before = screenToContent(pointer, vp, ORIGIN);
+      const after = screenToContent(pointer, next, ORIGIN);
+      expect(after.x).toBeCloseTo(before.x, 6);
+      expect(after.y).toBeCloseTo(before.y, 6);
+    }
+  });
+
+  it('honours a non-zero surface origin (pointer given in client px)', () => {
+    const vp: Viewport = { x: 10, y: 10, zoom: 1 };
+    const origin = { left: 80, top: 30 };
+    const pointer = { x: 480, y: 230 }; // client coords
+    const next = zoomAtPointer(vp, 2, pointer, origin);
+    const before = screenToContent(pointer, vp, origin);
+    const after = screenToContent(pointer, next, origin);
+    expect(after.x).toBeCloseTo(before.x, 6);
+    expect(after.y).toBeCloseTo(before.y, 6);
+  });
+});
+
+describe('clampZoom', () => {
+  it('clamps into [min, max]', () => {
+    expect(clampZoom(5, 0.5, 2)).toBe(2);
+    expect(clampZoom(0.1, 0.5, 2)).toBe(0.5);
+    expect(clampZoom(1, 0.5, 2)).toBe(1);
+  });
+});
+
+describe('clampViewport', () => {
+  it('clamps only the zoom when no translate extent is given', () => {
+    const vp = clampViewport({ x: 999, y: -999, zoom: 9 }, { minZoom: 0.5, maxZoom: 2 });
+    expect(vp).toEqual({ x: 999, y: -999, zoom: 2 });
+  });
+
+  it('clamps the translate to the extent', () => {
+    const vp = clampViewport({ x: 500, y: -500, zoom: 1 }, {
+      minZoom: 0.1,
+      maxZoom: 4,
+      translateExtent: { minX: -100, maxX: 100, minY: -100, maxY: 100 },
+    });
+    expect(vp.x).toBe(100);
+    expect(vp.y).toBe(-100);
+  });
+
+  it('centres a degenerate (min > max) translate interval instead of oscillating', () => {
+    // Content smaller than the surface → no room to pan → centre at the midpoint.
+    const vp = clampViewport({ x: 9999, y: -9999, zoom: 1 }, {
+      minZoom: 0.1,
+      maxZoom: 4,
+      translateExtent: { minX: 50, maxX: -50, minY: 20, maxY: -20 },
+    });
+    expect(vp.x).toBe(0); // (50 + -50) / 2
+    expect(vp.y).toBe(0); // (20 + -20) / 2
+  });
+
+  it('leaves an unconstrained side alone', () => {
+    const vp = clampViewport({ x: 1000, y: 1000, zoom: 1 }, {
+      minZoom: 0.1,
+      maxZoom: 4,
+      translateExtent: { maxX: 200 },
+    });
+    expect(vp.x).toBe(200);
+    expect(vp.y).toBe(1000);
+  });
+});
+
+describe('fitViewTransform', () => {
+  it('is a no-op on a zero-sized surface', () => {
+    const vp = fitViewTransform({ x: 0, y: 0, width: 100, height: 100 }, { width: 0, height: 0 }, { minZoom: 0.5, maxZoom: 2 });
+    expect(vp).toEqual({ x: 0, y: 0, zoom: 1 });
+  });
+
+  it('is a no-op on zero-sized bounds', () => {
+    const vp = fitViewTransform({ x: 0, y: 0, width: 0, height: 0 }, { width: 400, height: 400 }, { minZoom: 0.5, maxZoom: 2 });
+    expect(vp).toEqual({ x: 0, y: 0, zoom: 1 });
+  });
+
+  it('centres known bounds in the surface', () => {
+    const bounds = { x: 0, y: 0, width: 100, height: 100 };
+    const vp = fitViewTransform(bounds, { width: 400, height: 400 }, { padding: 0, minZoom: 0.1, maxZoom: 4 });
+    expect(vp.zoom).toBeCloseTo(4, 6);
+    const center = contentToScreen({ x: 50, y: 50 }, vp, ORIGIN);
+    expect(center.x).toBeCloseTo(200, 6);
+    expect(center.y).toBeCloseTo(200, 6);
+  });
+
+  it('respects maxZoom', () => {
+    const vp = fitViewTransform({ x: 0, y: 0, width: 10, height: 10 }, { width: 1000, height: 1000 }, { padding: 0, minZoom: 0.5, maxZoom: 2 });
+    expect(vp.zoom).toBe(2);
+  });
+});
+
+// ── component mount smoke test (browser mode → real layout) ──────────────────
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+/** Wait for `n` real animation frames so layout + ResizeObserver settle. */
+function raf(n = 1): Promise<void> {
+  return new Promise((resolve) => {
+    let i = 0;
+    const step = (): void => {
+      if (++i >= n) resolve();
+      else requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+  });
+}
+
+function mountViewport(props: Record<string, unknown> = {}) {
+  const exposed = ref<any>(null);
+  const Harness = defineComponent({
+    setup() {
+      return () => h(ViewportRoot, {
+        ref: (r: any) => { exposed.value = r; },
+        style: 'width: 400px; height: 300px;',
+        ...props,
+      }, {
+        default: () => h('div', { 'data-child': '', style: 'width: 100px; height: 100px;' }, 'content'),
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, exposed };
+}
+
+describe('ViewportRoot / Surface / Content (mount)', () => {
+  it('renders the surface, the transformed content layer, and the child', async () => {
+    mountViewport();
+    await nextTick();
+    const root = document.querySelector('[data-viewport-root]');
+    const surface = document.querySelector('[data-viewport-surface]');
+    const content = document.querySelector<HTMLElement>('[data-viewport-content]');
+    const child = document.querySelector('[data-child]');
+    expect(root).toBeTruthy();
+    expect(surface).toBeTruthy();
+    expect(content).toBeTruthy();
+    expect(child?.textContent).toBe('content');
+    // Default identity transform.
+    expect(content!.style.transform).toContain('translate(0px, 0px)');
+    expect(content!.style.transform).toContain('scale(1)');
+  });
+
+  it('sets touch-action:none + overflow:hidden on the surface and a11y role/tabindex', async () => {
+    mountViewport();
+    await nextTick();
+    const surface = document.querySelector<HTMLElement>('[data-viewport-surface]')!;
+    expect(surface.style.overflow).toBe('hidden');
+    expect(surface.style.touchAction).toBe('none');
+    expect(surface.getAttribute('role')).toBe('application');
+    expect(surface.tabIndex).toBe(0);
+  });
+
+  it('flags the surface as measured once it has a non-zero rect', async () => {
+    mountViewport();
+    await raf(2);
+    await nextTick();
+    const surface = document.querySelector<HTMLElement>('[data-viewport-surface]')!;
+    expect(surface.getAttribute('data-measured')).toBe('');
+  });
+
+  it('exposes the imperative api and reflects it in the content transform', async () => {
+    const { exposed } = mountViewport({ minZoom: 0.5, maxZoom: 4 });
+    await nextTick();
+    await nextTick();
+
+    expect(typeof exposed.value.zoomTo).toBe('function');
+    expect(typeof exposed.value.fit).toBe('function');
+
+    exposed.value.zoomTo(2);
+    await nextTick();
+    const content = document.querySelector<HTMLElement>('[data-viewport-content]')!;
+    expect(content.style.transform).toContain('scale(2)');
+
+    // panBy moves the translate.
+    exposed.value.panBy(40, 25);
+    await nextTick();
+    expect(content.style.transform).toContain('translate(40px, 25px)');
+  });
+
+  it('clamps an out-of-range setViewport through the api', async () => {
+    const { exposed } = mountViewport({ minZoom: 0.5, maxZoom: 2 });
+    await nextTick();
+    await nextTick();
+    exposed.value.setViewport({ x: 0, y: 0, zoom: 99 });
+    await nextTick();
+    expect(exposed.value.getViewport().zoom).toBe(2);
+  });
+
+  it('drives a controlled v-model:viewport', async () => {
+    const vp = ref<Viewport>({ x: 0, y: 0, zoom: 1 });
+    const Harness = defineComponent({
+      setup() {
+        return () => {
+          const rootProps: Record<string, unknown> = {
+            viewport: vp.value,
+            'onUpdate:viewport': (v: Viewport) => { vp.value = v; },
+            style: 'width: 400px; height: 300px;',
+          };
+          return h(ViewportRoot, rootProps, {
+            default: () => h('div', { 'data-child': '' }, 'x'),
+          });
+        };
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    vp.value = { x: 10, y: 20, zoom: 1.5 };
+    await nextTick();
+    const content = document.querySelector<HTMLElement>('[data-viewport-content]')!;
+    expect(content.style.transform).toContain('translate(10px, 20px)');
+    expect(content.style.transform).toContain('scale(1.5)');
+  });
+});
diff --git a/vue/primitives/src/canvas/zoom-pan/context.ts b/vue/primitives/src/canvas/zoom-pan/context.ts
new file mode 100644
index 0000000..6a26140
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/context.ts
@@ -0,0 +1,10 @@
+import { useContextFactory } from '@robonen/vue';
+import type { ViewportContext } from './types';
+
+const viewport = useContextFactory<ViewportContext>('ViewportContext');
+
+/** Provide the {@link ViewportContext} to descendants of `ViewportRoot`. */
+export const provideViewportContext = viewport.provide;
+
+/** Inject the {@link ViewportContext}. Throws when no `ViewportRoot` ancestor. */
+export const useViewportContext = viewport.inject;
diff --git a/vue/primitives/src/canvas/zoom-pan/demo.vue b/vue/primitives/src/canvas/zoom-pan/demo.vue
new file mode 100644
index 0000000..18847e2
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/demo.vue
@@ -0,0 +1,104 @@
+<script setup lang="ts">
+import { ViewportRoot } from '@robonen/primitives';
+import { ref, useTemplateRef } from 'vue';
+
+// The viewport transform: x/y in screen px (applied before scale), zoom factor.
+const viewport = ref({ x: 40, y: 40, zoom: 1 });
+const vp = useTemplateRef<InstanceType<typeof ViewportRoot>>('vp');
+
+// A fixed content box so `fit` has something to frame.
+const contentExtent = { x: 0, y: 0, width: 720, height: 480 };
+
+const tiles = Array.from({ length: 24 }, (_, i) => i);
+</script>
+
+<template>
+  <div class="demo-card w-full max-w-2xl space-y-4 p-6 text-fg">
+    <div class="flex items-center justify-between">
+      <span class="text-sm font-medium">Zoom / pan viewport</span>
+      <span class="font-mono text-xs text-fg-muted tabular-nums">
+        x {{ Math.round(viewport.x) }} · y {{ Math.round(viewport.y) }} · {{ (viewport.zoom * 100).toFixed(0) }}%
+      </span>
+    </div>
+
+    <ViewportRoot
+      ref="vp"
+      v-model:viewport="viewport"
+      :min-zoom="0.3"
+      :max-zoom="4"
+      :content-extent="contentExtent"
+      aria-label="Pan and zoom surface"
+      class="zp relative h-72 w-full overflow-hidden rounded-card border border-border bg-bg-inset shadow-(--shadow-card) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <template #default>
+        <!-- Content lives in the single transformed layer. -->
+        <div class="zp-content">
+          <div v-for="t in tiles" :key="t" class="zp-tile">{{ t }}</div>
+        </div>
+      </template>
+    </ViewportRoot>
+
+    <div class="flex flex-wrap items-center gap-2">
+      <button type="button" class="zp-btn" @click="vp?.zoomIn()">Zoom in</button>
+      <button type="button" class="zp-btn" @click="vp?.zoomOut()">Zoom out</button>
+      <button type="button" class="zp-btn" @click="vp?.fit(contentExtent)">Fit</button>
+      <button type="button" class="zp-btn" @click="vp?.center()">Center</button>
+      <button type="button" class="zp-btn" @click="vp?.reset()">Reset</button>
+    </div>
+
+    <p class="text-xs text-fg-subtle">
+      Drag to pan, scroll to zoom (⌘/Ctrl-scroll to pinch-zoom). The single
+      transformed layer keeps coordinate math and hit-testing exact at any zoom.
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.zp {
+  cursor: grab;
+  touch-action: none;
+}
+.zp:active {
+  cursor: grabbing;
+}
+
+.zp-content {
+  display: grid;
+  grid-template-columns: repeat(6, 110px);
+  gap: 10px;
+  width: 720px;
+  padding: 10px;
+}
+.zp-tile {
+  display: grid;
+  place-items: center;
+  height: 110px;
+  border-radius: 12px;
+  font-family: var(--font-mono);
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: #fff;
+  background: linear-gradient(135deg, var(--accent) 0%, color-mix(in oklch, var(--accent) 30%, #6d28d9) 100%);
+  box-shadow: inset 0 1px 0 rgb(255 255 255 / 0.15);
+}
+
+.zp-btn {
+  padding: 0.375rem 0.75rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  border-radius: 0.5rem;
+  color: var(--fg);
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  cursor: pointer;
+  transition: background 0.12s ease, border-color 0.12s ease;
+}
+.zp-btn:hover {
+  background: var(--bg-inset);
+  border-color: var(--border-strong);
+}
+.zp-btn:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--ring);
+}
+</style>
diff --git a/vue/primitives/src/canvas/zoom-pan/index.ts b/vue/primitives/src/canvas/zoom-pan/index.ts
new file mode 100644
index 0000000..a67d6d8
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/index.ts
@@ -0,0 +1,39 @@
+export { default as ViewportRoot } from './ViewportRoot.vue';
+export { default as ViewportSurface } from './ViewportSurface.vue';
+export { default as ViewportContent } from './ViewportContent.vue';
+
+export { provideViewportContext, useViewportContext } from './context';
+export { useZoomPan } from './useZoomPan';
+export type { UseZoomPanReturn } from './useZoomPan';
+export { useViewportApi } from './useViewportApi';
+export { useInteractionState } from './useInteractionState';
+
+export {
+  clamp,
+  clampViewport,
+  clampZoom,
+  contentToScreen,
+  fitViewTransform,
+  measureContentRect,
+  screenToContent,
+  wheelToZoomFactor,
+  zoomAtPointer,
+} from './utils';
+
+export type {
+  Dimensions,
+  FitParams,
+  FitViewportOptions,
+  Rect,
+  SurfaceOrigin,
+  SurfaceRect,
+  TranslateExtent,
+  Viewport,
+  ViewportApi,
+  ViewportConstraints,
+  ViewportContext,
+  ViewportRootProps,
+  XYPosition,
+  ZoomPanAxis,
+  ZoomPanOptions,
+} from './types';
diff --git a/vue/primitives/src/canvas/zoom-pan/types.ts b/vue/primitives/src/canvas/zoom-pan/types.ts
new file mode 100644
index 0000000..b435955
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/types.ts
@@ -0,0 +1,249 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Dimensions, Rect, Viewport, XYPosition } from '../flow/types';
+
+// The four geometry primitives are reused verbatim from the flow module rather
+// than redeclared: those names (`Viewport`, `Rect`, `XYPosition`,
+// `Dimensions`) are already published from the package root barrel by flow, so
+// re-declaring them here would make the barrel re-export the SAME name from two
+// modules → TS2308 ("Module has already exported a member"). Re-exporting the
+// identical symbol keeps one canonical type and one import surface.
+export type { Dimensions, Rect, Viewport, XYPosition };
+
+/** A surface origin: only `left`/`top` matter for coordinate conversion. */
+export interface SurfaceOrigin {
+  /** Distance from the viewport's left edge to the surface's left edge, in client px. */
+  left: number;
+  /** Distance from the viewport's top edge to the surface's top edge, in client px. */
+  top: number;
+}
+
+/** The live bounding rect of the interaction surface in client (screen) px. */
+export interface SurfaceRect {
+  /** Surface left edge in client px. */
+  left: number;
+  /** Surface top edge in client px. */
+  top: number;
+  /** Surface width in client px. */
+  width: number;
+  /** Surface height in client px. */
+  height: number;
+}
+
+/**
+ * The axis interaction is constrained to.
+ * - `'xy'`: free pan/zoom on both axes (the default).
+ * - `'x'` / `'y'`: lock panning (and drag) to that single axis.
+ */
+export type ZoomPanAxis = 'xy' | 'x' | 'y';
+
+/**
+ * Optional per-axis translate clamp applied to the viewport `x`/`y` after every
+ * write. When a side is `undefined` that side is unconstrained. When the allowed
+ * interval is degenerate (`min > max`, i.e. the content is smaller than the
+ * surface on that axis) the value is centred instead of pinned to a boundary.
+ */
+export interface TranslateExtent {
+  /** Lower bound for viewport `x`. */
+  minX?: number;
+  /** Upper bound for viewport `x`. */
+  maxX?: number;
+  /** Lower bound for viewport `y`. */
+  minY?: number;
+  /** Upper bound for viewport `y`. */
+  maxY?: number;
+}
+
+/** Constraints passed to {@link clampViewport}. */
+export interface ViewportConstraints {
+  /** Minimum zoom level. */
+  minZoom: number;
+  /** Maximum zoom level. */
+  maxZoom: number;
+  /** Optional per-axis translate clamp; `null` disables it. */
+  translateExtent?: TranslateExtent | null;
+}
+
+/** Options for {@link fitViewTransform}. */
+export interface FitViewportOptions {
+  /** Fractional inset on each side, 0–1. @default 0.1 */
+  padding?: number;
+  /** Minimum zoom level. @default 0 */
+  minZoom?: number;
+  /** Maximum zoom level. @default Infinity */
+  maxZoom?: number;
+}
+
+/** Parameters for the imperative {@link ViewportApi.fit}. */
+export interface FitParams {
+  /** Fractional inset on each side, 0–1. @default the root `fitPadding` */
+  padding?: number;
+  /** Override the min zoom of the fit. */
+  minZoom?: number;
+  /** Override the max zoom of the fit. */
+  maxZoom?: number;
+}
+
+/**
+ * Behaviour switches for {@link useZoomPan}. Mirrors the `ZoomPan*` props on
+ * `ViewportRoot`; the root passes these through the context.
+ */
+export interface ZoomPanOptions {
+  /** Axis interaction is constrained to. @default 'xy' */
+  axis?: ZoomPanAxis;
+  /** Drag the surface to pan. @default true */
+  panOnDrag?: boolean;
+  /** Wheel scroll zooms toward the pointer. @default true */
+  zoomOnScroll?: boolean;
+  /** Trackpad pinch (ctrl+wheel) zooms. @default true */
+  zoomOnPinch?: boolean;
+  /** Wheel scroll pans instead of zooms (pinch still zooms). @default false */
+  panOnScroll?: boolean;
+  /** Scroll-pan speed multiplier. @default 0.5 */
+  panOnScrollSpeed?: number;
+  /** Double-click zooms in toward the pointer. @default true */
+  zoomOnDoubleClick?: boolean;
+  /** Factor applied per double-click. @default 1.2 */
+  doubleClickZoomFactor?: number;
+  /**
+   * Modifier key that must be held for scroll to zoom. When set, plain scroll is
+   * ignored (or pans, if `panOnScroll`) and zoom requires the key. `null`
+   * disables the gate. @default null
+   */
+  zoomActivationKey?: 'Alt' | 'Control' | 'Meta' | 'Shift' | null;
+  /** Master interactivity switch (lock). @default false */
+  disabled?: boolean;
+  /** Disable the keyboard pan/zoom layer. @default false */
+  disableKeyboard?: boolean;
+  /** Pixel step for arrow-key panning. @default 20 */
+  keyboardPanStep?: number;
+}
+
+/**
+ * Imperative, framework-agnostic control surface for a zoom-pan viewport. Every
+ * write goes through `clampViewport`, so the result always honours
+ * `minZoom`/`maxZoom` and the translate extent.
+ */
+export interface ViewportApi {
+  /** Current viewport `{x,y,zoom}`. */
+  getViewport: () => Viewport;
+  /** Replace the viewport (clamped). */
+  setViewport: (viewport: Viewport) => void;
+  /** Zoom in, anchored at the surface centre. */
+  zoomIn: (factor?: number) => void;
+  /** Zoom out, anchored at the surface centre. */
+  zoomOut: (factor?: number) => void;
+  /** Zoom to an absolute level, anchored at the surface centre. */
+  zoomTo: (zoom: number) => void;
+  /** Zoom to an absolute level, anchored at a surface-relative pixel point. */
+  zoomToPoint: (zoom: number, point: XYPosition) => void;
+  /**
+   * Fit `bounds` (content space) into view, centred with padding. Defaults to
+   * the root `contentExtent`; an explicit no-op when both are null. Respects the
+   * surface `width === 0 || height === 0` early-return.
+   */
+  fit: (bounds?: Rect | null, params?: FitParams) => void;
+  /** Centre a content-space point in the surface, keeping the current zoom. */
+  center: (point?: XYPosition) => void;
+  /** Pan by a screen-pixel delta. */
+  panBy: (dx: number, dy: number) => void;
+  /** Reset to `{ x: 0, y: 0, zoom: 1 }` (clamped). */
+  reset: () => void;
+  /** Convert a screen (client) point to content space. */
+  screenToContent: (point: XYPosition) => XYPosition;
+  /** Convert a content-space point to a screen (client) point. */
+  contentToScreen: (point: XYPosition) => XYPosition;
+}
+
+/**
+ * Root context shared by every zoom-pan part. Reactive fields are `Ref` (never
+ * raw values — descendants would lose reactivity); the master `viewport` is
+ * read and written directly, all writes funnelled through `clampViewport`.
+ */
+export interface ViewportContext {
+  /** The master transform `{x,y,zoom}`. */
+  viewport: Ref<Viewport>;
+  /** Live bounding rect of `ViewportSurface`; the screen origin for coord math. */
+  surfaceRect: Readonly<Ref<SurfaceRect>>;
+  /** `ViewportSurface` reports its live bounding rect here (the screen origin). */
+  setSurfaceRect: (rect: SurfaceRect) => void;
+
+  /** Minimum zoom level. */
+  minZoom: Ref<number>;
+  /** Maximum zoom level. */
+  maxZoom: Ref<number>;
+  /** Axis interaction is constrained to. */
+  axis: Ref<ZoomPanAxis>;
+  /** Optional per-axis translate clamp; `null` disables it. */
+  translateExtent: Ref<TranslateExtent | null>;
+  /** Optional content bounds (content space) — the default `fit` target. */
+  contentExtent: Ref<Rect | null>;
+  /** Fractional fit padding, 0–1. */
+  fitPadding: Ref<number>;
+
+  /** Master interactivity switch (lock). */
+  interactive: Ref<boolean>;
+  /** False until the surface has reported its first non-zero rect. */
+  measured: Ref<boolean>;
+  /** ZoomPan behaviour switches, derived from the root props. */
+  options: ComputedRef<ZoomPanOptions>;
+
+  /** True while panning, zooming, or running an imperative API write. */
+  isInteracting: Readonly<Ref<boolean>>;
+  /** True while a drag-pan / scroll-pan gesture is active. */
+  isPanning: Readonly<Ref<boolean>>;
+  /** True while a wheel / pinch / dblclick zoom gesture is active. */
+  isZooming: Readonly<Ref<boolean>>;
+
+  /** Screen (client) point → content space, bound to the live viewport + surface. */
+  screenToContent: (point: XYPosition) => XYPosition;
+  /** Content space → screen (client) point. */
+  contentToScreen: (point: XYPosition) => XYPosition;
+  /** Measure a DOM element's rect back into content space (divide out zoom). */
+  measureContentRect: (el: HTMLElement) => Rect;
+  /** Clamp a candidate viewport against zoom + translate extent. */
+  clampViewport: (viewport: Viewport) => Viewport;
+
+  /** Imperative control surface. */
+  api: ViewportApi;
+}
+
+/**
+ * Props of `ViewportRoot`. Owns the `Viewport` state (controlled via
+ * `v-model:viewport`, or uncontrolled via `defaultViewport`) and the
+ * interaction configuration that flows into the context.
+ */
+export interface ViewportRootProps extends PrimitiveProps {
+  /** Uncontrolled initial viewport (ignored when `v-model:viewport` is bound). @default { x: 0, y: 0, zoom: 1 } */
+  defaultViewport?: Viewport;
+  /** Minimum zoom level. @default 0.5 */
+  minZoom?: number;
+  /** Maximum zoom level. @default 2 */
+  maxZoom?: number;
+  /** Axis interaction is constrained to. @default 'xy' */
+  axis?: ZoomPanAxis;
+  /** Drag the surface to pan. @default true */
+  panOnDrag?: boolean;
+  /** Wheel scroll zooms toward the pointer. @default true */
+  zoomOnScroll?: boolean;
+  /** Trackpad pinch (ctrl+wheel) zooms. @default true */
+  zoomOnPinch?: boolean;
+  /** Wheel scroll pans instead of zooms (pinch still zooms). @default false */
+  panOnScroll?: boolean;
+  /** Double-click zooms in toward the pointer. @default true */
+  zoomOnDoubleClick?: boolean;
+  /** Optional per-axis translate clamp; `null` disables it. @default null */
+  translateExtent?: TranslateExtent | null;
+  /** Optional content bounds (content space) — the default `fit` target. @default null */
+  contentExtent?: Rect | null;
+  /** Fractional fit padding, 0–1. @default 0.1 */
+  fitPadding?: number;
+  /** Fit `contentExtent` into view on mount (once the surface is measured). @default false */
+  fitView?: boolean;
+  /** Modifier key that must be held for scroll to zoom; `null` disables the gate. @default null */
+  zoomActivationKey?: 'Alt' | 'Control' | 'Meta' | 'Shift' | null;
+  /** Master interactivity switch (lock). @default false */
+  disabled?: boolean;
+  /** Disable the keyboard pan/zoom layer. @default false */
+  disableKeyboard?: boolean;
+}
diff --git a/vue/primitives/src/canvas/zoom-pan/useInteractionState.ts b/vue/primitives/src/canvas/zoom-pan/useInteractionState.ts
new file mode 100644
index 0000000..f70618e
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/useInteractionState.ts
@@ -0,0 +1,44 @@
+import type { Ref, WatchSource } from 'vue';
+import { onScopeDispose, shallowRef, watch } from 'vue';
+import type { Viewport } from './types';
+
+/**
+ * True while the viewport is actively panning/zooming, flipped back to `false`
+ * `idleDelay` ms after the last change. Driven purely by viewport mutations, so
+ * it covers every path — wheel, pinch, drag-pan, double-click, keyboard pan, and
+ * the imperative `zoomIn`/`zoomTo`/`fit` API — without each call site having to
+ * opt in.
+ *
+ * Used to gate `will-change: transform` on `ViewportContent`. Keeping that hint
+ * on permanently pins the compositor's raster scale: the layer is rasterised
+ * once and the `scale(zoom)` is applied by GPU-upscaling that cached texture, so
+ * at high zoom the content stays blurry even after the gesture ends. Toggling
+ * the hint on only while interacting lets the browser re-rasterise the layer
+ * crisply once motion settles.
+ *
+ * @param source A watch source yielding the master viewport.
+ * @param idleDelay Milliseconds of stillness before settling. @default 200
+ * @returns A read-only ref that is `true` while interacting.
+ */
+export function useInteractionState(
+  source: WatchSource<Viewport>,
+  idleDelay = 200,
+): Readonly<Ref<boolean>> {
+  const interacting = shallowRef(false);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  watch(source, () => {
+    interacting.value = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => {
+      interacting.value = false;
+      timer = undefined;
+    }, idleDelay);
+  });
+
+  onScopeDispose(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+
+  return interacting;
+}
diff --git a/vue/primitives/src/canvas/zoom-pan/useViewportApi.ts b/vue/primitives/src/canvas/zoom-pan/useViewportApi.ts
new file mode 100644
index 0000000..6135345
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/useViewportApi.ts
@@ -0,0 +1,81 @@
+import type { FitParams, Rect, Viewport, ViewportApi, ViewportContext, XYPosition } from './types';
+import { clampZoom, fitViewTransform, zoomAtPointer } from './utils';
+
+/**
+ * Builds the imperative {@link ViewportApi} over a {@link ViewportContext}.
+ *
+ * Every write funnels through `ctx.clampViewport`, so the resulting viewport
+ * always honours `minZoom`/`maxZoom` and the translate extent regardless of the
+ * entry point. Zoom helpers anchor at the surface centre (the imperative analogue
+ * of zoom-at-pointer). `fit`/`center` honour the surface `width === 0` /
+ * `height === 0` early-return — a not-yet-measured surface has no meaningful
+ * centre and a `0 / 0` zoom would be `NaN`.
+ *
+ * @param ctx The viewport context.
+ * @returns The imperative control surface.
+ */
+export function useViewportApi(ctx: ViewportContext): ViewportApi {
+  /** Surface centre in surface-local pixels. */
+  function center(): XYPosition {
+    const rect = ctx.surfaceRect.value;
+    return { x: rect.width / 2, y: rect.height / 2 };
+  }
+
+  function write(vp: Viewport): void {
+    ctx.viewport.value = ctx.clampViewport(vp);
+  }
+
+  function zoomToLevel(zoom: number, anchor: XYPosition): void {
+    const vp = ctx.viewport.value;
+    const next = clampZoom(zoom, ctx.minZoom.value, ctx.maxZoom.value);
+    write(zoomAtPointer(vp, next, anchor));
+  }
+
+  function zoomBy(factor: number): void {
+    zoomToLevel(ctx.viewport.value.zoom * factor, center());
+  }
+
+  return {
+    getViewport: () => ctx.viewport.value,
+    setViewport: vp => write(vp),
+    zoomIn: (factor = 1.2) => zoomBy(factor),
+    zoomOut: (factor = 1.2) => zoomBy(1 / factor),
+    zoomTo: zoom => zoomToLevel(zoom, center()),
+    zoomToPoint: (zoom, point) => zoomToLevel(zoom, point),
+    fit: (bounds?: Rect | null, params: FitParams = {}) => {
+      const target = bounds ?? ctx.contentExtent.value;
+      // Explicit no-op when there is nothing to fit (no argument and no extent).
+      if (!target) return;
+      const rect = ctx.surfaceRect.value;
+      if (rect.width === 0 || rect.height === 0) return;
+      write(fitViewTransform(target, { width: rect.width, height: rect.height }, {
+        padding: params.padding ?? ctx.fitPadding.value,
+        minZoom: params.minZoom ?? ctx.minZoom.value,
+        maxZoom: params.maxZoom ?? ctx.maxZoom.value,
+      }));
+    },
+    center: (point?: XYPosition) => {
+      const rect = ctx.surfaceRect.value;
+      if (rect.width === 0 || rect.height === 0) return;
+      const vp = ctx.viewport.value;
+      // Default target: the content point currently under the surface centre, so
+      // a no-arg `center()` is a stable identity (re-centres on itself).
+      const target = point ?? {
+        x: (rect.width / 2 - vp.x) / vp.zoom,
+        y: (rect.height / 2 - vp.y) / vp.zoom,
+      };
+      write({
+        zoom: vp.zoom,
+        x: rect.width / 2 - target.x * vp.zoom,
+        y: rect.height / 2 - target.y * vp.zoom,
+      });
+    },
+    panBy: (dx, dy) => {
+      const vp = ctx.viewport.value;
+      write({ zoom: vp.zoom, x: vp.x + dx, y: vp.y + dy });
+    },
+    reset: () => write({ x: 0, y: 0, zoom: 1 }),
+    screenToContent: point => ctx.screenToContent(point),
+    contentToScreen: point => ctx.contentToScreen(point),
+  };
+}
diff --git a/vue/primitives/src/canvas/zoom-pan/useZoomPan.ts b/vue/primitives/src/canvas/zoom-pan/useZoomPan.ts
new file mode 100644
index 0000000..c821614
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/useZoomPan.ts
@@ -0,0 +1,285 @@
+import type { Ref } from 'vue';
+import { computed, onScopeDispose, shallowRef } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import type { DragAxis } from '../../internal/pointer-drag';
+import type { Viewport, ViewportContext, ZoomPanAxis, ZoomPanOptions } from './types';
+import { clampZoom, wheelToZoomFactor, zoomAtPointer } from './utils';
+
+/** Return value of {@link useZoomPan}. */
+export interface UseZoomPanReturn {
+  /** True while a drag-pan / scroll-pan gesture is active. */
+  isPanning: Readonly<Ref<boolean>>;
+  /** True while a wheel / pinch / dblclick zoom gesture is active. */
+  isZooming: Readonly<Ref<boolean>>;
+}
+
+/** Map the public `'xy' | 'x' | 'y'` axis onto `usePointerDrag`'s `DragAxis`. */
+function toDragAxis(axis: ZoomPanAxis): DragAxis {
+  return axis === 'xy' ? 'both' : axis;
+}
+
+/** True when the activation key (if any) is held for the given event. */
+function activationHeld(event: WheelEvent, key: ZoomPanOptions['zoomActivationKey']): boolean {
+  switch (key) {
+    case null:
+    case undefined: return true;
+    case 'Alt': return event.altKey;
+    case 'Control': return event.ctrlKey;
+    case 'Meta': return event.metaKey;
+    case 'Shift': return event.shiftKey;
+  }
+}
+
+const EDITABLE = /^(?:input|textarea|select)$/i;
+
+/**
+ * Unit pan directions per arrow key (screen-space, before `step` scaling).
+ * Module-scope so the keydown handler allocates nothing on the non-arrow miss
+ * path and never rebuilds the table per event during OS key-repeat panning.
+ */
+const ARROW_UNITS: Record<string, readonly [number, number]> = {
+  ArrowUp: [0, 1],
+  ArrowDown: [0, -1],
+  ArrowLeft: [1, 0],
+  ArrowRight: [-1, 0],
+};
+
+/** True when focus is in a text field, so global shortcuts must stand down. */
+function isTyping(): boolean {
+  const el = document.activeElement as HTMLElement | null;
+  return !!el && (EDITABLE.test(el.tagName) || el.isContentEditable);
+}
+
+/**
+ * Wires wheel zoom-at-pointer, pinch, optional scroll-pan, drag-pan, double-click
+ * zoom, and a keyboard pan/zoom layer onto `target`, writing the master
+ * `ctx.viewport` through one RAF-batched flush per frame so a burst of
+ * wheel/pointer events never causes more than one layout write. Every scheduled
+ * value passes through axis-lock + `ctx.clampViewport`.
+ *
+ * Generalised from flow's `usePanZoom`: reads/writes a plain `Ref<Viewport>`
+ * (via the context) and is parameterised by `axis` + constraints rather than
+ * being bound to a flow graph. Crucially, `wheel` only `preventDefault`s when it
+ * actually consumes the delta — so an axis-locked or boundary-clamped surface
+ * embedded in a scrollable page does not swallow page scroll it ignored.
+ *
+ * @param target The interaction surface element (ref).
+ * @param ctx The viewport context.
+ * @param options Behaviour switches (usually `ctx.options.value`).
+ * @returns `{ isPanning, isZooming }`.
+ */
+export function useZoomPan(
+  target: Ref<HTMLElement | undefined>,
+  ctx: ViewportContext,
+  options: ZoomPanOptions = {},
+): UseZoomPanReturn {
+  const opts = computed<Required<Pick<ZoomPanOptions,
+    'axis' | 'panOnDrag' | 'zoomOnScroll' | 'zoomOnPinch' | 'panOnScroll' | 'panOnScrollSpeed'
+    | 'zoomOnDoubleClick' | 'doubleClickZoomFactor' | 'disabled' | 'disableKeyboard' | 'keyboardPanStep'>>
+    & Pick<ZoomPanOptions, 'zoomActivationKey'>>(() => ({
+    axis: options.axis ?? ctx.axis.value,
+    panOnDrag: options.panOnDrag ?? true,
+    zoomOnScroll: options.zoomOnScroll ?? true,
+    zoomOnPinch: options.zoomOnPinch ?? true,
+    panOnScroll: options.panOnScroll ?? false,
+    panOnScrollSpeed: options.panOnScrollSpeed ?? 0.5,
+    zoomOnDoubleClick: options.zoomOnDoubleClick ?? true,
+    doubleClickZoomFactor: options.doubleClickZoomFactor ?? 1.2,
+    zoomActivationKey: options.zoomActivationKey ?? null,
+    disabled: options.disabled ?? false,
+    disableKeyboard: options.disableKeyboard ?? false,
+    keyboardPanStep: options.keyboardPanStep ?? 20,
+  }));
+
+  /** Master enable: locked when the root is non-interactive or `disabled`. */
+  function enabled(): boolean {
+    return ctx.interactive.value && !opts.value.disabled;
+  }
+
+  const isPanning = shallowRef(false);
+  const isZooming = shallowRef(false);
+
+  // ── axis lock + clamp helper ──────────────────────────────────────────────
+  /**
+   * Apply the axis lock against `base` (so a locked axis keeps its current
+   * value), then clamp. Every scheduled viewport goes through here.
+   */
+  function constrain(next: Viewport, base: Viewport): Viewport {
+    const axis = opts.value.axis;
+    const locked: Viewport = {
+      zoom: next.zoom,
+      x: axis === 'y' ? base.x : next.x,
+      y: axis === 'x' ? base.y : next.y,
+    };
+    return ctx.clampViewport(locked);
+  }
+
+  // ── RAF-batched viewport writes ───────────────────────────────────────────
+  let rafId: number | null = null;
+  let pending: Viewport | null = null;
+
+  function flush(): void {
+    rafId = null;
+    if (pending) {
+      ctx.viewport.value = pending;
+      pending = null;
+    }
+  }
+
+  function schedule(next: Viewport, base: Viewport): void {
+    pending = constrain(next, base);
+    if (rafId === null) rafId = requestAnimationFrame(flush);
+  }
+
+  /** Latest known viewport, including any not-yet-flushed pending value. */
+  function current(): Viewport {
+    return pending ?? ctx.viewport.value;
+  }
+
+  function surfaceOffset(event: { clientX: number; clientY: number }): { x: number; y: number } {
+    const rect = ctx.surfaceRect.value;
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  }
+
+  // ── wheel (zoom-at-pointer / scroll-pan / pinch) ──────────────────────────
+  useEventListener(target, 'wheel', (event: WheelEvent) => {
+    if (!enabled()) return;
+    const o = opts.value;
+
+    const pinch = event.ctrlKey;
+    const wantZoom = pinch
+      ? o.zoomOnPinch
+      // Plain scroll zooms only when (a) configured, (b) not in pan-on-scroll
+      // mode, and (c) the activation key (if any) is held.
+      : o.zoomOnScroll && !o.panOnScroll && activationHeld(event, o.zoomActivationKey);
+
+    if (wantZoom) {
+      const vp = current();
+      const factor = wheelToZoomFactor(event);
+      const newZoom = clampZoom(vp.zoom * factor, ctx.minZoom.value, ctx.maxZoom.value);
+      // Boundary: at min/max zoom the gesture is a no-op — DON'T preventDefault,
+      // so an embedded surface lets the page scroll past the zoom limit.
+      if (newZoom === vp.zoom) return;
+      event.preventDefault();
+      isZooming.value = true;
+      schedule(zoomAtPointer(vp, newZoom, surfaceOffset(event)), vp);
+      return;
+    }
+
+    if (o.panOnScroll) {
+      const vp = current();
+      const next = constrain({
+        zoom: vp.zoom,
+        x: vp.x - event.deltaX * o.panOnScrollSpeed,
+        y: vp.y - event.deltaY * o.panOnScrollSpeed,
+      }, vp);
+      // Boundary: if the clamp/axis-lock left the viewport unchanged we consumed
+      // nothing — let the page scroll instead of silently swallowing the wheel.
+      if (next.x === vp.x && next.y === vp.y) return;
+      event.preventDefault();
+      isPanning.value = true;
+      pending = next;
+      if (rafId === null) rafId = requestAnimationFrame(flush);
+    }
+    // else: scroll not consumed → no preventDefault, page scrolls normally.
+  }, { passive: false });
+
+  // ── drag-pan (via usePointerDrag) ─────────────────────────────────────────
+  let dragBase: Viewport = { x: 0, y: 0, zoom: 1 };
+  const drag = usePointerDrag(target, {
+    axis: toDragAxis(opts.value.axis),
+    threshold: 0,
+    buttons: [0, 1],
+    disabled: () => !enabled() || !opts.value.panOnDrag,
+    preventDefault: false,
+    onStart: () => {
+      dragBase = current();
+      isPanning.value = true;
+    },
+    onMove: (state) => {
+      // `state.total` already has the drag axis lock applied by usePointerDrag;
+      // map the screen delta straight onto the viewport translate.
+      schedule({
+        zoom: dragBase.zoom,
+        x: dragBase.x + state.total.x,
+        y: dragBase.y + state.total.y,
+      }, dragBase);
+    },
+    onEnd: () => {
+      isPanning.value = false;
+    },
+  });
+
+  // ── double-click zoom ─────────────────────────────────────────────────────
+  useEventListener(target, 'dblclick', (event: MouseEvent) => {
+    if (!enabled() || !opts.value.zoomOnDoubleClick) return;
+    const vp = current();
+    const newZoom = clampZoom(vp.zoom * opts.value.doubleClickZoomFactor, ctx.minZoom.value, ctx.maxZoom.value);
+    if (newZoom === vp.zoom) return;
+    event.preventDefault();
+    isZooming.value = true;
+    schedule(zoomAtPointer(vp, newZoom, surfaceOffset(event)), vp);
+  });
+
+  // ── keyboard pan/zoom ─────────────────────────────────────────────────────
+  useEventListener(target, 'keydown', (event: KeyboardEvent) => {
+    if (!enabled() || opts.value.disableKeyboard || isTyping()) return;
+    const step = event.shiftKey ? opts.value.keyboardPanStep * 4 : opts.value.keyboardPanStep;
+
+    // Escape cancels an in-flight drag-pan.
+    if (event.key === 'Escape') {
+      if (drag.isDragging.value) {
+        drag.cancel();
+        isPanning.value = false;
+      }
+      return;
+    }
+
+    const axis = opts.value.axis;
+    const unit = ARROW_UNITS[event.key];
+    if (unit) {
+      const dx = unit[0] * step;
+      const dy = unit[1] * step;
+      // Respect axis lock: ignore the keypress entirely on the locked axis.
+      if ((axis === 'y' && dx !== 0) || (axis === 'x' && dy !== 0)) return;
+      event.preventDefault();
+      const vp = current();
+      schedule({ zoom: vp.zoom, x: vp.x + dx, y: vp.y + dy }, vp);
+      return;
+    }
+
+    // Zoom: +/= in, - out, 0 actual size (zoom 1), Home reset.
+    if (event.key === '+' || event.key === '=') {
+      event.preventDefault();
+      isZooming.value = true;
+      ctx.api.zoomIn();
+      return;
+    }
+    if (event.key === '-' || event.key === '_') {
+      event.preventDefault();
+      isZooming.value = true;
+      ctx.api.zoomOut();
+      return;
+    }
+    if (event.key === '0') {
+      event.preventDefault();
+      isZooming.value = true;
+      ctx.api.zoomTo(1);
+      return;
+    }
+    if (event.key === 'Home') {
+      event.preventDefault();
+      ctx.api.reset();
+    }
+  });
+
+  onScopeDispose(() => {
+    if (rafId !== null) cancelAnimationFrame(rafId);
+    // usePointerDrag releases its own capture on scope dispose; cancel any
+    // in-flight gesture too so a release happens even mid-drag.
+    drag.cancel();
+  });
+
+  return { isPanning, isZooming };
+}
diff --git a/vue/primitives/src/canvas/zoom-pan/utils.ts b/vue/primitives/src/canvas/zoom-pan/utils.ts
new file mode 100644
index 0000000..79bac55
--- /dev/null
+++ b/vue/primitives/src/canvas/zoom-pan/utils.ts
@@ -0,0 +1,206 @@
+import { clamp } from '@robonen/stdlib';
+import type {
+  Dimensions,
+  FitViewportOptions,
+  Rect,
+  SurfaceOrigin,
+  Viewport,
+  ViewportConstraints,
+  XYPosition,
+} from './types';
+
+/** Re-exported so zoom-pan code has one import surface for clamping. */
+export { clamp };
+
+/**
+ * Convert a screen (client) point to content space.
+ *
+ * Inverse of {@link contentToScreen}. The client point must have the surface's
+ * `left`/`top` subtracted first, then the viewport translation removed and the
+ * zoom divided out. On the pointer hot path — no allocations beyond the result.
+ *
+ * @param point Client (screen) point.
+ * @param vp Current viewport transform.
+ * @param surfaceRect Surface origin (`left`/`top`).
+ * @returns The point in content space.
+ */
+export function screenToContent(point: XYPosition, vp: Viewport, surfaceRect: SurfaceOrigin): XYPosition {
+  return {
+    x: (point.x - surfaceRect.left - vp.x) / vp.zoom,
+    y: (point.y - surfaceRect.top - vp.y) / vp.zoom,
+  };
+}
+
+/**
+ * Convert a content-space point to a screen (client) point. Inverse of
+ * {@link screenToContent}.
+ *
+ * @param point Content-space point.
+ * @param vp Current viewport transform.
+ * @param surfaceRect Surface origin (`left`/`top`).
+ * @returns The point in client (screen) space.
+ */
+export function contentToScreen(point: XYPosition, vp: Viewport, surfaceRect: SurfaceOrigin): XYPosition {
+  return {
+    x: point.x * vp.zoom + vp.x + surfaceRect.left,
+    y: point.y * vp.zoom + vp.y + surfaceRect.top,
+  };
+}
+
+/**
+ * New viewport that keeps the content point under `pointer` (surface-relative
+ * pixels) fixed on screen while the zoom changes to `nextZoom`. Caller is
+ * expected to clamp `nextZoom` first via {@link clampZoom}.
+ *
+ * @param vp Current viewport.
+ * @param nextZoom Target zoom level (already clamped).
+ * @param pointer Surface-relative pixel point to keep anchored.
+ * @param surfaceRect Surface origin (`left`/`top`); when `pointer` is already
+ *   surface-relative pass `{ left: 0, top: 0 }`.
+ * @returns The anchored viewport.
+ */
+export function zoomAtPointer(
+  vp: Viewport,
+  nextZoom: number,
+  pointer: XYPosition,
+  surfaceRect: SurfaceOrigin = { left: 0, top: 0 },
+): Viewport {
+  // Pointer in surface-local pixels (the math assumes the surface origin is 0,0).
+  const px = pointer.x - surfaceRect.left;
+  const py = pointer.y - surfaceRect.top;
+  const ratio = nextZoom / vp.zoom;
+  return {
+    zoom: nextZoom,
+    x: px - (px - vp.x) * ratio,
+    y: py - (py - vp.y) * ratio,
+  };
+}
+
+/**
+ * Multiplicative zoom factor for a wheel event, normalising the three
+ * `deltaMode` units and amplifying trackpad pinch (`ctrlKey`). Multiply the
+ * current zoom by the result.
+ *
+ * @param event The wheel event.
+ * @returns The factor to multiply the current zoom by.
+ */
+export function wheelToZoomFactor(event: WheelEvent): number {
+  const unit = event.deltaMode === 1 ? 0.05 : event.deltaMode ? 1 : 0.002;
+  const delta = -event.deltaY * unit * (event.ctrlKey ? 10 : 1);
+  return 2 ** delta;
+}
+
+/**
+ * Clamp a zoom level to `[min, max]`.
+ *
+ * @param zoom Candidate zoom.
+ * @param min Minimum zoom.
+ * @param max Maximum zoom.
+ * @returns The clamped zoom.
+ */
+export function clampZoom(zoom: number, min: number, max: number): number {
+  return clamp(zoom, min, max);
+}
+
+/**
+ * Clamp one axis of the viewport translation to `[min, max]`. When the interval
+ * is degenerate (`min > max` — the content is smaller than the surface on this
+ * axis, so there is no room to pan) the value is CENTRED at `(min + max) / 2`
+ * instead of pinned to a boundary, which would otherwise make the content
+ * oscillate against the edge.
+ */
+function clampTranslateAxis(value: number, min: number | undefined, max: number | undefined): number {
+  if (min === undefined && max === undefined) return value;
+  if (min !== undefined && max !== undefined) {
+    if (min > max) return (min + max) / 2;
+    return clamp(value, min, max);
+  }
+  if (min !== undefined) return Math.max(value, min);
+  return Math.min(value, max!);
+}
+
+/**
+ * Clamp a candidate viewport: first the zoom to `[minZoom, maxZoom]`, then —
+ * when a `translateExtent` is supplied — each translate axis. See
+ * {@link clampTranslateAxis} for the degenerate-interval centring rule.
+ *
+ * @param vp Candidate viewport.
+ * @param constraints Zoom bounds and optional translate extent.
+ * @returns The clamped viewport (a new object; never mutates `vp`).
+ */
+export function clampViewport(vp: Viewport, constraints: ViewportConstraints): Viewport {
+  const zoom = clampZoom(vp.zoom, constraints.minZoom, constraints.maxZoom);
+  const extent = constraints.translateExtent;
+  if (!extent) return { zoom, x: vp.x, y: vp.y };
+  return {
+    zoom,
+    x: clampTranslateAxis(vp.x, extent.minX, extent.maxX),
+    y: clampTranslateAxis(vp.y, extent.minY, extent.maxY),
+  };
+}
+
+/**
+ * Viewport that fits `contentBounds` inside a `surface` of the given size,
+ * centred, with `padding`. Zoom is clamped to `[minZoom, maxZoom]`. No-ops
+ * (returns an identity-ish viewport) when the surface or the bounds is
+ * zero-sized — there is nothing meaningful to fit.
+ *
+ * @param contentBounds Bounds to fit, in content space.
+ * @param surface Surface size in client px.
+ * @param opts Padding and zoom clamp.
+ * @returns The fitting viewport.
+ */
+export function fitViewTransform(
+  contentBounds: Rect,
+  surface: Dimensions,
+  opts: FitViewportOptions = {},
+): Viewport {
+  const padding = opts.padding ?? 0.1;
+  const minZoom = opts.minZoom ?? 0;
+  const maxZoom = opts.maxZoom ?? Infinity;
+  const { width: cw, height: ch } = surface;
+
+  // Early no-op: a zero-sized surface or zero-sized bounds has no fit.
+  if (cw === 0 || ch === 0 || contentBounds.width === 0 || contentBounds.height === 0)
+    return { x: 0, y: 0, zoom: clamp(1, minZoom, maxZoom) };
+
+  const bw = contentBounds.width;
+  const bh = contentBounds.height;
+
+  const zoom = clamp(Math.min(cw / bw, ch / bh) * (1 - padding), minZoom, maxZoom);
+  const centerX = contentBounds.x + contentBounds.width / 2;
+  const centerY = contentBounds.y + contentBounds.height / 2;
+
+  return {
+    zoom,
+    x: cw / 2 - centerX * zoom,
+    y: ch / 2 - centerY * zoom,
+  };
+}
+
+/**
+ * Measure a DOM element's rect back into content space.
+ *
+ * `getBoundingClientRect()` returns the element's *rendered* (post-`scale`)
+ * geometry; to recover the underlying content-space rect each dimension is
+ * divided by the current `zoom`, and the position is converted through
+ * {@link screenToContent} (this is the `getHandleBoundsFromDom` gotcha from
+ * flow — a measured rect is in screen px and must have the zoom divided out
+ * before it can be reasoned about in content space). Called once per
+ * measurement, never per frame.
+ *
+ * @param el The element to measure.
+ * @param vp Current viewport.
+ * @param surfaceRect Surface origin (`left`/`top`).
+ * @returns The element's rect in content space.
+ */
+export function measureContentRect(el: HTMLElement, vp: Viewport, surfaceRect: SurfaceOrigin): Rect {
+  const rect = el.getBoundingClientRect();
+  const topLeft = screenToContent({ x: rect.left, y: rect.top }, vp, surfaceRect);
+  return {
+    x: topLeft.x,
+    y: topLeft.y,
+    width: rect.width / vp.zoom,
+    height: rect.height / vp.zoom,
+  };
+}
diff --git a/vue/primitives/src/checkbox/CheckboxRoot.vue b/vue/primitives/src/checkbox/CheckboxRoot.vue
deleted file mode 100644
index 16d4613..0000000
--- a/vue/primitives/src/checkbox/CheckboxRoot.vue
+++ /dev/null
@@ -1,119 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { CheckedState } from './context';
-
-/**
- * A toggleable control with checked, unchecked, and `'indeterminate'` states,
- * built on a native `<button role="checkbox">`. The interactive root: it owns
- * the checked state (controlled via `v-model:checked` or uncontrolled via
- * `defaultChecked`), handles toggling, exposes a hidden form input when `name`
- * is set, and provides context to `CheckboxIndicator`. Use it whenever you need
- * a styled checkbox that integrates with forms or supports a mixed/partial state.
- */
-export interface CheckboxRootProps extends PrimitiveProps {
-  /** Uncontrolled initial checked state. */
-  defaultChecked?: CheckedState;
-  /** Disable interaction. */
-  disabled?: boolean;
-  /** Mark associated hidden input as required. */
-  required?: boolean;
-  /** Hidden input name attribute. */
-  name?: string;
-  /** Hidden input value attribute. @default 'on' */
-  value?: string;
-}
-
-export interface CheckboxRootEmits {
-  checkedChange: [value: CheckedState];
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed, ref, toRef } from 'vue';
-import { provideCheckboxContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
-
-const { disabled = false, required = false, value = 'on', defaultChecked, name, as = 'button' } = defineProps<CheckboxRootProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const emit = defineEmits<CheckboxRootEmits>();
-
-const localChecked = ref<CheckedState>(defaultChecked ?? false);
-
-// `defineModel` handles both controlled (parent `v-model:checked`) and
-// uncontrolled modes; `localChecked` backs the uncontrolled state seeded from
-// `defaultChecked`. `checkedChange` is a separate public emit, so it stays.
-const checked = defineModel<CheckedState | undefined>('checked', {
-  default: undefined,
-  get: v => v ?? localChecked.value,
-  set: (v) => {
-    localChecked.value = v as CheckedState;
-    return v;
-  },
-});
-
-function setChecked(v: CheckedState): void {
-  checked.value = v;
-  emit('checkedChange', v);
-}
-
-function toggle(): void {
-  if (disabled) return;
-  setChecked(checked.value !== true);
-}
-
-function onKeyDown(event: KeyboardEvent): void {
-  // Prevent form submit on Enter when inside a form.
-  if (event.key === 'Enter') event.preventDefault();
-  // <button> handles Space natively; synthesize toggle only for non-button hosts.
-  if (as !== 'button' && event.key === ' ') {
-    event.preventDefault();
-    toggle();
-  }
-}
-
-// Read through the model so the context reflects both controlled (parent
-// `v-model:checked`) and uncontrolled state; coalesce the model's `undefined`
-// default to `false`. `toRef(() => disabled)` gives a reactive identity
-// passthrough without `ReactiveEffect`/cache.
-const checkedState = computed<CheckedState>(() => checked.value ?? false);
-
-provideCheckboxContext({
-  checked: checkedState,
-  disabled: toRef(() => disabled),
-});
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    :type="as === 'button' ? 'button' : undefined"
-    :tabindex="as === 'button' ? undefined : (disabled ? -1 : 0)"
-    role="checkbox"
-    :aria-checked="checkedState === 'indeterminate' ? 'mixed' : checkedState"
-    :aria-required="required || undefined"
-    :aria-disabled="disabled || undefined"
-    :data-state="checkedState === 'indeterminate' ? 'indeterminate' : (checkedState ? 'checked' : 'unchecked')"
-    :data-disabled="disabled ? '' : undefined"
-    :disabled="disabled || undefined"
-    @click="toggle"
-    @keydown="onKeyDown"
-  >
-    <slot :checked="checkedState" />
-    <input
-      v-if="name"
-      type="checkbox"
-      tabindex="-1"
-      aria-hidden="true"
-      :name="name"
-      :value="value"
-      :checked="checkedState === true"
-      :required="required"
-      :disabled="disabled"
-      style="position: absolute; pointer-events: none; opacity: 0; margin: 0; transform: translateX(-100%);"
-    >
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/checkbox/context.ts b/vue/primitives/src/checkbox/context.ts
deleted file mode 100644
index 34d2014..0000000
--- a/vue/primitives/src/checkbox/context.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import type { Ref } from 'vue';
-import { useContextFactory } from '@robonen/vue';
-
-export type CheckedState = boolean | 'indeterminate';
-
-export interface CheckboxContext {
-  checked: Ref<CheckedState>;
-  disabled: Ref<boolean>;
-}
-
-const ctx = useContextFactory<CheckboxContext>('CheckboxContext');
-
-export const provideCheckboxContext = ctx.provide;
-export const useCheckboxContext = ctx.inject;
diff --git a/vue/primitives/src/checkbox/index.ts b/vue/primitives/src/checkbox/index.ts
deleted file mode 100644
index d141a6e..0000000
--- a/vue/primitives/src/checkbox/index.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-export { default as CheckboxIndicator } from './CheckboxIndicator.vue';
-export { default as CheckboxRoot } from './CheckboxRoot.vue';
-export type { CheckedState } from './context';
-export type { CheckboxIndicatorProps } from './CheckboxIndicator.vue';
-export type { CheckboxRootEmits, CheckboxRootProps } from './CheckboxRoot.vue';
diff --git a/vue/primitives/src/collapsible/CollapsibleContent.vue b/vue/primitives/src/collapsible/CollapsibleContent.vue
deleted file mode 100644
index a5f2d56..0000000
--- a/vue/primitives/src/collapsible/CollapsibleContent.vue
+++ /dev/null
@@ -1,41 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The panel revealed when the collapsible is open. Mounts and unmounts with
- * the open state (via `Presence`), is referenced by the trigger's
- * `aria-controls`, and is hidden from layout and assistive tech while closed.
- */
-export interface CollapsibleContentProps extends PrimitiveProps {
-
-  /** Render the content even when closed (useful for animation control). */
-  forceMount?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
-import { useCollapsibleContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
-
-const { as = 'div', forceMount = false } = defineProps<CollapsibleContentProps>();
-
-const { forwardRef } = useForwardExpose();
-const ctx = useCollapsibleContext();
-</script>
-
-<template>
-  <Presence :present="forceMount || ctx.open.value">
-    <Primitive
-      :ref="forwardRef"
-      :id="ctx.contentId.value"
-      :as="as"
-      :data-state="ctx.open.value ? 'open' : 'closed'"
-      :data-disabled="ctx.disabled.value ? '' : undefined"
-      :hidden="!ctx.open.value ? true : undefined"
-    >
-      <slot :open="ctx.open.value" />
-    </Primitive>
-  </Presence>
-</template>
diff --git a/vue/primitives/src/collapsible/__test__/Collapsible.test.ts b/vue/primitives/src/collapsible/__test__/Collapsible.test.ts
deleted file mode 100644
index 9b174ae..0000000
--- a/vue/primitives/src/collapsible/__test__/Collapsible.test.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { defineComponent, h, nextTick } from 'vue';
-import { CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from '../index';
-
-function mountCollapsible(props: Record<string, unknown> = {}) {
-  return mount(defineComponent({
-    setup: () => () => h(CollapsibleRoot, props, {
-      default: () => [
-        h(CollapsibleTrigger, { class: 'trig' }, { default: () => 'Toggle' }),
-        h(CollapsibleContent, { class: 'c' }, { default: () => 'Body' }),
-      ],
-    }),
-  }));
-}
-
-describe('Collapsible', () => {
-  it('starts closed by default; trigger toggles state', async () => {
-    const w = mountCollapsible();
-    const trigger = w.find('.trig');
-    expect(trigger.attributes('aria-expanded')).toBe('false');
-    expect(w.find('.c').exists()).toBe(false);
-    await trigger.trigger('click');
-    expect(trigger.attributes('aria-expanded')).toBe('true');
-    expect(w.find('.c').exists()).toBe(true);
-  });
-
-  it('opens via defaultOpen', async () => {
-    const w = mountCollapsible({ defaultOpen: true });
-    await nextTick();
-    expect(w.find('.trig').attributes('aria-expanded')).toBe('true');
-    expect(w.find('.c').exists()).toBe(true);
-    expect(w.find('.c').text()).toBe('Body');
-  });
-
-  it('wires aria-controls to content id', async () => {
-    const w = mountCollapsible({ defaultOpen: true });
-    await nextTick();
-    const id = w.find('.c').attributes('id');
-    expect(id).toMatch(/collapsible-content/);
-    expect(w.find('.trig').attributes('aria-controls')).toBe(id);
-  });
-
-  it('respects disabled', async () => {
-    const w = mountCollapsible({ disabled: true });
-    await w.find('.trig').trigger('click');
-    expect(w.find('.trig').attributes('aria-expanded')).toBe('false');
-    expect(w.find('.trig').attributes('data-disabled')).toBe('');
-  });
-
-  it('forceMount keeps content in DOM when closed', () => {
-    const w = mount(defineComponent({
-      setup: () => () => h(CollapsibleRoot, null, {
-        default: () => [
-          h(CollapsibleTrigger, { class: 'trig' }),
-          h(CollapsibleContent, { class: 'c', forceMount: true }, { default: () => 'Body' }),
-        ],
-      }),
-    }));
-    const content = w.find('.c');
-    expect(content.exists()).toBe(true);
-    expect(content.attributes('hidden')).toBeDefined();
-    expect(content.attributes('data-state')).toBe('closed');
-  });
-});
diff --git a/vue/primitives/src/color/alpha-slider/AlphaSliderRoot.vue b/vue/primitives/src/color/alpha-slider/AlphaSliderRoot.vue
new file mode 100644
index 0000000..ffe73ec
--- /dev/null
+++ b/vue/primitives/src/color/alpha-slider/AlphaSliderRoot.vue
@@ -0,0 +1,137 @@
+<script lang="ts">
+import type { AlphaSliderDirection, AlphaSliderOrientation } from './context';
+import type { HSVA } from '../../internal/color';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A 1D slider for picking the alpha (opacity, `0–1`) of a colour. It works
+ * standalone — owning its own `HSVA` via `v-model` / `defaultValue` — or, when
+ * nested inside a `ColorFieldRoot`, reads and writes that shared colour so the
+ * whole picker cluster stays in sync. Mirrors the standard slider anatomy: the
+ * root owns the value, maps pointer drags along the track, handles arrow / Page
+ * / Home / End keys, and provides context to `AlphaSliderThumb`. The background
+ * should be a checkerboard overlaid with an opaque→transparent colour gradient;
+ * style it via the exposed slot/`data-*` hooks. Reach for it as the opacity rail
+ * of a colour picker.
+ */
+export interface AlphaSliderRootProps extends PrimitiveProps {
+  /** Uncontrolled initial colour. @default { h: 0, s: 1, v: 1, a: 1 } */
+  defaultValue?: HSVA;
+  /** Keyboard step in alpha units. @default 0.01 */
+  step?: number;
+  /** Large-step multiplier (Page keys / Shift+Arrow). @default 10 */
+  largeStep?: number;
+  /** Orientation. @default 'horizontal' */
+  orientation?: AlphaSliderOrientation;
+  /** Writing direction (inherited from `ConfigProvider` when omitted). */
+  dir?: AlphaSliderDirection;
+  /** Disable interaction. @default false */
+  disabled?: boolean;
+}
+
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { clampChannel } from '../../internal/color';
+import { Primitive } from '../../internal/primitive';
+import { provideAlphaSliderContext } from './context';
+import { useColorState } from '../color-field/useColorState';
+import { useDirection } from '../../utilities/config-provider';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useForwardExpose } from '@robonen/vue';
+
+const {
+  defaultValue,
+  step = 0.01,
+  largeStep = 10,
+  orientation = 'horizontal',
+  dir,
+  disabled = false,
+  as = 'span',
+} = defineProps<AlphaSliderRootProps>();
+
+const direction = useDirection(() => dir);
+
+// shallowRef: HSVA is replaced wholesale by the setters, never mutated in place.
+const model = defineModel<HSVA | null>();
+const standalone = shallowRef<HSVA>(model.value ?? defaultValue ?? { h: 0, s: 1, v: 1, a: 1 });
+
+const standaloneState = computed<HSVA>({
+  get: () => standalone.value,
+  set: (v) => {
+    standalone.value = v;
+    model.value = v;
+  },
+});
+
+const colorState = useColorState(standaloneState, () => disabled);
+
+const alpha = computed(() => colorState.hsva.value.a);
+
+const trackRef = shallowRef<HTMLElement | null>(null);
+
+function setAlpha(next: number): void {
+  if (colorState.disabled.value) return;
+  colorState.setAlpha(clampChannel(next, 1));
+}
+
+function alphaFromPointer(clientCoord: { x: number; y: number }): number {
+  const track = trackRef.value;
+  if (!track) return alpha.value;
+  const rect = track.getBoundingClientRect();
+  const horizontal = orientation === 'horizontal';
+  const size = horizontal ? rect.width : rect.height;
+  if (size === 0) return alpha.value;
+  let offset = horizontal ? clientCoord.x - rect.left : clientCoord.y - rect.top;
+  const flip = horizontal ? direction.value === 'rtl' : true;
+  if (flip) offset = size - offset;
+  return clampChannel(offset / size, 1);
+}
+
+usePointerDrag(trackRef, {
+  axis: orientation === 'horizontal' ? 'x' : 'y',
+  threshold: 0,
+  trackElementRect: true,
+  disabled: () => colorState.disabled.value,
+  onStart: (state) => {
+    setAlpha(alphaFromPointer({ x: state.point.x, y: state.point.y }));
+  },
+  onMove: (state) => {
+    setAlpha(alphaFromPointer({ x: state.point.x, y: state.point.y }));
+  },
+});
+
+provideAlphaSliderContext({
+  hsva: colorState.hsva,
+  alpha,
+  step: toRef(() => step),
+  largeStep: toRef(() => largeStep),
+  orientation: toRef(() => orientation),
+  direction,
+  disabled: colorState.disabled,
+  labelId: colorState.labelId,
+  trackRef,
+  setAlpha,
+});
+
+defineExpose({ alpha });
+
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (node) => {
+  trackRef.value = node ?? null;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :dir="direction"
+    :aria-disabled="colorState.disabled.value || undefined"
+    :data-disabled="colorState.disabled.value ? '' : undefined"
+    :data-orientation="orientation"
+  >
+    <slot :alpha="alpha" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/alpha-slider/AlphaSliderThumb.vue b/vue/primitives/src/color/alpha-slider/AlphaSliderThumb.vue
new file mode 100644
index 0000000..4169a3d
--- /dev/null
+++ b/vue/primitives/src/color/alpha-slider/AlphaSliderThumb.vue
@@ -0,0 +1,126 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The draggable handle of an `AlphaSliderRoot`, rendered as `role="slider"`
+ * with full ARIA value attributes (`aria-valuemin="0"`, `aria-valuemax="1"`,
+ * `aria-valuenow` = current alpha, `aria-valuetext` = the alpha as a percent).
+ * It positions itself along the track by the alpha percentage and handles
+ * keyboard interaction (arrows step by `step`, Page Up/Down and Shift+Arrow by
+ * the large step, Home/End jump to `0`/`1`). Give it an `aria-label` or rely on
+ * the default `"Alpha"`. Exposes `alpha` and `percent` as slot props.
+ */
+export interface AlphaSliderThumbProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { computed, useAttrs } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useAlphaSliderContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'span' } = defineProps<AlphaSliderThumbProps>();
+const ctx = useAlphaSliderContext();
+const attrs = useAttrs();
+
+const alpha = computed(() => ctx.alpha.value);
+const percent = computed(() => alpha.value * 100);
+
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return ctx.labelId.value ? undefined : 'Alpha';
+});
+
+const valueText = computed(() => `${Math.round(alpha.value * 100)}%`);
+
+const positionStyle = computed<{
+  left: string | undefined;
+  right: string | undefined;
+  top: string | undefined;
+  bottom: string | undefined;
+}>(() => {
+  const pct = percent.value;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const rtl = ctx.direction.value === 'rtl';
+  if (horizontal) {
+    return {
+      left: rtl ? undefined : `${pct}%`,
+      right: rtl ? `${pct}%` : undefined,
+      top: undefined,
+      bottom: undefined,
+    };
+  }
+  return { left: undefined, right: undefined, top: undefined, bottom: `${pct}%` };
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const rtl = ctx.direction.value === 'rtl';
+  const step = ctx.step.value;
+  const big = step * ctx.largeStep.value;
+  const unit = event.shiftKey ? big : step;
+  const current = ctx.alpha.value;
+  let delta: number;
+  switch (event.key) {
+    case 'ArrowRight':
+      delta = horizontal ? (rtl ? -unit : unit) : 0;
+      break;
+    case 'ArrowLeft':
+      delta = horizontal ? (rtl ? unit : -unit) : 0;
+      break;
+    case 'ArrowUp':
+      delta = horizontal ? 0 : unit;
+      break;
+    case 'ArrowDown':
+      delta = horizontal ? 0 : -unit;
+      break;
+    case 'PageUp':
+      delta = big;
+      break;
+    case 'PageDown':
+      delta = -big;
+      break;
+    case 'Home':
+      event.preventDefault();
+      ctx.setAlpha(0);
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.setAlpha(1);
+      return;
+    default:
+      return;
+  }
+  if (delta === 0) return;
+  event.preventDefault();
+  ctx.setAlpha(current + delta);
+}
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
+    :aria-labelledby="!accessibleLabel ? ctx.labelId.value : undefined"
+    :aria-valuemin="0"
+    :aria-valuemax="1"
+    :aria-valuenow="alpha"
+    :aria-valuetext="valueText"
+    :aria-orientation="ctx.orientation.value"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :alpha="alpha" :percent="percent" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/alpha-slider/__test__/AlphaSlider.test.ts b/vue/primitives/src/color/alpha-slider/__test__/AlphaSlider.test.ts
new file mode 100644
index 0000000..04947fa
--- /dev/null
+++ b/vue/primitives/src/color/alpha-slider/__test__/AlphaSlider.test.ts
@@ -0,0 +1,110 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { HSVA } from '../../../internal/color';
+import { AlphaSliderRoot, AlphaSliderThumb } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false }));
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+function mountAlpha(opts: Partial<{ defaultValue: HSVA; step: number; disabled: boolean }> = {}) {
+  const model = ref<HSVA | undefined>(undefined);
+  const Harness = defineComponent({
+    setup: () => () => h(AlphaSliderRoot, {
+      modelValue: model.value,
+      'onUpdate:modelValue': (v: HSVA | null | undefined) => { model.value = v ?? undefined; },
+      ...opts,
+    }, { default: () => h(AlphaSliderThumb) }),
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+describe('AlphaSlider', () => {
+  it('thumb is role=slider with alpha aria-value*', async () => {
+    mountAlpha({ defaultValue: { h: 0, s: 1, v: 1, a: 0.5 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb).toBeTruthy();
+    expect(thumb.getAttribute('aria-valuemin')).toBe('0');
+    expect(thumb.getAttribute('aria-valuemax')).toBe('1');
+    expect(thumb.getAttribute('aria-valuenow')).toBe('0.5');
+    expect(thumb.getAttribute('aria-valuetext')).toBe('50%');
+    expect(thumb.getAttribute('aria-label')).toBe('Alpha');
+    expect(thumb.tabIndex).toBe(0);
+  });
+
+  it('ArrowRight / ArrowLeft step the alpha', async () => {
+    const { model } = mountAlpha({ defaultValue: { h: 0, s: 1, v: 1, a: 0.5 }, step: 0.1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(round(model.value!.a)).toBe(0.6);
+    keydown(thumb, 'ArrowLeft');
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(round(model.value!.a)).toBe(0.4);
+  });
+
+  it('Home / End clamp to 0 / 1', async () => {
+    const { model } = mountAlpha({ defaultValue: { h: 0, s: 1, v: 1, a: 0.5 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value!.a).toBe(0);
+    keydown(thumb, 'End');
+    await nextTick();
+    expect(model.value!.a).toBe(1);
+  });
+
+  it('clamps within [0, 1]', async () => {
+    const { model } = mountAlpha({ defaultValue: { h: 0, s: 1, v: 1, a: 0.95 }, step: 0.1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value!.a).toBe(1);
+  });
+
+  it('preserves hue / saturation / value while only changing alpha', async () => {
+    const { model } = mountAlpha({ defaultValue: { h: 100, s: 0.4, v: 0.6, a: 0.5 }, step: 0.1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value!.h).toBe(100);
+    expect(model.value!.s).toBe(0.4);
+    expect(model.value!.v).toBe(0.6);
+    expect(round(model.value!.a)).toBe(0.6);
+  });
+
+  it('disabled: tabindex=-1 and keys do nothing', async () => {
+    const { model } = mountAlpha({ defaultValue: { h: 0, s: 1, v: 1, a: 0.5 }, disabled: true });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.tabIndex).toBe(-1);
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+});
diff --git a/vue/primitives/src/color/alpha-slider/context.ts b/vue/primitives/src/color/alpha-slider/context.ts
new file mode 100644
index 0000000..a79f09e
--- /dev/null
+++ b/vue/primitives/src/color/alpha-slider/context.ts
@@ -0,0 +1,36 @@
+import type { Ref } from 'vue';
+import type { HSVA } from '../../internal/color';
+import { useContextFactory } from '@robonen/vue';
+
+export type AlphaSliderOrientation = 'horizontal' | 'vertical';
+export type AlphaSliderDirection = 'ltr' | 'rtl';
+
+/**
+ * Context shared between `AlphaSliderRoot` and `AlphaSliderThumb`.
+ *
+ * Scalar props are exposed as plain `Ref<T>` — `AlphaSliderRoot` builds them
+ * with `toRef(() => prop)` (a reactive getter ref without an extra effect).
+ */
+export interface AlphaSliderContext {
+  /** The canonical colour the slider reads its alpha from. */
+  hsva: Ref<HSVA>;
+  /** Current alpha (`0–1`). */
+  alpha: Ref<number>;
+  /** Step granularity for keyboard nudges. */
+  step: Ref<number>;
+  /** Large-step multiplier (Page keys / Shift+Arrow). */
+  largeStep: Ref<number>;
+  orientation: Ref<AlphaSliderOrientation>;
+  direction: Ref<AlphaSliderDirection>;
+  disabled: Ref<boolean>;
+  /** Accessible name id contributed by a `ColorFieldLabel`, if present. */
+  labelId: Ref<string | undefined>;
+  trackRef: Ref<HTMLElement | null>;
+  /** Set the alpha (`0–1`); clamped by the root. */
+  setAlpha: (alpha: number) => void;
+}
+
+const ctx = useContextFactory<AlphaSliderContext>('AlphaSliderContext');
+
+export const provideAlphaSliderContext = ctx.provide;
+export const useAlphaSliderContext = ctx.inject;
diff --git a/vue/primitives/src/color/alpha-slider/demo.vue b/vue/primitives/src/color/alpha-slider/demo.vue
new file mode 100644
index 0000000..761a37b
--- /dev/null
+++ b/vue/primitives/src/color/alpha-slider/demo.vue
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import type { HSVA } from '@robonen/primitives';
+import { AlphaSliderRoot, AlphaSliderThumb, hsvToRgb } from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+const color = ref<HSVA>({ h: 145, s: 0.85, v: 0.8, a: 0.6 });
+
+const rgb = computed(() => hsvToRgb(color.value));
+// Opaque end of the gradient (alpha → 1) and the live colour at the current alpha.
+const opaque = computed(() => `rgb(${rgb.value.r}, ${rgb.value.g}, ${rgb.value.b})`);
+const transparent = computed(() => `rgba(${rgb.value.r}, ${rgb.value.g}, ${rgb.value.b}, 0)`);
+const live = computed(() => `rgba(${rgb.value.r}, ${rgb.value.g}, ${rgb.value.b}, ${color.value.a})`);
+
+const gradient = computed(() => `linear-gradient(to right, ${transparent.value}, ${opaque.value})`);
+
+// Reusable checkerboard background for the rail and the preview chip.
+const CHECKER = {
+  backgroundImage:
+    'linear-gradient(45deg, #ccc 25%, transparent 25%), linear-gradient(-45deg, #ccc 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #ccc 75%), linear-gradient(-45deg, transparent 75%, #ccc 75%)',
+  backgroundSize: '10px 10px',
+  backgroundPosition: '0 0, 0 5px, 5px -5px, -5px 0',
+  backgroundColor: '#fff',
+} as const;
+</script>
+
+<template>
+  <div class="demo-card flex w-full max-w-sm flex-col gap-5 p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <span class="font-medium">Alpha</span>
+      <span class="font-mono text-fg-muted">{{ Math.round(color.a * 100) }}%</span>
+    </div>
+
+    <!-- The alpha rail: checkerboard underlay, gradient overlay; the root span IS the track -->
+    <AlphaSliderRoot
+      v-model="color"
+      class="relative block h-4 w-full touch-none select-none rounded-full border border-border shadow-(--shadow-card)"
+      :style="CHECKER"
+    >
+      <div
+        class="pointer-events-none absolute inset-0 rounded-full"
+        :style="{ backgroundImage: gradient }"
+      />
+      <AlphaSliderThumb
+        aria-label="Alpha"
+        class="absolute top-1/2 z-10 size-5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-md outline-none ring-1 ring-black/25 transition-[transform] focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+        :style="{ backgroundColor: live }"
+      />
+    </AlphaSliderRoot>
+
+    <div class="flex items-center gap-3 rounded-card bg-bg-inset p-3">
+      <span
+        class="size-9 shrink-0 overflow-hidden rounded-lg border border-border-strong"
+        :style="CHECKER"
+      >
+        <span class="block size-full" :style="{ backgroundColor: live }" />
+      </span>
+      <div class="flex flex-col text-sm leading-tight">
+        <span class="font-mono text-fg">{{ live }}</span>
+        <span class="font-mono text-xs text-fg-subtle">opacity {{ color.a.toFixed(2) }}</span>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/color/alpha-slider/index.ts b/vue/primitives/src/color/alpha-slider/index.ts
new file mode 100644
index 0000000..1d4c173
--- /dev/null
+++ b/vue/primitives/src/color/alpha-slider/index.ts
@@ -0,0 +1,11 @@
+export { default as AlphaSliderRoot } from './AlphaSliderRoot.vue';
+export { default as AlphaSliderThumb } from './AlphaSliderThumb.vue';
+export type { AlphaSliderRootProps } from './AlphaSliderRoot.vue';
+export type { AlphaSliderThumbProps } from './AlphaSliderThumb.vue';
+export {
+  type AlphaSliderContext,
+  type AlphaSliderDirection,
+  type AlphaSliderOrientation,
+  provideAlphaSliderContext,
+  useAlphaSliderContext,
+} from './context';
diff --git a/vue/primitives/src/color/color-area/ColorAreaRoot.vue b/vue/primitives/src/color/color-area/ColorAreaRoot.vue
new file mode 100644
index 0000000..657badb
--- /dev/null
+++ b/vue/primitives/src/color/color-area/ColorAreaRoot.vue
@@ -0,0 +1,156 @@
+<script lang="ts">
+import type { ColorAreaDirection } from './context';
+import type { HSVA } from '../../internal/color';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The 2D saturation/value square of a colour picker. The x-axis maps saturation
+ * (`0` at the left → `1` at the right) and the y-axis maps brightness/value
+ * (`1` at the top → `0` at the bottom). It works standalone — owning its own
+ * `HSVA` via `v-model` / `defaultValue` — or, nested inside a `ColorFieldRoot`,
+ * reads and writes that shared colour so the whole picker cluster stays in sync.
+ * A pointer press anywhere in the area sets saturation and brightness at once;
+ * the `--color-area-hue` CSS variable is exposed so the consumer can paint the
+ * full-saturation / full-value hue background. Provides context to
+ * `ColorAreaThumb`. Reach for it as the main square of a colour picker.
+ */
+export interface ColorAreaRootProps extends PrimitiveProps {
+  /** Uncontrolled initial colour. @default { h: 0, s: 1, v: 1, a: 1 } */
+  defaultValue?: HSVA;
+  /** Keyboard step for saturation/value nudges (`0–1`). @default 0.01 */
+  step?: number;
+  /** Large keyboard step (Shift+Arrow / Page keys, `0–1`). @default 0.1 */
+  largeStep?: number;
+  /** Writing direction (inherited from `ConfigProvider` when omitted). */
+  dir?: ColorAreaDirection;
+  /** Disable interaction. @default false */
+  disabled?: boolean;
+}
+
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { clampChannel, hsvToRgb } from '../../internal/color';
+import { Primitive } from '../../internal/primitive';
+import { provideColorAreaContext } from './context';
+import { useColorState } from '../color-field/useColorState';
+import { useDirection } from '../../utilities/config-provider';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useForwardExpose } from '@robonen/vue';
+
+const {
+  defaultValue,
+  step = 0.01,
+  largeStep = 0.1,
+  dir,
+  disabled = false,
+  as = 'div',
+} = defineProps<ColorAreaRootProps>();
+
+const direction = useDirection(() => dir);
+
+const model = defineModel<HSVA | null>();
+// shallowRef: the HSVA object is always replaced wholesale (setters build a fresh
+// `{ ...cur }`), never mutated channel-by-channel, so deep proxying {h,s,v,a} only
+// adds per-pointer-move proxy-get/track cost. Identity replacement still triggers.
+const standalone = shallowRef<HSVA>(model.value ?? defaultValue ?? { h: 0, s: 1, v: 1, a: 1 });
+
+const standaloneState = computed<HSVA>({
+  get: () => standalone.value,
+  set: (v) => {
+    standalone.value = v;
+    model.value = v;
+  },
+});
+
+const colorState = useColorState(standaloneState, () => disabled);
+
+const saturation = computed(() => colorState.hsva.value.s);
+const value = computed(() => colorState.hsva.value.v);
+const hue = computed(() => colorState.hsva.value.h);
+
+// Background hue colour at full saturation & value (consumer paints the
+// gradients over this via the exposed CSS variable / slot prop).
+const hueColor = computed(() => {
+  const { r, g, b } = hsvToRgb({ h: hue.value, s: 1, v: 1 });
+  return `rgb(${r}, ${g}, ${b})`;
+});
+
+const trackRef = shallowRef<HTMLElement | null>(null);
+
+function setSaturation(next: number): void {
+  if (colorState.disabled.value) return;
+  colorState.setSaturation(clampChannel(next, 1));
+}
+function setValue(next: number): void {
+  if (colorState.disabled.value) return;
+  colorState.setValue(clampChannel(next, 1));
+}
+
+// Rect cached for the duration of a gesture (snapshotted in `onStart`): the track
+// box cannot change mid-drag, so re-reading getBoundingClientRect() every onMove
+// frame is a needless forced reflow. A live read is the fallback.
+let gestureRect: DOMRect | undefined;
+
+function setFromPointer(clientCoord: { x: number; y: number }, rect?: DOMRect): void {
+  const r = rect ?? trackRef.value?.getBoundingClientRect();
+  if (!r || r.width === 0 || r.height === 0) return;
+  let sx = (clientCoord.x - r.left) / r.width;
+  // RTL flips the saturation axis.
+  if (direction.value === 'rtl') sx = 1 - sx;
+  // y-axis: top = full brightness (1), bottom = 0.
+  const vy = 1 - (clientCoord.y - r.top) / r.height;
+  colorState.setSaturationValue(clampChannel(sx, 1), clampChannel(vy, 1));
+}
+
+usePointerDrag(trackRef, {
+  axis: 'both',
+  threshold: 0,
+  disabled: () => colorState.disabled.value,
+  onStart: (state) => {
+    gestureRect = trackRef.value?.getBoundingClientRect();
+    setFromPointer({ x: state.point.x, y: state.point.y }, gestureRect);
+  },
+  onMove: (state) => {
+    setFromPointer({ x: state.point.x, y: state.point.y }, gestureRect);
+  },
+  onEnd: () => {
+    gestureRect = undefined;
+  },
+});
+
+provideColorAreaContext({
+  hsva: colorState.hsva,
+  saturation,
+  value,
+  step: toRef(() => step),
+  largeStep: toRef(() => largeStep),
+  direction,
+  disabled: colorState.disabled,
+  labelId: colorState.labelId,
+  trackRef,
+  setSaturation,
+  setValue,
+});
+
+defineExpose({ saturation, value, hue });
+
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (node) => {
+  trackRef.value = node ?? null;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :dir="direction"
+    :aria-disabled="colorState.disabled.value || undefined"
+    :data-disabled="colorState.disabled.value ? '' : undefined"
+    :style="{ '--color-area-hue': hueColor }"
+  >
+    <slot :saturation="saturation" :value="value" :hue="hue" :hue-color="hueColor" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/color-area/ColorAreaThumb.vue b/vue/primitives/src/color/color-area/ColorAreaThumb.vue
new file mode 100644
index 0000000..f982fd5
--- /dev/null
+++ b/vue/primitives/src/color/color-area/ColorAreaThumb.vue
@@ -0,0 +1,128 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The 2D handle of a `ColorAreaRoot`. A single thumb carries two axes
+ * (saturation on x, brightness on y) which one `aria-valuenow` cannot express,
+ * so it is exposed as `role="slider"` with `aria-valuenow` set to the primary
+ * axis (brightness) and `aria-valuetext` conveying **both** channels (e.g.
+ * `"Saturation 60%, Brightness 80%"`). Keyboard: Left/Right nudge saturation by
+ * `step` (direction-aware), Up/Down nudge brightness (Up = brighter),
+ * Shift+Arrow uses the large step, Home/End set saturation to `0`/`1`, and Page
+ * Up/Down change brightness by the large step. It positions itself at
+ * `left = saturation`, `top = 1 − brightness`. Pass `valueText` to override the
+ * announced text and `aria-label` for the accessible name (default
+ * `"Saturation and brightness"`).
+ */
+export interface ColorAreaThumbProps extends PrimitiveProps {
+  /**
+   * Override the `aria-valuetext` describing both axes. Receives saturation and
+   * value/brightness as `0–1` floats.
+   */
+  valueText?: (saturation: number, value: number) => string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useAttrs } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useColorAreaContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { valueText, as = 'span' } = defineProps<ColorAreaThumbProps>();
+const ctx = useColorAreaContext();
+const attrs = useAttrs();
+
+const saturation = computed(() => ctx.saturation.value);
+const value = computed(() => ctx.value.value);
+
+// `left = s`, `top = 1 − v` (top of the area is full brightness).
+const positionStyle = computed(() => ({
+  left: `${saturation.value * 100}%`,
+  top: `${(1 - value.value) * 100}%`,
+}));
+
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return ctx.labelId.value ? undefined : 'Saturation and brightness';
+});
+
+// One thumb, two axes: announce BOTH via aria-valuetext.
+const ariaValueText = computed(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  if (valueText) return valueText(saturation.value, value.value);
+  return `Saturation ${Math.round(saturation.value * 100)}%, Brightness ${Math.round(value.value * 100)}%`;
+});
+
+// `aria-valuenow` carries the primary axis (brightness).
+const ariaValueNow = computed(() => Math.round(value.value * 100));
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const rtl = ctx.direction.value === 'rtl';
+  const step = ctx.step.value;
+  const big = ctx.largeStep.value;
+  const unit = event.shiftKey ? big : step;
+  switch (event.key) {
+    case 'ArrowRight':
+      event.preventDefault();
+      ctx.setSaturation(saturation.value + (rtl ? -unit : unit));
+      return;
+    case 'ArrowLeft':
+      event.preventDefault();
+      ctx.setSaturation(saturation.value + (rtl ? unit : -unit));
+      return;
+    case 'ArrowUp':
+      event.preventDefault();
+      ctx.setValue(value.value + unit);
+      return;
+    case 'ArrowDown':
+      event.preventDefault();
+      ctx.setValue(value.value - unit);
+      return;
+    case 'Home':
+      event.preventDefault();
+      ctx.setSaturation(0);
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.setSaturation(1);
+      return;
+    case 'PageUp':
+      event.preventDefault();
+      ctx.setValue(value.value + big);
+      return;
+    case 'PageDown':
+      event.preventDefault();
+      ctx.setValue(value.value - big);
+      break;
+    default:
+      break;
+  }
+}
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
+    :aria-labelledby="!accessibleLabel ? ctx.labelId.value : undefined"
+    :aria-valuemin="0"
+    :aria-valuemax="100"
+    :aria-valuenow="ariaValueNow"
+    :aria-valuetext="ariaValueText"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :saturation="saturation" :value="value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/color-area/__test__/ColorArea.test.ts b/vue/primitives/src/color/color-area/__test__/ColorArea.test.ts
new file mode 100644
index 0000000..505a804
--- /dev/null
+++ b/vue/primitives/src/color/color-area/__test__/ColorArea.test.ts
@@ -0,0 +1,168 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { HSVA } from '../../../internal/color';
+import { ColorAreaRoot, ColorAreaThumb } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false }));
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+function mountArea(opts: Partial<{ defaultValue: HSVA; step: number; largeStep: number; disabled: boolean }> = {}, thumbProps: Record<string, unknown> = {}) {
+  const model = ref<HSVA | undefined>(undefined);
+  const Harness = defineComponent({
+    setup: () => () => h(ColorAreaRoot, {
+      modelValue: model.value,
+      'onUpdate:modelValue': (v: HSVA | null | undefined) => { model.value = v ?? undefined; },
+      ...opts,
+    }, { default: () => h(ColorAreaThumb, thumbProps) }),
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+describe('ColorArea', () => {
+  it('thumb is role=slider with aria-valuetext conveying both axes', async () => {
+    mountArea({ defaultValue: { h: 0, s: 0.6, v: 0.8, a: 1 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb).toBeTruthy();
+    // aria-valuenow carries the primary axis (brightness).
+    expect(thumb.getAttribute('aria-valuenow')).toBe('80');
+    expect(thumb.getAttribute('aria-valuetext')).toBe('Saturation 60%, Brightness 80%');
+    expect(thumb.getAttribute('aria-label')).toBe('Saturation and brightness');
+    expect(thumb.tabIndex).toBe(0);
+  });
+
+  it('positions the thumb at left=s, top=1-v', async () => {
+    mountArea({ defaultValue: { h: 0, s: 0.25, v: 0.75, a: 1 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.style.left).toBe('25%');
+    expect(thumb.style.top).toBe('25%');
+  });
+
+  it('ArrowRight / ArrowLeft change saturation by step', async () => {
+    const { model } = mountArea({ defaultValue: { h: 0, s: 0.5, v: 0.5, a: 1 }, step: 0.1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(round(model.value!.s)).toBe(0.6);
+    keydown(thumb, 'ArrowLeft');
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(round(model.value!.s)).toBe(0.4);
+  });
+
+  it('ArrowUp increases brightness, ArrowDown decreases', async () => {
+    const { model } = mountArea({ defaultValue: { h: 0, s: 0.5, v: 0.5, a: 1 }, step: 0.1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowUp');
+    await nextTick();
+    expect(round(model.value!.v)).toBe(0.6);
+    keydown(thumb, 'ArrowDown');
+    keydown(thumb, 'ArrowDown');
+    await nextTick();
+    expect(round(model.value!.v)).toBe(0.4);
+  });
+
+  it('Shift+Arrow uses the large step', async () => {
+    const { model } = mountArea({ defaultValue: { h: 0, s: 0.5, v: 0.5, a: 1 }, step: 0.01, largeStep: 0.1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(round(model.value!.s)).toBe(0.6);
+  });
+
+  it('Home / End set saturation to 0 / 1', async () => {
+    const { model } = mountArea({ defaultValue: { h: 30, s: 0.5, v: 0.5, a: 1 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value!.s).toBe(0);
+    keydown(thumb, 'End');
+    await nextTick();
+    expect(model.value!.s).toBe(1);
+  });
+
+  it('PageUp / PageDown change brightness by the large step', async () => {
+    const { model } = mountArea({ defaultValue: { h: 0, s: 0.5, v: 0.5, a: 1 }, largeStep: 0.2 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'PageUp');
+    await nextTick();
+    expect(round(model.value!.v)).toBe(0.7);
+    keydown(thumb, 'PageDown');
+    keydown(thumb, 'PageDown');
+    await nextTick();
+    expect(round(model.value!.v)).toBe(0.3);
+  });
+
+  it('clamps saturation / value within [0, 1]', async () => {
+    const { model } = mountArea({ defaultValue: { h: 0, s: 0.95, v: 0.05, a: 1 }, step: 0.1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    keydown(thumb, 'ArrowDown');
+    await nextTick();
+    expect(model.value!.s).toBe(1);
+    expect(model.value!.v).toBe(0);
+  });
+
+  it('preserve-hue at s=0: dragging into and back out keeps the hue', async () => {
+    const { model } = mountArea({ defaultValue: { h: 200, s: 0.5, v: 0.5, a: 1 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    // Collapse saturation to 0 (grey — hue becomes ambiguous).
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value!.s).toBe(0);
+    expect(model.value!.h).toBe(200);
+    // Restore saturation; the original hue must come back.
+    keydown(thumb, 'End');
+    await nextTick();
+    expect(model.value!.s).toBe(1);
+    expect(model.value!.h).toBe(200);
+  });
+
+  it('valueText prop overrides the announced text', async () => {
+    mountArea(
+      { defaultValue: { h: 0, s: 0.5, v: 0.5, a: 1 } },
+      { valueText: (s: number, v: number) => `S${Math.round(s * 100)}/V${Math.round(v * 100)}` },
+    );
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.getAttribute('aria-valuetext')).toBe('S50/V50');
+  });
+
+  it('disabled: tabindex=-1 and keys do nothing', async () => {
+    const { model } = mountArea({ defaultValue: { h: 0, s: 0.5, v: 0.5, a: 1 }, disabled: true });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.tabIndex).toBe(-1);
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+});
diff --git a/vue/primitives/src/color/color-area/context.ts b/vue/primitives/src/color/color-area/context.ts
new file mode 100644
index 0000000..034ccc7
--- /dev/null
+++ b/vue/primitives/src/color/color-area/context.ts
@@ -0,0 +1,38 @@
+import type { Ref } from 'vue';
+import type { HSVA } from '../../internal/color';
+import { useContextFactory } from '@robonen/vue';
+
+export type ColorAreaDirection = 'ltr' | 'rtl';
+
+/**
+ * Context shared between `ColorAreaRoot` and `ColorAreaThumb`.
+ *
+ * Scalar props are exposed as plain `Ref<T>` — `ColorAreaRoot` builds them with
+ * `toRef(() => prop)` (a reactive getter ref without an extra effect).
+ */
+export interface ColorAreaContext {
+  /** The canonical colour the area reads saturation/value from. */
+  hsva: Ref<HSVA>;
+  /** Current saturation (`0–1`, x-axis). */
+  saturation: Ref<number>;
+  /** Current value/brightness (`0–1`, y-axis). */
+  value: Ref<number>;
+  /** Step granularity for keyboard nudges. */
+  step: Ref<number>;
+  /** Large-step granularity (Shift+Arrow / Page keys). */
+  largeStep: Ref<number>;
+  direction: Ref<ColorAreaDirection>;
+  disabled: Ref<boolean>;
+  /** Accessible name id contributed by a `ColorFieldLabel`, if present. */
+  labelId: Ref<string | undefined>;
+  trackRef: Ref<HTMLElement | null>;
+  /** Set the saturation channel (`0–1`), preserving hue and value. */
+  setSaturation: (saturation: number) => void;
+  /** Set the value/brightness channel (`0–1`), preserving hue and saturation. */
+  setValue: (value: number) => void;
+}
+
+const ctx = useContextFactory<ColorAreaContext>('ColorAreaContext');
+
+export const provideColorAreaContext = ctx.provide;
+export const useColorAreaContext = ctx.inject;
diff --git a/vue/primitives/src/color/color-area/demo.vue b/vue/primitives/src/color/color-area/demo.vue
new file mode 100644
index 0000000..0c7fee1
--- /dev/null
+++ b/vue/primitives/src/color/color-area/demo.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import type { HSVA } from '@robonen/primitives';
+import { ColorAreaRoot, ColorAreaThumb, hsvToRgb } from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+const color = ref<HSVA>({ h: 265, s: 0.72, v: 0.86, a: 1 });
+
+const rgb = computed(() => hsvToRgb(color.value));
+const cssColor = computed(() => `rgb(${rgb.value.r}, ${rgb.value.g}, ${rgb.value.b})`);
+</script>
+
+<template>
+  <div class="demo-card flex w-full max-w-sm flex-col gap-5 p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <span class="font-medium">Saturation / Brightness</span>
+      <span class="font-mono text-fg-muted">
+        S {{ Math.round(color.s * 100) }}% · V {{ Math.round(color.v * 100) }}%
+      </span>
+    </div>
+
+    <!-- The SV square: hue base, white→transparent left-right, transparent→black top-bottom -->
+    <ColorAreaRoot
+      v-model="color"
+      class="relative aspect-[4/3] w-full touch-none select-none overflow-hidden rounded-card border border-border shadow-(--shadow-card)"
+      :style="{ backgroundColor: 'var(--color-area-hue)' }"
+    >
+      <!-- white (left) → transparent (right) -->
+      <div
+        class="pointer-events-none absolute inset-0"
+        style="background: linear-gradient(to right, #fff, transparent)"
+      />
+      <!-- transparent (top) → black (bottom) -->
+      <div
+        class="pointer-events-none absolute inset-0"
+        style="background: linear-gradient(to top, #000, transparent)"
+      />
+
+      <ColorAreaThumb
+        aria-label="Saturation and brightness"
+        class="absolute z-10 size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-md outline-none ring-1 ring-black/25 transition-[transform] focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+        :style="{ backgroundColor: cssColor }"
+      />
+    </ColorAreaRoot>
+
+    <div class="flex items-center gap-3 rounded-card bg-bg-inset p-3">
+      <span
+        class="size-9 shrink-0 rounded-lg border border-border-strong"
+        :style="{ backgroundColor: cssColor }"
+      />
+      <div class="flex flex-col text-sm leading-tight">
+        <span class="font-mono text-fg">{{ cssColor }}</span>
+        <span class="font-mono text-xs text-fg-subtle">
+          hsv({{ Math.round(color.h) }}, {{ Math.round(color.s * 100) }}%, {{ Math.round(color.v * 100) }}%)
+        </span>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/color/color-area/index.ts b/vue/primitives/src/color/color-area/index.ts
new file mode 100644
index 0000000..4837daf
--- /dev/null
+++ b/vue/primitives/src/color/color-area/index.ts
@@ -0,0 +1,10 @@
+export { default as ColorAreaRoot } from './ColorAreaRoot.vue';
+export { default as ColorAreaThumb } from './ColorAreaThumb.vue';
+export type { ColorAreaRootProps } from './ColorAreaRoot.vue';
+export type { ColorAreaThumbProps } from './ColorAreaThumb.vue';
+export {
+  type ColorAreaContext,
+  type ColorAreaDirection,
+  provideColorAreaContext,
+  useColorAreaContext,
+} from './context';
diff --git a/vue/primitives/src/color/color-field/ColorFieldHiddenInput.vue b/vue/primitives/src/color/color-field/ColorFieldHiddenInput.vue
new file mode 100644
index 0000000..a5a4ded
--- /dev/null
+++ b/vue/primitives/src/color/color-field/ColorFieldHiddenInput.vue
@@ -0,0 +1,37 @@
+<script lang="ts">
+/**
+ * A visually-hidden native `<input>` carrying the surrounding `ColorFieldRoot`'s
+ * formatted colour under `name`, so the colour participates in native form
+ * submission and constraint validation. Renders nothing unless `name` is set.
+ * Place it inside a `ColorFieldRoot`.
+ */
+export interface ColorFieldHiddenInputProps {
+  /** Form field `name`. The input is only rendered when this is set. */
+  name?: string;
+  /** Mark the hidden input as required for native validation. */
+  required?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { formatHsva } from '../../internal/color';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
+import { useColorFieldContext } from './context';
+
+const { name, required } = defineProps<ColorFieldHiddenInputProps>();
+const ctx = useColorFieldContext();
+
+// Serialize as `#rrggbbaa` so alpha survives the round-trip through the form.
+const value = computed(() => formatHsva(ctx.hsva.value, 'hex8'));
+</script>
+
+<template>
+  <VisuallyHiddenInput
+    v-if="name"
+    :name="name"
+    :value="value"
+    :required="required"
+    :disabled="ctx.disabled.value"
+  />
+</template>
diff --git a/vue/primitives/src/color/color-field/ColorFieldInput.vue b/vue/primitives/src/color/color-field/ColorFieldInput.vue
new file mode 100644
index 0000000..add79e5
--- /dev/null
+++ b/vue/primitives/src/color/color-field/ColorFieldInput.vue
@@ -0,0 +1,83 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A native text `<input>` bound to the formatted colour string of the
+ * surrounding `ColorFieldRoot`. As the user types it parses the value via
+ * `parseColor`; a valid colour updates the canonical state, an invalid one is
+ * left uncommitted and `aria-invalid` flips to `true` so the field reflects the
+ * live parse state. While the input is focused it shows the user's in-progress
+ * text; on blur it re-syncs to the canonical formatted value. Place it inside a
+ * `ColorFieldRoot`.
+ */
+export interface ColorFieldInputProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { formatHsva, parseColor } from '../../internal/color';
+import { Primitive } from '../../internal/primitive';
+import { useColorFieldContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'input' } = defineProps<ColorFieldInputProps>();
+const ctx = useColorFieldContext();
+
+// The canonical colour, formatted as a hex string for editing.
+const canonical = computed(() => formatHsva(ctx.hsva.value, 'hex'));
+
+// Local draft text: what the user sees/types. Mirrors `canonical` unless the
+// user is mid-edit with text that does not (yet) parse.
+const draft = ref(canonical.value);
+const focused = ref(false);
+
+// When the canonical colour changes externally (e.g. dragging a slider), reflect
+// it into the input — but only while the user is not actively editing.
+watch(canonical, (next) => {
+  if (!focused.value) draft.value = next;
+});
+
+const parsed = computed(() => parseColor(draft.value));
+const invalid = computed(() => parsed.value === null);
+
+function onInput(event: Event): void {
+  if (ctx.disabled.value) return;
+  draft.value = (event.target as HTMLInputElement).value;
+  const result = parseColor(draft.value);
+  if (result) {
+    // Drive the canonical colour through the shared setters so preserve-hue
+    // policy still applies (set all channels in one shot via SV + hue + alpha).
+    ctx.setHue(result.h);
+    ctx.setSaturationValue(result.s, result.v);
+    ctx.setAlpha(result.a);
+  }
+}
+
+function onFocus(): void {
+  focused.value = true;
+}
+
+function onBlur(): void {
+  focused.value = false;
+  // Snap back to the canonical formatted value, discarding invalid drafts.
+  draft.value = canonical.value;
+}
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :value="draft"
+    :disabled="ctx.disabled.value || undefined"
+    :aria-invalid="invalid || undefined"
+    :aria-labelledby="ctx.labelId.value"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-invalid="invalid ? '' : undefined"
+    @input="onInput"
+    @focus="onFocus"
+    @blur="onBlur"
+  />
+</template>
diff --git a/vue/primitives/src/color/color-field/ColorFieldLabel.vue b/vue/primitives/src/color/color-field/ColorFieldLabel.vue
new file mode 100644
index 0000000..98d97b3
--- /dev/null
+++ b/vue/primitives/src/color/color-field/ColorFieldLabel.vue
@@ -0,0 +1,52 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The accessible name for the whole colour-picker cluster. It renders a
+ * `<label>` (or any element via `as`) with a generated `id` that it registers
+ * into the `ColorFieldRoot` context, so the otherwise-orphaned sub-pickers
+ * (`ColorArea`, `HueSlider`, `AlphaSlider`) and `ColorFieldInput` can reference
+ * it via `aria-labelledby`. This closes the "four orphaned controls" a11y gap.
+ * Place it inside a `ColorFieldRoot`.
+ */
+export interface ColorFieldLabelProps extends PrimitiveProps {
+  /** Override the generated label id. */
+  id?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { onScopeDispose, watchEffect } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useColorFieldContext } from './context';
+import { useId } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+
+const { id, as = 'label' } = defineProps<ColorFieldLabelProps>();
+const ctx = useColorFieldContext();
+
+const generatedId = useId(undefined, 'color-field-label');
+// An explicit `id` prop wins over the generated one.
+const labelId = () => id ?? generatedId.value;
+
+// Publish our id into the shared context so the sub-pickers can reference it.
+watchEffect(() => {
+  ctx.labelId.value = labelId();
+});
+onScopeDispose(() => {
+  ctx.labelId.value = undefined;
+});
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :id="labelId()"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/color-field/ColorFieldRoot.vue b/vue/primitives/src/color/color-field/ColorFieldRoot.vue
new file mode 100644
index 0000000..e880677
--- /dev/null
+++ b/vue/primitives/src/color/color-field/ColorFieldRoot.vue
@@ -0,0 +1,181 @@
+<script lang="ts">
+import type { ColorFormat } from './context';
+import type { HSV, HSVA, RGB } from '../../internal/color';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The composite root of the colour-picker cluster. It owns the canonical
+ * {@link HSVA} colour (controlled via `v-model`, uncontrolled via
+ * `defaultValue`) and provides a shared context that `ColorArea`, `HueSlider`,
+ * and `AlphaSlider` read and write into, keeping every control in sync without
+ * round-tripping through RGB. The model accepts either an `HSVA` object or any
+ * CSS colour string (`#rrggbb`, `rgb()/rgba()`, `hsl()/hsla()`) via `parseColor`
+ * and emits in the configured `format`. Compose it with `ColorFieldSwatch`,
+ * `ColorFieldInput`, `ColorFieldLabel`, and `ColorFieldHiddenInput`. Reach for
+ * it whenever you need a full, accessible colour picker tied to a form value.
+ */
+export interface ColorFieldRootProps extends PrimitiveProps {
+  /**
+   * Uncontrolled initial value (`HSVA` object or CSS colour string).
+   * @default '#ff0000'
+   */
+  defaultValue?: HSVA | string;
+  /**
+   * Serialization format used for `update:modelValue`, the swatch label, the
+   * input string, and the hidden form input.
+   * @default 'hex'
+   */
+  format?: ColorFormat;
+  /** Disable all interaction across the cluster. @default false */
+  disabled?: boolean;
+  /** Hidden form input `name` (enables native form submission). */
+  name?: string;
+}
+
+</script>
+
+<script setup lang="ts">
+import { computed, ref, shallowRef, toRef, watch } from 'vue';
+import { formatHsva, hsvToRgb, hsvaToCss, parseColor } from '../../internal/color';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
+import { Primitive } from '../../internal/primitive';
+import { provideColorFieldContext } from './context';
+import { useHsvaSetters } from './useColorState';
+import { useForwardExpose } from '@robonen/vue';
+
+const {
+  defaultValue = '#ff0000',
+  format = 'hex',
+  disabled = false,
+  name,
+  as = 'div',
+} = defineProps<ColorFieldRootProps>();
+
+// `defineModel` drives both controlled (`v-model`) and uncontrolled modes. The
+// raw model may be an HSVA object OR a CSS string OR null; the canonical state
+// below normalizes it to HSVA once. We do NOT bind `defineModel` directly to
+// the canonical ref because we emit in the configured `format`, not the raw in.
+const model = defineModel<HSVA | string | null>();
+
+/** Normalize any accepted input (object | string) to canonical HSVA. */
+function toHsva(input: HSVA | string | null | undefined): HSVA | null {
+  if (input === null || input === undefined) return null;
+  if (typeof input === 'string') return parseColor(input);
+  return { ...input };
+}
+
+const seed = toHsva(model.value) ?? toHsva(defaultValue) ?? { h: 0, s: 1, v: 1, a: 1 };
+
+// The canonical, reactive HSVA. Every sub-picker replaces this wholesale through
+// the shared setters (preserve-hue policy lives in `useHsvaSetters`); it is never
+// mutated channel-by-channel, so shallowRef triggers identically without proxying.
+const hsva = shallowRef<HSVA>(seed);
+
+const setters = useHsvaSetters(hsva);
+
+/** Serialize the current canonical colour in the configured format. */
+function serialize(c: HSVA): HSVA | string {
+  if (format === 'hsva') return { ...c };
+  return formatHsva(c, format);
+}
+
+// Push the canonical colour out through the model in the configured format.
+// Guarded against the echo where our own emit comes back in as `model.value`.
+let writingOut = false;
+function pushOut(c: HSVA): void {
+  writingOut = true;
+  model.value = serialize(c);
+  writingOut = false;
+}
+// `hsva` (shallowRef) is replaced wholesale on every change, so watching its
+// identity already fires on each update — no deep {h,s,v,a} traversal per frame.
+watch(hsva, c => pushOut(c));
+
+// Uncontrolled adoption: when no controlled `modelValue` was supplied, surface
+// the seeded (default) colour to the model once on mount so the consumer's
+// `v-model` reflects the initial value in the configured format.
+if (model.value === null || model.value === undefined) pushOut(hsva.value);
+
+// Adopt externally driven model changes (controlled mode). Ignore the echo from
+// our own outward write and any unparseable strings.
+watch(model, (next) => {
+  if (writingOut) return;
+  const parsed = toHsva(next);
+  if (!parsed) return;
+  const cur = hsva.value;
+  if (parsed.h === cur.h && parsed.s === cur.s && parsed.v === cur.v && parsed.a === cur.a) return;
+  hsva.value = parsed;
+});
+
+// Derived, read-only views for consumers (`defineExpose`) and parts.
+const rgb = computed<RGB>(() => hsvToRgb(hsva.value));
+const hsv = computed<HSV>(() => ({ h: hsva.value.h, s: hsva.value.s, v: hsva.value.v }));
+const cssColor = computed(() => hsvaToCss(hsva.value));
+const hex = computed(() => formatHsva(hsva.value, 'hex'));
+const hex8 = computed(() => formatHsva(hsva.value, 'hex8'));
+const rgbaString = computed(() => formatHsva(hsva.value, 'rgba'));
+const hslaString = computed(() => formatHsva(hsva.value, 'hsla'));
+/** The value serialized in the configured `format` (used by parts). */
+const formatted = computed(() => formatHsva(hsva.value, format === 'hsva' ? 'rgba' : format));
+
+const labelId = ref<string | undefined>(undefined);
+
+provideColorFieldContext({
+  hsva,
+  setHue: setters.setHue,
+  setSaturation: setters.setSaturation,
+  setValue: setters.setValue,
+  setAlpha: setters.setAlpha,
+  setSaturationValue: setters.setSaturationValue,
+  disabled: toRef(() => disabled),
+  labelId,
+});
+
+defineExpose({
+  /** The canonical HSVA colour (read-only view). */
+  hsva,
+  /** The colour as RGB. */
+  rgb,
+  /** The colour as HSV (no alpha). */
+  hsv,
+  /** The colour as a CSS `rgba()` string. */
+  cssColor,
+  /** The colour as `#rrggbb`. */
+  hex,
+  /** The colour as `#rrggbbaa`. */
+  hex8,
+  /** The colour as `rgba()`. */
+  rgbaString,
+  /** The colour as `hsla()`. */
+  hslaString,
+  /** The value serialized in the configured `format`. */
+  formatted,
+});
+
+// `useForwardExpose` runs AFTER `defineExpose` so it merges the prior expose
+// bindings (plus props + `$el`) instead of clobbering them.
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+  >
+    <slot
+      :hsva="hsva"
+      :rgb="rgb"
+      :hex="hex"
+      :css-color="cssColor"
+      :formatted="formatted"
+    />
+    <VisuallyHiddenInput
+      v-if="name"
+      :name="name"
+      :value="hex8"
+      :disabled="disabled"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/color-field/ColorFieldSwatch.vue b/vue/primitives/src/color/color-field/ColorFieldSwatch.vue
new file mode 100644
index 0000000..b01f9c3
--- /dev/null
+++ b/vue/primitives/src/color/color-field/ColorFieldSwatch.vue
@@ -0,0 +1,51 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A presentational swatch showing the current colour of the surrounding
+ * `ColorFieldRoot`. It paints its `background` from the canonical colour and,
+ * unless `decorative`, exposes itself as `role="img"` with an `aria-label`
+ * carrying the formatted colour string so the swatch is announced to assistive
+ * technology. Place it inside a `ColorFieldRoot`.
+ */
+export interface ColorFieldSwatchProps extends PrimitiveProps {
+  /**
+   * When `true`, the swatch is hidden from assistive technology
+   * (`aria-hidden`) instead of being announced as an image.
+   * @default false
+   */
+  decorative?: boolean;
+  /** Override the accessible label (defaults to the formatted colour). */
+  label?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { formatHsva, hsvaToCss } from '../../internal/color';
+import { Primitive } from '../../internal/primitive';
+import { useColorFieldContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { decorative = false, label, as = 'span' } = defineProps<ColorFieldSwatchProps>();
+const ctx = useColorFieldContext();
+
+const background = computed(() => hsvaToCss(ctx.hsva.value));
+const accessibleLabel = computed(() => label ?? formatHsva(ctx.hsva.value, 'hex8'));
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :role="decorative ? undefined : 'img'"
+    :aria-hidden="decorative ? '' : undefined"
+    :aria-label="decorative ? undefined : accessibleLabel"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :style="{ background, backgroundColor: background }"
+  >
+    <slot :background="background" :label="accessibleLabel" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/color-field/__test__/ColorField.test.ts b/vue/primitives/src/color/color-field/__test__/ColorField.test.ts
new file mode 100644
index 0000000..67347b5
--- /dev/null
+++ b/vue/primitives/src/color/color-field/__test__/ColorField.test.ts
@@ -0,0 +1,229 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { HSVA } from '../../../internal/color';
+import { hsvToRgb, parseColor } from '../../../internal/color';
+import { AlphaSliderRoot, AlphaSliderThumb } from '../../alpha-slider';
+import { ColorAreaRoot, ColorAreaThumb } from '../../color-area';
+import { HueSliderRoot, HueSliderThumb } from '../../hue-slider';
+import {
+  ColorFieldHiddenInput,
+  ColorFieldInput,
+  ColorFieldLabel,
+  ColorFieldRoot,
+  ColorFieldSwatch,
+} from '../index';
+import type { ColorFormat } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false }));
+}
+
+function typeInput(el: HTMLInputElement, value: string): void {
+  el.value = value;
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+describe('ColorField — value & format', () => {
+  it('parses a hex string default into HSVA and emits the configured format', async () => {
+    const model = ref<HSVA | string | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, {
+        modelValue: model.value,
+        defaultValue: '#00ff00',
+        format: 'rgb',
+        'onUpdate:modelValue': (v: HSVA | string | null | undefined) => { model.value = v ?? undefined; },
+      }, { default: () => h(ColorFieldInput) }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    // #00ff00 is pure green → hsv { h: 120, s: 1, v: 1 }.
+    const input = document.querySelector<HTMLInputElement>('input')!;
+    expect(input.value.toLowerCase()).toBe('#00ff00');
+    // First emit is the default colour serialized as rgb.
+    expect(model.value).toBe('rgb(0, 255, 0)');
+  });
+
+  it('ColorFieldInput parses a typed hex into the canonical HSVA', async () => {
+    const model = ref<HSVA | string | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, {
+        modelValue: model.value,
+        defaultValue: '#000000',
+        format: 'hex',
+        'onUpdate:modelValue': (v: HSVA | string | null | undefined) => { model.value = v ?? undefined; },
+      }, { default: () => h(ColorFieldInput) }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('input')!;
+    typeInput(input, '#3366ff');
+    await nextTick();
+    const expected = parseColor('#3366ff')!;
+    // Emitted as hex.
+    expect((model.value as string).toLowerCase()).toBe('#3366ff');
+    // The canonical conversion round-trips back to the same rgb.
+    expect(hsvToRgb(expected)).toEqual({ r: 51, g: 102, b: 255 });
+  });
+
+  it('marks the input aria-invalid for an unparseable value and does not commit', async () => {
+    const model = ref<HSVA | string | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, {
+        modelValue: model.value,
+        defaultValue: '#ff0000',
+        'onUpdate:modelValue': (v: HSVA | string | null | undefined) => { model.value = v ?? undefined; },
+      }, { default: () => h(ColorFieldInput) }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('input')!;
+    typeInput(input, 'not-a-color');
+    await nextTick();
+    expect(input.getAttribute('aria-invalid')).toBe('true');
+    // The canonical value stays the red default (#ff0000), so the emit never
+    // changed to the garbage text.
+    expect(model.value).toBe('#ff0000');
+  });
+});
+
+describe('ColorField — cluster sync', () => {
+  function mountCluster(format: ColorFormat = 'hex') {
+    const model = ref<HSVA | string | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, {
+        modelValue: model.value,
+        defaultValue: { h: 0, s: 1, v: 1, a: 1 },
+        format,
+        'onUpdate:modelValue': (v: HSVA | string | null | undefined) => { model.value = v ?? undefined; },
+      }, {
+        default: () => [
+          h(ColorAreaRoot, null, { default: () => h(ColorAreaThumb, { id: 'area-thumb' }) }),
+          h(HueSliderRoot, null, { default: () => h(HueSliderThumb, { id: 'hue-thumb' }) }),
+          h(AlphaSliderRoot, null, { default: () => h(AlphaSliderThumb, { id: 'alpha-thumb' }) }),
+          h(ColorFieldSwatch, { id: 'swatch' }),
+        ],
+      }),
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    return { wrapper: w, model };
+  }
+
+  it('changing the hue slider updates the field value (cluster stays in sync)', async () => {
+    const { model } = mountCluster('hsva');
+    await nextTick();
+    const hueThumb = document.getElementById('hue-thumb')!;
+    // default hue is 0; nudge it up.
+    keydown(hueThumb, 'ArrowRight');
+    await nextTick();
+    expect((model.value as HSVA).h).toBe(1);
+    // The area thumb reads the SAME shared colour (s=1, v=1 unchanged).
+    const areaThumb = document.getElementById('area-thumb')!;
+    expect(areaThumb.getAttribute('aria-valuetext')).toBe('Saturation 100%, Brightness 100%');
+  });
+
+  it('all three pickers share one HSVA: area edits show on the hue/alpha thumbs', async () => {
+    const { model } = mountCluster('hsva');
+    await nextTick();
+    const alphaThumb = document.getElementById('alpha-thumb')!;
+    expect(alphaThumb.getAttribute('aria-valuenow')).toBe('1');
+    keydown(alphaThumb, 'Home');
+    await nextTick();
+    expect((model.value as HSVA).a).toBe(0);
+    // The swatch reflects the new alpha (rgba background with a=0).
+    const swatch = document.getElementById('swatch')!;
+    expect(swatch.style.background).toContain('rgba(255, 0, 0, 0)');
+  });
+
+  it('preserve-hue at s=0 across the cluster: hue is unchanged', async () => {
+    const { model } = mountCluster('hsva');
+    await nextTick();
+    const hueThumb = document.getElementById('hue-thumb')!;
+    // Move hue to a known non-zero value first.
+    for (let i = 0; i < 5; i++) keydown(hueThumb, 'ArrowRight');
+    await nextTick();
+    expect((model.value as HSVA).h).toBe(5);
+    const areaThumb = document.getElementById('area-thumb')!;
+    // Collapse saturation to 0 then back to 1.
+    keydown(areaThumb, 'Home');
+    await nextTick();
+    expect((model.value as HSVA).s).toBe(0);
+    expect((model.value as HSVA).h).toBe(5);
+    keydown(areaThumb, 'End');
+    await nextTick();
+    expect((model.value as HSVA).s).toBe(1);
+    expect((model.value as HSVA).h).toBe(5);
+  });
+});
+
+describe('ColorField — accessibility & form', () => {
+  it('ColorFieldLabel provides an id the sub-pickers reference via aria-labelledby', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, { defaultValue: '#ff0000' }, {
+        default: () => [
+          h(ColorFieldLabel, { id: 'cf-label' }, { default: () => 'Brand colour' }),
+          h(HueSliderRoot, null, { default: () => h(HueSliderThumb, { id: 'hue-thumb' }) }),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const hueThumb = document.getElementById('hue-thumb')!;
+    expect(hueThumb.getAttribute('aria-labelledby')).toBe('cf-label');
+    // The default 'Hue' label is suppressed in favour of the shared name.
+    expect(hueThumb.getAttribute('aria-label')).toBeNull();
+  });
+
+  it('ColorFieldHiddenInput carries the value when name is set', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, { defaultValue: '#ff0000' }, {
+        default: () => h(ColorFieldHiddenInput, { name: 'brand' }),
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('input[name="brand"]')!;
+    expect(input).toBeTruthy();
+    // Serialized as #rrggbbaa so alpha survives.
+    expect(input.value.toLowerCase()).toBe('#ff0000ff');
+  });
+
+  it('ColorFieldRoot name renders a hidden form input directly', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, { defaultValue: '#00ff00', name: 'fav' }, {
+        default: () => h(ColorFieldSwatch),
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('input[name="fav"]')!;
+    expect(input).toBeTruthy();
+    expect(input.value.toLowerCase()).toBe('#00ff00ff');
+  });
+
+  it('the swatch exposes role=img with a formatted aria-label', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(ColorFieldRoot, { defaultValue: '#ff0000' }, {
+        default: () => h(ColorFieldSwatch, { id: 'swatch' }),
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const swatch = document.getElementById('swatch')!;
+    expect(swatch.getAttribute('role')).toBe('img');
+    expect(swatch.getAttribute('aria-label')!.toLowerCase()).toBe('#ff0000ff');
+  });
+});
diff --git a/vue/primitives/src/color/color-field/__test__/__screenshots__/ColorField.test.ts/ColorField---value---format-marks-the-input-aria-invalid-for-an-unparseable-value-and-does-not-commit-1.png b/vue/primitives/src/color/color-field/__test__/__screenshots__/ColorField.test.ts/ColorField---value---format-marks-the-input-aria-invalid-for-an-unparseable-value-and-does-not-commit-1.png
new file mode 100644
index 0000000..e285d9d
Binary files /dev/null and b/vue/primitives/src/color/color-field/__test__/__screenshots__/ColorField.test.ts/ColorField---value---format-marks-the-input-aria-invalid-for-an-unparseable-value-and-does-not-commit-1.png differ
diff --git a/vue/primitives/src/color/color-field/__test__/__screenshots__/ColorField.test.ts/ColorField---value---format-parses-a-hex-string-default-into-HSVA-and-emits-the-configured-format-1.png b/vue/primitives/src/color/color-field/__test__/__screenshots__/ColorField.test.ts/ColorField---value---format-parses-a-hex-string-default-into-HSVA-and-emits-the-configured-format-1.png
new file mode 100644
index 0000000..8791a47
Binary files /dev/null and b/vue/primitives/src/color/color-field/__test__/__screenshots__/ColorField.test.ts/ColorField---value---format-parses-a-hex-string-default-into-HSVA-and-emits-the-configured-format-1.png differ
diff --git a/vue/primitives/src/color/color-field/context.ts b/vue/primitives/src/color/color-field/context.ts
new file mode 100644
index 0000000..e657780
--- /dev/null
+++ b/vue/primitives/src/color/color-field/context.ts
@@ -0,0 +1,43 @@
+import type { InjectionKey, Ref } from 'vue';
+import type { HSVA } from '../../internal/color';
+import { useContextFactory } from '@robonen/vue';
+
+/** CSS color string formats `ColorFieldRoot` can serialize the value to. */
+export type ColorFormat = 'hsva' | 'hex' | 'hex8' | 'rgb' | 'rgba' | 'hsl' | 'hsla';
+
+/**
+ * Shared color state surfaced by `ColorFieldRoot` and consumed by the picker
+ * sub-components (`ColorArea`, `HueSlider`, `AlphaSlider`).
+ *
+ * The canonical model is always {@link HSVA} (the value never round-trips
+ * through RGB). Each picker reads `hsva` and writes back through the channel
+ * setters so the whole cluster stays in sync. Sub-pickers inject this context
+ * with a fallback (`undefined`) so they also work standalone, owning their own
+ * HSVA via `defineModel`.
+ */
+export interface ColorFieldContext {
+  /** The canonical, reactive HSVA color shared across the cluster. */
+  hsva: Ref<HSVA>;
+  /** Set the hue channel (`0–360`), preserving the other channels. */
+  setHue: (hue: number) => void;
+  /** Set the saturation channel (`0–1`), preserving the other channels. */
+  setSaturation: (saturation: number) => void;
+  /** Set the value/brightness channel (`0–1`), preserving the other channels. */
+  setValue: (value: number) => void;
+  /** Set the alpha channel (`0–1`), preserving the other channels. */
+  setAlpha: (alpha: number) => void;
+  /** Set saturation and value/brightness together (used by the 2D area). */
+  setSaturationValue: (saturation: number, value: number) => void;
+  /** Whether the whole cluster is disabled. */
+  disabled: Ref<boolean>;
+  /** Accessible name id contributed by `ColorFieldLabel`, if present. */
+  labelId: Ref<string | undefined>;
+}
+
+const ctx = useContextFactory<ColorFieldContext>('ColorFieldContext');
+
+export const provideColorFieldContext = ctx.provide;
+export const useColorFieldContext = ctx.inject;
+
+/** Injection key — used by the sub-pickers to inject with a fallback. */
+export const colorFieldContextKey = ctx.key as InjectionKey<ColorFieldContext>;
diff --git a/vue/primitives/src/color/color-field/demo.vue b/vue/primitives/src/color/color-field/demo.vue
new file mode 100644
index 0000000..ec6531d
--- /dev/null
+++ b/vue/primitives/src/color/color-field/demo.vue
@@ -0,0 +1,117 @@
+<script setup lang="ts">
+import type { HSVA, RGB } from '@robonen/primitives';
+import {
+  AlphaSliderRoot,
+  AlphaSliderThumb,
+  ColorAreaRoot,
+  ColorAreaThumb,
+  ColorFieldInput,
+  ColorFieldLabel,
+  ColorFieldRoot,
+  ColorFieldSwatch,
+  HueSliderRoot,
+  HueSliderThumb,
+  hsvToRgb,
+} from '@robonen/primitives';
+import { ref } from 'vue';
+
+const color = ref('#7c5cff');
+
+function hueRgb(hsva: HSVA): string {
+  const { r, g, b } = hsvToRgb({ h: hsva.h, s: 1, v: 1 });
+  return `rgb(${r}, ${g}, ${b})`;
+}
+function rgbStr(rgb: RGB): string {
+  return `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`;
+}
+function alphaGradient(rgb: RGB): string {
+  return `linear-gradient(to right, rgba(${rgb.r},${rgb.g},${rgb.b},0), rgb(${rgb.r},${rgb.g},${rgb.b}))`;
+}
+
+const HUE_GRADIENT
+  = 'linear-gradient(to right, #f00 0%, #ff0 17%, #0f0 33%, #0ff 50%, #00f 67%, #f0f 83%, #f00 100%)';
+
+const CHECKER = {
+  backgroundImage:
+    'linear-gradient(45deg, #ccc 25%, transparent 25%), linear-gradient(-45deg, #ccc 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #ccc 75%), linear-gradient(-45deg, transparent 75%, #ccc 75%)',
+  backgroundSize: '10px 10px',
+  backgroundPosition: '0 0, 0 5px, 5px -5px, -5px 0',
+  backgroundColor: '#fff',
+} as const;
+</script>
+
+<template>
+  <ColorFieldRoot
+    v-slot="{ hsva, rgb, hex }"
+    v-model="color"
+    format="hex"
+    class="demo-card flex w-full max-w-xs flex-col gap-4 p-5 text-fg"
+  >
+    <ColorFieldLabel class="text-sm font-medium">Pick a color</ColorFieldLabel>
+
+    <!-- SV square -->
+    <ColorAreaRoot
+      class="relative aspect-square w-full touch-none select-none overflow-hidden rounded-card border border-border shadow-(--shadow-card)"
+      :style="{ backgroundColor: 'var(--color-area-hue)' }"
+    >
+      <div
+        class="pointer-events-none absolute inset-0"
+        style="background: linear-gradient(to right, #fff, transparent)"
+      />
+      <div
+        class="pointer-events-none absolute inset-0"
+        style="background: linear-gradient(to top, #000, transparent)"
+      />
+      <ColorAreaThumb
+        class="absolute z-10 size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-md outline-none ring-1 ring-black/25 transition-[transform] focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+        :style="{ backgroundColor: rgbStr(rgb) }"
+      />
+    </ColorAreaRoot>
+
+    <!-- Hue + alpha rails -->
+    <div class="flex flex-col gap-3">
+      <HueSliderRoot
+        class="relative block h-3.5 w-full touch-none select-none rounded-full border border-border"
+        :style="{ background: HUE_GRADIENT }"
+      >
+        <HueSliderThumb
+          class="absolute top-1/2 z-10 size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-md outline-none ring-1 ring-black/25 transition-[transform] focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+          :style="{ backgroundColor: hueRgb(hsva) }"
+        />
+      </HueSliderRoot>
+
+      <AlphaSliderRoot
+        class="relative block h-3.5 w-full touch-none select-none rounded-full border border-border"
+        :style="CHECKER"
+      >
+        <div
+          class="pointer-events-none absolute inset-0 rounded-full"
+          :style="{ backgroundImage: alphaGradient(rgb) }"
+        />
+        <AlphaSliderThumb
+          class="absolute top-1/2 z-10 size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-md outline-none ring-1 ring-black/25 transition-[transform] focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+          :style="{ backgroundColor: rgbStr(rgb) }"
+        />
+      </AlphaSliderRoot>
+    </div>
+
+    <!-- Swatch + editable text input -->
+    <div class="flex items-center gap-2 rounded-card bg-bg-inset p-2">
+      <span
+        class="size-9 shrink-0 overflow-hidden rounded-lg border border-border-strong"
+        :style="CHECKER"
+      >
+        <ColorFieldSwatch class="block size-full" />
+      </span>
+      <ColorFieldInput
+        class="min-w-0 flex-1 rounded-lg border border-border bg-bg px-2.5 py-1.5 font-mono text-sm text-fg uppercase outline-none transition focus-visible:ring-2 focus-visible:ring-ring data-[invalid]:border-red-500 data-[invalid]:text-red-500"
+        spellcheck="false"
+        autocomplete="off"
+      />
+    </div>
+
+    <p class="font-mono text-xs text-fg-subtle">
+      v-model → <span class="text-fg-muted">{{ hex }}</span>
+    </p>
+  </ColorFieldRoot>
+</template>
diff --git a/vue/primitives/src/color/color-field/index.ts b/vue/primitives/src/color/color-field/index.ts
new file mode 100644
index 0000000..fb76b80
--- /dev/null
+++ b/vue/primitives/src/color/color-field/index.ts
@@ -0,0 +1,18 @@
+export { default as ColorFieldRoot } from './ColorFieldRoot.vue';
+export { default as ColorFieldHiddenInput } from './ColorFieldHiddenInput.vue';
+export { default as ColorFieldInput } from './ColorFieldInput.vue';
+export { default as ColorFieldLabel } from './ColorFieldLabel.vue';
+export { default as ColorFieldSwatch } from './ColorFieldSwatch.vue';
+export type { ColorFieldRootProps } from './ColorFieldRoot.vue';
+export type { ColorFieldHiddenInputProps } from './ColorFieldHiddenInput.vue';
+export type { ColorFieldInputProps } from './ColorFieldInput.vue';
+export type { ColorFieldLabelProps } from './ColorFieldLabel.vue';
+export type { ColorFieldSwatchProps } from './ColorFieldSwatch.vue';
+export {
+  type ColorFieldContext,
+  colorFieldContextKey,
+  type ColorFormat,
+  provideColorFieldContext,
+  useColorFieldContext,
+} from './context';
+export { useColorState, useHsvaSetters } from './useColorState';
diff --git a/vue/primitives/src/color/color-field/useColorState.ts b/vue/primitives/src/color/color-field/useColorState.ts
new file mode 100644
index 0000000..3adffff
--- /dev/null
+++ b/vue/primitives/src/color/color-field/useColorState.ts
@@ -0,0 +1,135 @@
+import type { Ref } from 'vue';
+import { computed, inject, ref, watch } from 'vue';
+import type { HSVA } from '../../internal/color';
+import { clampChannel } from '../../internal/color';
+import { colorFieldContextKey } from './context';
+
+/**
+ * Wraps the four canonical HSVA channel setters so they all share one
+ * **preserve-hue** policy and never round-trip through RGB.
+ *
+ * When saturation or value collapses to `0` the hue becomes ambiguous (any hue
+ * yields the same grey). Photoshop's HSB picker keeps the *last meaningful* hue
+ * so dragging into and back out of a corner restores the colour the user
+ * expects. We track that last non-zero hue and re-apply it whenever the live
+ * hue would otherwise be lost.
+ *
+ * @param hsva The reactive canonical colour to mutate.
+ */
+export function useHsvaSetters(hsva: Ref<HSVA>): {
+  setHue: (hue: number) => void;
+  setSaturation: (saturation: number) => void;
+  setValue: (value: number) => void;
+  setAlpha: (alpha: number) => void;
+  setSaturationValue: (saturation: number, value: number) => void;
+} {
+  // Seed the remembered hue from the initial colour.
+  let lastHue = hsva.value.h;
+
+  // Keep `lastHue` current whenever a real (non-grey) colour is present, so an
+  // externally driven hue change is respected on the next preserve.
+  // No `deep: true`: `hsva` is replaced wholesale on every change, so watching its
+  // identity already fires per update — a deep traverse of {h,s,v,a} (once per
+  // pointer-move during a colour drag) is pure overhead.
+  watch(
+    () => hsva.value,
+    (c) => {
+      if (c.s > 0 && c.v > 0) lastHue = c.h;
+    },
+  );
+
+  function commit(next: HSVA): void {
+    hsva.value = next;
+  }
+
+  function setHue(hue: number): void {
+    // Clamp to the [0, 360] rail rather than wrapping: the picker treats hue as
+    // a bounded slider, so `End` (360°) stays 360 instead of collapsing to 0.
+    // Rendering still normalizes internally, so 360 reads as red like 0.
+    const h = clampChannel(hue, 360);
+    lastHue = h;
+    commit({ ...hsva.value, h });
+  }
+
+  function setSaturation(saturation: number): void {
+    const s = clampChannel(saturation, 1);
+    const cur = hsva.value;
+    // Preserve hue when the colour was/becomes grey.
+    const h = s > 0 && cur.v > 0 ? cur.h : lastHue;
+    commit({ ...cur, s, h });
+  }
+
+  function setValue(value: number): void {
+    const v = clampChannel(value, 1);
+    const cur = hsva.value;
+    const h = cur.s > 0 && v > 0 ? cur.h : lastHue;
+    commit({ ...cur, v, h });
+  }
+
+  function setAlpha(alpha: number): void {
+    commit({ ...hsva.value, a: clampChannel(alpha, 1) });
+  }
+
+  function setSaturationValue(saturation: number, value: number): void {
+    const s = clampChannel(saturation, 1);
+    const v = clampChannel(value, 1);
+    const cur = hsva.value;
+    const h = s > 0 && v > 0 ? cur.h : lastHue;
+    commit({ ...cur, s, v, h });
+  }
+
+  return { setHue, setSaturation, setValue, setAlpha, setSaturationValue };
+}
+
+/**
+ * Resolve the colour state a picker sub-component should drive.
+ *
+ * - When a `ColorFieldRoot` is an ancestor, the sub-component reads and writes
+ *   that shared context so the whole cluster stays in sync.
+ * - Otherwise the sub-component is **standalone**: it owns the supplied
+ *   `standalone` HSVA ref (typically backed by `defineModel`) and gets its own
+ *   preserve-hue setters.
+ *
+ * Returns the resolved `hsva` ref plus the five channel setters, regardless of
+ * which mode is active, so the caller never branches.
+ *
+ * @param standalone The component's own HSVA ref, used only when no field
+ *   context is present.
+ * @param disabledLocal The component's own `disabled` getter (standalone mode).
+ */
+export function useColorState(
+  standalone: Ref<HSVA>,
+  disabledLocal: () => boolean,
+): {
+  hsva: Ref<HSVA>;
+  disabled: Ref<boolean>;
+  labelId: Ref<string | undefined>;
+  setHue: (hue: number) => void;
+  setSaturation: (saturation: number) => void;
+  setValue: (value: number) => void;
+  setAlpha: (alpha: number) => void;
+  setSaturationValue: (saturation: number, value: number) => void;
+} {
+  const field = inject(colorFieldContextKey, null);
+
+  if (field) {
+    return {
+      hsva: field.hsva,
+      disabled: computed(() => field.disabled.value || disabledLocal()),
+      labelId: field.labelId,
+      setHue: field.setHue,
+      setSaturation: field.setSaturation,
+      setValue: field.setValue,
+      setAlpha: field.setAlpha,
+      setSaturationValue: field.setSaturationValue,
+    };
+  }
+
+  const setters = useHsvaSetters(standalone);
+  return {
+    hsva: standalone,
+    disabled: computed(disabledLocal),
+    labelId: ref<string | undefined>(undefined),
+    ...setters,
+  };
+}
diff --git a/vue/primitives/src/color/hue-slider/HueSliderRoot.vue b/vue/primitives/src/color/hue-slider/HueSliderRoot.vue
new file mode 100644
index 0000000..bcef2fe
--- /dev/null
+++ b/vue/primitives/src/color/hue-slider/HueSliderRoot.vue
@@ -0,0 +1,150 @@
+<script lang="ts">
+import type { HueSliderDirection, HueSliderOrientation } from './context';
+import type { HSVA } from '../../internal/color';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A 1D slider for picking the hue (`0–360°`) of a colour. It works standalone —
+ * owning its own `HSVA` via `v-model` / `defaultValue` — or, when nested inside
+ * a `ColorFieldRoot`, reads and writes that shared colour so the whole picker
+ * cluster stays in sync. Mirrors the standard slider anatomy: the root owns the
+ * value, maps pointer drags along the track, handles arrow / Page / Home / End
+ * keys, and provides context to `HueSliderTrack` and `HueSliderThumb`. The
+ * gradient background should run through the full hue wheel; style it via the
+ * exposed slot/`data-*` hooks. Reach for it as the hue rail of a colour picker.
+ */
+export interface HueSliderRootProps extends PrimitiveProps {
+  /** Uncontrolled initial colour. @default { h: 0, s: 1, v: 1, a: 1 } */
+  defaultValue?: HSVA;
+  /** Keyboard step in degrees. @default 1 */
+  step?: number;
+  /** Large-step multiplier (Page keys / Shift+Arrow). @default 10 */
+  largeStep?: number;
+  /** Orientation. @default 'horizontal' */
+  orientation?: HueSliderOrientation;
+  /** Writing direction (inherited from `ConfigProvider` when omitted). */
+  dir?: HueSliderDirection;
+  /** Disable interaction. @default false */
+  disabled?: boolean;
+}
+
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, toRef, watch } from 'vue';
+import { clampChannel } from '../../internal/color';
+import { Primitive } from '../../internal/primitive';
+import { provideHueSliderContext } from './context';
+import { useColorState } from '../color-field/useColorState';
+import { useDirection } from '../../utilities/config-provider';
+import { usePointerDrag } from '../../internal/pointer-drag';
+import { useForwardExpose } from '@robonen/vue';
+
+const {
+  defaultValue,
+  step = 1,
+  largeStep = 10,
+  orientation = 'horizontal',
+  dir,
+  disabled = false,
+  as = 'span',
+} = defineProps<HueSliderRootProps>();
+
+const direction = useDirection(() => dir);
+
+// Standalone colour state (used only when there is no `ColorFieldRoot`).
+// shallowRef: HSVA is replaced wholesale by the setters, never mutated in place.
+const model = defineModel<HSVA | null>();
+const standalone = shallowRef<HSVA>(model.value ?? defaultValue ?? { h: 0, s: 1, v: 1, a: 1 });
+
+// Reflect standalone writes out through the model.
+const standaloneState = computed<HSVA>({
+  get: () => standalone.value,
+  set: (v) => {
+    standalone.value = v;
+    model.value = v;
+  },
+});
+
+// Resolve shared (ColorField) vs standalone colour + setters.
+const colorState = useColorState(standaloneState, () => disabled);
+
+const hue = computed(() => colorState.hsva.value.h);
+
+const trackRef = shallowRef<HTMLElement | null>(null);
+
+function setHue(next: number): void {
+  if (colorState.disabled.value) return;
+  // Hue is cyclic but the slider treats it as a clamped [0,360] rail.
+  colorState.setHue(clampChannel(next, 360));
+}
+
+// Rect cached for the duration of a gesture (snapshotted in `onStart`): the track
+// box cannot change mid-drag, so re-reading getBoundingClientRect() every onMove
+// frame is a needless forced reflow. A live read is the fallback for any caller
+// without a cached rect.
+let gestureRect: DOMRect | undefined;
+
+function hueFromPointer(clientCoord: { x: number; y: number }, rect?: DOMRect): number {
+  const r = rect ?? trackRef.value?.getBoundingClientRect();
+  if (!r) return hue.value;
+  const horizontal = orientation === 'horizontal';
+  const size = horizontal ? r.width : r.height;
+  if (size === 0) return hue.value;
+  let offset = horizontal ? clientCoord.x - r.left : clientCoord.y - r.top;
+  // Horizontal ltr: left = 0. RTL flips. Vertical: top = max by convention.
+  const flip = horizontal ? direction.value === 'rtl' : true;
+  if (flip) offset = size - offset;
+  return clampChannel((offset / size) * 360, 360);
+}
+
+usePointerDrag(trackRef, {
+  axis: orientation === 'horizontal' ? 'x' : 'y',
+  threshold: 0,
+  disabled: () => colorState.disabled.value,
+  onStart: (state) => {
+    gestureRect = trackRef.value?.getBoundingClientRect();
+    setHue(hueFromPointer({ x: state.point.x, y: state.point.y }, gestureRect));
+  },
+  onMove: (state) => {
+    setHue(hueFromPointer({ x: state.point.x, y: state.point.y }, gestureRect));
+  },
+  onEnd: () => {
+    gestureRect = undefined;
+  },
+});
+
+provideHueSliderContext({
+  hsva: colorState.hsva,
+  hue,
+  step: toRef(() => step),
+  largeStep: toRef(() => largeStep),
+  orientation: toRef(() => orientation),
+  direction,
+  disabled: colorState.disabled,
+  labelId: colorState.labelId,
+  trackRef,
+  setHue,
+});
+
+defineExpose({ hue });
+
+// The root element IS the draggable rail; bind it as the geometry track.
+const { forwardRef, currentElement } = useForwardExpose();
+watch(currentElement, (node) => {
+  trackRef.value = node ?? null;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :dir="direction"
+    :aria-disabled="colorState.disabled.value || undefined"
+    :data-disabled="colorState.disabled.value ? '' : undefined"
+    :data-orientation="orientation"
+  >
+    <slot :hue="hue" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/hue-slider/HueSliderThumb.vue b/vue/primitives/src/color/hue-slider/HueSliderThumb.vue
new file mode 100644
index 0000000..4c22214
--- /dev/null
+++ b/vue/primitives/src/color/hue-slider/HueSliderThumb.vue
@@ -0,0 +1,128 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The draggable handle of a `HueSliderRoot`, rendered as `role="slider"` with
+ * full ARIA value attributes (`aria-valuemin="0"`, `aria-valuemax="360"`,
+ * `aria-valuenow` = current hue, `aria-valuetext` = `"<n>°"`). It positions
+ * itself along the track by the hue percentage and handles keyboard interaction
+ * (arrows step by `step`, Page Up/Down and Shift+Arrow by the large step,
+ * Home/End jump to `0°`/`360°`). Give it an `aria-label` or rely on the default
+ * `"Hue"`. Exposes `hue` and `percent` as slot props.
+ */
+export interface HueSliderThumbProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { computed, useAttrs } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useHueSliderContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'span' } = defineProps<HueSliderThumbProps>();
+const ctx = useHueSliderContext();
+const attrs = useAttrs();
+
+const hue = computed(() => ctx.hue.value);
+const percent = computed(() => (hue.value / 360) * 100);
+
+// Fall back to the default "Hue" label unless the consumer supplied an
+// explicit accessible name.
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return ctx.labelId.value ? undefined : 'Hue';
+});
+
+const valueText = computed(() => `${Math.round(hue.value)}°`);
+
+const positionStyle = computed<{
+  left: string | undefined;
+  right: string | undefined;
+  top: string | undefined;
+  bottom: string | undefined;
+}>(() => {
+  const pct = percent.value;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const rtl = ctx.direction.value === 'rtl';
+  if (horizontal) {
+    return {
+      left: rtl ? undefined : `${pct}%`,
+      right: rtl ? `${pct}%` : undefined,
+      top: undefined,
+      bottom: undefined,
+    };
+  }
+  return { left: undefined, right: undefined, top: undefined, bottom: `${pct}%` };
+});
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value) return;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const rtl = ctx.direction.value === 'rtl';
+  const step = ctx.step.value;
+  const big = step * ctx.largeStep.value;
+  const unit = event.shiftKey ? big : step;
+  const current = ctx.hue.value;
+  let delta: number;
+  switch (event.key) {
+    case 'ArrowRight':
+      delta = horizontal ? (rtl ? -unit : unit) : 0;
+      break;
+    case 'ArrowLeft':
+      delta = horizontal ? (rtl ? unit : -unit) : 0;
+      break;
+    case 'ArrowUp':
+      delta = horizontal ? 0 : unit;
+      break;
+    case 'ArrowDown':
+      delta = horizontal ? 0 : -unit;
+      break;
+    case 'PageUp':
+      delta = big;
+      break;
+    case 'PageDown':
+      delta = -big;
+      break;
+    case 'Home':
+      event.preventDefault();
+      ctx.setHue(0);
+      return;
+    case 'End':
+      event.preventDefault();
+      ctx.setHue(360);
+      return;
+    default:
+      return;
+  }
+  if (delta === 0) return;
+  event.preventDefault();
+  ctx.setHue(current + delta);
+}
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="slider"
+    :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
+    :aria-labelledby="!accessibleLabel ? ctx.labelId.value : undefined"
+    :aria-valuemin="0"
+    :aria-valuemax="360"
+    :aria-valuenow="Math.round(hue)"
+    :aria-valuetext="valueText"
+    :aria-orientation="ctx.orientation.value"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+    :style="positionStyle"
+    @keydown="onKeyDown"
+  >
+    <slot :hue="hue" :percent="percent" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/color/hue-slider/__test__/HueSlider.test.ts b/vue/primitives/src/color/hue-slider/__test__/HueSlider.test.ts
new file mode 100644
index 0000000..0839c36
--- /dev/null
+++ b/vue/primitives/src/color/hue-slider/__test__/HueSlider.test.ts
@@ -0,0 +1,120 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { HSVA } from '../../../internal/color';
+import { HueSliderRoot, HueSliderThumb } from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false }));
+}
+
+function mountHue(opts: Partial<{ defaultValue: HSVA; step: number; disabled: boolean; orientation: 'horizontal' | 'vertical' }> = {}) {
+  const model = ref<HSVA | undefined>(undefined);
+  const Harness = defineComponent({
+    setup: () => () => h(HueSliderRoot, {
+      modelValue: model.value,
+      'onUpdate:modelValue': (v: HSVA | null | undefined) => { model.value = v ?? undefined; },
+      ...opts,
+    }, { default: () => h(HueSliderThumb) }),
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+describe('HueSlider', () => {
+  it('thumb is role=slider with hue aria-value*', async () => {
+    mountHue({ defaultValue: { h: 120, s: 1, v: 1, a: 1 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb).toBeTruthy();
+    expect(thumb.getAttribute('aria-valuemin')).toBe('0');
+    expect(thumb.getAttribute('aria-valuemax')).toBe('360');
+    expect(thumb.getAttribute('aria-valuenow')).toBe('120');
+    expect(thumb.getAttribute('aria-valuetext')).toBe('120°');
+    expect(thumb.getAttribute('aria-label')).toBe('Hue');
+    expect(thumb.tabIndex).toBe(0);
+  });
+
+  it('ArrowRight / ArrowLeft step the hue', async () => {
+    const { model } = mountHue({ defaultValue: { h: 100, s: 1, v: 1, a: 1 }, step: 5 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value!.h).toBe(105);
+    keydown(thumb, 'ArrowLeft');
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(model.value!.h).toBe(95);
+  });
+
+  it('Shift+Arrow uses the large step', async () => {
+    const { model } = mountHue({ defaultValue: { h: 100, s: 1, v: 1, a: 1 }, step: 1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(model.value!.h).toBe(110);
+  });
+
+  it('Home / End clamp to 0 / 360', async () => {
+    const { model } = mountHue({ defaultValue: { h: 180, s: 1, v: 1, a: 1 } });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value!.h).toBe(0);
+    keydown(thumb, 'End');
+    await nextTick();
+    expect(model.value!.h).toBe(360);
+  });
+
+  it('clamps within [0, 360]', async () => {
+    const { model } = mountHue({ defaultValue: { h: 2, s: 1, v: 1, a: 1 }, step: 5 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(model.value!.h).toBe(0);
+  });
+
+  it('preserves saturation / value / alpha while only changing hue', async () => {
+    const { model } = mountHue({ defaultValue: { h: 100, s: 0.4, v: 0.6, a: 0.8 }, step: 10 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toMatchObject({ h: 110, s: 0.4, v: 0.6, a: 0.8 });
+  });
+
+  it('disabled: tabindex=-1 and keys do nothing', async () => {
+    const { model } = mountHue({ defaultValue: { h: 100, s: 1, v: 1, a: 1 }, disabled: true });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.tabIndex).toBe(-1);
+    expect(thumb.getAttribute('aria-disabled')).toBe('true');
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+
+  it('vertical orientation reports aria-orientation', async () => {
+    mountHue({ defaultValue: { h: 100, s: 1, v: 1, a: 1 }, orientation: 'vertical' });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.getAttribute('aria-orientation')).toBe('vertical');
+  });
+});
diff --git a/vue/primitives/src/color/hue-slider/__test__/__screenshots__/HueSlider.test.ts/HueSlider-Home---End-clamp-to-0---360-1.png b/vue/primitives/src/color/hue-slider/__test__/__screenshots__/HueSlider.test.ts/HueSlider-Home---End-clamp-to-0---360-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/color/hue-slider/__test__/__screenshots__/HueSlider.test.ts/HueSlider-Home---End-clamp-to-0---360-1.png differ
diff --git a/vue/primitives/src/color/hue-slider/context.ts b/vue/primitives/src/color/hue-slider/context.ts
new file mode 100644
index 0000000..9603cf4
--- /dev/null
+++ b/vue/primitives/src/color/hue-slider/context.ts
@@ -0,0 +1,36 @@
+import type { Ref } from 'vue';
+import type { HSVA } from '../../internal/color';
+import { useContextFactory } from '@robonen/vue';
+
+export type HueSliderOrientation = 'horizontal' | 'vertical';
+export type HueSliderDirection = 'ltr' | 'rtl';
+
+/**
+ * Context shared between `HueSliderRoot` and `HueSliderThumb`.
+ *
+ * Scalar props are exposed as plain `Ref<T>` — `HueSliderRoot` builds them with
+ * `toRef(() => prop)` (a reactive getter ref without an extra effect).
+ */
+export interface HueSliderContext {
+  /** The canonical colour the slider reads its hue from. */
+  hsva: Ref<HSVA>;
+  /** Current hue (`0–360`). */
+  hue: Ref<number>;
+  /** Step granularity for keyboard nudges. */
+  step: Ref<number>;
+  /** Large-step multiplier (Page keys / Shift+Arrow). */
+  largeStep: Ref<number>;
+  orientation: Ref<HueSliderOrientation>;
+  direction: Ref<HueSliderDirection>;
+  disabled: Ref<boolean>;
+  /** Accessible name id contributed by a `ColorFieldLabel`, if present. */
+  labelId: Ref<string | undefined>;
+  trackRef: Ref<HTMLElement | null>;
+  /** Set the hue (`0–360`); clamped/wrapped by the root. */
+  setHue: (hue: number) => void;
+}
+
+const ctx = useContextFactory<HueSliderContext>('HueSliderContext');
+
+export const provideHueSliderContext = ctx.provide;
+export const useHueSliderContext = ctx.inject;
diff --git a/vue/primitives/src/color/hue-slider/demo.vue b/vue/primitives/src/color/hue-slider/demo.vue
new file mode 100644
index 0000000..bad4d66
--- /dev/null
+++ b/vue/primitives/src/color/hue-slider/demo.vue
@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import type { HSVA } from '@robonen/primitives';
+import { HueSliderRoot, HueSliderThumb, hsvToRgb } from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+const color = ref<HSVA>({ h: 210, s: 1, v: 1, a: 1 });
+
+const rgb = computed(() => hsvToRgb({ h: color.value.h, s: 1, v: 1 }));
+const hueColor = computed(() => `rgb(${rgb.value.r}, ${rgb.value.g}, ${rgb.value.b})`);
+
+const HUE_GRADIENT
+  = 'linear-gradient(to right, #f00 0%, #ff0 17%, #0f0 33%, #0ff 50%, #00f 67%, #f0f 83%, #f00 100%)';
+</script>
+
+<template>
+  <div class="demo-card flex w-full max-w-sm flex-col gap-5 p-6 text-fg">
+    <div class="flex items-baseline justify-between text-sm">
+      <span class="font-medium">Hue</span>
+      <span class="font-mono text-fg-muted">{{ Math.round(color.h) }}°</span>
+    </div>
+
+    <!-- The hue rail: the root span IS the track -->
+    <HueSliderRoot
+      v-model="color"
+      class="relative block h-4 w-full touch-none select-none rounded-full border border-border shadow-(--shadow-card)"
+      :style="{ background: HUE_GRADIENT }"
+    >
+      <HueSliderThumb
+        aria-label="Hue"
+        class="absolute top-1/2 z-10 size-5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-md outline-none ring-1 ring-black/25 transition-[transform] focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
+        :style="{ backgroundColor: hueColor }"
+      />
+    </HueSliderRoot>
+
+    <div class="flex items-center gap-3 rounded-card bg-bg-inset p-3">
+      <span
+        class="size-9 shrink-0 rounded-lg border border-border-strong"
+        :style="{ backgroundColor: hueColor }"
+      />
+      <div class="flex flex-col text-sm leading-tight">
+        <span class="font-mono text-fg">{{ hueColor }}</span>
+        <span class="font-mono text-xs text-fg-subtle">hue {{ Math.round(color.h) }}° of 360°</span>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/color/hue-slider/index.ts b/vue/primitives/src/color/hue-slider/index.ts
new file mode 100644
index 0000000..7703c2a
--- /dev/null
+++ b/vue/primitives/src/color/hue-slider/index.ts
@@ -0,0 +1,11 @@
+export { default as HueSliderRoot } from './HueSliderRoot.vue';
+export { default as HueSliderThumb } from './HueSliderThumb.vue';
+export type { HueSliderRootProps } from './HueSliderRoot.vue';
+export type { HueSliderThumbProps } from './HueSliderThumb.vue';
+export {
+  type HueSliderContext,
+  type HueSliderDirection,
+  type HueSliderOrientation,
+  provideHueSliderContext,
+  useHueSliderContext,
+} from './context';
diff --git a/vue/primitives/src/combobox/ComboboxViewport.vue b/vue/primitives/src/combobox/ComboboxViewport.vue
deleted file mode 100644
index 08fc65f..0000000
--- a/vue/primitives/src/combobox/ComboboxViewport.vue
+++ /dev/null
@@ -1,36 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The scrollable region inside ComboboxContent that holds the items. Provides the overflow
- * container that keeps the highlighted item scrolled into view.
- */
-export interface ComboboxViewportProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { watchPostEffect } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { useComboboxContentContext } from './context';
-
-const { as = 'div' } = defineProps<ComboboxViewportProps>();
-
-const { forwardRef, currentElement } = useForwardExpose();
-const contentCtx = useComboboxContentContext();
-
-watchPostEffect(() => contentCtx.onViewportChange(currentElement.value));
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    role="presentation"
-    data-primitives-combobox-viewport
-    style="position: relative; flex: 1 1 0%; overflow: hidden auto"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/combobox/utils.ts b/vue/primitives/src/combobox/utils.ts
deleted file mode 100644
index 5ad775f..0000000
--- a/vue/primitives/src/combobox/utils.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-export type AcceptableValue = string | number | boolean | Record<string, unknown>;
-
-export const OPEN_KEYS = ['Enter', ' ', 'ArrowDown', 'ArrowUp', 'PageUp', 'PageDown', 'Home', 'End'];
-// The input is a text field: Space must type a space and Home/End/Page* must move
-// the caret, so only the arrow keys open a closed list (typing opens it via input).
-export const INPUT_OPEN_KEYS = ['ArrowDown', 'ArrowUp'];
-export const SELECTION_KEYS = ['Enter', ' '];
-
-export function clamp(value: number, min: number, max: number): number {
-  return Math.min(Math.max(value, min), max);
-}
-
-export function getOpenState(open: boolean): 'open' | 'closed' {
-  return open ? 'open' : 'closed';
-}
-
-export function compare<T>(
-  a: T | undefined,
-  b: T | undefined,
-  by?: string | ((a: T, b: T) => boolean),
-): boolean {
-  if (a === undefined || b === undefined) return false;
-  if (by === undefined) return a === b;
-  if (typeof by === 'function') return by(a as T, b as T);
-  return (a as any)?.[by] === (b as any)?.[by];
-}
-
-export function valueComparator<T>(
-  value: T | T[] | undefined,
-  current: T,
-  by?: string | ((a: T, b: T) => boolean),
-): boolean {
-  if (value === undefined) return false;
-  if (!Array.isArray(value)) return compare(value, current, by);
-  for (const v of value) {
-    if (compare(v, current, by)) return true;
-  }
-  return false;
-}
-
-export interface ComboboxFilterItem {
-  id: string;
-  textValue: string;
-}
-
-export type ComboboxFilterFunction = (
-  items: ComboboxFilterItem[],
-  searchTerm: string,
-) => ComboboxFilterItem[];
-
-export const defaultFilter: ComboboxFilterFunction = (items, searchTerm) => {
-  const term = searchTerm.toLowerCase();
-  if (!term) return items;
-  const out: ComboboxFilterItem[] = [];
-  for (let i = 0; i < items.length; i++) {
-    const it = items[i]!;
-    if (it.textValue.toLowerCase().includes(term)) out.push(it);
-  }
-  return out;
-};
diff --git a/vue/primitives/src/command/demo.vue b/vue/primitives/src/command/demo.vue
deleted file mode 100644
index 0473790..0000000
--- a/vue/primitives/src/command/demo.vue
+++ /dev/null
@@ -1,134 +0,0 @@
-<script setup lang="ts">
-import { ref } from 'vue';
-
-import {
-  CommandEmpty,
-  CommandGroup,
-  CommandInput,
-  CommandItem,
-  CommandList,
-  CommandRoot,
-  CommandSeparator,
-} from '@robonen/primitives';
-
-interface Action {
-  value: string;
-  label: string;
-  icon: string;
-  keywords?: string[];
-  shortcut?: string;
-}
-
-const navigation: Action[] = [
-  { value: 'home', label: 'Go to Dashboard', icon: 'i-carbon-dashboard', keywords: ['overview', 'start'] },
-  { value: 'projects', label: 'Open Projects', icon: 'i-carbon-folder', keywords: ['repos', 'work'] },
-  { value: 'settings', label: 'Open Settings', icon: 'i-carbon-settings', keywords: ['preferences', 'config'], shortcut: ',' },
-];
-
-const actions: Action[] = [
-  { value: 'new-file', label: 'Create new file', icon: 'i-carbon-document-add', keywords: ['add'], shortcut: 'N' },
-  { value: 'invite', label: 'Invite teammate', icon: 'i-carbon-user-follow', keywords: ['member', 'share'] },
-  { value: 'theme', label: 'Toggle dark mode', icon: 'i-carbon-moon', keywords: ['appearance', 'light'] },
-  { value: 'archive', label: 'Archive workspace', icon: 'i-carbon-archive', keywords: ['delete'] },
-];
-
-const selected = ref<string>();
-const lastRun = ref<string>();
-
-function run(value: string) {
-  lastRun.value = value;
-}
-</script>
-
-<template>
-  <div class="flex flex-col items-center gap-4 p-6 bg-(--bg-inset) text-(--fg)">
-    <CommandRoot
-      v-model="selected"
-      label="Command palette"
-      loop
-      class="w-full max-w-100 overflow-hidden rounded-xl border border-(--border) bg-(--bg-elevated) shadow-lg"
-    >
-      <template #default="{ filteredCount }">
-        <!-- Search -->
-        <div class="flex items-center gap-2 border-b border-(--border) px-3">
-          <span class="i-carbon-search shrink-0 text-(--fg-subtle)" aria-hidden="true" />
-          <CommandInput
-            auto-focus
-            placeholder="Type a command or search…"
-            class="w-full bg-transparent py-3 text-sm text-(--fg) outline-none placeholder:text-(--fg-subtle)"
-          />
-          <span class="shrink-0 text-xs tabular-nums text-(--fg-subtle)">{{ filteredCount }}</span>
-        </div>
-
-        <!-- Results -->
-        <CommandList class="max-h-72 overflow-y-auto p-2">
-          <CommandEmpty class="px-3 py-8 text-center text-sm text-(--fg-muted)">
-            No results found.
-          </CommandEmpty>
-
-          <CommandGroup
-            heading="Navigation"
-            class="[&_[data-primitives-command-group-heading]]:px-2 [&_[data-primitives-command-group-heading]]:pb-1 [&_[data-primitives-command-group-heading]]:pt-2 [&_[data-primitives-command-group-heading]]:text-xs [&_[data-primitives-command-group-heading]]:font-medium [&_[data-primitives-command-group-heading]]:text-(--fg-subtle)"
-          >
-            <template #default>
-              <CommandItem
-                v-for="item in navigation"
-                :key="item.value"
-                :value="item.value"
-                :keywords="item.keywords"
-                class="group flex cursor-pointer items-center gap-2 rounded-md px-2 py-2 text-sm data-[state=selected]:bg-(--accent) data-[state=selected]:text-(--accent-fg)"
-                @select="run"
-              >
-                <template #default="{ selected: isSelected }">
-                  <span :class="item.icon" class="shrink-0 text-(--fg-muted) group-data-[state=selected]:text-(--accent-fg)" aria-hidden="true" />
-                  <span class="flex-1">{{ item.label }}</span>
-                  <kbd
-                    v-if="item.shortcut"
-                    class="rounded border border-(--border) bg-(--bg-subtle) px-1.5 text-xs text-(--fg-muted) group-data-[state=selected]:border-transparent"
-                  >⌘{{ item.shortcut }}</kbd>
-                  <span v-if="isSelected" class="i-carbon-checkmark text-emerald-500 dark:text-emerald-400" aria-hidden="true" />
-                </template>
-              </CommandItem>
-            </template>
-          </CommandGroup>
-
-          <CommandSeparator class="my-2 h-px bg-(--border)" />
-
-          <CommandGroup
-            heading="Actions"
-            class="[&_[data-primitives-command-group-heading]]:px-2 [&_[data-primitives-command-group-heading]]:pb-1 [&_[data-primitives-command-group-heading]]:pt-2 [&_[data-primitives-command-group-heading]]:text-xs [&_[data-primitives-command-group-heading]]:font-medium [&_[data-primitives-command-group-heading]]:text-(--fg-subtle)"
-          >
-            <template #default>
-              <CommandItem
-                v-for="item in actions"
-                :key="item.value"
-                :value="item.value"
-                :keywords="item.keywords"
-                :disabled="item.value === 'archive'"
-                class="group flex cursor-pointer items-center gap-2 rounded-md px-2 py-2 text-sm data-[state=selected]:bg-(--accent) data-[state=selected]:text-(--accent-fg) data-[disabled]:cursor-not-allowed data-[disabled]:opacity-40"
-                @select="run"
-              >
-                <span :class="item.icon" class="shrink-0 text-(--fg-muted) group-data-[state=selected]:text-(--accent-fg)" aria-hidden="true" />
-                <span class="flex-1">{{ item.label }}</span>
-                <span v-if="item.value === 'archive'" class="text-xs text-red-500 dark:text-red-400">disabled</span>
-                <kbd
-                  v-else-if="item.shortcut"
-                  class="rounded border border-(--border) bg-(--bg-subtle) px-1.5 text-xs text-(--fg-muted) group-data-[state=selected]:border-transparent"
-                >⌘{{ item.shortcut }}</kbd>
-              </CommandItem>
-            </template>
-          </CommandGroup>
-        </CommandList>
-      </template>
-    </CommandRoot>
-
-    <p class="text-sm text-(--fg-muted)">
-      <template v-if="lastRun">
-        Ran: <code class="rounded bg-(--bg-subtle) px-1.5 py-0.5 font-medium text-(--fg)">{{ lastRun }}</code>
-      </template>
-      <template v-else>
-        Use ↑ ↓ to navigate, Enter to run.
-      </template>
-    </p>
-  </div>
-</template>
diff --git a/vue/primitives/src/config-provider/__test__/config-provider.test.ts b/vue/primitives/src/config-provider/__test__/config-provider.test.ts
deleted file mode 100644
index 3b0daf7..0000000
--- a/vue/primitives/src/config-provider/__test__/config-provider.test.ts
+++ /dev/null
@@ -1,197 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { computed, defineComponent, h } from 'vue';
-import { mount } from '@vue/test-utils';
-import {
-  provideAppConfig,
-  provideConfig,
-  useConfig,
-  useId,
-} from '..';
-
-// --- useConfig ---
-
-describe('useConfig', () => {
-  it('returns default config when no provider exists', () => {
-    const wrapper = mount(
-      defineComponent({
-        setup() {
-          const config = useConfig();
-          return { config };
-        },
-        render() {
-          return h('div', {
-            'data-dir': this.config.dir.value,
-            'data-target': this.config.teleportTarget.value,
-          });
-        },
-      }),
-    );
-
-    expect(wrapper.find('div').attributes('data-dir')).toBe('ltr');
-    expect(wrapper.find('div').attributes('data-target')).toBe('body');
-
-    wrapper.unmount();
-  });
-
-  it('returns custom config from provideConfig', () => {
-    const Child = defineComponent({
-      setup() {
-        const config = useConfig();
-        return { config };
-      },
-      render() {
-        return h('div', {
-          'data-dir': this.config.dir.value,
-          'data-target': this.config.teleportTarget.value,
-        });
-      },
-    });
-
-    const Parent = defineComponent({
-      setup() {
-        provideConfig({
-          dir: 'rtl',
-          teleportTarget: '#app',
-        });
-      },
-      render() {
-        return h(Child);
-      },
-    });
-
-    const wrapper = mount(Parent);
-
-    expect(wrapper.find('div').attributes('data-dir')).toBe('rtl');
-    expect(wrapper.find('div').attributes('data-target')).toBe('#app');
-
-    wrapper.unmount();
-  });
-
-  it('exposes mutable refs for runtime updates', async () => {
-    const Child = defineComponent({
-      setup() {
-        const config = useConfig();
-        return { config };
-      },
-      render() {
-        return h('div', { 'data-dir': this.config.dir.value });
-      },
-    });
-
-    const Parent = defineComponent({
-      setup() {
-        const config = provideConfig({ dir: 'ltr' });
-        return { config };
-      },
-      render() {
-        return h(Child);
-      },
-    });
-
-    const wrapper = mount(Parent);
-    expect(wrapper.find('div').attributes('data-dir')).toBe('ltr');
-
-    wrapper.vm.config.dir.value = 'rtl';
-    await wrapper.vm.$nextTick();
-
-    expect(wrapper.find('div').attributes('data-dir')).toBe('rtl');
-
-    wrapper.unmount();
-  });
-});
-
-// --- provideAppConfig ---
-
-describe('provideAppConfig', () => {
-  it('provides config at app level', () => {
-    const Child = defineComponent({
-      setup() {
-        const config = useConfig();
-        return { config };
-      },
-      render() {
-        return h('div', {
-          'data-dir': this.config.dir.value,
-        });
-      },
-    });
-
-    const wrapper = mount(Child, {
-      global: {
-        plugins: [
-          app => provideAppConfig(app, { dir: 'rtl' }),
-        ],
-      },
-    });
-
-    expect(wrapper.find('div').attributes('data-dir')).toBe('rtl');
-
-    wrapper.unmount();
-  });
-});
-
-// --- useId override ---
-
-describe('useId (config override)', () => {
-  it('uses the toolkit fallback when no override is provided', () => {
-    const Child = defineComponent({
-      setup() {
-        const id = useId();
-        return { id };
-      },
-      render() {
-        return h('div', { 'data-id': this.id });
-      },
-    });
-
-    const wrapper = mount(Child);
-    expect(wrapper.find('div').attributes('data-id')).toMatch(/^robonen-/);
-    wrapper.unmount();
-  });
-
-  it('routes through a provided useId override', () => {
-    let count = 0;
-    const customUseId = (_deterministic?: unknown, prefix = 'x') => {
-      count += 1;
-      const n = count;
-      return computed(() => `${prefix}-${n}`);
-    };
-
-    const Child = defineComponent({
-      setup() {
-        const a = useId();
-        const b = useId(undefined, 'custom');
-        return { a, b };
-      },
-      render() {
-        return h('div', { 'data-a': this.a, 'data-b': this.b });
-      },
-    });
-
-    const wrapper = mount(Child, {
-      global: {
-        plugins: [app => provideAppConfig(app, { useId: customUseId })],
-      },
-    });
-
-    expect(wrapper.find('div').attributes('data-a')).toBe('x-1');
-    expect(wrapper.find('div').attributes('data-b')).toBe('custom-2');
-    wrapper.unmount();
-  });
-
-  it('respects deterministic id passed through the override', () => {
-    const Child = defineComponent({
-      setup() {
-        const id = useId(() => 'fixed-id');
-        return { id };
-      },
-      render() {
-        return h('div', { 'data-id': this.id });
-      },
-    });
-
-    const wrapper = mount(Child);
-    expect(wrapper.find('div').attributes('data-id')).toBe('fixed-id');
-    wrapper.unmount();
-  });
-});
diff --git a/vue/primitives/src/config-provider/context.ts b/vue/primitives/src/config-provider/context.ts
deleted file mode 100644
index 2d829f2..0000000
--- a/vue/primitives/src/config-provider/context.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import type { App, ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from 'vue';
-import { ref, shallowRef, toValue } from 'vue';
-import { useId as toolkitUseId, useContextFactory } from '@robonen/vue';
-
-export type Direction = 'ltr' | 'rtl';
-
-export type UseIdFn = (
-  deterministic?: MaybeRefOrGetter<string | undefined>,
-  prefix?: string,
-) => ComputedRef<string>;
-
-export interface ConfigContext {
-  dir: Ref<Direction>;
-  teleportTarget: ShallowRef<string | HTMLElement>;
-  useId: UseIdFn;
-}
-
-export interface ConfigOptions {
-  dir?: MaybeRefOrGetter<Direction>;
-  teleportTarget?: MaybeRefOrGetter<string | HTMLElement>;
-  useId?: UseIdFn;
-}
-
-const DEFAULT_CONFIG = {
-  dir: 'ltr' as Direction,
-  teleportTarget: 'body' as string | HTMLElement,
-};
-
-const ConfigCtx = useContextFactory<ConfigContext>('ConfigContext');
-
-function resolveContext(options?: ConfigOptions): ConfigContext {
-  return {
-    dir: ref(toValue(options?.dir) ?? DEFAULT_CONFIG.dir),
-    teleportTarget: shallowRef(toValue(options?.teleportTarget) ?? DEFAULT_CONFIG.teleportTarget),
-    useId: options?.useId ?? toolkitUseId,
-  };
-}
-
-export function provideConfig(options?: ConfigOptions): ConfigContext {
-  return ConfigCtx.provide(resolveContext(options));
-}
-
-export function provideAppConfig(app: App, options?: ConfigOptions): ConfigContext {
-  return ConfigCtx.appProvide(app)(resolveContext(options));
-}
-
-export function useConfig(): ConfigContext {
-  return ConfigCtx.inject(resolveContext());
-}
diff --git a/vue/primitives/src/config-provider/index.ts b/vue/primitives/src/config-provider/index.ts
deleted file mode 100644
index e6a7e0b..0000000
--- a/vue/primitives/src/config-provider/index.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-export {
-  provideConfig,
-  provideAppConfig,
-  useConfig,
-  type ConfigContext,
-  type ConfigOptions,
-  type Direction,
-  type UseIdFn,
-} from './context';
-export { useId } from './useId';
diff --git a/vue/primitives/src/context-menu/ContextMenuContent.vue b/vue/primitives/src/context-menu/ContextMenuContent.vue
deleted file mode 100644
index be97fde..0000000
--- a/vue/primitives/src/context-menu/ContextMenuContent.vue
+++ /dev/null
@@ -1,37 +0,0 @@
-<script lang="ts">
-import type { MenuContentEmits, MenuContentProps } from '../menu';
-
-/**
- * The floating surface that holds the menu items, positioned at the pointer
- * where the menu was invoked. Handles focus management, typeahead, and
- * dismissal on outside click or Escape; render it inside a portal.
- */
-export interface ContextMenuContentProps extends MenuContentProps {}
-export type ContextMenuContentEmits = MenuContentEmits;
-</script>
-
-<script setup lang="ts">
-import { MenuContent } from '../menu';
-
-const props = defineProps<ContextMenuContentProps>();
-const emit = defineEmits<ContextMenuContentEmits>();
-</script>
-
-<template>
-  <MenuContent
-    v-bind="props"
-    side="right"
-    align="start"
-    update-position-strategy="always"
-    @close-auto-focus="emit('closeAutoFocus', $event)"
-    @escape-key-down="emit('escapeKeyDown', $event)"
-    @pointer-down-outside="emit('pointerDownOutside', $event)"
-    @focus-outside="emit('focusOutside', $event)"
-    @interact-outside="emit('interactOutside', $event)"
-    @dismiss="emit('dismiss')"
-    @entry-focus="emit('entryFocus', $event)"
-    @open-auto-focus="emit('openAutoFocus', $event)"
-  >
-    <slot />
-  </MenuContent>
-</template>
diff --git a/vue/primitives/src/context-menu/ContextMenuSub.vue b/vue/primitives/src/context-menu/ContextMenuSub.vue
deleted file mode 100644
index a60605e..0000000
--- a/vue/primitives/src/context-menu/ContextMenuSub.vue
+++ /dev/null
@@ -1,22 +0,0 @@
-<script lang="ts">
-import type { MenuSubEmits, MenuSubProps } from '../menu';
-
-/**
- * Wraps a nested submenu, pairing a `ContextMenuSubTrigger` with its
- * `ContextMenuSubContent` and owning that submenu's open state. Listen to
- * `update:open` to track expansion.
- */
-export interface ContextMenuSubProps extends MenuSubProps {}
-export type ContextMenuSubEmits = MenuSubEmits;
-</script>
-
-<script setup lang="ts">
-import { MenuSub } from '../menu';
-
-const props = defineProps<ContextMenuSubProps>();
-const emit = defineEmits<ContextMenuSubEmits>();
-</script>
-
-<template>
-  <MenuSub v-bind="props" @update:open="emit('update:open', $event)"><slot /></MenuSub>
-</template>
diff --git a/vue/primitives/src/context-menu/ContextMenuTrigger.vue b/vue/primitives/src/context-menu/ContextMenuTrigger.vue
deleted file mode 100644
index 43031aa..0000000
--- a/vue/primitives/src/context-menu/ContextMenuTrigger.vue
+++ /dev/null
@@ -1,101 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The region that captures right-click (and touch/pen long-press), preventing the
- * native context menu and opening the menu anchored at the pointer position.
- * Wrap whatever area should respond to a secondary click.
- */
-export interface ContextMenuTriggerProps extends PrimitiveProps {
-  disabled?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { computed, onScopeDispose, shallowRef } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { MenuAnchor, useMenuContext } from '../menu';
-import { Primitive } from '../primitive';
-import { useContextMenuRootContext } from './context';
-
-const { disabled = false, as = 'span' } = defineProps<ContextMenuTriggerProps>();
-
-const menuCtx = useMenuContext();
-const ctxMenuCtx = useContextMenuRootContext();
-const { forwardRef } = useForwardExpose();
-
-const point = shallowRef({ x: 0, y: 0 });
-const virtualEl = computed(() => ({
-  getBoundingClientRect: () => ({
-    x: point.value.x,
-    y: point.value.y,
-    width: 0,
-    height: 0,
-    top: point.value.y,
-    right: point.value.x,
-    bottom: point.value.y,
-    left: point.value.x,
-    toJSON: () => {},
-  }),
-}));
-
-let longPressTimer: ReturnType<typeof setTimeout> | undefined;
-const LONG_PRESS_DELAY = 700;
-
-function clearLongPress() {
-  clearTimeout(longPressTimer);
-}
-
-onScopeDispose(clearLongPress);
-
-function handleContextMenu(event: MouseEvent) {
-  if (disabled) return;
-  clearLongPress();
-  point.value = { x: event.clientX, y: event.clientY };
-  event.preventDefault();
-  ctxMenuCtx.onOpenChange(true);
-}
-
-function handlePointerDown(event: PointerEvent) {
-  if (disabled || event.button !== 0) return;
-  // Long-press applies to touch AND pen; mouse uses the native contextmenu event.
-  if (event.pointerType === 'mouse') return;
-  clearLongPress();
-  longPressTimer = setTimeout(() => {
-    point.value = { x: event.clientX, y: event.clientY };
-    ctxMenuCtx.onOpenChange(true);
-  }, LONG_PRESS_DELAY);
-}
-
-function handlePointerMove(event: PointerEvent) {
-  // A drag/scroll gesture must not open the menu after the delay.
-  if (event.pointerType !== 'mouse') clearLongPress();
-}
-
-function handlePointerCancel() {
-  clearLongPress();
-}
-
-function handlePointerUp() {
-  clearLongPress();
-}
-</script>
-
-<template>
-  <MenuAnchor as="template" :reference="virtualEl">
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      :data-state="menuCtx.open.value ? 'open' : 'closed'"
-      :data-disabled="disabled ? '' : undefined"
-      @contextmenu="handleContextMenu"
-      @pointerdown="handlePointerDown"
-      @pointermove="handlePointerMove"
-      @pointercancel="handlePointerCancel"
-      @pointerup="handlePointerUp"
-    >
-      <slot />
-    </Primitive>
-  </MenuAnchor>
-</template>
diff --git a/vue/primitives/src/context-menu/__test__/ContextMenu.test.ts b/vue/primitives/src/context-menu/__test__/ContextMenu.test.ts
deleted file mode 100644
index 970e52a..0000000
--- a/vue/primitives/src/context-menu/__test__/ContextMenu.test.ts
+++ /dev/null
@@ -1,175 +0,0 @@
-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 } from 'vue';
-
-import {
-  ContextMenuContent,
-  ContextMenuItem,
-  ContextMenuPortal,
-  ContextMenuRoot,
-  ContextMenuTrigger,
-} from '../../index';
-
-const wrappers: Array<VueWrapper<any>> = [];
-
-afterEach(() => {
-  while (wrappers.length) wrappers.pop()!.unmount();
-  document.body.innerHTML = '';
-  document.body.removeAttribute('style');
-  vi.useRealTimers();
-});
-
-function track<T extends VueWrapper<any>>(w: T): T {
-  wrappers.push(w);
-  return w;
-}
-
-function mountContextMenu(options: {
-  triggerAttrs?: Record<string, unknown>;
-  onUpdateOpen?: (v: boolean) => void;
-} = {}) {
-  const Harness = defineComponent({
-    setup() {
-      return () =>
-        h(
-          ContextMenuRoot,
-          { 'onUpdate:open': options.onUpdateOpen },
-          {
-            default: () => [
-              h(
-                ContextMenuTrigger,
-                { 'data-testid': 'trigger', ...options.triggerAttrs },
-                { default: () => 'Right-click me' },
-              ),
-              h(ContextMenuPortal, null, {
-                default: () =>
-                  h(ContextMenuContent, null, {
-                    default: () => h(ContextMenuItem, null, { default: () => 'Item' }),
-                  }),
-              }),
-            ],
-          },
-        );
-    },
-  });
-  return track(mount(Harness, { attachTo: document.body }));
-}
-
-function getTrigger(): HTMLElement {
-  return document.querySelector('[data-testid="trigger"]') as HTMLElement;
-}
-
-function dispatchContextMenu(el: HTMLElement, x = 100, y = 80) {
-  el.dispatchEvent(new MouseEvent('contextmenu', {
-    bubbles: true,
-    cancelable: true,
-    clientX: x,
-    clientY: y,
-  }));
-}
-
-describe('context-menu — trigger element', () => {
-  it('merges fallthrough attrs onto the element carrying data-state (no anchor wrapper div)', () => {
-    mountContextMenu({ triggerAttrs: { id: 'trigger-el', class: 'canvas-area' } });
-    const trigger = getTrigger();
-    expect(trigger).toBeTruthy();
-    expect(trigger.id).toBe('trigger-el');
-    expect(trigger.classList.contains('canvas-area')).toBe(true);
-    expect(trigger.getAttribute('data-state')).toBe('closed');
-    // No intermediate anchor element between the harness root and the trigger.
-    expect(trigger.parentElement).toBe(wrappers[0]!.element);
-  });
-
-  it('opens the menu when contextmenu is dispatched on the attr-bearing element', async () => {
-    const onUpdateOpen = vi.fn();
-    mountContextMenu({ triggerAttrs: { class: 'canvas-area' }, onUpdateOpen });
-    const trigger = getTrigger();
-
-    dispatchContextMenu(trigger);
-    await nextTick();
-    await nextTick();
-
-    expect(onUpdateOpen).toHaveBeenCalledWith(true);
-    expect(trigger.getAttribute('data-state')).toBe('open');
-    expect(document.querySelector('[role="menu"]')).toBeTruthy();
-  });
-});
-
-describe('context-menu — long-press', () => {
-  function pointerDown(el: HTMLElement, pointerType: string, x = 50, y = 60) {
-    el.dispatchEvent(new PointerEvent('pointerdown', {
-      bubbles: true,
-      button: 0,
-      pointerType,
-      clientX: x,
-      clientY: y,
-    }));
-  }
-
-  it('opens after a 700ms touch long-press', async () => {
-    vi.useFakeTimers();
-    mountContextMenu();
-    const trigger = getTrigger();
-
-    pointerDown(trigger, 'touch');
-    expect(trigger.getAttribute('data-state')).toBe('closed');
-
-    vi.advanceTimersByTime(700);
-    await nextTick();
-    expect(trigger.getAttribute('data-state')).toBe('open');
-  });
-
-  it('opens after a pen long-press', async () => {
-    vi.useFakeTimers();
-    mountContextMenu();
-    const trigger = getTrigger();
-
-    pointerDown(trigger, 'pen');
-    vi.advanceTimersByTime(700);
-    await nextTick();
-    expect(trigger.getAttribute('data-state')).toBe('open');
-  });
-
-  it('cancels the long-press when the pointer moves (drag/scroll gesture)', async () => {
-    vi.useFakeTimers();
-    mountContextMenu();
-    const trigger = getTrigger();
-
-    pointerDown(trigger, 'touch');
-    vi.advanceTimersByTime(300);
-    trigger.dispatchEvent(new PointerEvent('pointermove', {
-      bubbles: true,
-      pointerType: 'touch',
-      clientX: 50,
-      clientY: 120,
-    }));
-    vi.advanceTimersByTime(700);
-    await nextTick();
-    expect(trigger.getAttribute('data-state')).toBe('closed');
-  });
-
-  it('cancels the long-press on pointerup', async () => {
-    vi.useFakeTimers();
-    mountContextMenu();
-    const trigger = getTrigger();
-
-    pointerDown(trigger, 'touch');
-    vi.advanceTimersByTime(300);
-    trigger.dispatchEvent(new PointerEvent('pointerup', { bubbles: true, pointerType: 'touch' }));
-    vi.advanceTimersByTime(700);
-    await nextTick();
-    expect(trigger.getAttribute('data-state')).toBe('closed');
-  });
-
-  it('does not start a long-press for mouse pointers', async () => {
-    vi.useFakeTimers();
-    mountContextMenu();
-    const trigger = getTrigger();
-
-    pointerDown(trigger, 'mouse');
-    vi.advanceTimersByTime(700);
-    await nextTick();
-    expect(trigger.getAttribute('data-state')).toBe('closed');
-  });
-});
diff --git a/vue/primitives/src/context-menu/context.ts b/vue/primitives/src/context-menu/context.ts
deleted file mode 100644
index af2f918..0000000
--- a/vue/primitives/src/context-menu/context.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import type { Ref } from 'vue';
-
-import { useContextFactory } from '@robonen/vue';
-
-export interface ContextMenuRootContext {
-  open: Ref<boolean>;
-  onOpenChange: (open: boolean) => void;
-  modal: Ref<boolean>;
-}
-
-export const {
-  inject: useContextMenuRootContext,
-  provide: provideContextMenuRootContext,
-} = useContextFactory<ContextMenuRootContext>('ContextMenuRootContext');
diff --git a/vue/primitives/src/date-picker/DatePickerRoot.vue b/vue/primitives/src/date-picker/DatePickerRoot.vue
deleted file mode 100644
index 67d1a80..0000000
--- a/vue/primitives/src/date-picker/DatePickerRoot.vue
+++ /dev/null
@@ -1,340 +0,0 @@
-<script lang="ts">
-import type { CalendarMonth, CalendarRootProps, WeekDayFormat } from '../calendar';
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A single-date picker that pairs a popover-anchored calendar with an optional
- * trigger, field, and hidden form input. Owns the selected date, placeholder
- * month, and open state, and provides both date-picker and calendar context to
- * its parts. Use it when you need a compact, accessible "pick one date" control
- * (e.g. a form field) rather than an always-visible `Calendar`.
- */
-export interface DatePickerRootProps extends PrimitiveProps,
-  Omit<CalendarRootProps, 'as' | 'asChild'> {
-  /** Uncontrolled initial open state. */
-  defaultOpen?: boolean;
-  /** Modal popover (traps focus + blocks outside pointer). @default false */
-  modal?: boolean;
-  /** Hidden form input name for submission. */
-  name?: string;
-  /** Format used to serialize the hidden input value. @default 'iso' */
-  valueFormat?: 'iso' | ((d: Date) => string);
-  /** Close popover on selection. @default true */
-  closeOnSelect?: boolean;
-}
-
-export interface DatePickerRootEmits {
-  'update:modelValue': [date: Date | undefined];
-  'update:placeholder': [date: Date];
-  'update:open': [open: boolean];
-}
-</script>
-
-<script setup lang="ts">
-import { useEventListener, useForwardExpose } from '@robonen/vue';
-import { computed, onMounted, ref, toRef, watch } from 'vue';
-import {
-  addMonths,
-  addYears,
-  clamp,
-  createMonths,
-  formatMonthYear,
-  getWeekdayLabels,
-  isAfter,
-  isBefore,
-  isSameDay,
-  isSameMonth,
-  isDateUnavailable as isUnavailable,
-  provideCalendarRootContext,
-  toDateOnly,
-} from '../calendar';
-import { useId } from '../config-provider';
-import { PopperRoot } from '../popper';
-import { Primitive } from '../primitive';
-import { provideDatePickerRootContext } from './context';
-
-defineOptions({ inheritAttrs: false });
-
-const {
-  as = 'div',
-  defaultOpen = false,
-  modal = false,
-  name,
-  valueFormat = 'iso',
-  closeOnSelect = true,
-  defaultValue,
-  defaultPlaceholder,
-  minValue,
-  maxValue,
-  isDateUnavailable: propsIsDateUnavailable,
-  isDateDisabled: propsIsDateDisabled,
-  pagedNavigation = false,
-  weekStartsOn = 0,
-  weekdayFormat = 'short',
-  fixedWeeks = true,
-  numberOfMonths = 1,
-  disabled = false,
-  readonly = false,
-  initialFocus = false,
-  locale = 'en',
-  dir = 'ltr',
-  nextPage: propsNextPage,
-  prevPage: propsPrevPage,
-  calendarLabel = 'Calendar',
-} = defineProps<DatePickerRootProps>();
-
-defineEmits<DatePickerRootEmits>();
-
-const { forwardRef, currentElement: parentElement } = useForwardExpose();
-
-const localOpen = ref<boolean>(defaultOpen);
-const open = defineModel<boolean>('open', {
-  default: undefined,
-  get: v => v ?? localOpen.value,
-  set: (v) => {
-    localOpen.value = v;
-    return v;
-  },
-});
-
-const localValue = ref<Date | undefined>(defaultValue);
-const modelValue = defineModel<Date | undefined>('modelValue', {
-  default: undefined,
-  get: v => v ?? localValue.value,
-  set: (v) => {
-    localValue.value = v;
-    return v;
-  },
-});
-
-const localPlaceholder = ref<Date>(
-  toDateOnly(defaultPlaceholder ?? modelValue.value ?? new Date()),
-);
-const placeholder = defineModel<Date>('placeholder', {
-  default: undefined,
-  get: v => v ?? localPlaceholder.value,
-  set: (v) => {
-    localPlaceholder.value = toDateOnly(v);
-    return localPlaceholder.value;
-  },
-});
-
-const triggerId = useId(undefined, 'date-picker-trigger');
-const contentId = useId(undefined, 'date-picker-content');
-const triggerElement = ref<HTMLElement>();
-const hasCustomAnchor = ref(false);
-const focusedDate = ref<Date | undefined>();
-
-const localeRef = toRef(() => locale);
-const dirRef = toRef(() => dir);
-const modalRef = toRef(() => modal);
-const nameRef = toRef(() => name);
-const weekStartsOnRef = toRef(() => weekStartsOn);
-const weekdayFormatRef = toRef(() => weekdayFormat as WeekDayFormat);
-const fixedWeeksRef = toRef(() => fixedWeeks);
-const numberOfMonthsRef = toRef(() => numberOfMonths);
-const disabledRef = toRef(() => disabled);
-const readonlyRef = toRef(() => readonly);
-const pagedNavigationRef = toRef(() => pagedNavigation);
-const minValueRef = toRef(() => minValue);
-const maxValueRef = toRef(() => maxValue);
-
-const grid = computed<CalendarMonth[]>(() => createMonths({
-  date: placeholder.value,
-  numberOfMonths,
-  weekStartsOn,
-}));
-
-const weekDays = computed(() => getWeekdayLabels(weekStartsOn, locale, weekdayFormat));
-
-const headingValue = computed(() => {
-  const months = grid.value;
-  if (!months.length) return '';
-  if (months.length === 1) return formatMonthYear(months[0]!.value, locale);
-  const first = formatMonthYear(months[0]!.value, locale);
-  const last = formatMonthYear(months[months.length - 1]!.value, locale);
-  return `${first} - ${last}`;
-});
-
-const fullCalendarLabel = computed(() => `${calendarLabel}, ${headingValue.value}`);
-
-function isDateDisabled(date: Date): boolean {
-  if (disabled) return true;
-  if (propsIsDateDisabled?.(date)) return true;
-  if (minValue && isBefore(date, minValue)) return true;
-  if (maxValue && isAfter(date, maxValue)) return true;
-  return false;
-}
-
-function isDateUnavailableLocal(date: Date): boolean {
-  return isUnavailable(date, propsIsDateUnavailable, minValue, maxValue);
-}
-
-function isDateSelected(date: Date): boolean {
-  return modelValue.value ? isSameDay(modelValue.value, date) : false;
-}
-
-function isOutsideVisibleView(date: Date): boolean {
-  return !grid.value.some(m => isSameMonth(m.value, date));
-}
-
-const isInvalid = computed(() => {
-  if (!modelValue.value) return false;
-  return isDateDisabled(modelValue.value) || isDateUnavailableLocal(modelValue.value);
-});
-
-function setDate(date: Date | undefined) {
-  if (readonly) return;
-  if (date && (isDateDisabled(date) || isDateUnavailableLocal(date))) return;
-  modelValue.value = date ? toDateOnly(date) : undefined;
-  if (date && closeOnSelect) open.value = false;
-}
-
-function setPlaceholder(date: Date) {
-  placeholder.value = clamp(date, minValue, maxValue);
-}
-
-function pageStep(): number {
-  return pagedNavigation ? numberOfMonths : 1;
-}
-function nextPage(fn?: (placeholder: Date) => Date) {
-  const fnToUse = fn ?? propsNextPage;
-  placeholder.value = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(placeholder.value, pageStep());
-}
-function prevPage(fn?: (placeholder: Date) => Date) {
-  const fnToUse = fn ?? propsPrevPage;
-  placeholder.value = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(placeholder.value, -pageStep());
-}
-function nextYear() {
-  placeholder.value = addYears(placeholder.value, 1);
-}
-function prevYear() {
-  placeholder.value = addYears(placeholder.value, -1);
-}
-
-function isNextButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
-  if (disabled) return true;
-  if (!maxValue) return false;
-  const lastMonth = grid.value[grid.value.length - 1]?.value;
-  if (!lastMonth) return false;
-  const fnToUse = fn ?? propsNextPage;
-  const probe = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(lastMonth, 1);
-  return isAfter(probe, maxValue);
-}
-function isPrevButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
-  if (disabled) return true;
-  if (!minValue) return false;
-  const firstMonth = grid.value[0]?.value;
-  if (!firstMonth) return false;
-  const fnToUse = fn ?? propsPrevPage;
-  const probe = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(firstMonth, -1);
-  return isBefore(probe, minValue);
-}
-
-watch(modelValue, (v) => {
-  if (v && !isSameMonth(v, placeholder.value))
-    placeholder.value = toDateOnly(v);
-});
-
-onMounted(() => {
-  if (!initialFocus || !open.value || !parentElement.value) return;
-  const target = parentElement.value.querySelector<HTMLElement>(
-    '[data-primitives-calendar-cell-trigger][data-selected]'
-    + ',[data-primitives-calendar-cell-trigger][data-today]'
-    + ',[data-primitives-calendar-cell-trigger]:not([data-outside-view]):not([data-disabled])',
-  );
-  target?.focus();
-});
-
-useEventListener(parentElement, 'focusout', (e) => {
-  if (!parentElement.value?.contains(e.relatedTarget as Node | null))
-    focusedDate.value = undefined;
-});
-
-const hiddenValue = computed(() => {
-  if (!modelValue.value) return '';
-  if (typeof valueFormat === 'function') return valueFormat(modelValue.value);
-  return modelValue.value.toISOString().slice(0, 10);
-});
-
-provideDatePickerRootContext({
-  open,
-  modal: modalRef,
-  name: nameRef,
-  modelValue,
-  locale: localeRef,
-  triggerId,
-  contentId,
-  triggerElement,
-  hasCustomAnchor,
-  onOpenChange: (v) => { open.value = v; },
-  onOpenToggle: () => { open.value = !open.value; },
-});
-
-provideCalendarRootContext({
-  modelValue,
-  placeholder,
-  locale: localeRef,
-  dir: dirRef,
-  grid,
-  weekDays,
-  headingValue,
-  fullCalendarLabel,
-  weekStartsOn: weekStartsOnRef,
-  weekdayFormat: weekdayFormatRef,
-  fixedWeeks: fixedWeeksRef,
-  numberOfMonths: numberOfMonthsRef,
-  disabled: disabledRef,
-  readonly: readonlyRef,
-  pagedNavigation: pagedNavigationRef,
-  minValue: minValueRef,
-  maxValue: maxValueRef,
-  isDateDisabled,
-  isDateUnavailable: isDateUnavailableLocal,
-  isDateSelected,
-  isOutsideVisibleView,
-  isInvalid,
-  parentElement,
-  focusedDate,
-  setDate,
-  setPlaceholder,
-  nextPage,
-  prevPage,
-  nextYear,
-  prevYear,
-  isNextButtonDisabled,
-  isPrevButtonDisabled,
-});
-</script>
-
-<template>
-  <PopperRoot>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      :data-primitives-date-picker-root="''"
-      :data-state="open ? 'open' : 'closed'"
-      :data-disabled="disabled ? '' : undefined"
-    >
-      <slot :open="open" :model-value="modelValue" />
-      <input
-        v-if="name"
-        type="hidden"
-        :name="name"
-        :value="hiddenValue"
-        :disabled="disabled"
-        aria-hidden="true"
-        tabindex="-1"
-        style="display: none"
-      >
-    </Primitive>
-  </PopperRoot>
-</template>
diff --git a/vue/primitives/src/date-picker/context.ts b/vue/primitives/src/date-picker/context.ts
deleted file mode 100644
index 74b3d87..0000000
--- a/vue/primitives/src/date-picker/context.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { ComputedRef, Ref } from 'vue';
-import { useContextFactory } from '@robonen/vue';
-
-export interface DatePickerRootContext {
-  open: Ref<boolean>;
-  modal: Ref<boolean>;
-  name: Ref<string | undefined>;
-  modelValue: Ref<Date | undefined>;
-  locale: Ref<string>;
-  triggerId: ComputedRef<string>;
-  contentId: ComputedRef<string>;
-  triggerElement: Ref<HTMLElement | undefined>;
-  hasCustomAnchor: Ref<boolean>;
-  onOpenChange: (value: boolean) => void;
-  onOpenToggle: () => void;
-}
-
-const ctx = useContextFactory<DatePickerRootContext>('DatePickerRoot');
-export const provideDatePickerRootContext = ctx.provide;
-export const useDatePickerRootContext = ctx.inject;
diff --git a/vue/primitives/src/dialog/DialogContentNonModal.vue b/vue/primitives/src/dialog/DialogContentNonModal.vue
deleted file mode 100644
index 56cda19..0000000
--- a/vue/primitives/src/dialog/DialogContentNonModal.vue
+++ /dev/null
@@ -1,36 +0,0 @@
-<script setup lang="ts">
-import type { DialogContentImplEmits, DialogContentImplProps } from './DialogContentImpl.vue';
-import { watch } from 'vue';
-import { useForwardExpose } from '@robonen/vue';
-import { useDialogContext } from './context';
-import DialogContentImpl from './DialogContentImpl.vue';
-
-const { as = 'div', role = 'dialog' } = defineProps<DialogContentImplProps>();
-const emit = defineEmits<DialogContentImplEmits>();
-
-const ctx = useDialogContext();
-const { forwardRef, currentElement } = useForwardExpose();
-
-watch(currentElement, (el) => {
-  ctx.contentElement.value = el as HTMLElement | undefined;
-}, { immediate: true, flush: 'post' });
-</script>
-
-<template>
-  <DialogContentImpl
-    :ref="forwardRef"
-    :as="as"
-    :role="role"
-    :trap-focus="false"
-    :disable-outside-pointer-events="false"
-    @open-auto-focus="emit('openAutoFocus', $event)"
-    @close-auto-focus="emit('closeAutoFocus', $event)"
-    @escape-key-down="emit('escapeKeyDown', $event)"
-    @pointer-down-outside="emit('pointerDownOutside', $event)"
-    @focus-outside="emit('focusOutside', $event)"
-    @interact-outside="emit('interactOutside', $event)"
-    @dismiss="emit('dismiss')"
-  >
-    <slot />
-  </DialogContentImpl>
-</template>
diff --git a/vue/primitives/src/disclosure/accordion/AccordionContent.vue b/vue/primitives/src/disclosure/accordion/AccordionContent.vue
new file mode 100644
index 0000000..b28cee6
--- /dev/null
+++ b/vue/primitives/src/disclosure/accordion/AccordionContent.vue
@@ -0,0 +1,161 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The collapsible panel revealed when its item is open. Rendered as an ARIA
+ * `region` labelled by its trigger and mounted/unmounted via `Presence` so
+ * enter/leave transitions can run (use `forceMount` to keep it mounted for
+ * custom animation).
+ *
+ * While transitioning it measures its natural size and exposes
+ * `--accordion-content-height` / `--accordion-content-width` CSS variables so
+ * consumers can drive height/width transitions purely from CSS. When the item
+ * (or root) sets `unmountOnHide: false`, closed content stays in the DOM with
+ * `hidden="until-found"` so the browser's find-in-page can reveal it.
+ */
+export interface AccordionContentProps extends PrimitiveProps {
+  /** Keep content mounted even when closed. */
+  forceMount?: boolean;
+}
+
+/** Emit contract for `AccordionContent`. */
+export interface AccordionContentEmits {
+  /**
+   * Fired when the browser's find-in-page reveals the content via the
+   * `beforematch` event (only possible when the item is kept mounted via
+   * `unmountOnHide: false`, which renders closed content with
+   * `hidden="until-found"`).
+   */
+  contentFound: [];
+}
+</script>
+
+<script setup lang="ts">
+import type { ComponentPublicInstance } from 'vue';
+import { computed, nextTick, onMounted, ref, shallowRef, useTemplateRef, watch } from 'vue';
+import { useAccordionContext, useAccordionItemContext } from './context';
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+
+defineOptions({
+  inheritAttrs: false,
+});
+
+const { as = 'div', forceMount = false } = defineProps<AccordionContentProps>();
+const emit = defineEmits<AccordionContentEmits>();
+
+defineSlots<{
+  default?: (props: {
+    /** Current open state of the item. */
+    open: boolean;
+  }) => unknown;
+}>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const ctx = useAccordionContext();
+const item = useAccordionItemContext();
+
+const presenceRef = useTemplateRef<ComponentPublicInstance & { present: boolean }>('presence');
+
+// Measured natural dimensions of the content, exposed as CSS variables so
+// consumers can transition height/width without JS. `shallowRef` because the
+// numbers are replaced wholesale.
+const width = shallowRef(0);
+const height = shallowRef(0);
+
+const isOpen = computed(() => item.open.value);
+
+// Suppress the enter/leave animation on the very first frame so a panel that
+// is open via `defaultValue` does not animate in on mount.
+const isMountAnimationPrevented = ref(isOpen.value);
+const originalStyle = shallowRef<{ transitionDuration: string; animationName: string }>();
+
+watch(
+  () => [isOpen.value, presenceRef.value?.present] as const,
+  async () => {
+    await nextTick();
+    const node = currentElement.value;
+    if (!node)
+      return;
+
+    // Cache the author-defined styles once so we can restore them later.
+    originalStyle.value ||= {
+      transitionDuration: node.style.transitionDuration,
+      animationName: node.style.animationName,
+    };
+
+    // Freeze animations/transitions so the element settles at its full size.
+    node.style.transitionDuration = '0s';
+    node.style.animationName = 'none';
+
+    const rect = node.getBoundingClientRect();
+    height.value = rect.height;
+    width.value = rect.width;
+
+    // Restore the original animation setup unless this is the initial mount.
+    if (!isMountAnimationPrevented.value) {
+      node.style.transitionDuration = originalStyle.value.transitionDuration;
+      node.style.animationName = originalStyle.value.animationName;
+    }
+  },
+  { immediate: true },
+);
+
+const sizeStyle = computed(() => ({
+  '--accordion-content-height': `${height.value}px`,
+  '--accordion-content-width': `${width.value}px`,
+}));
+
+onMounted(() => {
+  requestAnimationFrame(() => {
+    isMountAnimationPrevented.value = false;
+  });
+});
+
+// `hidden="until-found"` lets the browser's find-in-page reveal collapsed
+// content; when it does it fires `beforematch`, which we use to open the item
+// and notify consumers.
+useEventListener(currentElement, 'beforematch', () => {
+  requestAnimationFrame(() => {
+    ctx.open(item.value);
+    emit('contentFound');
+  });
+});
+
+// `hidden` reflects the logical open state (not Presence's mounted state) so
+// content kept mounted via `forceMount` / `unmountOnHide` is still hidden from
+// layout and assistive tech while closed. `until-found` keeps it discoverable
+// by the browser's find-in-page when the consumer opted out of unmounting.
+const hidden = computed<'' | 'until-found' | undefined>(() => {
+  if (isOpen.value)
+    return undefined;
+
+  return item.unmountOnHide.value ? '' : 'until-found';
+});
+</script>
+
+<template>
+  <Presence
+    ref="presence"
+    v-slot="{ present }"
+    :present="forceMount || item.open.value"
+    :force-mount="forceMount || !item.unmountOnHide.value"
+  >
+    <Primitive
+      v-bind="$attrs"
+      :ref="forwardRef"
+      :as="as"
+      role="region"
+      :id="item.contentId.value"
+      :aria-labelledby="item.triggerId.value"
+      :data-state="item.open.value ? 'open' : 'closed'"
+      :data-disabled="item.disabled.value ? '' : undefined"
+      :data-orientation="ctx.orientation.value"
+      :hidden="hidden"
+      :style="sizeStyle"
+    >
+      <slot v-if="item.unmountOnHide.value ? present : true" :open="item.open.value" />
+    </Primitive>
+  </Presence>
+</template>
diff --git a/vue/primitives/src/disclosure/accordion/AccordionHeader.vue b/vue/primitives/src/disclosure/accordion/AccordionHeader.vue
new file mode 100644
index 0000000..bc3147d
--- /dev/null
+++ b/vue/primitives/src/disclosure/accordion/AccordionHeader.vue
@@ -0,0 +1,36 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The heading element that wraps an `AccordionTrigger`. The WAI-ARIA accordion
+ * pattern requires each trigger to live inside a heading (`h1`–`h6`) so screen
+ * readers can navigate sections by heading level. Renders as `<h3>` by default
+ * and forwards `data-state` / `data-disabled` / `data-orientation` for styling.
+ */
+export interface AccordionHeaderProps extends PrimitiveProps {
+}
+</script>
+
+<script setup lang="ts">
+import { useAccordionContext, useAccordionItemContext } from './context';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'h3' } = defineProps<AccordionHeaderProps>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useAccordionContext();
+const item = useAccordionItemContext();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :data-state="item.open.value ? 'open' : 'closed'"
+    :data-disabled="item.disabled.value ? '' : undefined"
+    :data-orientation="ctx.orientation.value"
+  >
+    <slot :open="item.open.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/accordion/AccordionItem.vue b/vue/primitives/src/disclosure/accordion/AccordionItem.vue
similarity index 56%
rename from vue/primitives/src/accordion/AccordionItem.vue
rename to vue/primitives/src/disclosure/accordion/AccordionItem.vue
index c73a0aa..74b971f 100644
--- a/vue/primitives/src/accordion/AccordionItem.vue
+++ b/vue/primitives/src/disclosure/accordion/AccordionItem.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A single collapsible section of the accordion, grouping one trigger with
@@ -12,23 +12,36 @@ export interface AccordionItemProps extends PrimitiveProps {
   value: string;
   /** Disable this item. */
   disabled?: boolean;
+  /**
+   * Override the root's `unmountOnHide` for this item only. When omitted the
+   * root value is inherited. Set `false` to keep this item's closed content
+   * mounted (find-in-page discoverable) regardless of the root setting.
+   */
+  unmountOnHide?: boolean;
 }
 </script>
 
 <script setup lang="ts">
 import { provideAccordionItemContext, useAccordionContext } from './context';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
-const { value, disabled = false, as = 'div' } = defineProps<AccordionItemProps>();
-
-const { forwardRef } = useForwardExpose();
+// `unmountOnHide` defaults to `undefined` (not Vue's boolean-cast `false`) so
+// an omitted prop inherits the root value; only an explicit boolean overrides.
+const { value, disabled = false, unmountOnHide = undefined, as = 'div' } = defineProps<AccordionItemProps>();
 
 const ctx = useAccordionContext();
 const isOpen = computed(() => ctx.isOpen(value));
 const isDisabled = computed(() => ctx.disabled.value || disabled);
+const itemUnmountOnHide = computed(() => unmountOnHide ?? ctx.unmountOnHide.value);
+
+// Expose before `useForwardExpose` so the latter merges these into the
+// forwarded expose, keeping both element ref-forwarding and readable state.
+defineExpose({ open: isOpen, disabled: isDisabled });
+
+const { forwardRef } = useForwardExpose();
 
 const triggerId = useId(undefined, 'accordion-trigger');
 const contentId = useId(undefined, 'accordion-content');
@@ -39,6 +52,7 @@ provideAccordionItemContext({
   disabled: isDisabled,
   triggerId,
   contentId,
+  unmountOnHide: itemUnmountOnHide,
 });
 </script>
 
diff --git a/vue/primitives/src/accordion/AccordionRoot.vue b/vue/primitives/src/disclosure/accordion/AccordionRoot.vue
similarity index 53%
rename from vue/primitives/src/accordion/AccordionRoot.vue
rename to vue/primitives/src/disclosure/accordion/AccordionRoot.vue
index 78cc4af..1b81665 100644
--- a/vue/primitives/src/accordion/AccordionRoot.vue
+++ b/vue/primitives/src/disclosure/accordion/AccordionRoot.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { RovingDirection } from '../utils/roving-focus';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { RovingDirection } from '../../internal/utils/roving-focus';
 
 /**
  * A vertically (or horizontally) stacked set of headers that each reveal an
@@ -11,12 +11,18 @@ import type { RovingDirection } from '../utils/roving-focus';
  * The root owns open state (single or multiple panels), keyboard roving
  * focus across triggers, and provides context to every `AccordionItem`.
  */
+export type AccordionType = 'single' | 'multiple';
+
 export interface AccordionRootProps extends PrimitiveProps {
   /** Initial value(s) for uncontrolled mode. */
   defaultValue?: string | string[];
 
-  /** 'single' allows one panel; 'multiple' allows many. @default 'single' */
-  type?: 'single' | 'multiple';
+  /**
+   * 'single' allows one panel; 'multiple' allows many. When omitted, the mode
+   * is inferred from the shape of `modelValue`/`defaultValue` (array →
+   * 'multiple', otherwise 'single'). @default 'single'
+   */
+  type?: AccordionType;
 
   /** Allow closing all panels in single mode. @default false */
   collapsible?: boolean;
@@ -32,33 +38,97 @@ export interface AccordionRootProps extends PrimitiveProps {
 
   /** Wrap keyboard navigation. @default true */
   loop?: boolean;
+
+  /**
+   * Unmount closed content from the DOM instead of keeping it mounted. When
+   * `false`, closed panels stay in the DOM rendered with `hidden="until-found"`
+   * so the browser's find-in-page can locate and reveal them. Individual items
+   * may override this via `AccordionItem`'s own `unmountOnHide`. @default true
+   */
+  unmountOnHide?: boolean;
+}
+
+/**
+ * Emit contract for `AccordionRoot`. The payload narrows with `Type`: a single
+ * accordion emits `string | undefined`, a multiple accordion emits `string[]`.
+ */
+export interface AccordionRootEmits<Type extends AccordionType = AccordionType> {
+  'update:modelValue': [value: (Type extends 'single' ? string : string[]) | undefined];
 }
 </script>
 
 <script setup lang="ts">
-import { computed, ref, toRef } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { Primitive } from '../primitive';
+import { computed, ref, toRef, watchEffect } from 'vue';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { Primitive } from '../../internal/primitive';
 import { provideAccordionContext } from './context';
 import { toArray } from '@robonen/stdlib';
-import { useCollectionProvider } from '../collection';
+import { useCollectionProvider } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
 
 const {
-  type = 'single',
+  type,
   collapsible = false,
   disabled = false,
   orientation = 'vertical',
   dir = 'ltr',
   loop = true,
+  unmountOnHide = true,
   defaultValue,
+  modelValue,
   as = 'div',
 } = defineProps<AccordionRootProps>();
 
+defineEmits<AccordionRootEmits>();
+
+defineSlots<{
+  default?: (props: {
+    /** Current open value(s): a `string | undefined` in single mode, `string[]` in multiple. */
+    modelValue: string | string[] | undefined;
+  }) => unknown;
+}>();
+
 const { forwardRef } = useForwardExpose();
 
 type RovingAction = NonNullable<ReturnType<typeof rovingKeyToAction>>;
 
+// Infer the mode from value shape when `type` is omitted, mirroring how a
+// `defaultValue: []` / array `modelValue` implies a multiple accordion. An
+// explicit `type` always wins.
+const resolvedType = computed<AccordionType>(() => {
+  if (type !== undefined)
+    return type;
+
+  const sample = modelValue ?? defaultValue;
+  if (sample === undefined)
+    return 'single';
+
+  return Array.isArray(sample) ? 'multiple' : 'single';
+});
+
+const isSingle = computed(() => resolvedType.value === 'single');
+
+// Dev-only coherence check: an explicit `type` that disagrees with the value
+// shape is surfaced as a warning (the explicit `type` is still honored).
+if (__DEV__) {
+  watchEffect(() => {
+    const sample = modelValue ?? defaultValue;
+    if (type === undefined || sample === undefined)
+      return;
+
+    const inferred: AccordionType = Array.isArray(sample) ? 'multiple' : 'single';
+    if (type !== inferred) {
+      console.warn(
+        `[Accordion] "type" is "${type}" but the provided value is ${
+          Array.isArray(sample) ? 'an array' : 'not an array'
+        }. Following the explicit "type"; pass a ${
+          type === 'single' ? 'string' : 'string[]'
+        } value to silence this warning.`,
+      );
+    }
+  });
+}
+
 const localValue = ref<string | string[] | undefined>(defaultValue);
 
 const model = defineModel<string | string[] | undefined>({
@@ -74,7 +144,7 @@ const openSet = computed<Set<string>>(() => new Set(toArray(model.value)));
 function nextOpenSet(cur: Set<string>, value: string): Set<string> {
   const present = cur.has(value);
 
-  if (type === 'single') {
+  if (isSingle.value) {
     if (!present) return new Set([value]);
     return collapsible ? new Set() : cur;
   }
@@ -86,7 +156,7 @@ function nextOpenSet(cur: Set<string>, value: string): Set<string> {
 }
 
 function toModelValue(set: Set<string>): string | string[] | undefined {
-  return type === 'single' ? set.values().next().value : [...set];
+  return isSingle.value ? set.values().next().value : [...set];
 }
 
 function commit(next: Set<string>): void {
@@ -104,6 +174,13 @@ function toggle(value: string): void {
   if (next !== cur) commit(next);
 }
 
+function open(value: string): void {
+  if (disabled || openSet.value.has(value)) return;
+  const cur = openSet.value;
+  const next = isSingle.value ? new Set([value]) : new Set(cur).add(value);
+  commit(next);
+}
+
 const { getItems, CollectionSlot } = useCollectionProvider();
 const triggerElements = computed(() => getItems(true).map(i => i.ref));
 
@@ -128,9 +205,12 @@ provideAccordionContext({
   direction: toRef(() => dir),
   loop: toRef(() => loop),
   collapsible: toRef(() => collapsible),
+  isSingle,
+  unmountOnHide: toRef(() => unmountOnHide),
   triggerElements,
   isOpen,
   toggle,
+  open,
   onTriggerKeyDown,
 });
 </script>
@@ -143,7 +223,7 @@ provideAccordionContext({
       :data-orientation="orientation"
       :data-disabled="disabled ? '' : undefined"
     >
-      <slot />
+      <slot :model-value="model" />
     </Primitive>
   </CollectionSlot>
 </template>
diff --git a/vue/primitives/src/accordion/AccordionTrigger.vue b/vue/primitives/src/disclosure/accordion/AccordionTrigger.vue
similarity index 77%
rename from vue/primitives/src/accordion/AccordionTrigger.vue
rename to vue/primitives/src/disclosure/accordion/AccordionTrigger.vue
index fdfadf3..51eb14b 100644
--- a/vue/primitives/src/accordion/AccordionTrigger.vue
+++ b/vue/primitives/src/disclosure/accordion/AccordionTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The interactive header button that toggles its item's content open and
@@ -13,8 +13,8 @@ export interface AccordionTriggerProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { useAccordionContext, useAccordionItemContext } from './context';
-import { Primitive } from '../primitive';
-import { useCollectionInjector } from '../collection';
+import { Primitive } from '../../internal/primitive';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
 
 const { as = 'button' } = defineProps<AccordionTriggerProps>();
@@ -25,7 +25,10 @@ const { forwardRef, currentElement } = useForwardExpose();
 const { CollectionItem } = useCollectionInjector();
 
 function onClick(): void {
-  if (item.disabled.value) return;
+  // In single, non-collapsible mode an already-open item cannot be closed, so
+  // the click is a true no-op — short-circuit before reaching the root.
+  const cannotCollapse = ctx.isSingle.value && item.open.value && !ctx.collapsible.value;
+  if (item.disabled.value || cannotCollapse) return;
   ctx.toggle(item.value);
 }
 
diff --git a/vue/primitives/src/accordion/__test__/Accordion.test.ts b/vue/primitives/src/disclosure/accordion/__test__/Accordion.test.ts
similarity index 100%
rename from vue/primitives/src/accordion/__test__/Accordion.test.ts
rename to vue/primitives/src/disclosure/accordion/__test__/Accordion.test.ts
diff --git a/vue/primitives/src/disclosure/accordion/__test__/AccordionParity.test.ts b/vue/primitives/src/disclosure/accordion/__test__/AccordionParity.test.ts
new file mode 100644
index 0000000..693fa36
--- /dev/null
+++ b/vue/primitives/src/disclosure/accordion/__test__/AccordionParity.test.ts
@@ -0,0 +1,293 @@
+import {
+  AccordionContent,
+  AccordionHeader,
+  AccordionItem,
+  AccordionRoot,
+  AccordionTrigger,
+} from '../index';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { describe, expect, it, vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+
+interface BuildOptions {
+  rootProps?: Record<string, unknown>;
+  itemProps?: (index: number) => Record<string, unknown>;
+  withHeader?: boolean;
+  itemCount?: number;
+  contentProps?: Record<string, unknown>;
+  contentListeners?: Record<string, unknown>;
+}
+
+function build({
+  rootProps = {},
+  itemProps,
+  withHeader = false,
+  itemCount = 3,
+  contentProps = {},
+  contentListeners = {},
+}: BuildOptions = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () => h(AccordionRoot, { ...rootProps }, {
+          default: () => Array.from({ length: itemCount }, (_, i) => {
+            const val = String.fromCodePoint(97 + i);
+            const trigger = h(AccordionTrigger, null, { default: () => `Trigger ${val.toUpperCase()}` });
+            return h(AccordionItem, { value: val, key: val, ...(itemProps ? itemProps(i) : {}) }, {
+              default: () => [
+                withHeader ? h(AccordionHeader, null, { default: () => trigger }) : trigger,
+                h(AccordionContent, { ...contentProps, ...contentListeners }, { default: () => `Content ${val.toUpperCase()}` }),
+              ],
+            });
+          }),
+        });
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+describe('Accordion parity additions', () => {
+  describe('AccordionHeader', () => {
+    it('renders an h3 wrapping the trigger by default with forwarded data-attrs', () => {
+      const w = build({ rootProps: { defaultValue: 'a' }, withHeader: true });
+      const headers = w.findAll('h3');
+      expect(headers).toHaveLength(3);
+      // first item open
+      expect(headers[0]!.attributes('data-state')).toBe('open');
+      expect(headers[1]!.attributes('data-state')).toBe('closed');
+      // trigger lives inside the heading (WAI-ARIA accordion requirement)
+      expect(headers[0]!.find('button').exists()).toBe(true);
+      w.unmount();
+    });
+
+    it('respects the as prop and reflects data-orientation/data-disabled', () => {
+      const w = build({
+        rootProps: { orientation: 'horizontal' },
+        withHeader: true,
+        itemProps: i => (i === 0 ? { disabled: true } : {}),
+      });
+      const headers = w.findAll('h3');
+      expect(headers[0]!.attributes('data-orientation')).toBe('horizontal');
+      expect(headers[0]!.attributes('data-disabled')).toBe('');
+      expect(headers[1]!.attributes('data-disabled')).toBeUndefined();
+      w.unmount();
+    });
+  });
+
+  describe('content dimension CSS variables', () => {
+    it('exposes --accordion-content-height/width on open content', () => {
+      const w = build({ rootProps: { defaultValue: 'a' } });
+      const region = w.find('[role="region"]');
+      const style = region.attributes('style') ?? '';
+      expect(style).toContain('--accordion-content-height');
+      expect(style).toContain('--accordion-content-width');
+      w.unmount();
+    });
+  });
+
+  describe('unmountOnHide', () => {
+    it('default unmounts closed content (no region rendered)', () => {
+      const w = build();
+      expect(w.findAll('[role="region"]')).toHaveLength(0);
+      w.unmount();
+    });
+
+    it('root unmountOnHide=false keeps closed content mounted with hidden="until-found"', async () => {
+      const w = build({ rootProps: { unmountOnHide: false } });
+      await nextTick();
+      const regions = w.findAll('[role="region"]');
+      expect(regions.length).toBe(3);
+      // all closed -> hidden=until-found
+      regions.forEach((r) => {
+        expect(r.attributes('hidden')).toBe('until-found');
+        expect(r.attributes('data-state')).toBe('closed');
+      });
+      w.unmount();
+    });
+
+    it('per-item unmountOnHide overrides the root default', async () => {
+      const w = build({
+        rootProps: { unmountOnHide: true },
+        itemProps: i => (i === 0 ? { unmountOnHide: false } : {}),
+      });
+      await nextTick();
+      // item 0 kept mounted (until-found), items 1/2 unmounted
+      const regions = w.findAll('[role="region"]');
+      expect(regions).toHaveLength(1);
+      expect(regions[0]!.attributes('hidden')).toBe('until-found');
+      expect(regions[0]!.text()).toBe('Content A');
+      w.unmount();
+    });
+
+    it('open content has no hidden attribute', async () => {
+      const w = build({ rootProps: { unmountOnHide: false, defaultValue: 'a' } });
+      await nextTick();
+      const open = w.findAll('[role="region"]').find(r => r.attributes('data-state') === 'open');
+      expect(open).toBeDefined();
+      expect(open!.attributes('hidden')).toBeUndefined();
+      w.unmount();
+    });
+  });
+
+  describe('beforematch find-in-page reveal', () => {
+    it('opens the item and emits contentFound when beforematch fires', async () => {
+      const found = vi.fn();
+      const w = build({
+        rootProps: { unmountOnHide: false, collapsible: true },
+        contentListeners: { onContentFound: found },
+      });
+      await nextTick();
+      const region = w.findAll('[role="region"]')[0]!.element as HTMLElement;
+
+      const rafSpy = vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation((cb: FrameRequestCallback) => {
+        cb(0);
+        return 0;
+      });
+
+      region.dispatchEvent(new Event('beforematch', { bubbles: true }));
+      await nextTick();
+
+      expect(found).toHaveBeenCalledTimes(1);
+      const open = w.findAll('[role="region"]').find(r => r.attributes('data-state') === 'open');
+      expect(open?.text()).toBe('Content A');
+
+      rafSpy.mockRestore();
+      w.unmount();
+    });
+  });
+
+  describe('root slot exposes modelValue', () => {
+    it('passes current value(s) to the default slot', async () => {
+      let slotValue: unknown;
+      const value = ref<string | undefined>('a');
+      const w = mount(
+        defineComponent({
+          setup() {
+            return () => h(AccordionRoot, {
+              modelValue: value.value,
+              'onUpdate:modelValue': (v: string | string[] | undefined) => { value.value = v as string | undefined; },
+              collapsible: true,
+            }, {
+              default: (slotProps: { modelValue: unknown }) => {
+                slotValue = slotProps.modelValue;
+                return [
+                  h(AccordionItem, { value: 'a' }, {
+                    default: () => [
+                      h(AccordionTrigger, null, { default: () => 'A' }),
+                      h(AccordionContent, null, { default: () => 'PA' }),
+                    ],
+                  }),
+                ];
+              },
+            });
+          },
+        }),
+        { attachTo: document.body },
+      );
+      await nextTick();
+      expect(slotValue).toBe('a');
+      w.unmount();
+    });
+  });
+
+  describe('AccordionItem defineExpose', () => {
+    it('exposes open and disabled state via template ref', async () => {
+      const itemRef = ref<{ open: boolean; disabled: boolean } | null>(null);
+      const w = mount(
+        defineComponent({
+          setup() {
+            return () => h(AccordionRoot, { defaultValue: 'a' }, {
+              default: () => [
+                h(AccordionItem, { value: 'a', ref: itemRef as never, disabled: true }, {
+                  default: () => [
+                    h(AccordionTrigger, null, { default: () => 'A' }),
+                    h(AccordionContent, null, { default: () => 'PA' }),
+                  ],
+                }),
+              ],
+            });
+          },
+        }),
+        { attachTo: document.body },
+      );
+      await nextTick();
+      expect(itemRef.value?.open).toBe(true);
+      expect(itemRef.value?.disabled).toBe(true);
+      w.unmount();
+    });
+  });
+
+  describe('type inference', () => {
+    it('infers multiple mode from an array defaultValue without explicit type', async () => {
+      const w = build({ rootProps: { defaultValue: ['a', 'b'] } });
+      await nextTick();
+      expect(w.findAll('[role="region"]')).toHaveLength(2);
+      // multiple: opening a third keeps the first two
+      const triggers = w.findAll('button');
+      await triggers[2 - 2]!.trigger('click'); // toggle 'a' off
+      await nextTick();
+      // after toggling 'a' off, only 'b' remains -> still multiple semantics
+      expect(w.findAll('[role="region"]')).toHaveLength(1);
+      w.unmount();
+    });
+
+    it('infers single mode from a string defaultValue without explicit type', async () => {
+      const w = build({ rootProps: { defaultValue: 'a' } });
+      await nextTick();
+      const triggers = w.findAll('button');
+      await triggers[1]!.trigger('click');
+      await nextTick();
+      // single: opening b closes a
+      const regions = w.findAll('[role="region"]');
+      expect(regions).toHaveLength(1);
+      expect(regions[0]!.text()).toBe('Content B');
+      w.unmount();
+    });
+
+    it('warns in dev when explicit type conflicts with value shape', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const w = build({ rootProps: { type: 'single', defaultValue: ['a', 'b'] } });
+      expect(warn).toHaveBeenCalled();
+      // explicit type wins: single coercion
+      warn.mockRestore();
+      w.unmount();
+    });
+  });
+
+  describe('trigger no-op guard (single, non-collapsible)', () => {
+    it('clicking an already-open item does not emit when not collapsible', async () => {
+      const updates: unknown[] = [];
+      const w = mount(
+        defineComponent({
+          setup() {
+            return () => h(AccordionRoot, {
+              type: 'single',
+              collapsible: false,
+              defaultValue: 'a',
+              'onUpdate:modelValue': (v: unknown) => updates.push(v),
+            }, {
+              default: () => [
+                h(AccordionItem, { value: 'a' }, {
+                  default: () => [
+                    h(AccordionTrigger, null, { default: () => 'A' }),
+                    h(AccordionContent, null, { default: () => 'PA' }),
+                  ],
+                }),
+              ],
+            });
+          },
+        }),
+        { attachTo: document.body },
+      );
+      await nextTick();
+      const trigger = w.find('button');
+      await trigger.trigger('click');
+      await nextTick();
+      expect(updates).toHaveLength(0);
+      // still open
+      expect(w.find('[role="region"]').text()).toBe('PA');
+      w.unmount();
+    });
+  });
+});
diff --git a/vue/primitives/src/accordion/context.ts b/vue/primitives/src/disclosure/accordion/context.ts
similarity index 70%
rename from vue/primitives/src/accordion/context.ts
rename to vue/primitives/src/disclosure/accordion/context.ts
index be8f067..dae78a7 100644
--- a/vue/primitives/src/accordion/context.ts
+++ b/vue/primitives/src/disclosure/accordion/context.ts
@@ -7,10 +7,16 @@ export interface AccordionContext {
   direction: Ref<'ltr' | 'rtl'>;
   loop: Ref<boolean>;
   collapsible: Ref<boolean>;
+  /** Whether the root is single-select (`type === 'single'`). */
+  isSingle: Ref<boolean>;
+  /** Root-level default for keeping closed content mounted; items may override. */
+  unmountOnHide: Ref<boolean>;
   /** DOM-ordered trigger elements, sourced from the internal Collection. */
   triggerElements: ComputedRef<HTMLElement[]>;
   isOpen: (value: string) => boolean;
   toggle: (value: string) => void;
+  /** Force an item open (used by find-in-page reveal); never closes. */
+  open: (value: string) => void;
   onTriggerKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
 }
 
@@ -25,6 +31,8 @@ export interface AccordionItemContext {
   disabled: ComputedRef<boolean>;
   triggerId: ComputedRef<string>;
   contentId: ComputedRef<string>;
+  /** Effective unmount-on-hide for this item (per-item override or root default). */
+  unmountOnHide: ComputedRef<boolean>;
 }
 
 export const {
diff --git a/vue/primitives/src/accordion/demo.vue b/vue/primitives/src/disclosure/accordion/demo.vue
similarity index 81%
rename from vue/primitives/src/accordion/demo.vue
rename to vue/primitives/src/disclosure/accordion/demo.vue
index 228b994..2d064d0 100644
--- a/vue/primitives/src/accordion/demo.vue
+++ b/vue/primitives/src/disclosure/accordion/demo.vue
@@ -33,7 +33,7 @@ const items = [
     v-model="open"
     type="single"
     collapsible
-    class="w-full max-w-md divide-y divide-(--border) rounded-lg border border-(--border) bg-(--bg) text-(--fg)"
+    class="w-full max-w-md divide-y divide-border rounded-lg border border-border bg-bg text-fg"
   >
     <AccordionItem
       v-for="item in items"
@@ -41,11 +41,11 @@ const items = [
       :value="item.value"
     >
       <AccordionTrigger
-        class="group flex w-full items-center justify-between gap-4 px-4 py-3.5 text-left text-sm font-medium outline-none transition-colors hover:bg-(--bg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="group flex w-full items-center justify-between gap-4 px-4 py-3.5 text-left text-sm font-medium outline-none transition-colors hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-ring"
       >
         <span>{{ item.question }}</span>
         <svg
-          class="size-4 shrink-0 text-(--fg-subtle) transition-transform duration-200 group-data-[state=open]:rotate-180"
+          class="size-4 shrink-0 text-fg-subtle transition-transform duration-200 group-data-[state=open]:rotate-180"
           viewBox="0 0 24 24"
           fill="none"
           stroke="currentColor"
@@ -57,7 +57,7 @@ const items = [
         </svg>
       </AccordionTrigger>
       <AccordionContent
-        class="px-4 pb-4 text-sm text-(--fg-muted)"
+        class="px-4 pb-4 text-sm text-fg-muted"
       >
         {{ item.answer }}
       </AccordionContent>
diff --git a/vue/primitives/src/accordion/index.ts b/vue/primitives/src/disclosure/accordion/index.ts
similarity index 64%
rename from vue/primitives/src/accordion/index.ts
rename to vue/primitives/src/disclosure/accordion/index.ts
index fbdb0c6..e6f3ba1 100644
--- a/vue/primitives/src/accordion/index.ts
+++ b/vue/primitives/src/disclosure/accordion/index.ts
@@ -1,12 +1,14 @@
 export { default as AccordionRoot } from './AccordionRoot.vue';
 export { default as AccordionItem } from './AccordionItem.vue';
+export { default as AccordionHeader } from './AccordionHeader.vue';
 export { default as AccordionTrigger } from './AccordionTrigger.vue';
 export { default as AccordionContent } from './AccordionContent.vue';
 
 export { provideAccordionContext, useAccordionContext, provideAccordionItemContext, useAccordionItemContext } from './context';
 
-export type { AccordionRootProps } from './AccordionRoot.vue';
+export type { AccordionRootProps, AccordionRootEmits, AccordionType } from './AccordionRoot.vue';
 export type { AccordionItemProps } from './AccordionItem.vue';
+export type { AccordionHeaderProps } from './AccordionHeader.vue';
 export type { AccordionTriggerProps } from './AccordionTrigger.vue';
-export type { AccordionContentProps } from './AccordionContent.vue';
+export type { AccordionContentProps, AccordionContentEmits } from './AccordionContent.vue';
 export type { AccordionContext, AccordionItemContext } from './context';
diff --git a/vue/primitives/src/disclosure/collapsible/CollapsibleContent.vue b/vue/primitives/src/disclosure/collapsible/CollapsibleContent.vue
new file mode 100644
index 0000000..8ff5ef9
--- /dev/null
+++ b/vue/primitives/src/disclosure/collapsible/CollapsibleContent.vue
@@ -0,0 +1,163 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The panel revealed when the collapsible is open. Mounts and unmounts with
+ * the open state (via `Presence`), is referenced by the trigger's
+ * `aria-controls`, and is hidden from layout and assistive tech while closed.
+ *
+ * While transitioning it measures its natural size and exposes
+ * `--collapsible-content-height` / `--collapsible-content-width` CSS variables
+ * so consumers can drive height/width transitions purely from CSS.
+ */
+export interface CollapsibleContentProps extends PrimitiveProps {
+
+  /** Render the content even when closed (useful for animation control). */
+  forceMount?: boolean;
+}
+
+/** Emit contract for `CollapsibleContent`. */
+export interface CollapsibleContentEmits {
+  /**
+   * Fired when the browser's find-in-page reveals the content via the
+   * `beforematch` event (only possible when the root has `unmountOnHide` set
+   * to `false`, which renders closed content with `hidden="until-found"`).
+   */
+  contentFound: [];
+}
+</script>
+
+<script setup lang="ts">
+import type { ComponentPublicInstance } from 'vue';
+import { computed, nextTick, onMounted, ref, shallowRef, useTemplateRef, watch } from 'vue';
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
+import { useCollapsibleContext } from './context';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+
+defineOptions({
+  inheritAttrs: false,
+});
+
+const { as = 'div', forceMount = false } = defineProps<CollapsibleContentProps>();
+const emit = defineEmits<CollapsibleContentEmits>();
+
+defineSlots<{
+  default?: (props: {
+    /** Current open state of the collapsible. */
+    open: boolean;
+  }) => unknown;
+}>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const ctx = useCollapsibleContext();
+
+const presenceRef = useTemplateRef<ComponentPublicInstance & { present: boolean }>('presence');
+
+// Measured natural dimensions of the content, exposed as CSS variables so
+// consumers can transition height/width without JS. `shallowRef` because the
+// numbers are replaced wholesale.
+const width = shallowRef(0);
+const height = shallowRef(0);
+
+const isOpen = computed(() => ctx.open.value);
+
+// Suppress the enter/leave animation on the very first frame so a
+// `defaultOpen` collapsible does not animate in on mount.
+const isMountAnimationPrevented = ref(isOpen.value);
+const originalStyle = shallowRef<{ transitionDuration: string; animationName: string }>();
+
+watch(
+  () => [isOpen.value, presenceRef.value?.present] as const,
+  async () => {
+    await nextTick();
+    const node = currentElement.value;
+    if (!node)
+      return;
+
+    // Cache the author-defined styles once so we can restore them later.
+    originalStyle.value ||= {
+      transitionDuration: node.style.transitionDuration,
+      animationName: node.style.animationName,
+    };
+
+    // Freeze animations/transitions so the element settles at its full size.
+    node.style.transitionDuration = '0s';
+    node.style.animationName = 'none';
+
+    const rect = node.getBoundingClientRect();
+    height.value = rect.height;
+    width.value = rect.width;
+
+    // Restore the original animation setup unless this is the initial mount.
+    if (!isMountAnimationPrevented.value) {
+      node.style.transitionDuration = originalStyle.value.transitionDuration;
+      node.style.animationName = originalStyle.value.animationName;
+    }
+  },
+  { immediate: true },
+);
+
+const skipAnimation = computed(() => isMountAnimationPrevented.value && isOpen.value);
+
+const dataState = computed(() => {
+  if (skipAnimation.value)
+    return undefined;
+
+  return isOpen.value ? 'open' : 'closed';
+});
+
+const sizeStyle = computed(() => ({
+  '--collapsible-content-height': `${height.value}px`,
+  '--collapsible-content-width': `${width.value}px`,
+}));
+
+onMounted(() => {
+  requestAnimationFrame(() => {
+    isMountAnimationPrevented.value = false;
+  });
+});
+
+// `hidden="until-found"` lets the browser's find-in-page reveal collapsed
+// content; when it does it fires `beforematch`, which we use to open the
+// collapsible and notify consumers.
+useEventListener(currentElement, 'beforematch', () => {
+  requestAnimationFrame(() => {
+    ctx.onOpen();
+    emit('contentFound');
+  });
+});
+
+// `hidden` reflects the logical open state (not Presence's mounted state) so
+// content kept mounted via `forceMount` / `unmountOnHide` is still hidden from
+// layout and assistive tech while closed. `until-found` keeps it discoverable
+// by the browser's find-in-page when the consumer opted out of unmounting.
+const hidden = computed<'' | 'until-found' | undefined>(() => {
+  if (isOpen.value)
+    return undefined;
+
+  return ctx.unmountOnHide.value ? '' : 'until-found';
+});
+</script>
+
+<template>
+  <Presence
+    ref="presence"
+    v-slot="{ present }"
+    :present="forceMount || ctx.open.value"
+    :force-mount="forceMount || !ctx.unmountOnHide.value"
+  >
+    <Primitive
+      v-bind="$attrs"
+      :id="ctx.contentId.value"
+      :ref="forwardRef"
+      :as="as"
+      :data-state="dataState"
+      :data-disabled="ctx.disabled.value ? '' : undefined"
+      :hidden="hidden"
+      :style="sizeStyle"
+    >
+      <slot v-if="ctx.unmountOnHide.value ? present : true" :open="ctx.open.value" />
+    </Primitive>
+  </Presence>
+</template>
diff --git a/vue/primitives/src/collapsible/CollapsibleRoot.vue b/vue/primitives/src/disclosure/collapsible/CollapsibleRoot.vue
similarity index 55%
rename from vue/primitives/src/collapsible/CollapsibleRoot.vue
rename to vue/primitives/src/disclosure/collapsible/CollapsibleRoot.vue
index 9168d06..4bf9669 100644
--- a/vue/primitives/src/collapsible/CollapsibleRoot.vue
+++ b/vue/primitives/src/disclosure/collapsible/CollapsibleRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * An interactive component that expands and collapses a panel of content.
@@ -13,19 +13,38 @@ export interface CollapsibleRootProps extends PrimitiveProps {
 
   defaultOpen?: boolean;
   disabled?: boolean;
+
+  /**
+   * Keep the content mounted while closed instead of unmounting it. When
+   * `false`, the closed content stays in the DOM and is rendered with
+   * `hidden="until-found"` so the browser's find-in-page can locate and
+   * reveal it. Defaults to `true` (closed content is unmounted).
+   */
+  unmountOnHide?: boolean;
+}
+
+/** Emit contract for the open/closed state of `CollapsibleRoot`. */
+export interface CollapsibleRootEmits {
+  /** Fired when the open state of the collapsible changes. */
+  'update:open': [value: boolean];
 }
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { ref, toRef } from 'vue';
 import { provideCollapsibleContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
-const { defaultOpen = false, disabled = false, as = 'div' } = defineProps<CollapsibleRootProps>();
+const { defaultOpen = false, disabled = false, unmountOnHide = true, as = 'div' } = defineProps<CollapsibleRootProps>();
 
-const { forwardRef } = useForwardExpose();
+defineSlots<{
+  default?: (props: {
+    /** Current open state of the collapsible. */
+    open: boolean;
+  }) => unknown;
+}>();
 
 const localOpen = ref<boolean>(defaultOpen);
 
@@ -38,14 +57,23 @@ const open = defineModel<boolean>('open', {
   },
 });
 
+// Expose `open` before `useForwardExpose` so the latter merges it into the
+// forwarded expose (it reads `instance.exposed`), keeping both the element
+// ref-forwarding and the readable open state without calling expose() twice.
+defineExpose({ open });
+
+const { forwardRef } = useForwardExpose();
+
 // Identity passthrough via `toRef` — reactive without `computed`'s effect/cache.
 const disabledRef = toRef(() => disabled);
+const unmountOnHideRef = toRef(() => unmountOnHide);
 const contentId = useId(undefined, 'collapsible-content');
 
 provideCollapsibleContext({
   open,
   disabled: disabledRef,
   contentId,
+  unmountOnHide: unmountOnHideRef,
   onToggle: () => { if (!disabled) open.value = !open.value; },
   onOpen: () => { if (!disabled) open.value = true; },
   onClose: () => { if (!disabled) open.value = false; },
diff --git a/vue/primitives/src/collapsible/CollapsibleTrigger.vue b/vue/primitives/src/disclosure/collapsible/CollapsibleTrigger.vue
similarity index 89%
rename from vue/primitives/src/collapsible/CollapsibleTrigger.vue
rename to vue/primitives/src/disclosure/collapsible/CollapsibleTrigger.vue
index 3ff4d9a..b56322e 100644
--- a/vue/primitives/src/collapsible/CollapsibleTrigger.vue
+++ b/vue/primitives/src/disclosure/collapsible/CollapsibleTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button that toggles the collapsible open and closed. Wires up
@@ -10,7 +10,7 @@ export interface CollapsibleTriggerProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCollapsibleContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
diff --git a/vue/primitives/src/disclosure/collapsible/__test__/Collapsible.test.ts b/vue/primitives/src/disclosure/collapsible/__test__/Collapsible.test.ts
new file mode 100644
index 0000000..3a01ec1
--- /dev/null
+++ b/vue/primitives/src/disclosure/collapsible/__test__/Collapsible.test.ts
@@ -0,0 +1,211 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from '../index';
+
+function mountCollapsible(props: Record<string, unknown> = {}, contentProps: Record<string, unknown> = {}) {
+  return mount(defineComponent({
+    setup: () => () => h(CollapsibleRoot, props, {
+      default: () => [
+        h(CollapsibleTrigger, { class: 'trig' }, { default: () => 'Toggle' }),
+        h(CollapsibleContent, { class: 'c', ...contentProps }, { default: () => 'Body' }),
+      ],
+    }),
+  }), { attachTo: document.body });
+}
+
+function raf() {
+  return new Promise<void>(resolve => requestAnimationFrame(() => resolve()));
+}
+
+describe('Collapsible', () => {
+  it('starts closed by default; trigger toggles state', async () => {
+    const w = mountCollapsible();
+    const trigger = w.find('.trig');
+    expect(trigger.attributes('aria-expanded')).toBe('false');
+    expect(w.find('.c').exists()).toBe(false);
+    await trigger.trigger('click');
+    expect(trigger.attributes('aria-expanded')).toBe('true');
+    expect(w.find('.c').exists()).toBe(true);
+  });
+
+  it('opens via defaultOpen', async () => {
+    const w = mountCollapsible({ defaultOpen: true });
+    await nextTick();
+    expect(w.find('.trig').attributes('aria-expanded')).toBe('true');
+    expect(w.find('.c').exists()).toBe(true);
+    expect(w.find('.c').text()).toBe('Body');
+  });
+
+  it('wires aria-controls to content id', async () => {
+    const w = mountCollapsible({ defaultOpen: true });
+    await nextTick();
+    const id = w.find('.c').attributes('id');
+    expect(id).toMatch(/collapsible-content/);
+    expect(w.find('.trig').attributes('aria-controls')).toBe(id);
+  });
+
+  it('respects disabled', async () => {
+    const w = mountCollapsible({ disabled: true });
+    await w.find('.trig').trigger('click');
+    expect(w.find('.trig').attributes('aria-expanded')).toBe('false');
+    expect(w.find('.trig').attributes('data-disabled')).toBe('');
+  });
+
+  it('forceMount keeps content in DOM when closed', () => {
+    const w = mount(defineComponent({
+      setup: () => () => h(CollapsibleRoot, null, {
+        default: () => [
+          h(CollapsibleTrigger, { class: 'trig' }),
+          h(CollapsibleContent, { class: 'c', forceMount: true }, { default: () => 'Body' }),
+        ],
+      }),
+    }));
+    const content = w.find('.c');
+    expect(content.exists()).toBe(true);
+    expect(content.attributes('hidden')).toBeDefined();
+    expect(content.attributes('data-state')).toBe('closed');
+    w.unmount();
+  });
+});
+
+describe('Collapsible v-model:open (controlled)', () => {
+  it('reflects an external v-model and toggles it on click', async () => {
+    const open = ref(false);
+    const w = mount(defineComponent({
+      setup: () => () => h(CollapsibleRoot, {
+        open: open.value,
+        'onUpdate:open': (v: boolean) => { open.value = v; },
+      }, {
+        default: () => [
+          h(CollapsibleTrigger, { class: 'trig' }),
+          h(CollapsibleContent, { class: 'c' }, { default: () => 'Body' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+
+    expect(w.find('.trig').attributes('aria-expanded')).toBe('false');
+    await w.find('.trig').trigger('click');
+    expect(open.value).toBe(true);
+    await nextTick();
+    expect(w.find('.trig').attributes('aria-expanded')).toBe('true');
+    w.unmount();
+  });
+});
+
+describe('Collapsible Root exposes open via template ref', () => {
+  it('parent can read live open state through a component ref', async () => {
+    const rootRef = ref<any>();
+    const w = mount(defineComponent({
+      setup: () => () => h(CollapsibleRoot, { ref: rootRef, defaultOpen: true }, {
+        default: () => [
+          h(CollapsibleTrigger, { class: 'trig' }),
+          h(CollapsibleContent, { class: 'c' }, { default: () => 'Body' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+
+    await nextTick();
+    expect(rootRef.value.open).toBe(true);
+    await w.find('.trig').trigger('click');
+    expect(rootRef.value.open).toBe(false);
+    w.unmount();
+  });
+});
+
+describe('Collapsible content size CSS variables', () => {
+  it('exposes --collapsible-content-height/width inline style', async () => {
+    const w = mountCollapsible({ defaultOpen: true });
+    await nextTick();
+    await raf();
+    const style = w.find('.c').attributes('style') ?? '';
+    expect(style).toContain('--collapsible-content-height');
+    expect(style).toContain('--collapsible-content-width');
+    w.unmount();
+  });
+});
+
+describe('Collapsible unmountOnHide=false', () => {
+  it('keeps content mounted while closed and uses hidden="until-found"', async () => {
+    const w = mountCollapsible({ unmountOnHide: false });
+    await nextTick();
+    const content = w.find('.c');
+    expect(content.exists()).toBe(true);
+    expect(content.attributes('hidden')).toBe('until-found');
+    expect(content.attributes('data-state')).toBe('closed');
+    w.unmount();
+  });
+
+  it('clears hidden when opened and renders slot content while closed', async () => {
+    const w = mountCollapsible({ unmountOnHide: false });
+    await nextTick();
+    const content = w.find('.c');
+    expect(content.text()).toBe('Body');
+    await w.find('.trig').trigger('click');
+    await nextTick();
+    expect(content.attributes('hidden')).toBeUndefined();
+    expect(content.attributes('data-state')).toBe('open');
+    w.unmount();
+  });
+
+  it('default unmountOnHide uses plain hidden when forceMount keeps it mounted', async () => {
+    const w = mountCollapsible({}, { forceMount: true });
+    await nextTick();
+    const content = w.find('.c');
+    expect(content.attributes('hidden')).toBe('');
+    w.unmount();
+  });
+});
+
+describe('Collapsible initial-mount animation suppression', () => {
+  it('omits data-state on first frame for a defaultOpen collapsible, then restores it', async () => {
+    const w = mountCollapsible({ defaultOpen: true });
+    await nextTick();
+    // On the very first frame the enter animation is suppressed, so data-state
+    // is intentionally absent to avoid animating in on load.
+    expect(w.find('.c').attributes('data-state')).toBeUndefined();
+    await raf();
+    await nextTick();
+    expect(w.find('.c').attributes('data-state')).toBe('open');
+    w.unmount();
+  });
+
+  it('does not suppress data-state for an initially-closed collapsible', async () => {
+    const w = mountCollapsible({});
+    await w.find('.trig').trigger('click');
+    await nextTick();
+    expect(w.find('.c').attributes('data-state')).toBe('open');
+    w.unmount();
+  });
+});
+
+describe('Collapsible find-in-page (beforematch)', () => {
+  it('opens and emits contentFound on beforematch when kept mounted', async () => {
+    const found = ref(0);
+    const open = ref(false);
+    const w = mount(defineComponent({
+      setup: () => () => h(CollapsibleRoot, {
+        open: open.value,
+        unmountOnHide: false,
+        'onUpdate:open': (v: boolean) => { open.value = v; },
+      }, {
+        default: () => [
+          h(CollapsibleTrigger, { class: 'trig' }),
+          h(CollapsibleContent, {
+            class: 'c',
+            onContentFound: () => { found.value += 1; },
+          }, { default: () => 'Body' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+
+    await nextTick();
+    const content = w.find('.c').element;
+    content.dispatchEvent(new Event('beforematch', { bubbles: true }));
+    await raf();
+    await nextTick();
+    expect(open.value).toBe(true);
+    expect(found.value).toBe(1);
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/collapsible/context.ts b/vue/primitives/src/disclosure/collapsible/context.ts
similarity index 93%
rename from vue/primitives/src/collapsible/context.ts
rename to vue/primitives/src/disclosure/collapsible/context.ts
index db537df..6a143fb 100644
--- a/vue/primitives/src/collapsible/context.ts
+++ b/vue/primitives/src/disclosure/collapsible/context.ts
@@ -5,6 +5,7 @@ export interface CollapsibleContext {
   open: Ref<boolean>;
   disabled: Ref<boolean>;
   contentId: ComputedRef<string>;
+  unmountOnHide: Ref<boolean>;
   onToggle: () => void;
   onOpen: () => void;
   onClose: () => void;
diff --git a/vue/primitives/src/collapsible/demo.vue b/vue/primitives/src/disclosure/collapsible/demo.vue
similarity index 72%
rename from vue/primitives/src/collapsible/demo.vue
rename to vue/primitives/src/disclosure/collapsible/demo.vue
index fca6628..a05f069 100644
--- a/vue/primitives/src/collapsible/demo.vue
+++ b/vue/primitives/src/disclosure/collapsible/demo.vue
@@ -18,15 +18,15 @@ const commits = [
 <template>
   <CollapsibleRoot
     v-model:open="open"
-    class="w-full max-w-sm rounded-xl border border-(--border) bg-(--bg-elevated) p-3 text-(--fg)"
+    class="demo-card w-full max-w-sm p-3 text-fg"
   >
     <div class="flex items-center justify-between gap-3 px-1">
       <span class="text-sm font-medium">
-        <span class="font-mono text-(--fg-muted)">@robonen</span> pushed 3 commits
+        <span class="font-mono text-fg-muted">@robonen</span> pushed 3 commits
       </span>
 
       <CollapsibleTrigger
-        class="inline-flex size-7 items-center justify-center rounded-md border border-(--border) bg-(--bg) text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
+        class="inline-flex size-7 items-center justify-center rounded-md border border-border bg-bg text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
         :aria-label="open ? 'Collapse commits' : 'Expand commits'"
       >
         <svg
@@ -40,7 +40,7 @@ const commits = [
       </CollapsibleTrigger>
     </div>
 
-    <div class="mt-2 rounded-lg border border-(--border) bg-(--bg) px-3 py-2 font-mono text-xs text-(--fg-muted)">
+    <div class="mt-2 rounded-lg border border-border bg-bg px-3 py-2 font-mono text-xs text-fg-muted">
       <span class="text-emerald-600 dark:text-emerald-400">{{ commits[0].id }}</span>
       {{ commits[0].msg }}
     </div>
@@ -49,7 +49,7 @@ const commits = [
       <div
         v-for="commit in commits.slice(1)"
         :key="commit.id"
-        class="rounded-lg border border-(--border) bg-(--bg) px-3 py-2 font-mono text-xs text-(--fg-muted)"
+        class="rounded-lg border border-border bg-bg px-3 py-2 font-mono text-xs text-fg-muted"
       >
         <span class="text-emerald-600 dark:text-emerald-400">{{ commit.id }}</span>
         {{ commit.msg }}
diff --git a/vue/primitives/src/collapsible/index.ts b/vue/primitives/src/disclosure/collapsible/index.ts
similarity index 69%
rename from vue/primitives/src/collapsible/index.ts
rename to vue/primitives/src/disclosure/collapsible/index.ts
index 17578f2..3b6565a 100644
--- a/vue/primitives/src/collapsible/index.ts
+++ b/vue/primitives/src/disclosure/collapsible/index.ts
@@ -1,8 +1,8 @@
 export { default as CollapsibleRoot } from './CollapsibleRoot.vue';
 export { default as CollapsibleTrigger } from './CollapsibleTrigger.vue';
 export { default as CollapsibleContent } from './CollapsibleContent.vue';
-export type { CollapsibleRootProps } from './CollapsibleRoot.vue';
+export type { CollapsibleRootEmits, CollapsibleRootProps } from './CollapsibleRoot.vue';
 export type { CollapsibleTriggerProps } from './CollapsibleTrigger.vue';
-export type { CollapsibleContentProps } from './CollapsibleContent.vue';
+export type { CollapsibleContentEmits, CollapsibleContentProps } from './CollapsibleContent.vue';
 export { provideCollapsibleContext, useCollapsibleContext } from './context';
 export type { CollapsibleContext } from './context';
diff --git a/vue/primitives/src/disclosure/tabs/TabsContent.vue b/vue/primitives/src/disclosure/tabs/TabsContent.vue
new file mode 100644
index 0000000..37eb1ad
--- /dev/null
+++ b/vue/primitives/src/disclosure/tabs/TabsContent.vue
@@ -0,0 +1,91 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { TabsValue } from './context';
+
+/**
+ * The panel shown when its matching `TabsTrigger` is active. Mounted via
+ * `Presence` so enter/leave transitions can run before it leaves the DOM; use
+ * `forceMount` to keep it mounted for custom animation, or rely on the root's
+ * `unmountOnHide` to keep inactive panels mounted-but-hidden. Pair one with each
+ * trigger via a shared `value`.
+ */
+export interface TabsContentProps extends PrimitiveProps {
+  /** Value that links this panel to a trigger. */
+  value: TabsValue;
+  /** Keep content mounted even when inactive. */
+  forceMount?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Presence } from '../../utilities/presence';
+import { useTabsContext } from './context';
+
+defineOptions({ inheritAttrs: false });
+
+const { value, forceMount = false, as = 'div' } = defineProps<TabsContentProps>();
+
+defineSlots<{
+  default?: (props: {
+    /** Whether this panel is the active one. */
+    selected: boolean;
+  }) => unknown;
+}>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useTabsContext();
+
+const isSelected = computed(() => ctx.value.value === value);
+
+const triggerId = computed(() => ctx.getTriggerId(value));
+const contentId = computed(() => ctx.getContentId(value));
+
+// Register this panel so the matching trigger can wire `aria-controls`.
+// Mount/unmount lifecycle (not a tracked effect) avoids the read-then-write
+// cycle on the shared `contentIds` set; a `value` watch re-keys on the rare
+// case where the panel's `value` changes in place.
+onMounted(() => ctx.registerContent(value));
+onBeforeUnmount(() => ctx.unregisterContent(value));
+watch(() => value, (next, prev) => {
+  ctx.unregisterContent(prev);
+  ctx.registerContent(next);
+});
+
+// Suppress the enter animation on the very first frame so a panel that is
+// active on mount (via `defaultValue`) does not animate in.
+const isMountAnimationPrevented = ref(isSelected.value);
+onMounted(() => {
+  requestAnimationFrame(() => {
+    isMountAnimationPrevented.value = false;
+  });
+});
+
+const keepMounted = computed(() => forceMount || !ctx.unmountOnHide.value);
+</script>
+
+<template>
+  <Presence
+    v-slot="{ present }"
+    :present="isSelected"
+    :force-mount="keepMounted"
+  >
+    <Primitive
+      v-bind="$attrs"
+      :ref="forwardRef"
+      :as="as"
+      :id="contentId"
+      role="tabpanel"
+      :aria-labelledby="triggerId"
+      :data-state="isSelected ? 'active' : 'inactive'"
+      :data-orientation="ctx.orientation.value"
+      :tabindex="0"
+      :hidden="!isSelected ? true : undefined"
+      :style="{ animationDuration: isMountAnimationPrevented ? '0s' : undefined }"
+    >
+      <slot v-if="ctx.unmountOnHide.value ? present : true" :selected="isSelected" />
+    </Primitive>
+  </Presence>
+</template>
diff --git a/vue/primitives/src/disclosure/tabs/TabsIndicator.vue b/vue/primitives/src/disclosure/tabs/TabsIndicator.vue
new file mode 100644
index 0000000..03a4232
--- /dev/null
+++ b/vue/primitives/src/disclosure/tabs/TabsIndicator.vue
@@ -0,0 +1,97 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * An optional visual cue (e.g. an underline or pill) that tracks the currently
+ * active trigger. Render it inside `TabsList`; it exposes the active tab's size
+ * and position as CSS variables (`--primitives-tabs-indicator-size` /
+ * `--primitives-tabs-indicator-position`) so consumers can animate a highlight
+ * purely from CSS.
+ */
+export interface TabsIndicatorProps extends PrimitiveProps {
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onScopeDispose, shallowRef, watch } from 'vue';
+import { useForwardExpose, useMounted } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useTabsContext } from './context';
+
+const { as = 'span' } = defineProps<TabsIndicatorProps>();
+
+const ctx = useTabsContext();
+
+const isHorizontal = computed(() => ctx.orientation.value === 'horizontal');
+const isMounted = useMounted();
+
+const rect = shallowRef<{ size: number; position: number }>();
+
+function activeTab(): HTMLElement | null {
+  const list = ctx.tabsListElement.value;
+  if (!list) return null;
+  return list.querySelector<HTMLElement>('[role="tab"][data-state="active"]');
+}
+
+function updateIndicatorStyle(): void {
+  const tab = activeTab();
+  if (!tab) {
+    rect.value = undefined;
+    return;
+  }
+  rect.value = isHorizontal.value
+    ? { size: tab.offsetWidth, position: tab.offsetLeft }
+    : { size: tab.offsetHeight, position: tab.offsetTop };
+}
+
+defineExpose({ updateIndicatorStyle });
+
+// `useForwardExpose` runs AFTER `defineExpose` so the composable merges the
+// prior expose bindings (plus props + `$el`) instead of `defineExpose`'s
+// `expose()` clobbering them and warning "expose() should be called only once".
+const { forwardRef } = useForwardExpose();
+
+let listObserver: ResizeObserver | undefined;
+
+watch(
+  () => [ctx.value.value, ctx.tabsListElement.value, ctx.direction.value, isHorizontal.value],
+  () => {
+    listObserver?.disconnect();
+    const list = ctx.tabsListElement.value;
+    if (!list) return;
+    listObserver = new ResizeObserver(updateIndicatorStyle);
+    listObserver.observe(list);
+    for (const tab of list.querySelectorAll<HTMLElement>('[role="tab"]')) {
+      listObserver.observe(tab);
+    }
+    updateIndicatorStyle();
+  },
+  { immediate: true, flush: 'post' },
+);
+
+onScopeDispose(() => {
+  listObserver?.disconnect();
+});
+
+const indicatorStyle = computed(() => {
+  if (!rect.value) return undefined;
+  return {
+    '--primitives-tabs-indicator-size': `${rect.value.size}px`,
+    '--primitives-tabs-indicator-position': `${rect.value.position}px`,
+  };
+});
+</script>
+
+<template>
+  <Primitive
+    v-if="isMounted && rect"
+    :ref="forwardRef"
+    :as="as"
+    :data-state="ctx.value.value !== undefined ? 'active' : 'inactive'"
+    :data-orientation="ctx.orientation.value"
+    data-primitives-tabs-indicator
+    :style="indicatorStyle"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/tabs/TabsList.vue b/vue/primitives/src/disclosure/tabs/TabsList.vue
similarity index 65%
rename from vue/primitives/src/tabs/TabsList.vue
rename to vue/primitives/src/disclosure/tabs/TabsList.vue
index 9a89d32..e45bfbe 100644
--- a/vue/primitives/src/tabs/TabsList.vue
+++ b/vue/primitives/src/disclosure/tabs/TabsList.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Container that groups the tab triggers and exposes them as an ARIA `tablist`.
@@ -10,13 +10,19 @@ export interface TabsListProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { watchEffect } from 'vue';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useTabsContext } from './context';
 
 const { as = 'div' } = defineProps<TabsListProps>();
-const { forwardRef } = useForwardExpose();
+const { forwardRef, currentElement } = useForwardExpose();
 const ctx = useTabsContext();
+
+// Surface the list element to the root so `TabsIndicator` can measure it.
+watchEffect(() => {
+  ctx.tabsListElement.value = currentElement.value;
+});
 </script>
 
 <template>
diff --git a/vue/primitives/src/disclosure/tabs/TabsRoot.vue b/vue/primitives/src/disclosure/tabs/TabsRoot.vue
new file mode 100644
index 0000000..bff3ef2
--- /dev/null
+++ b/vue/primitives/src/disclosure/tabs/TabsRoot.vue
@@ -0,0 +1,197 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { RovingDirection } from '../../internal/utils/roving-focus';
+import type { TabsValue } from './context';
+
+/**
+ * A set of layered sections of content — known as tab panels — where only one
+ * panel is shown at a time, each surfaced by its own trigger. Use it to split
+ * related content into switchable views without leaving the page: settings
+ * panes, dashboards, or product detail sections.
+ *
+ * The root owns the selected value (controlled via `v-model` or uncontrolled
+ * via `defaultValue`), orientation, keyboard roving focus across triggers, and
+ * provides context to every `TabsList`, `TabsTrigger`, and `TabsContent`.
+ */
+export interface TabsRootProps extends PrimitiveProps {
+  /** Controlled selected value. Bind with `v-model`. */
+  modelValue?: TabsValue;
+  /** Uncontrolled initial value. */
+  defaultValue?: TabsValue;
+  /** Orientation of the tab list. @default 'horizontal' */
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * Writing direction. When omitted, inherits from a `ConfigProvider`,
+   * falling back to `'ltr'`.
+   */
+  dir?: RovingDirection;
+  /** Wrap keyboard navigation. @default true */
+  loop?: boolean;
+  /** Disable all tabs. */
+  disabled?: boolean;
+  /** How tabs are activated. @default 'automatic' */
+  activationMode?: 'automatic' | 'manual';
+  /**
+   * Unmount inactive panels from the DOM instead of keeping them mounted but
+   * hidden. When `false`, panels stay mounted (hidden) so their state/animation
+   * survives switching. Individual panels can opt in via `forceMount`.
+   * @default true
+   */
+  unmountOnHide?: boolean;
+}
+
+export interface TabsRootEmits {
+  /** Fired when the selected value changes. */
+  'update:modelValue': [value: TabsValue | undefined];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, shallowRef, toRef } from 'vue';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useForwardExpose } from '@robonen/vue';
+import { useDirection, useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
+import { provideTabsContext } from './context';
+
+const {
+  orientation = 'horizontal',
+  dir,
+  loop = true,
+  disabled = false,
+  activationMode = 'automatic',
+  unmountOnHide = true,
+  defaultValue,
+  as = 'div',
+} = defineProps<TabsRootProps>();
+
+defineEmits<TabsRootEmits>();
+
+defineSlots<{
+  default?: (props: {
+    /** Current selected value. */
+    value: TabsValue | undefined;
+  }) => unknown;
+}>();
+
+const { forwardRef } = useForwardExpose();
+
+const direction = useDirection(() => dir);
+
+const localValue = ref<TabsValue | undefined>(defaultValue);
+
+const value = defineModel<TabsValue | undefined>({
+  get: v => v ?? localValue.value,
+  set: (v) => {
+    localValue.value = v;
+    return v;
+  },
+});
+
+const baseId = useId(undefined, 'tabs');
+const tabsListElement = shallowRef<HTMLElement>();
+
+function getTriggerId(v: TabsValue): string {
+  return `${baseId.value}-trigger-${v}`;
+}
+
+function getContentId(v: TabsValue): string {
+  return `${baseId.value}-content-${v}`;
+}
+
+// Replace-wholesale `Set` of mounted panel values, kept in a `shallowRef` so
+// reading it in triggers does not pay for deep reactivity on the Set.
+const contentIds = shallowRef<Set<TabsValue>>(new Set());
+
+function registerContent(v: TabsValue): void {
+  contentIds.value = new Set(contentIds.value).add(v);
+}
+
+function unregisterContent(v: TabsValue): void {
+  const next = new Set(contentIds.value);
+  next.delete(v);
+  contentIds.value = next;
+}
+
+function select(v: TabsValue): void {
+  if (disabled) return;
+  value.value = v;
+}
+
+// DOM-order tabs via Collection primitive — survives `v-for` reorders and
+// teleport/portal children, unlike a mount-order array. Items carry their typed
+// `value`, so numeric tab values keep their identity through navigation.
+const { getItems, CollectionSlot } = useCollectionProvider<TabsValue>();
+const tabElements = computed(() => getItems(true).map(i => i.ref));
+
+function onTriggerKeyDown(event: KeyboardEvent, el: HTMLElement): void {
+  // A fully disabled root should not roam focus at all.
+  if (disabled) return;
+  const action = rovingKeyToAction(event, { orientation, dir: direction.value, loop });
+  // `rovingKeyToAction` only handles Arrow/Home/End; map PageUp/PageDown to the
+  // first/last enabled tab locally (the shared util is intentionally minimal).
+  const pageAbsolute = event.key === 'PageUp'
+    ? 'home'
+    : event.key === 'PageDown' ? 'end' : undefined;
+  if (!action && !pageAbsolute) return;
+  event.preventDefault();
+
+  const items = getItems(true).filter(i => !i.ref.hasAttribute('data-disabled'));
+  if (items.length === 0) return;
+
+  const current = items.findIndex(i => i.ref === el);
+  const absolute = action?.absolute ?? pageAbsolute;
+  let target: typeof items[number];
+  if (absolute === 'home') {
+    target = items[0]!;
+  }
+  else if (absolute === 'end') {
+    target = items[items.length - 1]!;
+  }
+  else {
+    const nextIdx = resolveNextIndex(current === -1 ? 0 : current, action!.delta, items.length, loop);
+    target = items[nextIdx]!;
+  }
+
+  target.ref.focus();
+  if (activationMode === 'automatic' && target.value !== undefined) {
+    select(target.value);
+  }
+}
+
+provideTabsContext({
+  value,
+  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
+  orientation: toRef(() => orientation),
+  direction,
+  loop: toRef(() => loop),
+  disabled: toRef(() => disabled),
+  activationMode: toRef(() => activationMode),
+  unmountOnHide: toRef(() => unmountOnHide),
+  baseId,
+  tabsListElement,
+  contentIds,
+  tabElements,
+  getTriggerId,
+  getContentId,
+  registerContent,
+  unregisterContent,
+  select,
+  onTriggerKeyDown,
+});
+</script>
+
+<template>
+  <CollectionSlot>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :dir="direction"
+      :data-orientation="orientation"
+      :data-disabled="disabled ? '' : undefined"
+    >
+      <slot :value="value" />
+    </Primitive>
+  </CollectionSlot>
+</template>
diff --git a/vue/primitives/src/tabs/TabsTrigger.vue b/vue/primitives/src/disclosure/tabs/TabsTrigger.vue
similarity index 55%
rename from vue/primitives/src/tabs/TabsTrigger.vue
rename to vue/primitives/src/disclosure/tabs/TabsTrigger.vue
index 4bd1aa0..78f2a24 100644
--- a/vue/primitives/src/tabs/TabsTrigger.vue
+++ b/vue/primitives/src/disclosure/tabs/TabsTrigger.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { TabsValue } from './context';
 
 /**
  * The clickable control that activates its associated `TabsContent` panel.
@@ -8,16 +9,16 @@ import type { PrimitiveProps } from '../primitive';
  */
 export interface TabsTriggerProps extends PrimitiveProps {
   /** Value that links this trigger to a content panel. */
-  value: string;
+  value: TabsValue;
   /** Disable this trigger. */
   disabled?: boolean;
 }
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
-import { useCollectionInjector } from '../collection';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
 import { useTabsContext } from './context';
 
@@ -30,32 +31,59 @@ const { CollectionItem } = useCollectionInjector();
 const isSelected = computed(() => ctx.value.value === value);
 const isDisabled = computed(() => ctx.disabled.value || disabled);
 
+const triggerId = computed(() => ctx.getTriggerId(value));
+// Only advertise `aria-controls` when a matching panel is actually mounted, so
+// screen readers never point at a non-existent element.
+const contentId = computed(() =>
+  ctx.contentIds.value.has(value) ? ctx.getContentId(value) : undefined,
+);
+
 function onClick(): void {
   if (isDisabled.value) return;
   ctx.select(value);
 }
 
+// Guard pointer activation: ignore non-left buttons and ctrl+left-click (the
+// macOS context-menu chord) so they don't accidentally select the tab. We only
+// suppress focus here; activation itself still happens on `click`.
+function onMouseDown(event: MouseEvent): void {
+  if (isDisabled.value || event.button !== 0 || event.ctrlKey) {
+    event.preventDefault();
+  }
+}
+
 function onKeyDown(event: KeyboardEvent): void {
   if (!currentElement.value) return;
+  // Enter/Space explicitly activate the focused tab — essential for
+  // `activationMode="manual"`, where arrow keys only move focus.
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault();
+    if (!isDisabled.value) ctx.select(value);
+    return;
+  }
   ctx.onTriggerKeyDown(event, currentElement.value);
 }
 </script>
 
 <template>
-  <CollectionItem>
+  <CollectionItem :value="value">
     <Primitive
       :as="as"
       :ref="forwardRef"
+      :id="triggerId"
       role="tab"
       :type="as === 'button' ? 'button' : undefined"
       :aria-selected="isSelected"
+      :aria-controls="contentId"
       :aria-disabled="isDisabled || undefined"
       :data-state="isSelected ? 'active' : 'inactive'"
       :data-disabled="isDisabled ? '' : undefined"
+      :data-orientation="ctx.orientation.value"
       :data-value="value"
       :tabindex="isSelected ? 0 : -1"
       :disabled="isDisabled || undefined"
       @click="onClick"
+      @mousedown="onMouseDown"
       @keydown="onKeyDown"
     >
       <slot :selected="isSelected" />
diff --git a/vue/primitives/src/disclosure/tabs/__test__/Tabs.test.ts b/vue/primitives/src/disclosure/tabs/__test__/Tabs.test.ts
new file mode 100644
index 0000000..248385e
--- /dev/null
+++ b/vue/primitives/src/disclosure/tabs/__test__/Tabs.test.ts
@@ -0,0 +1,448 @@
+import { TabsContent, TabsList, TabsRoot, TabsTrigger } from '../index';
+import { provideConfig } from '../../../utilities/config-provider';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+
+// Minimal declarative config wrapper (the package ships no ConfigProvider
+// component; config is provided via `provideConfig` inside a setup).
+const ConfigProvider = defineComponent({
+  props: { dir: { type: String, default: undefined } },
+  setup(props, { slots }) {
+    provideConfig({ dir: () => props.dir as 'ltr' | 'rtl' | undefined });
+    return () => slots.default?.();
+  },
+});
+
+function createTabs(props: Record<string, unknown> = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () => h(TabsRoot, { ...props }, {
+          default: () => [
+            h(TabsList, null, {
+              default: () => [
+                h(TabsTrigger, { value: 'a' }, { default: () => 'Tab A' }),
+                h(TabsTrigger, { value: 'b' }, { default: () => 'Tab B' }),
+                h(TabsTrigger, { value: 'c', disabled: true }, { default: () => 'Tab C' }),
+              ],
+            }),
+            h(TabsContent, { value: 'a' }, { default: () => 'Panel A' }),
+            h(TabsContent, { value: 'b' }, { default: () => 'Panel B' }),
+            h(TabsContent, { value: 'c' }, { default: () => 'Panel C' }),
+          ],
+        });
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+function press(el: Element, key: string, opts: Record<string, unknown> = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...opts }));
+}
+
+describe('Tabs', () => {
+  it('renders tablist with correct roles', () => {
+    const w = createTabs({ defaultValue: 'a' });
+    expect(w.find('[role="tablist"]').exists()).toBe(true);
+    expect(w.findAll('[role="tab"]')).toHaveLength(3);
+    expect(w.find('[role="tabpanel"]').exists()).toBe(true);
+    w.unmount();
+  });
+
+  it('shows correct panel based on defaultValue', () => {
+    const w = createTabs({ defaultValue: 'b' });
+    const panels = w.findAll('[role="tabpanel"]');
+    expect(panels).toHaveLength(1);
+    expect(panels[0]!.text()).toBe('Panel B');
+    w.unmount();
+  });
+
+  it('selects tab on click', async () => {
+    const w = createTabs({ defaultValue: 'a' });
+    const tabs = w.findAll('[role="tab"]');
+    await tabs[1]!.trigger('click');
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel B');
+    const tabB = tabs[1]!.element;
+    expect(tabB.getAttribute('aria-selected')).toBe('true');
+    expect(tabB.getAttribute('data-state')).toBe('active');
+    w.unmount();
+  });
+
+  it('supports v-model', async () => {
+    const value = ref('a');
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(TabsRoot, {
+            modelValue: value.value,
+            'onUpdate:modelValue': (v: string | undefined) => { value.value = v!; },
+          }, {
+            default: () => [
+              h(TabsList, null, {
+                default: () => [
+                  h(TabsTrigger, { value: 'a' }, { default: () => 'A' }),
+                  h(TabsTrigger, { value: 'b' }, { default: () => 'B' }),
+                ],
+              }),
+              h(TabsContent, { value: 'a' }, { default: () => 'PA' }),
+              h(TabsContent, { value: 'b' }, { default: () => 'PB' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    expect(w.find('[role="tabpanel"]').text()).toBe('PA');
+    const tabs = w.findAll('[role="tab"]');
+    await tabs[1]!.trigger('click');
+    await nextTick();
+    expect(value.value).toBe('b');
+    w.unmount();
+  });
+
+  it('navigates with arrow keys (horizontal)', async () => {
+    const w = createTabs({ defaultValue: 'a' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const tabA = tabs[0]!.element as HTMLElement;
+    tabA.focus();
+
+    press(tabA, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[1]!.element);
+    // automatic mode → panel also switches
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel B');
+
+    // ArrowRight from B should skip disabled C and loop to A
+    press(tabs[1]!.element, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[0]!.element);
+
+    w.unmount();
+  });
+
+  it('navigates with arrow keys (vertical)', async () => {
+    const w = createTabs({ defaultValue: 'a', orientation: 'vertical' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const tabA = tabs[0]!.element as HTMLElement;
+    tabA.focus();
+
+    press(tabA, 'ArrowDown');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[1]!.element);
+    w.unmount();
+  });
+
+  it('Home/End keys', async () => {
+    const w = createTabs({ defaultValue: 'a' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const tabB = tabs[1]!.element as HTMLElement;
+    tabB.focus();
+
+    press(tabB, 'Home');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[0]!.element);
+
+    press(tabs[0]!.element, 'End');
+    await nextTick();
+    // End goes to last enabled — B (C is disabled)
+    expect(document.activeElement).toBe(tabs[1]!.element);
+    w.unmount();
+  });
+
+  it('does not select disabled tabs', async () => {
+    const w = createTabs({ defaultValue: 'a' });
+    const tabs = w.findAll('[role="tab"]');
+    await tabs[2]!.trigger('click');
+    await nextTick();
+    // Should remain on panel A
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
+    w.unmount();
+  });
+
+  it('disabled root blocks all interaction', async () => {
+    const w = createTabs({ defaultValue: 'a', disabled: true });
+    const tabs = w.findAll('[role="tab"]');
+    await tabs[1]!.trigger('click');
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
+    w.unmount();
+  });
+
+  it('manual activation mode: arrow keys move focus but do not select', async () => {
+    const w = createTabs({ defaultValue: 'a', activationMode: 'manual' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const tabA = tabs[0]!.element as HTMLElement;
+    tabA.focus();
+
+    press(tabA, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[1]!.element);
+    // panel stays on A until explicit Enter/Space
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
+    w.unmount();
+  });
+
+  it('sets correct tabindex: selected=0, others=-1', () => {
+    const w = createTabs({ defaultValue: 'b' });
+    const tabs = w.findAll('[role="tab"]');
+    expect(tabs[0]!.attributes('tabindex')).toBe('-1');
+    expect(tabs[1]!.attributes('tabindex')).toBe('0');
+    expect(tabs[2]!.attributes('tabindex')).toBe('-1');
+    w.unmount();
+  });
+
+  it('forceMount keeps panels in DOM', () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(TabsRoot, { defaultValue: 'a' }, {
+            default: () => [
+              h(TabsList, null, {
+                default: () => [
+                  h(TabsTrigger, { value: 'a' }, { default: () => 'A' }),
+                  h(TabsTrigger, { value: 'b' }, { default: () => 'B' }),
+                ],
+              }),
+              h(TabsContent, { value: 'a', forceMount: true }, { default: () => 'PA' }),
+              h(TabsContent, { value: 'b', forceMount: true }, { default: () => 'PB' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    const panels = w.findAll('[role="tabpanel"]');
+    expect(panels).toHaveLength(2);
+    // inactive panel has hidden attribute
+    expect(panels[1]!.attributes('hidden')).toBeDefined();
+    w.unmount();
+  });
+
+  it('orientation reflects in data-orientation and aria-orientation', () => {
+    const w = createTabs({ defaultValue: 'a', orientation: 'vertical' });
+    expect(w.find('[role="tablist"]').attributes('aria-orientation')).toBe('vertical');
+    expect(w.find('[role="tablist"]').attributes('data-orientation')).toBe('vertical');
+    w.unmount();
+  });
+
+  it('wires ARIA relationship: trigger id + aria-controls, panel id + aria-labelledby', async () => {
+    const w = createTabs({ defaultValue: 'a' });
+    await nextTick();
+    const triggerA = w.findAll('[role="tab"]')[0]!;
+    const panelA = w.find('[role="tabpanel"]');
+
+    const triggerId = triggerA.attributes('id');
+    const contentId = panelA.attributes('id');
+    expect(triggerId).toBeTruthy();
+    expect(contentId).toBeTruthy();
+    // Trigger points at its panel; panel points back at its trigger.
+    expect(triggerA.attributes('aria-controls')).toBe(contentId);
+    expect(panelA.attributes('aria-labelledby')).toBe(triggerId);
+    w.unmount();
+  });
+
+  it('omits aria-controls on a trigger that has no matching content', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(TabsRoot, { defaultValue: 'a' }, {
+            default: () => [
+              h(TabsList, null, {
+                default: () => [
+                  h(TabsTrigger, { value: 'a' }, { default: () => 'A' }),
+                  h(TabsTrigger, { value: 'b' }, { default: () => 'B' }),
+                ],
+              }),
+              // only a panel for `a`
+              h(TabsContent, { value: 'a' }, { default: () => 'PA' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    expect(tabs[0]!.attributes('aria-controls')).toBeTruthy();
+    expect(tabs[1]!.attributes('aria-controls')).toBeUndefined();
+    w.unmount();
+  });
+
+  it('Enter activates the focused tab in manual mode', async () => {
+    const w = createTabs({ defaultValue: 'a', activationMode: 'manual' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const tabA = tabs[0]!.element as HTMLElement;
+    tabA.focus();
+
+    press(tabA, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[1]!.element);
+    // still on A until explicit activation
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
+
+    press(tabs[1]!.element, 'Enter');
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel B');
+    w.unmount();
+  });
+
+  it('Space activates the focused tab in manual mode', async () => {
+    const w = createTabs({ defaultValue: 'a', activationMode: 'manual' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    tabs[0]!.element.focus();
+    press(tabs[0]!.element, 'ArrowRight');
+    await nextTick();
+    press(tabs[1]!.element, ' ');
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel B');
+    w.unmount();
+  });
+
+  it('Enter/Space do not activate a disabled trigger', async () => {
+    const w = createTabs({ defaultValue: 'a' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const disabledTab = tabs[2]!.element as HTMLElement; // c is disabled
+    disabledTab.focus();
+    press(disabledTab, 'Enter');
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
+    w.unmount();
+  });
+
+  it('PageUp jumps to first, PageDown jumps to last enabled tab', async () => {
+    const w = createTabs({ defaultValue: 'a' });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const tabA = tabs[0]!.element as HTMLElement;
+    tabA.focus();
+
+    press(tabA, 'PageDown');
+    await nextTick();
+    // last ENABLED tab is B (C is disabled)
+    expect(document.activeElement).toBe(tabs[1]!.element);
+
+    press(tabs[1]!.element, 'PageUp');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[0]!.element);
+    w.unmount();
+  });
+
+  it('disabled root does not roam focus with arrow keys', async () => {
+    const w = createTabs({ defaultValue: 'a', disabled: true });
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    const tabA = tabs[0]!.element as HTMLElement;
+    tabA.focus();
+    press(tabA, 'ArrowRight');
+    await nextTick();
+    // a fully disabled root does not navigate focus to a sibling trigger
+    expect(document.activeElement).not.toBe(tabs[1]!.element);
+    w.unmount();
+  });
+
+  it('supports numeric tab values', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(TabsRoot, { defaultValue: 0 }, {
+            default: () => [
+              h(TabsList, null, {
+                default: () => [
+                  h(TabsTrigger, { value: 0 }, { default: () => 'Zero' }),
+                  h(TabsTrigger, { value: 1 }, { default: () => 'One' }),
+                ],
+              }),
+              h(TabsContent, { value: 0 }, { default: () => 'P0' }),
+              h(TabsContent, { value: 1 }, { default: () => 'P1' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('P0');
+    const tabs = w.findAll('[role="tab"]');
+    await tabs[1]!.trigger('click');
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('P1');
+    // automatic keyboard nav recovers the numeric identity
+    tabs[1]!.element.focus();
+    press(tabs[1]!.element, 'ArrowLeft');
+    await nextTick();
+    expect(w.find('[role="tabpanel"]').text()).toBe('P0');
+    w.unmount();
+  });
+
+  it('inherits dir from ConfigProvider (rtl flips arrow navigation)', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(ConfigProvider, { dir: 'rtl' }, {
+            default: () => h(TabsRoot, { defaultValue: 'a' }, {
+              default: () => [
+                h(TabsList, null, {
+                  default: () => [
+                    h(TabsTrigger, { value: 'a' }, { default: () => 'A' }),
+                    h(TabsTrigger, { value: 'b' }, { default: () => 'B' }),
+                  ],
+                }),
+                h(TabsContent, { value: 'a' }, { default: () => 'PA' }),
+                h(TabsContent, { value: 'b' }, { default: () => 'PB' }),
+              ],
+            }),
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const tabs = w.findAll('[role="tab"]');
+    tabs[0]!.element.focus();
+    // in RTL, ArrowLeft moves to the NEXT item
+    press(tabs[0]!.element, 'ArrowLeft');
+    await nextTick();
+    expect(document.activeElement).toBe(tabs[1]!.element);
+    w.unmount();
+  });
+
+  it('unmountOnHide=false keeps inactive panel mounted but hidden', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(TabsRoot, { defaultValue: 'a', unmountOnHide: false }, {
+            default: () => [
+              h(TabsList, null, {
+                default: () => [
+                  h(TabsTrigger, { value: 'a' }, { default: () => 'A' }),
+                  h(TabsTrigger, { value: 'b' }, { default: () => 'B' }),
+                ],
+              }),
+              h(TabsContent, { value: 'a' }, { default: () => 'PA' }),
+              h(TabsContent, { value: 'b' }, { default: () => 'PB' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const panels = w.findAll('[role="tabpanel"]');
+    expect(panels).toHaveLength(2);
+    const inactive = panels.find(p => p.attributes('data-state') === 'inactive')!;
+    expect(inactive.attributes('hidden')).toBeDefined();
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/disclosure/tabs/context.ts b/vue/primitives/src/disclosure/tabs/context.ts
new file mode 100644
index 0000000..9938182
--- /dev/null
+++ b/vue/primitives/src/disclosure/tabs/context.ts
@@ -0,0 +1,42 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+/**
+ * A tab value. Strings are the common case; numbers are accepted as
+ * first-class so numeric tab ids (e.g. `:value="0"`) work without coercion.
+ */
+export type TabsValue = string | number;
+
+export interface TabsContext {
+  value: Ref<TabsValue | undefined>;
+  orientation: Ref<'horizontal' | 'vertical'>;
+  direction: Ref<'ltr' | 'rtl'>;
+  loop: Ref<boolean>;
+  disabled: Ref<boolean>;
+  activationMode: Ref<'automatic' | 'manual'>;
+  /** When `true`, inactive panels are unmounted instead of kept hidden. */
+  unmountOnHide: Ref<boolean>;
+  /** Stable base id used to derive per-tab trigger/content ids. */
+  baseId: Ref<string>;
+  /** Live `TabsList` element, consumed by `TabsIndicator`. */
+  tabsListElement: ShallowRef<HTMLElement | undefined>;
+  /** Values of currently-mounted `TabsContent` panels (for `aria-controls`). */
+  contentIds: ShallowRef<Set<TabsValue>>;
+  /** DOM-ordered tab elements, sourced from the internal Collection. */
+  tabElements: ComputedRef<HTMLElement[]>;
+  /** Build the trigger element id for a tab value. */
+  getTriggerId: (value: TabsValue) => string;
+  /** Build the content/panel element id for a tab value. */
+  getContentId: (value: TabsValue) => string;
+  /** Register a mounted `TabsContent` so triggers can wire `aria-controls`. */
+  registerContent: (value: TabsValue) => void;
+  /** Unregister a `TabsContent` on unmount. */
+  unregisterContent: (value: TabsValue) => void;
+  select: (value: TabsValue) => void;
+  onTriggerKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
+}
+
+export const {
+  inject: useTabsContext,
+  provide: provideTabsContext,
+} = useContextFactory<TabsContext>('TabsContext');
diff --git a/vue/primitives/src/tabs/demo.vue b/vue/primitives/src/disclosure/tabs/demo.vue
similarity index 62%
rename from vue/primitives/src/tabs/demo.vue
rename to vue/primitives/src/disclosure/tabs/demo.vue
index da4f365..c79c5e7 100644
--- a/vue/primitives/src/tabs/demo.vue
+++ b/vue/primitives/src/disclosure/tabs/demo.vue
@@ -19,16 +19,16 @@ const tabs = [
 <template>
   <TabsRoot
     v-model="tab"
-    class="w-full max-w-md rounded-lg border border-(--border) bg-(--bg) text-(--fg)"
+    class="w-full max-w-md rounded-lg border border-border bg-bg text-fg"
   >
     <TabsList
-      class="flex gap-1 border-b border-(--border) p-1"
+      class="flex gap-1 border-b border-border p-1"
     >
       <TabsTrigger
         v-for="t in tabs"
         :key="t.value"
         :value="t.value"
-        class="flex-1 rounded-md px-3 py-2 text-sm font-medium text-(--fg-muted) outline-none transition-colors hover:text-(--fg) focus-visible:ring-2 focus-visible:ring-(--ring) data-[state=active]:bg-(--bg-subtle) data-[state=active]:text-(--fg)"
+        class="flex-1 rounded-md px-3 py-2 text-sm font-medium text-fg-muted outline-none transition-colors hover:text-fg focus-visible:ring-2 focus-visible:ring-ring data-[state=active]:bg-bg-subtle data-[state=active]:text-fg"
       >
         {{ t.label }}
       </TabsTrigger>
@@ -36,9 +36,9 @@ const tabs = [
 
     <TabsContent
       value="account"
-      class="p-4 text-sm text-(--fg-muted) outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+      class="p-4 text-sm text-fg-muted outline-none focus-visible:ring-2 focus-visible:ring-ring"
     >
-      <p class="font-medium text-(--fg)">
+      <p class="font-medium text-fg">
         Account
       </p>
       <p class="mt-1">
@@ -48,9 +48,9 @@ const tabs = [
 
     <TabsContent
       value="password"
-      class="p-4 text-sm text-(--fg-muted) outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+      class="p-4 text-sm text-fg-muted outline-none focus-visible:ring-2 focus-visible:ring-ring"
     >
-      <p class="font-medium text-(--fg)">
+      <p class="font-medium text-fg">
         Password
       </p>
       <p class="mt-1">
@@ -60,9 +60,9 @@ const tabs = [
 
     <TabsContent
       value="notifications"
-      class="p-4 text-sm text-(--fg-muted) outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+      class="p-4 text-sm text-fg-muted outline-none focus-visible:ring-2 focus-visible:ring-ring"
     >
-      <p class="font-medium text-(--fg)">
+      <p class="font-medium text-fg">
         Notifications
       </p>
       <p class="mt-1">
diff --git a/vue/primitives/src/tabs/index.ts b/vue/primitives/src/disclosure/tabs/index.ts
similarity index 64%
rename from vue/primitives/src/tabs/index.ts
rename to vue/primitives/src/disclosure/tabs/index.ts
index 706045a..09a3c6c 100644
--- a/vue/primitives/src/tabs/index.ts
+++ b/vue/primitives/src/disclosure/tabs/index.ts
@@ -2,11 +2,13 @@ export { default as TabsRoot } from './TabsRoot.vue';
 export { default as TabsList } from './TabsList.vue';
 export { default as TabsTrigger } from './TabsTrigger.vue';
 export { default as TabsContent } from './TabsContent.vue';
+export { default as TabsIndicator } from './TabsIndicator.vue';
 
 export { provideTabsContext, useTabsContext } from './context';
 
-export type { TabsRootProps } from './TabsRoot.vue';
+export type { TabsRootProps, TabsRootEmits } from './TabsRoot.vue';
 export type { TabsListProps } from './TabsList.vue';
 export type { TabsTriggerProps } from './TabsTrigger.vue';
 export type { TabsContentProps } from './TabsContent.vue';
-export type { TabsContext } from './context';
+export type { TabsIndicatorProps } from './TabsIndicator.vue';
+export type { TabsContext, TabsValue } from './context';
diff --git a/vue/primitives/src/dismissable-layer/stack.ts b/vue/primitives/src/dismissable-layer/stack.ts
deleted file mode 100644
index 69293d1..0000000
--- a/vue/primitives/src/dismissable-layer/stack.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-export interface DismissableLayerElement {
-  el: HTMLElement;
-  disableOutsidePointerEvents: boolean;
-}
-
-const layers: DismissableLayerElement[] = [];
-
-/**
- * Module-level stack of active DismissableLayers. The most recently-pushed
- * non-disabled layer is considered the topmost and is the only one that
- * should dispatch dismiss-style events (escape, pointer-outside, focus-outside).
- */
-export const dismissableLayerStack = {
-  push(layer: DismissableLayerElement) {
-    layers.push(layer);
-  },
-
-  remove(layer: DismissableLayerElement) {
-    const i = layers.indexOf(layer);
-    if (i !== -1) layers.splice(i, 1);
-  },
-
-  isTopmost(layer: DismissableLayerElement): boolean {
-    return layers.at(-1) === layer;
-  },
-
-  hasDisablingLayerAbove(layer: DismissableLayerElement): boolean {
-    const i = layers.indexOf(layer);
-    if (i === -1) return false;
-    return layers.slice(i + 1).some(l => l.disableOutsidePointerEvents);
-  },
-
-  any(): boolean {
-    return layers.length > 0;
-  },
-
-  anyDisabling(): boolean {
-    return layers.some(l => l.disableOutsidePointerEvents);
-  },
-};
diff --git a/vue/primitives/src/aspect-ratio/AspectRatio.vue b/vue/primitives/src/display/aspect-ratio/AspectRatio.vue
similarity index 56%
rename from vue/primitives/src/aspect-ratio/AspectRatio.vue
rename to vue/primitives/src/display/aspect-ratio/AspectRatio.vue
index b0cfe3b..d28a522 100644
--- a/vue/primitives/src/aspect-ratio/AspectRatio.vue
+++ b/vue/primitives/src/display/aspect-ratio/AspectRatio.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Displays content within a fixed, responsive width-to-height ratio. The
@@ -18,17 +18,36 @@ export interface AspectRatioProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 
 const { forwardRef } = useForwardExpose();
 
 const { ratio = 1, as = 'div' } = defineProps<AspectRatioProps>();
 
+defineSlots<{
+  /**
+   * Default content placed inside the fixed-ratio box. Receives the resolved
+   * geometry so consumers can react to runtime `ratio` changes without
+   * re-deriving it: `ratio` is the raw width-to-height value and `aspect` is
+   * the height-as-percent-of-width used for the layout reservation.
+   */
+  default?: (props: {
+    /** The resolved width-to-height ratio currently in effect. */
+    ratio: number;
+    /** Height expressed as a percentage of width (`(1 / ratio) * 100`). */
+    aspect: number;
+  }) => unknown;
+}>();
+
+// `aspect` is the height-as-percent-of-width; isolated so the slot prop and the
+// wrapper style share a single cached derivation that tracks `ratio`.
+const aspect = computed(() => (1 / ratio) * 100);
+
 const wrapperStyle = computed(() => ({
   position: 'relative' as const,
   width: '100%',
-  paddingBottom: `${(1 / ratio) * 100}%`,
+  paddingBottom: `${aspect.value}%`,
 }));
 
 // Hoisted constant — the inner style never depends on props, so a single
@@ -42,7 +61,7 @@ const INNER_STYLE = {
 <template>
   <div :ref="forwardRef" :style="wrapperStyle" data-aspect-ratio-wrapper>
     <Primitive :as="as" :style="INNER_STYLE" :data-aspect-ratio="true">
-      <slot />
+      <slot :ratio="ratio" :aspect="aspect" />
     </Primitive>
   </div>
 </template>
diff --git a/vue/primitives/src/display/aspect-ratio/__test__/AspectRatio.test.ts b/vue/primitives/src/display/aspect-ratio/__test__/AspectRatio.test.ts
new file mode 100644
index 0000000..c776a89
--- /dev/null
+++ b/vue/primitives/src/display/aspect-ratio/__test__/AspectRatio.test.ts
@@ -0,0 +1,82 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { nextTick } from 'vue';
+import { AspectRatio } from '../index';
+
+describe('AspectRatio', () => {
+  it('renders with default 1:1 ratio', () => {
+    const wrapper = mount(AspectRatio);
+    const outer = wrapper.element as HTMLElement;
+    expect(outer.style.paddingBottom).toBe('100%');
+  });
+
+  it('computes padding-bottom from ratio', () => {
+    const wrapper = mount(AspectRatio, { props: { ratio: 16 / 9 } });
+    const outer = wrapper.element as HTMLElement;
+    expect(outer.style.paddingBottom).toMatch(/^56\.25%$/);
+  });
+
+  it('updates padding-bottom when ratio prop changes', async () => {
+    const wrapper = mount(AspectRatio, { props: { ratio: 16 / 9 } });
+    const outer = wrapper.element as HTMLElement;
+    expect(outer.style.paddingBottom).toBe('56.25%');
+
+    await wrapper.setProps({ ratio: 1 });
+    expect(outer.style.paddingBottom).toBe('100%');
+
+    await wrapper.setProps({ ratio: 4 / 3 });
+    expect(outer.style.paddingBottom).toBe('75%');
+  });
+
+  it('places inner element absolutely covering the wrapper', () => {
+    const wrapper = mount(AspectRatio, { props: { ratio: 4 / 3 }, slots: { default: '<img />' } });
+    const inner = wrapper.element.firstElementChild as HTMLElement;
+    expect(inner.style.position).toBe('absolute');
+    expect(inner.getAttribute('data-aspect-ratio')).toBe('true');
+  });
+
+  it('renders the inner element with a custom `as` tag', () => {
+    const wrapper = mount(AspectRatio, { props: { as: 'section' } });
+    const inner = wrapper.element.firstElementChild as HTMLElement;
+    expect(inner.tagName).toBe('SECTION');
+    expect(inner.getAttribute('data-aspect-ratio')).toBe('true');
+  });
+
+  it('exposes resolved ratio and aspect to the default slot', () => {
+    const wrapper = mount(AspectRatio, {
+      props: { ratio: 16 / 9 },
+      slots: {
+        default: `<template #default="{ ratio, aspect }"><span class="slot">{{ ratio }}|{{ aspect }}</span></template>`,
+      },
+    });
+
+    const span = wrapper.find('.slot');
+    expect(span.exists()).toBe(true);
+    const [ratio, aspect] = span.text().split('|').map(Number);
+    expect(ratio).toBeCloseTo(16 / 9);
+    expect(aspect).toBeCloseTo(56.25);
+  });
+
+  it('updates the slot props reactively when ratio changes', async () => {
+    const wrapper = mount(AspectRatio, {
+      props: { ratio: 1 },
+      slots: {
+        default: `<template #default="{ aspect }"><span class="slot">{{ aspect }}</span></template>`,
+      },
+    });
+
+    expect(wrapper.find('.slot').text()).toBe('100');
+
+    await wrapper.setProps({ ratio: 4 });
+    await nextTick();
+    expect(wrapper.find('.slot').text()).toBe('25');
+  });
+
+  it('handles extreme ratios without breaking the layout reservation', () => {
+    const tall = mount(AspectRatio, { props: { ratio: 1 / 4 } });
+    expect((tall.element as HTMLElement).style.paddingBottom).toBe('400%');
+
+    const wide = mount(AspectRatio, { props: { ratio: 100 } });
+    expect((wide.element as HTMLElement).style.paddingBottom).toBe('1%');
+  });
+});
diff --git a/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-computes-padding-bottom-from-ratio-1.png b/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-computes-padding-bottom-from-ratio-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-computes-padding-bottom-from-ratio-1.png differ
diff --git a/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-places-inner-element-absolutely-covering-the-wrapper-1.png b/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-places-inner-element-absolutely-covering-the-wrapper-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-places-inner-element-absolutely-covering-the-wrapper-1.png differ
diff --git a/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-renders-with-default-1-1-ratio-1.png b/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-renders-with-default-1-1-ratio-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-renders-with-default-1-1-ratio-1.png differ
diff --git a/vue/primitives/src/display/aspect-ratio/__test__/a11y.test.ts b/vue/primitives/src/display/aspect-ratio/__test__/a11y.test.ts
new file mode 100644
index 0000000..a62909b
--- /dev/null
+++ b/vue/primitives/src/display/aspect-ratio/__test__/a11y.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { mount } from '@vue/test-utils';
+import axe from 'axe-core';
+import { AspectRatio } from '../index';
+
+async function checkA11y(element: Element) {
+  const results = await axe.run(element);
+
+  return results.violations;
+}
+
+function createAspectRatio(props: Record<string, unknown> = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () =>
+          h(
+            AspectRatio,
+            props,
+            {
+              default: () =>
+                h('img', {
+                  class: 'h-full w-full object-cover',
+                  src: 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==',
+                  alt: 'Decorative placeholder',
+                }),
+            },
+          );
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+describe('AspectRatio a11y', () => {
+  it('has no axe violations with the default ratio', async () => {
+    const wrapper = createAspectRatio();
+    await nextTick();
+
+    const violations = await checkA11y(wrapper.element);
+    expect(violations).toEqual([]);
+
+    wrapper.unmount();
+  });
+
+  it('has no axe violations with a custom ratio', async () => {
+    const wrapper = createAspectRatio({ ratio: 16 / 9 });
+    await nextTick();
+
+    const violations = await checkA11y(wrapper.element);
+    expect(violations).toEqual([]);
+
+    wrapper.unmount();
+  });
+
+  it('has no axe violations when rendered as a custom element', async () => {
+    const wrapper = createAspectRatio({ as: 'figure' });
+    await nextTick();
+
+    const violations = await checkA11y(wrapper.element);
+    expect(violations).toEqual([]);
+
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/aspect-ratio/demo.vue b/vue/primitives/src/display/aspect-ratio/demo.vue
similarity index 65%
rename from vue/primitives/src/aspect-ratio/demo.vue
rename to vue/primitives/src/display/aspect-ratio/demo.vue
index 9e62136..26011ee 100644
--- a/vue/primitives/src/aspect-ratio/demo.vue
+++ b/vue/primitives/src/display/aspect-ratio/demo.vue
@@ -12,16 +12,16 @@ const ratio = ref(ratios[0].value);
 </script>
 
 <template>
-  <div class="flex flex-col gap-4 w-full max-w-md text-(--fg)">
-    <div class="flex items-center gap-1 p-1 rounded-lg bg-(--bg-inset) border border-(--border) w-fit">
+  <div class="demo-stack max-w-md text-fg">
+    <div class="flex items-center gap-1 p-1 rounded-lg bg-bg-inset border border-border w-fit">
       <button
         v-for="r in ratios"
         :key="r.label"
         type="button"
         class="px-3 py-1 text-sm rounded-md transition-colors"
         :class="ratio === r.value
-          ? 'bg-(--accent) text-(--accent-fg)'
-          : 'text-(--fg-muted) hover:text-(--fg) hover:bg-(--bg-subtle)'"
+          ? 'bg-accent text-accent-fg'
+          : 'text-fg-muted hover:text-fg hover:bg-bg-subtle'"
         @click="ratio = r.value"
       >
         {{ r.label }}
@@ -30,7 +30,7 @@ const ratio = ref(ratios[0].value);
 
     <AspectRatio
       :ratio="ratio"
-      class="overflow-hidden rounded-xl border border-(--border) bg-(--bg-subtle)"
+      class="overflow-hidden rounded-xl border border-border bg-bg-subtle"
     >
       <img
         src="https://images.unsplash.com/photo-1535025183041-0991a977e25b?w=800&q=80"
@@ -39,9 +39,9 @@ const ratio = ref(ratios[0].value);
       >
     </AspectRatio>
 
-    <p class="text-sm text-(--fg-muted)">
+    <p class="text-sm text-fg-muted">
       The frame keeps a fixed
-      <span class="font-medium text-(--fg)">{{ ratios.find((r) => r.value === ratio)?.label }}</span>
+      <span class="font-medium text-fg">{{ ratios.find((r) => r.value === ratio)?.label }}</span>
       proportion as the container resizes, so the image never shifts surrounding layout.
     </p>
   </div>
diff --git a/vue/primitives/src/aspect-ratio/index.ts b/vue/primitives/src/display/aspect-ratio/index.ts
similarity index 100%
rename from vue/primitives/src/aspect-ratio/index.ts
rename to vue/primitives/src/display/aspect-ratio/index.ts
diff --git a/vue/primitives/src/avatar/AvatarFallback.vue b/vue/primitives/src/display/avatar/AvatarFallback.vue
similarity index 67%
rename from vue/primitives/src/avatar/AvatarFallback.vue
rename to vue/primitives/src/display/avatar/AvatarFallback.vue
index f65ea9f..b43d6c4 100644
--- a/vue/primitives/src/avatar/AvatarFallback.vue
+++ b/vue/primitives/src/display/avatar/AvatarFallback.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Content shown while the image is loading or when it fails to load — typically
@@ -15,10 +15,10 @@ export interface AvatarFallbackProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { computed, ref, watch } from 'vue';
 import { useAvatarContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
+import { useForwardExpose, useTimeoutFn } from '@robonen/vue';
 
 const { as = 'span', delayMs = 0 } = defineProps<AvatarFallbackProps>();
 
@@ -27,32 +27,28 @@ const { forwardRef } = useForwardExpose();
 const ctx = useAvatarContext();
 
 const canShow = ref<boolean>(delayMs === 0);
-let timer: ReturnType<typeof setTimeout> | null = null;
+
+// Delay rendering the fallback to avoid a flash on fast connections. The timer
+// is SSR-safe and torn down automatically on scope dispose — no manual cleanup.
+const { start: startDelay, stop: stopDelay } = useTimeoutFn(() => {
+  canShow.value = true;
+}, () => delayMs, { immediate: false });
 
 watch(() => ctx.imageLoadingStatus.value, (status) => {
   if (status === 'loaded') {
+    stopDelay();
     canShow.value = false;
-    if (timer) {
-      clearTimeout(timer);
-      timer = null;
-    }
     return;
   }
   if (delayMs === 0) {
     canShow.value = true;
     return;
   }
-  if (timer) clearTimeout(timer);
+  stopDelay();
   canShow.value = false;
-  timer = setTimeout(() => {
-    canShow.value = true;
-  }, delayMs);
+  startDelay();
 }, { immediate: true });
 
-onBeforeUnmount(() => {
-  if (timer) clearTimeout(timer);
-});
-
 const shouldRender = computed(() => canShow.value && ctx.imageLoadingStatus.value !== 'loaded');
 </script>
 
diff --git a/vue/primitives/src/display/avatar/AvatarImage.vue b/vue/primitives/src/display/avatar/AvatarImage.vue
new file mode 100644
index 0000000..184d65d
--- /dev/null
+++ b/vue/primitives/src/display/avatar/AvatarImage.vue
@@ -0,0 +1,129 @@
+<script lang="ts">
+import type { ImgHTMLAttributes } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { AvatarImageLoadingStatus } from './context';
+
+/**
+ * The image to display. It loads the `src` out of band and only renders once
+ * the image has successfully loaded, reporting its loading status to the root
+ * so the fallback can take over while loading or on error.
+ *
+ * A browser-cached image is detected synchronously, so an already-loaded
+ * avatar shows instantly without a fallback flash.
+ */
+export interface AvatarImageProps extends PrimitiveProps {
+  /** Image source URL — loaded out of band before the image is shown. */
+  src?: string;
+  /** Alternative text describing the image. */
+  alt?: string;
+  /**
+   * Referrer policy applied to both the out-of-band preload and the rendered
+   * image, so the displayed `<img>` reuses the preload cache entry.
+   */
+  referrerPolicy?: ImgHTMLAttributes['referrerpolicy'];
+  /**
+   * CORS setting applied to both the out-of-band preload and the rendered
+   * image (required for canvas tainting / credentialed CDNs and cache reuse).
+   */
+  crossOrigin?: ImgHTMLAttributes['crossorigin'];
+  /** Called whenever the image's loading status changes (`idle`/`loading`/`loaded`/`error`). */
+  onLoadingStatusChange?: (status: AvatarImageLoadingStatus) => void;
+}
+
+export interface AvatarImageEmits {
+  /** Emitted whenever the image's loading status changes. */
+  loadingStatusChange: [status: AvatarImageLoadingStatus];
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import { useAvatarContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'img', src, alt, referrerPolicy, crossOrigin, onLoadingStatusChange } = defineProps<AvatarImageProps>();
+
+const emit = defineEmits<AvatarImageEmits>();
+
+const { forwardRef } = useForwardExpose();
+
+const ctx = useAvatarContext();
+
+const status = ref<AvatarImageLoadingStatus>('idle');
+
+function setStatus(next: AvatarImageLoadingStatus) {
+  status.value = next;
+  ctx.onImageLoadingStatusChange(next);
+  onLoadingStatusChange?.(next);
+  emit('loadingStatusChange', next);
+}
+
+let currentImage: HTMLImageElement | null = null;
+
+function detachCurrent() {
+  if (currentImage) {
+    currentImage.onload = null;
+    currentImage.onerror = null;
+    currentImage = null;
+  }
+}
+
+// A `load`/`onload` event can still fire for a degenerate (0×0) response, so a
+// real image is only the one that actually decoded to non-zero dimensions.
+function isDecoded(image: HTMLImageElement) {
+  return image.complete && image.naturalWidth > 0;
+}
+
+function load(nextSrc: string | undefined) {
+  detachCurrent();
+  if (!nextSrc) {
+    setStatus('error');
+    return;
+  }
+  if (globalThis.window === undefined) {
+    setStatus('loading');
+    return;
+  }
+  const img = new globalThis.Image();
+  currentImage = img;
+  // Mirror the rendered element's fetch configuration onto the preload so the
+  // displayed `<img>` reuses this cache entry instead of issuing a new request.
+  if (referrerPolicy !== undefined) img.referrerPolicy = referrerPolicy;
+  if (typeof crossOrigin === 'string') img.crossOrigin = crossOrigin;
+  img.onload = () => {
+    if (currentImage === img) setStatus(isDecoded(img) ? 'loaded' : 'error');
+  };
+  img.onerror = () => {
+    if (currentImage === img) setStatus('error');
+  };
+  img.src = nextSrc;
+  // Synchronously surface a browser-cached image to avoid a fallback flash.
+  if (isDecoded(img)) {
+    setStatus('loaded');
+    return;
+  }
+  setStatus('loading');
+}
+
+watch(() => src, load, { immediate: true });
+
+onBeforeUnmount(detachCurrent);
+
+const shouldRender = computed(() => status.value === 'loaded');
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    v-if="shouldRender"
+    role="img"
+    :src="src"
+    :alt="alt"
+    :referrerpolicy="referrerPolicy"
+    :crossorigin="crossOrigin"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/avatar/AvatarRoot.vue b/vue/primitives/src/display/avatar/AvatarRoot.vue
similarity index 91%
rename from vue/primitives/src/avatar/AvatarRoot.vue
rename to vue/primitives/src/display/avatar/AvatarRoot.vue
index 5050cd3..e8499ce 100644
--- a/vue/primitives/src/avatar/AvatarRoot.vue
+++ b/vue/primitives/src/display/avatar/AvatarRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * An image element representing a user, with a graceful text/icon fallback for
@@ -16,7 +16,7 @@ export interface AvatarRootProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import type { AvatarImageLoadingStatus } from './context';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { provideAvatarContext } from './context';
 import { ref } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
diff --git a/vue/primitives/src/display/avatar/__test__/Avatar.test.ts b/vue/primitives/src/display/avatar/__test__/Avatar.test.ts
new file mode 100644
index 0000000..dd9b65d
--- /dev/null
+++ b/vue/primitives/src/display/avatar/__test__/Avatar.test.ts
@@ -0,0 +1,310 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { AvatarFallback, AvatarImage, AvatarRoot } from '../index';
+
+class MockImage {
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  complete = false;
+  naturalWidth = 0;
+  referrerPolicy = '';
+  crossOrigin: string | null = null;
+  private _src = '';
+  set src(value: string) {
+    this._src = value;
+    queueMicrotask(() => {
+      if (value.includes('broken')) {
+        this.onerror?.();
+      }
+      else if (value.includes('zero')) {
+        // Fires load but decoded to 0×0 (degenerate response).
+        this.complete = true;
+        this.naturalWidth = 0;
+        this.onload?.();
+      }
+      else {
+        this.complete = true;
+        this.naturalWidth = 64;
+        this.onload?.();
+      }
+    });
+  }
+
+  get src() { return this._src; }
+}
+
+// A synchronously-cached image: `complete`/`naturalWidth` are already truthy
+// the moment `src` is assigned, so no async event is needed.
+class CachedImage {
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  complete = true;
+  naturalWidth = 64;
+  referrerPolicy = '';
+  crossOrigin: string | null = null;
+  src = '';
+}
+
+describe('Avatar', () => {
+  beforeEach(() => {
+    vi.stubGlobal('Image', MockImage as unknown as typeof Image);
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('renders fallback until image loads', async () => {
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, { src: '/ok.png', alt: 'user' }),
+          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    expect(w.find('.fb').exists()).toBe(true);
+    expect(w.find('img').exists()).toBe(false);
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await nextTick();
+    expect(w.find('img').exists()).toBe(true);
+    expect(w.find('img').attributes('src')).toBe('/ok.png');
+    expect(w.find('.fb').exists()).toBe(false);
+    w.unmount();
+  });
+
+  it('keeps fallback visible on error', async () => {
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, { src: '/broken.png' }),
+          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await nextTick();
+    expect(w.find('img').exists()).toBe(false);
+    expect(w.find('.fb').exists()).toBe(true);
+    w.unmount();
+  });
+
+  it('treats a zero-dimension (degenerate) onload as error', async () => {
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, { src: '/zero.png' }),
+          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await nextTick();
+    expect(w.find('img').exists()).toBe(false);
+    expect(w.find('.fb').exists()).toBe(true);
+    expect(w.element.getAttribute('data-status')).toBe('error');
+    w.unmount();
+  });
+
+  it('shows a browser-cached image synchronously without a fallback flash', async () => {
+    vi.stubGlobal('Image', CachedImage as unknown as typeof Image);
+    const statuses: string[] = [];
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, {
+            src: '/cached.png',
+            onLoadingStatusChange: (s: string) => statuses.push(s),
+          }),
+          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await nextTick();
+    // It jumped straight to loaded — never went through a visible loading/error flash.
+    expect(statuses).not.toContain('loading');
+    expect(statuses).not.toContain('error');
+    expect(statuses.at(-1)).toBe('loaded');
+    expect(w.find('img').exists()).toBe(true);
+    expect(w.find('.fb').exists()).toBe(false);
+    w.unmount();
+  });
+
+  it('delays fallback rendering when delayMs is set', async () => {
+    vi.useFakeTimers();
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarFallback, { class: 'fb', delayMs: 500 }, { default: () => 'AB' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    expect(w.find('.fb').exists()).toBe(false);
+    vi.advanceTimersByTime(500);
+    await nextTick();
+    expect(w.find('.fb').exists()).toBe(true);
+    vi.useRealTimers();
+    w.unmount();
+  });
+
+  it('sets data-status on the root element', async () => {
+    // A manually-driven image: it never auto-resolves, so the transient
+    // 'loading' state is observable deterministically before we fire onload.
+    const created: ManualImage[] = [];
+    class ManualImage {
+      onload: (() => void) | null = null;
+      onerror: (() => void) | null = null;
+      complete = false;
+      naturalWidth = 0;
+      src = '';
+      constructor() {
+        created.push(this);
+      }
+
+      resolve() {
+        this.complete = true;
+        this.naturalWidth = 64;
+        this.onload?.();
+      }
+    }
+    vi.stubGlobal('Image', ManualImage as unknown as typeof Image);
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, { src: '/ok.png' }),
+          h(AvatarFallback, null, { default: () => '?' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await nextTick();
+    expect(w.element.getAttribute('data-status')).toBe('loading');
+    created[0]!.resolve();
+    await nextTick();
+    expect(w.element.getAttribute('data-status')).toBe('loaded');
+    w.unmount();
+  });
+
+  it('shows fallback when src is empty (error status)', async () => {
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, {}),
+          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await nextTick();
+    expect(w.element.getAttribute('data-status')).toBe('error');
+    expect(w.find('img').exists()).toBe(false);
+    expect(w.find('.fb').exists()).toBe(true);
+    w.unmount();
+  });
+
+  it('renders role="img" on the loaded image', async () => {
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, { src: '/ok.png', alt: 'user' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await nextTick();
+    const img = w.find('img');
+    expect(img.exists()).toBe(true);
+    expect(img.attributes('role')).toBe('img');
+    expect(img.attributes('alt')).toBe('user');
+    w.unmount();
+  });
+
+  it('forwards referrerPolicy and crossOrigin to the rendered image', async () => {
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, {
+            src: '/ok.png',
+            referrerPolicy: 'no-referrer',
+            crossOrigin: 'anonymous',
+          }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await nextTick();
+    const img = w.find('img');
+    expect(img.attributes('referrerpolicy')).toBe('no-referrer');
+    expect(img.attributes('crossorigin')).toBe('anonymous');
+    w.unmount();
+  });
+
+  it('applies referrerPolicy and crossOrigin to the out-of-band preload', async () => {
+    const created: MockImage[] = [];
+    class TrackingImage extends MockImage {
+      constructor() {
+        super();
+        created.push(this);
+      }
+    }
+    vi.stubGlobal('Image', TrackingImage as unknown as typeof Image);
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, {
+            src: '/ok.png',
+            referrerPolicy: 'origin',
+            crossOrigin: 'use-credentials',
+          }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await nextTick();
+    expect(created.length).toBe(1);
+    expect(created[0]!.referrerPolicy).toBe('origin');
+    expect(created[0]!.crossOrigin).toBe('use-credentials');
+    w.unmount();
+  });
+
+  it('emits loadingStatusChange as a Vue emit', async () => {
+    const events: string[] = [];
+    const w = mount(defineComponent({
+      setup: () => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, {
+            src: '/ok.png',
+            onLoadingStatusChange: (s: string) => events.push(s),
+          }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await nextTick();
+    expect(events).toContain('loading');
+    expect(events).toContain('loaded');
+    w.unmount();
+  });
+
+  it('guards against a stale in-flight load when src changes', async () => {
+    const statuses: string[] = [];
+    const w = mount(defineComponent({
+      props: { src: { type: String, default: '/broken.png' } },
+      setup: props => () => h(AvatarRoot, null, {
+        default: () => [
+          h(AvatarImage, {
+            src: props.src,
+            onLoadingStatusChange: (s: string) => statuses.push(s),
+          }),
+          h(AvatarFallback, { class: 'fb' }, { default: () => 'AB' }),
+        ],
+      }),
+    }), { attachTo: document.body, props: { src: '/broken.png' } });
+    // Swap to a good src before the broken one's microtask resolves.
+    await w.setProps({ src: '/ok.png' });
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await new Promise(r => queueMicrotask(() => r(null)));
+    await nextTick();
+    // The stale broken load must not clobber the newer good status.
+    expect(w.element.getAttribute('data-status')).toBe('loaded');
+    expect(w.find('img').exists()).toBe(true);
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/avatar/context.ts b/vue/primitives/src/display/avatar/context.ts
similarity index 100%
rename from vue/primitives/src/avatar/context.ts
rename to vue/primitives/src/display/avatar/context.ts
diff --git a/vue/primitives/src/avatar/demo.vue b/vue/primitives/src/display/avatar/demo.vue
similarity index 86%
rename from vue/primitives/src/avatar/demo.vue
rename to vue/primitives/src/display/avatar/demo.vue
index 9f5993a..7bf8760 100644
--- a/vue/primitives/src/avatar/demo.vue
+++ b/vue/primitives/src/display/avatar/demo.vue
@@ -28,7 +28,7 @@ const people = [
       class="flex flex-col items-center gap-2"
     >
       <AvatarRoot
-        class="relative inline-flex h-14 w-14 select-none items-center justify-center overflow-hidden rounded-full border border-(--border) bg-(--bg-subtle) align-middle"
+        class="relative inline-flex h-14 w-14 select-none items-center justify-center overflow-hidden rounded-full border border-border bg-bg-subtle align-middle"
       >
         <AvatarImage
           :src="person.src"
@@ -37,12 +37,12 @@ const people = [
         />
         <AvatarFallback
           :delay-ms="200"
-          class="flex h-full w-full items-center justify-center bg-(--bg-inset) text-sm font-medium text-(--fg-muted)"
+          class="flex h-full w-full items-center justify-center bg-bg-inset text-sm font-medium text-fg-muted"
         >
           {{ person.initials }}
         </AvatarFallback>
       </AvatarRoot>
-      <span class="text-xs text-(--fg-subtle)">{{ person.name }}</span>
+      <span class="text-xs text-fg-subtle">{{ person.name }}</span>
     </div>
   </div>
 </template>
diff --git a/vue/primitives/src/avatar/index.ts b/vue/primitives/src/display/avatar/index.ts
similarity index 85%
rename from vue/primitives/src/avatar/index.ts
rename to vue/primitives/src/display/avatar/index.ts
index 9508ce3..8e69b17 100644
--- a/vue/primitives/src/avatar/index.ts
+++ b/vue/primitives/src/display/avatar/index.ts
@@ -2,7 +2,7 @@ export { default as AvatarRoot } from './AvatarRoot.vue';
 export { default as AvatarImage } from './AvatarImage.vue';
 export { default as AvatarFallback } from './AvatarFallback.vue';
 export type { AvatarRootProps } from './AvatarRoot.vue';
-export type { AvatarImageProps } from './AvatarImage.vue';
+export type { AvatarImageProps, AvatarImageEmits } from './AvatarImage.vue';
 export type { AvatarFallbackProps } from './AvatarFallback.vue';
 export { provideAvatarContext, useAvatarContext } from './context';
 export type { AvatarContext, AvatarImageLoadingStatus } from './context';
diff --git a/vue/primitives/src/calendar/CalendarCell.vue b/vue/primitives/src/display/calendar/CalendarCell.vue
similarity index 68%
rename from vue/primitives/src/calendar/CalendarCell.vue
rename to vue/primitives/src/display/calendar/CalendarCell.vue
index 084859d..6558403 100644
--- a/vue/primitives/src/calendar/CalendarCell.vue
+++ b/vue/primitives/src/display/calendar/CalendarCell.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A single `role="gridcell"` day container (`<td>`). Reflects the date's state
@@ -15,20 +15,24 @@ export interface CalendarCellProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCalendarGridContext, useCalendarRootContext } from './context';
-import { isSameDay, isSameMonth } from './utils';
 
 const { as = 'td', date } = defineProps<CalendarCellProps>();
 
 const ctx = useCalendarRootContext();
 const gridCtx = useCalendarGridContext();
+const adapter = ctx.dateAdapter;
 
 const isSelected = computed(() => ctx.isDateSelected(date));
-const isDisabled = computed(() => ctx.isDateDisabled(date));
+const isOutsideView = computed(() => !adapter.value.isSameMonth(date, gridCtx.month.value));
+const isDisabled = computed(() =>
+  ctx.isDateDisabled(date)
+  || (ctx.disableDaysOutsideCurrentView.value && isOutsideView.value),
+);
 const isUnavailable = computed(() => ctx.isDateUnavailable(date));
-const isOutsideView = computed(() => !isSameMonth(date, gridCtx.month.value));
-const isToday = computed(() => isSameDay(date, new Date()));
+const isOutsideVisibleView = computed(() => ctx.isOutsideVisibleView(date));
+const isToday = computed(() => adapter.value.isSameDay(date, adapter.value.now()));
 </script>
 
 <template>
@@ -42,6 +46,7 @@ const isToday = computed(() => isSameDay(date, new Date()));
     :data-disabled="isDisabled ? '' : undefined"
     :data-unavailable="isUnavailable ? '' : undefined"
     :data-outside-view="isOutsideView ? '' : undefined"
+    :data-outside-visible-view="isOutsideVisibleView ? '' : undefined"
     :data-today="isToday ? '' : undefined"
   >
     <slot />
diff --git a/vue/primitives/src/display/calendar/CalendarCellTrigger.vue b/vue/primitives/src/display/calendar/CalendarCellTrigger.vue
new file mode 100644
index 0000000..5cd383f
--- /dev/null
+++ b/vue/primitives/src/display/calendar/CalendarCellTrigger.vue
@@ -0,0 +1,262 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The focusable, clickable day button inside a `CalendarCell`. Selects its
+ * `day` on click/Enter/Space, drives roving focus and full arrow-key /
+ * Home-End / PageUp-Down keyboard navigation (paging the month when focus
+ * crosses the visible range), and exposes day state through its slot.
+ */
+export interface CalendarCellTriggerProps extends PrimitiveProps {
+  /** The day this trigger represents. */
+  day: Date;
+  /** The month this trigger's cell belongs to. Defaults to grid context. */
+  month?: Date;
+}
+
+export interface CalendarCellTriggerSlotProps {
+  dayValue: string;
+  disabled: boolean;
+  selected: boolean;
+  today: boolean;
+  outsideView: boolean;
+  outsideVisibleView: boolean;
+  unavailable: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
+import { computed, nextTick } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useCalendarGridContext, useCalendarRootContext } from './context';
+
+/**
+ * Cache of `Intl.NumberFormat` instances keyed by locale. `Number#toLocaleString`
+ * with an explicit locale internally constructs a fresh `Intl.NumberFormat` on
+ * every call; this trigger renders ~42 day cells per month, so caching one
+ * immutable formatter per locale at module scope removes that per-cell
+ * allocation while preserving locale-specific numbering systems.
+ */
+const dayNumberFormatCache = new Map<string, Intl.NumberFormat>();
+
+function formatDayNumber(day: number, locale: string): string {
+  let fmt = dayNumberFormatCache.get(locale);
+  if (fmt === undefined) {
+    fmt = new Intl.NumberFormat(locale);
+    dayNumberFormatCache.set(locale, fmt);
+  }
+  return fmt.format(day);
+}
+
+const { as = 'div', day, month } = defineProps<CalendarCellTriggerProps>();
+
+defineSlots<{
+  default?: (props: CalendarCellTriggerSlotProps) => unknown;
+}>();
+
+const ctx = useCalendarRootContext();
+const gridCtx = useCalendarGridContext();
+const { forwardRef } = useForwardExpose();
+const adapter = ctx.dateAdapter;
+
+const monthValue = computed(() => month ?? gridCtx.month.value);
+
+const isOutsideView = computed(() => !adapter.value.isSameMonth(day, monthValue.value));
+const isOutsideVisibleView = computed(() => ctx.isOutsideVisibleView(day));
+const isDisabled = computed(() =>
+  ctx.isDateDisabled(day)
+  || (ctx.disableDaysOutsideCurrentView.value && isOutsideView.value),
+);
+const isUnavailable = computed(() => ctx.isDateUnavailable(day));
+const isSelected = computed(() => ctx.isDateSelected(day));
+const isToday = computed(() => adapter.value.isSameDay(day, adapter.value.now()));
+
+const dayValue = computed(() => formatDayNumber(adapter.value.getParts(day).day, ctx.locale.value));
+const labelText = computed(() => adapter.value.formatFullDate(day, ctx.locale.value));
+
+function selectionInView(): Date | undefined {
+  const v = ctx.modelValue.value;
+  if (Array.isArray(v))
+    return v.find(d => adapter.value.isSameMonth(d, monthValue.value));
+  return v && adapter.value.isSameMonth(v, monthValue.value) ? v : undefined;
+}
+
+const isFocusedDate = computed(() => {
+  if (isOutsideView.value || isDisabled.value) return false;
+  if (ctx.focusedDate.value) return adapter.value.isSameDay(day, ctx.focusedDate.value);
+  // Fallback focusable: selected (in view), else today (if in view), else the
+  // first actionable (non-disabled) date — never an unfocusable cell.
+  const selected = selectionInView();
+  if (selected) return adapter.value.isSameDay(day, selected);
+  const today = adapter.value.now();
+  if (adapter.value.isSameMonth(today, monthValue.value) && !ctx.isDateDisabled(today) && !ctx.isDateUnavailable(today))
+    return adapter.value.isSameDay(day, today);
+  const first = ctx.firstFocusableDate.value;
+  return first ? adapter.value.isSameDay(day, first) : false;
+});
+
+function selectIfAllowed() {
+  if (ctx.readonly.value) return;
+  if (isDisabled.value || isUnavailable.value) return;
+  ctx.setDate(day);
+  ctx.focusedDate.value = day;
+}
+
+function handleClick() {
+  selectIfAllowed();
+}
+
+function cellFor(target: Date): HTMLElement | null {
+  const parent = ctx.parentElement.value;
+  if (!parent) return null;
+  return parent.querySelector<HTMLElement>(
+    `[data-primitives-calendar-cell-trigger][data-value="${adapter.value.toIsoDate(target)}"]:not([data-outside-view])`,
+  );
+}
+
+/**
+ * Move focus to `target`. When `step` is provided (arrow navigation) and the
+ * resolved cell is disabled, keep stepping in the same direction so focus
+ * never parks on a disabled day. Home/End/Page jumps pass no step and land
+ * directly on the target.
+ */
+function shiftFocus(target: Date, step?: number) {
+  if (ctx.minValue.value && adapter.value.isBefore(target, ctx.minValue.value)) return;
+  if (ctx.maxValue.value && adapter.value.isAfter(target, ctx.maxValue.value)) return;
+
+  const inViewCell = cellFor(target);
+  if (inViewCell) {
+    if (step && inViewCell.hasAttribute('data-disabled')) {
+      shiftFocus(adapter.value.addDays(target, step), step);
+      return;
+    }
+    ctx.focusedDate.value = target;
+    // Keep the placeholder in sync with the focused day, but only while it
+    // stays within the placeholder's own month — `grid` derives its visible
+    // window from the placeholder, so a cross-month write would shift a
+    // multi-month view. Cross-view moves are handled by the paging branch.
+    if (adapter.value.isSameMonth(target, ctx.placeholder.value))
+      ctx.setPlaceholder(target);
+    inViewCell.focus();
+    return;
+  }
+
+  // Crossed visible range — page placeholder and retry.
+  ctx.focusedDate.value = target;
+  if (target > ctx.placeholder.value) {
+    if (ctx.isNextButtonDisabled()) return;
+    ctx.nextPage();
+  }
+  else {
+    if (ctx.isPrevButtonDisabled()) return;
+    ctx.prevPage();
+  }
+  nextTick(() => {
+    const el = cellFor(target);
+    if (!el) return;
+    if (step && el.hasAttribute('data-disabled')) {
+      shiftFocus(adapter.value.addDays(target, step), step);
+      return;
+    }
+    el.focus();
+  });
+}
+
+function handleKeyDown(e: KeyboardEvent) {
+  if (isDisabled.value) return;
+  const rtl = ctx.dir.value === 'rtl' ? -1 : 1;
+  switch (e.key) {
+    case 'ArrowRight':
+      e.preventDefault();
+      shiftFocus(adapter.value.addDays(day, rtl), rtl);
+      break;
+    case 'ArrowLeft':
+      e.preventDefault();
+      shiftFocus(adapter.value.addDays(day, -rtl), -rtl);
+      break;
+    case 'ArrowUp':
+      e.preventDefault();
+      shiftFocus(adapter.value.addDays(day, -7), -7);
+      break;
+    case 'ArrowDown':
+      e.preventDefault();
+      shiftFocus(adapter.value.addDays(day, 7), 7);
+      break;
+    case 'Home': {
+      e.preventDefault();
+      const dow = adapter.value.getDay(day);
+      const offset = (dow - ctx.weekStartsOn.value + 7) % 7;
+      shiftFocus(adapter.value.addDays(day, -offset));
+      break;
+    }
+    case 'End': {
+      e.preventDefault();
+      const dow = adapter.value.getDay(day);
+      const offset = (dow - ctx.weekStartsOn.value + 7) % 7;
+      shiftFocus(adapter.value.addDays(day, 6 - offset));
+      break;
+    }
+    case 'PageUp':
+      e.preventDefault();
+      shiftFocus(e.shiftKey ? adapter.value.addYears(day, -1) : adapter.value.addMonths(day, -1));
+      break;
+    case 'PageDown':
+      e.preventDefault();
+      shiftFocus(e.shiftKey ? adapter.value.addYears(day, 1) : adapter.value.addMonths(day, 1));
+      break;
+    case 'Enter':
+    case ' ':
+      e.preventDefault();
+      selectIfAllowed();
+      break;
+  }
+}
+
+function handleFocus() {
+  ctx.focusedDate.value = day;
+}
+
+const dataValue = computed(() => adapter.value.toIsoDate(day));
+const tabindex = computed(() => {
+  if (isFocusedDate.value) return 0;
+  if (isOutsideView.value || isDisabled.value) return undefined;
+  return -1;
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="button"
+    :aria-label="labelText"
+    :aria-disabled="(isDisabled || isUnavailable) ? true : undefined"
+    :aria-selected="isSelected ? true : undefined"
+    :tabindex="tabindex"
+    :data-primitives-calendar-cell-trigger="''"
+    :data-value="dataValue"
+    :data-selected="isSelected ? '' : undefined"
+    :data-disabled="isDisabled ? '' : undefined"
+    :data-unavailable="isUnavailable ? '' : undefined"
+    :data-outside-view="isOutsideView ? '' : undefined"
+    :data-outside-visible-view="isOutsideVisibleView ? '' : undefined"
+    :data-today="isToday ? '' : undefined"
+    :data-focused="isFocusedDate ? '' : undefined"
+    @click="handleClick"
+    @focus="handleFocus"
+    @keydown="handleKeyDown"
+  >
+    <slot
+      :day-value="dayValue"
+      :disabled="isDisabled"
+      :selected="isSelected"
+      :today="isToday"
+      :outside-view="isOutsideView"
+      :outside-visible-view="isOutsideVisibleView"
+      :unavailable="isUnavailable"
+    >
+      {{ dayValue }}
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/calendar/CalendarGrid.vue b/vue/primitives/src/display/calendar/CalendarGrid.vue
similarity index 91%
rename from vue/primitives/src/calendar/CalendarGrid.vue
rename to vue/primitives/src/display/calendar/CalendarGrid.vue
index c3c40c8..5ce72ee 100644
--- a/vue/primitives/src/calendar/CalendarGrid.vue
+++ b/vue/primitives/src/display/calendar/CalendarGrid.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The `role="grid"` table for a single month. Provides grid context (the month
@@ -14,7 +14,7 @@ export interface CalendarGridProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed, toRef } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { provideCalendarGridContext, useCalendarRootContext } from './context';
 
 const { as = 'table', month } = defineProps<CalendarGridProps>();
diff --git a/vue/primitives/src/calendar/CalendarGridBody.vue b/vue/primitives/src/display/calendar/CalendarGridBody.vue
similarity index 77%
rename from vue/primitives/src/calendar/CalendarGridBody.vue
rename to vue/primitives/src/display/calendar/CalendarGridBody.vue
index ef71645..657abf3 100644
--- a/vue/primitives/src/calendar/CalendarGridBody.vue
+++ b/vue/primitives/src/display/calendar/CalendarGridBody.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The grid's `<tbody>` wrapper containing the week rows (`CalendarGridRow`) of
@@ -9,7 +9,7 @@ export interface CalendarGridBodyProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'tbody' } = defineProps<CalendarGridBodyProps>();
 </script>
diff --git a/vue/primitives/src/display/calendar/CalendarGridHead.vue b/vue/primitives/src/display/calendar/CalendarGridHead.vue
new file mode 100644
index 0000000..0b83d36
--- /dev/null
+++ b/vue/primitives/src/display/calendar/CalendarGridHead.vue
@@ -0,0 +1,22 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The grid's `<thead>` wrapper holding the row of weekday `CalendarHeadCell`
+ * labels. Marked `aria-hidden` since each day cell already carries its full
+ * accessible label, avoiding a double weekday-column announcement.
+ */
+export interface CalendarGridHeadProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+
+const { as = 'thead' } = defineProps<CalendarGridHeadProps>();
+</script>
+
+<template>
+  <Primitive :as="as" aria-hidden="true" :data-primitives-calendar-grid-head="''">
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/calendar/CalendarGridRow.vue b/vue/primitives/src/display/calendar/CalendarGridRow.vue
similarity index 78%
rename from vue/primitives/src/calendar/CalendarGridRow.vue
rename to vue/primitives/src/display/calendar/CalendarGridRow.vue
index aebda04..8440391 100644
--- a/vue/primitives/src/calendar/CalendarGridRow.vue
+++ b/vue/primitives/src/display/calendar/CalendarGridRow.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A single table row (`<tr>`) representing one week of the month, or the
@@ -9,7 +9,7 @@ export interface CalendarGridRowProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'tr' } = defineProps<CalendarGridRowProps>();
 </script>
diff --git a/vue/primitives/src/calendar/CalendarHeadCell.vue b/vue/primitives/src/display/calendar/CalendarHeadCell.vue
similarity index 74%
rename from vue/primitives/src/calendar/CalendarHeadCell.vue
rename to vue/primitives/src/display/calendar/CalendarHeadCell.vue
index e8d7fc1..0b15bac 100644
--- a/vue/primitives/src/calendar/CalendarHeadCell.vue
+++ b/vue/primitives/src/display/calendar/CalendarHeadCell.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A `scope="col"` weekday header cell (`<th>`). Renders the localized short
@@ -14,14 +14,14 @@ export interface CalendarHeadCellProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCalendarRootContext } from './context';
-import { formatWeekday } from './utils';
 
 const { as = 'th', day } = defineProps<CalendarHeadCellProps>();
 
 const ctx = useCalendarRootContext();
-const longLabel = computed(() => (day ? formatWeekday(day, ctx.locale.value, 'long') : undefined));
+const adapter = ctx.dateAdapter;
+const longLabel = computed(() => (day ? adapter.value.formatWeekday(day, ctx.locale.value, 'long') : undefined));
 </script>
 
 <template>
diff --git a/vue/primitives/src/calendar/CalendarHeader.vue b/vue/primitives/src/display/calendar/CalendarHeader.vue
similarity index 79%
rename from vue/primitives/src/calendar/CalendarHeader.vue
rename to vue/primitives/src/display/calendar/CalendarHeader.vue
index a1cca2e..e7e5cad 100644
--- a/vue/primitives/src/calendar/CalendarHeader.vue
+++ b/vue/primitives/src/display/calendar/CalendarHeader.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Layout container for the calendar's top bar. Holds the `CalendarPrev`,
@@ -9,7 +9,7 @@ export interface CalendarHeaderProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'div' } = defineProps<CalendarHeaderProps>();
 </script>
diff --git a/vue/primitives/src/calendar/CalendarHeading.vue b/vue/primitives/src/display/calendar/CalendarHeading.vue
similarity index 88%
rename from vue/primitives/src/calendar/CalendarHeading.vue
rename to vue/primitives/src/display/calendar/CalendarHeading.vue
index 8d99168..953630d 100644
--- a/vue/primitives/src/calendar/CalendarHeading.vue
+++ b/vue/primitives/src/display/calendar/CalendarHeading.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Displays the currently visible month and year (e.g. "June 2026"), or a range
@@ -11,7 +11,7 @@ export interface CalendarHeadingProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCalendarRootContext } from './context';
 
 const { as = 'div' } = defineProps<CalendarHeadingProps>();
diff --git a/vue/primitives/src/calendar/CalendarNext.vue b/vue/primitives/src/display/calendar/CalendarNext.vue
similarity index 91%
rename from vue/primitives/src/calendar/CalendarNext.vue
rename to vue/primitives/src/display/calendar/CalendarNext.vue
index 5fb52e8..78f82f3 100644
--- a/vue/primitives/src/calendar/CalendarNext.vue
+++ b/vue/primitives/src/display/calendar/CalendarNext.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Button that pages the calendar forward (by one month, or by
@@ -14,7 +14,7 @@ export interface CalendarNextProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCalendarRootContext } from './context';
 
 const { as = 'button', nextPage: nextPageProp } = defineProps<CalendarNextProps>();
diff --git a/vue/primitives/src/calendar/CalendarPrev.vue b/vue/primitives/src/display/calendar/CalendarPrev.vue
similarity index 91%
rename from vue/primitives/src/calendar/CalendarPrev.vue
rename to vue/primitives/src/display/calendar/CalendarPrev.vue
index 9d4b881..b79a596 100644
--- a/vue/primitives/src/calendar/CalendarPrev.vue
+++ b/vue/primitives/src/display/calendar/CalendarPrev.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Button that pages the calendar backward (by one month, or by
@@ -14,7 +14,7 @@ export interface CalendarPrevProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCalendarRootContext } from './context';
 
 const { as = 'button', prevPage: prevPageProp } = defineProps<CalendarPrevProps>();
diff --git a/vue/primitives/src/calendar/CalendarRoot.vue b/vue/primitives/src/display/calendar/CalendarRoot.vue
similarity index 55%
rename from vue/primitives/src/calendar/CalendarRoot.vue
rename to vue/primitives/src/display/calendar/CalendarRoot.vue
index 0e84c85..0d18ee4 100644
--- a/vue/primitives/src/calendar/CalendarRoot.vue
+++ b/vue/primitives/src/display/calendar/CalendarRoot.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { DateAdapter } from '../../utilities/config-provider';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { CalendarMonth, WeekDayFormat } from './utils';
 
 /**
@@ -14,8 +15,8 @@ import type { CalendarMonth, WeekDayFormat } from './utils';
  * selected date and `v-model:placeholder` for the visible month.
  */
 export interface CalendarRootProps extends PrimitiveProps {
-  /** Uncontrolled default selected date. */
-  defaultValue?: Date;
+  /** Uncontrolled default selected date (or dates when `multiple`). */
+  defaultValue?: Date | Date[];
   /** Uncontrolled default placeholder (displayed month). */
   defaultPlaceholder?: Date;
   /** Minimum selectable date. */
@@ -52,10 +53,21 @@ export interface CalendarRootProps extends PrimitiveProps {
   prevPage?: (placeholder: Date) => Date;
   /** Calendar accessible label prefix. @default 'Calendar' */
   calendarLabel?: string;
+  /** Allow selecting multiple dates; model becomes a `Date[]`. @default false */
+  multiple?: boolean;
+  /** Prevent deselecting the last selected date by re-clicking it. @default false */
+  preventDeselect?: boolean;
+  /** Disable days that belong to adjacent months (outside the current view). @default false */
+  disableDaysOutsideCurrentView?: boolean;
+  /**
+   * Pluggable date backend driving all date math/formatting. Falls back to the
+   * app `ConfigProvider` `dateAdapter` (native `Date`) when omitted.
+   */
+  dateAdapter?: DateAdapter<Date>;
 }
 
 export interface CalendarRootEmits {
-  'update:modelValue': [date: Date | undefined];
+  'update:modelValue': [date: Date | Date[] | undefined];
   'update:placeholder': [date: Date];
 }
 </script>
@@ -63,22 +75,9 @@ export interface CalendarRootEmits {
 <script setup lang="ts">
 import { useEventListener, useForwardExpose } from '@robonen/vue';
 import { computed, onMounted, ref, toRef, watch } from 'vue';
-import { Primitive } from '../primitive';
+import { useDateAdapter } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { provideCalendarRootContext } from './context';
-import {
-  addMonths,
-  addYears,
-  clamp,
-  createMonths,
-  formatMonthYear,
-  getWeekdayLabels,
-  isAfter,
-  isBefore,
-  isSameDay,
-  isSameMonth,
-  isDateUnavailable as isUnavailable,
-  toDateOnly,
-} from './utils';
 
 const {
   as = 'div',
@@ -89,7 +88,7 @@ const {
   isDateUnavailable: propsIsDateUnavailable,
   isDateDisabled: propsIsDateDisabled,
   pagedNavigation = false,
-  weekStartsOn = 0,
+  weekStartsOn: weekStartsOnProp,
   weekdayFormat = 'short',
   fixedWeeks = true,
   numberOfMonths = 1,
@@ -101,6 +100,10 @@ const {
   nextPage: propsNextPage,
   prevPage: propsPrevPage,
   calendarLabel = 'Calendar',
+  multiple = false,
+  preventDeselect = false,
+  disableDaysOutsideCurrentView = false,
+  dateAdapter,
 } = defineProps<CalendarRootProps>();
 
 defineEmits<CalendarRootEmits>();
@@ -112,12 +115,16 @@ defineSlots<{
     weekDays: string[];
     weekStartsOn: number;
     locale: string;
-    modelValue: Date | undefined;
+    modelValue: Date | Date[] | undefined;
   }) => unknown;
 }>();
 
-const localValue = ref<Date | undefined>(defaultValue);
-const modelValue = defineModel<Date | undefined>('modelValue', {
+// Resolve the effective date backend: per-instance prop wins over the global
+// `ConfigProvider` adapter, falling back to the native `Date` adapter.
+const adapter = useDateAdapter(() => dateAdapter);
+
+const localValue = ref<Date | Date[] | undefined>(defaultValue);
+const modelValue = defineModel<Date | Date[] | undefined>('modelValue', {
   default: undefined,
   get: v => v ?? localValue.value,
   set: (v) => {
@@ -126,14 +133,19 @@ const modelValue = defineModel<Date | undefined>('modelValue', {
   },
 });
 
+function lastSelected(v: Date | Date[] | undefined): Date | undefined {
+  if (Array.isArray(v)) return v.at(-1);
+  return v;
+}
+
 const localPlaceholder = ref<Date>(
-  toDateOnly(defaultPlaceholder ?? modelValue.value ?? new Date()),
+  adapter.value.toDateOnly(defaultPlaceholder ?? lastSelected(modelValue.value) ?? adapter.value.now()),
 );
 const placeholder = defineModel<Date>('placeholder', {
   default: undefined,
   get: v => v ?? localPlaceholder.value,
   set: (v) => {
-    localPlaceholder.value = toDateOnly(v);
+    localPlaceholder.value = adapter.value.toDateOnly(v);
     return localPlaceholder.value;
   },
 });
@@ -143,31 +155,38 @@ const focusedDate = ref<Date | undefined>();
 
 const localeRef = toRef(() => locale);
 const dirRef = toRef(() => dir);
-const weekStartsOnRef = toRef(() => weekStartsOn);
+// Locale-aware default: when `weekStartsOn` is omitted, derive it from the
+// locale (e.g. 'en-US' → Sunday, 'fr'/'de' → Monday).
+const weekStartsOn = computed<0 | 1 | 2 | 3 | 4 | 5 | 6>(() =>
+  weekStartsOnProp ?? adapter.value.getLocaleWeekStartsOn(locale),
+);
 const weekdayFormatRef = toRef(() => weekdayFormat);
 const fixedWeeksRef = toRef(() => fixedWeeks);
 const numberOfMonthsRef = toRef(() => numberOfMonths);
 const disabledRef = toRef(() => disabled);
 const readonlyRef = toRef(() => readonly);
 const pagedNavigationRef = toRef(() => pagedNavigation);
+const multipleRef = toRef(() => multiple);
+const preventDeselectRef = toRef(() => preventDeselect);
+const disableDaysOutsideCurrentViewRef = toRef(() => disableDaysOutsideCurrentView);
 const minValueRef = toRef(() => minValue);
 const maxValueRef = toRef(() => maxValue);
 
-const grid = computed<CalendarMonth[]>(() => createMonths({
+const grid = computed<CalendarMonth[]>(() => adapter.value.createMonths({
   date: placeholder.value,
   numberOfMonths,
-  weekStartsOn,
+  weekStartsOn: weekStartsOn.value,
   fixedWeeks,
 }));
 
-const weekDays = computed(() => getWeekdayLabels(weekStartsOn, locale, weekdayFormat));
+const weekDays = computed(() => adapter.value.getWeekdayLabels(weekStartsOn.value, locale, weekdayFormat));
 
 const headingValue = computed(() => {
   const months = grid.value;
   if (!months.length) return '';
-  if (months.length === 1) return formatMonthYear(months[0]!.value, locale);
-  const first = formatMonthYear(months[0]!.value, locale);
-  const last = formatMonthYear(months[months.length - 1]!.value, locale);
+  if (months.length === 1) return adapter.value.formatMonthYear(months[0]!.value, locale);
+  const first = adapter.value.formatMonthYear(months[0]!.value, locale);
+  const last = adapter.value.formatMonthYear(months[months.length - 1]!.value, locale);
   return `${first} - ${last}`;
 });
 
@@ -176,36 +195,74 @@ const fullCalendarLabel = computed(() => `${calendarLabel}, ${headingValue.value
 function isDateDisabled(date: Date): boolean {
   if (disabled) return true;
   if (propsIsDateDisabled?.(date)) return true;
-  if (minValue && isBefore(date, minValue)) return true;
-  if (maxValue && isAfter(date, maxValue)) return true;
+  if (minValue && adapter.value.isBefore(date, minValue)) return true;
+  if (maxValue && adapter.value.isAfter(date, maxValue)) return true;
   return false;
 }
 
 function isDateUnavailableLocal(date: Date): boolean {
-  return isUnavailable(date, propsIsDateUnavailable, minValue, maxValue);
+  return adapter.value.isDateUnavailable(date, propsIsDateUnavailable, minValue, maxValue);
 }
 
 function isDateSelected(date: Date): boolean {
-  return modelValue.value ? isSameDay(modelValue.value, date) : false;
+  const v = modelValue.value;
+  if (Array.isArray(v)) return v.some(d => adapter.value.isSameDay(d, date));
+  return v ? adapter.value.isSameDay(v, date) : false;
 }
 
 function isOutsideVisibleView(date: Date): boolean {
-  return !grid.value.some(m => isSameMonth(m.value, date));
+  return !grid.value.some(m => adapter.value.isSameMonth(m.value, date));
 }
 
 const isInvalid = computed(() => {
-  if (!modelValue.value) return false;
-  return isDateDisabled(modelValue.value) || isDateUnavailableLocal(modelValue.value);
+  const v = modelValue.value;
+  if (Array.isArray(v)) {
+    if (!v.length) return false;
+    return v.some(d => isDateDisabled(d) || isDateUnavailableLocal(d));
+  }
+  if (!v) return false;
+  return isDateDisabled(v) || isDateUnavailableLocal(v);
 });
 
 function setDate(date: Date | undefined) {
   if (readonly) return;
   if (date && (isDateDisabled(date) || isDateUnavailableLocal(date))) return;
-  modelValue.value = date ? toDateOnly(date) : undefined;
+
+  if (!multiple) {
+    // Single mode: re-clicking the selected date deselects it unless prevented.
+    if (date && !preventDeselect && !Array.isArray(modelValue.value)
+      && modelValue.value && adapter.value.isSameDay(modelValue.value, date)) {
+      placeholder.value = date;
+      modelValue.value = undefined;
+      return;
+    }
+    modelValue.value = date ? adapter.value.toDateOnly(date) : undefined;
+    return;
+  }
+
+  // Multiple mode: toggle membership, keeping a fresh array reference.
+  const current = Array.isArray(modelValue.value)
+    ? modelValue.value
+    : modelValue.value
+      ? [modelValue.value]
+      : [];
+  if (!date) {
+    modelValue.value = [];
+    return;
+  }
+  const normalized = adapter.value.toDateOnly(date);
+  const idx = current.findIndex(d => adapter.value.isSameDay(d, normalized));
+  if (idx === -1) {
+    modelValue.value = [...current, normalized];
+    return;
+  }
+  if (preventDeselect) return;
+  const next = current.filter((_, i) => i !== idx);
+  modelValue.value = next.length ? next : undefined;
 }
 
 function setPlaceholder(date: Date) {
-  placeholder.value = clamp(date, minValue, maxValue);
+  placeholder.value = adapter.value.clamp(date, minValue, maxValue);
 }
 
 function pageStep(): number {
@@ -215,20 +272,20 @@ function pageStep(): number {
 function nextPage(fn?: (placeholder: Date) => Date) {
   const fnToUse = fn ?? propsNextPage;
   placeholder.value = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(placeholder.value, pageStep());
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(placeholder.value, pageStep());
 }
 function prevPage(fn?: (placeholder: Date) => Date) {
   const fnToUse = fn ?? propsPrevPage;
   placeholder.value = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(placeholder.value, -pageStep());
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(placeholder.value, -pageStep());
 }
 function nextYear() {
-  placeholder.value = addYears(placeholder.value, 1);
+  placeholder.value = adapter.value.addYears(placeholder.value, 1);
 }
 function prevYear() {
-  placeholder.value = addYears(placeholder.value, -1);
+  placeholder.value = adapter.value.addYears(placeholder.value, -1);
 }
 
 function isNextButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
@@ -238,9 +295,9 @@ function isNextButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
   if (!lastMonth) return false;
   const fnToUse = fn ?? propsNextPage;
   const probe = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(lastMonth, 1);
-  return isAfter(probe, maxValue);
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(lastMonth, 1);
+  return adapter.value.isAfter(probe, maxValue);
 }
 function isPrevButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
   if (disabled) return true;
@@ -249,16 +306,28 @@ function isPrevButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
   if (!firstMonth) return false;
   const fnToUse = fn ?? propsPrevPage;
   const probe = fnToUse
-    ? toDateOnly(fnToUse(placeholder.value))
-    : addMonths(firstMonth, -1);
-  return isBefore(probe, minValue);
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(firstMonth, -1);
+  return adapter.value.isBefore(probe, minValue);
 }
 
 watch(modelValue, (v) => {
-  if (v && !isSameMonth(v, placeholder.value))
-    placeholder.value = toDateOnly(v);
+  const last = lastSelected(v);
+  if (last && !adapter.value.isSameMonth(last, placeholder.value))
+    placeholder.value = adapter.value.toDateOnly(last);
 });
 
+const hasSelectedDate = computed(() => {
+  const v = modelValue.value;
+  return Array.isArray(v) ? v.length > 0 : !!v;
+});
+
+// First in-view, non-disabled, non-unavailable date — the roving-focus fallback
+// so the initial tab stop is always actionable.
+const firstFocusableDate = computed(() =>
+  adapter.value.findFirstFocusableDate(grid.value, isDateDisabled, isDateUnavailableLocal),
+);
+
 onMounted(() => {
   if (!initialFocus || !parentElement.value) return;
   const target = parentElement.value.querySelector<HTMLElement>(
@@ -275,6 +344,7 @@ useEventListener(parentElement, 'focusout', (e) => {
 });
 
 provideCalendarRootContext({
+  dateAdapter: adapter,
   modelValue,
   placeholder,
   locale: localeRef,
@@ -283,13 +353,16 @@ provideCalendarRootContext({
   weekDays,
   headingValue,
   fullCalendarLabel,
-  weekStartsOn: weekStartsOnRef,
+  weekStartsOn,
   weekdayFormat: weekdayFormatRef,
   fixedWeeks: fixedWeeksRef,
   numberOfMonths: numberOfMonthsRef,
   disabled: disabledRef,
   readonly: readonlyRef,
   pagedNavigation: pagedNavigationRef,
+  multiple: multipleRef,
+  preventDeselect: preventDeselectRef,
+  disableDaysOutsideCurrentView: disableDaysOutsideCurrentViewRef,
   minValue: minValueRef,
   maxValue: maxValueRef,
   isDateDisabled,
@@ -297,6 +370,8 @@ provideCalendarRootContext({
   isDateSelected,
   isOutsideVisibleView,
   isInvalid,
+  hasSelectedDate,
+  firstFocusableDate,
   parentElement,
   focusedDate,
   setDate,
@@ -330,5 +405,16 @@ provideCalendarRootContext({
       :locale="locale"
       :model-value="modelValue"
     />
+    <div
+      :data-primitives-calendar-sr-heading="''"
+      style="border:0;clip:rect(0 0 0 0);clip-path:inset(50%);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;white-space:nowrap;width:1px;"
+    >
+      <div
+        role="heading"
+        aria-level="2"
+      >
+        {{ fullCalendarLabel }}
+      </div>
+    </div>
   </Primitive>
 </template>
diff --git a/vue/primitives/src/calendar/__test__/Calendar.test.ts b/vue/primitives/src/display/calendar/__test__/Calendar.test.ts
similarity index 100%
rename from vue/primitives/src/calendar/__test__/Calendar.test.ts
rename to vue/primitives/src/display/calendar/__test__/Calendar.test.ts
diff --git a/vue/primitives/src/display/calendar/__test__/CalendarFeatures.test.ts b/vue/primitives/src/display/calendar/__test__/CalendarFeatures.test.ts
new file mode 100644
index 0000000..45be70c
--- /dev/null
+++ b/vue/primitives/src/display/calendar/__test__/CalendarFeatures.test.ts
@@ -0,0 +1,270 @@
+import type { CalendarMonth } from '../utils';
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import {
+  CalendarCell,
+  CalendarCellTrigger,
+  CalendarGrid,
+  CalendarGridBody,
+  CalendarGridHead,
+  CalendarGridRow,
+  CalendarHeadCell,
+  CalendarRoot,
+} from '../index';
+import { findFirstFocusableDate, getLocaleWeekStartsOn, toIsoDate } from '../utils';
+
+function mountCalendar(
+  props: Record<string, unknown> = {},
+  options: Record<string, unknown> = {},
+) {
+  return mount(defineComponent({
+    setup: () => () => h(CalendarRoot, props, {
+      default: ({ grid, weekDays }: { grid: CalendarMonth[]; weekDays: string[] }) =>
+        grid.map(month =>
+          h(CalendarGrid, { key: month.value.toString(), month: month.value }, {
+            default: () => [
+              h(CalendarGridHead, null, {
+                default: () => h(CalendarGridRow, null, {
+                  default: () => weekDays.map((wd, i) => h(CalendarHeadCell, { key: i }, () => wd)),
+                }),
+              }),
+              h(CalendarGridBody, null, {
+                default: () => month.weeks.map((week, w) =>
+                  h(CalendarGridRow, { key: w }, {
+                    default: () => week.map(day =>
+                      h(CalendarCell, { key: day.toString(), date: day }, {
+                        default: () => h(CalendarCellTrigger, { day, month: month.value }),
+                      })),
+                  })),
+              }),
+            ],
+          })),
+    }),
+  }), options);
+}
+
+function press(el: Element, key: string) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+}
+
+describe('Calendar — accessibility skeleton', () => {
+  it('renders an SR-only role=heading mirroring the calendar label', () => {
+    const w = mountCalendar({ defaultPlaceholder: new Date(2026, 5, 1) });
+    const srHeading = w.find('[data-primitives-calendar-sr-heading] [role="heading"]');
+    expect(srHeading.exists()).toBe(true);
+    expect(srHeading.attributes('aria-level')).toBe('2');
+    expect(srHeading.text()).toContain('2026');
+    w.unmount();
+  });
+
+  it('marks the grid head as aria-hidden', () => {
+    const w = mountCalendar({ defaultPlaceholder: new Date(2026, 5, 1) });
+    const head = w.find('[data-primitives-calendar-grid-head]');
+    expect(head.attributes('aria-hidden')).toBe('true');
+    w.unmount();
+  });
+});
+
+describe('Calendar — single mode deselect', () => {
+  it('re-clicking the selected date clears the model (deselect-on-reclick)', async () => {
+    const selected = new Date(2026, 5, 15);
+    const w = mountCalendar({ defaultValue: selected, defaultPlaceholder: selected });
+    const cell = w.find('[data-value="2026-06-15"]:not([data-outside-view])');
+    await cell.trigger('click');
+    await nextTick();
+    expect(w.find('[data-value="2026-06-15"][data-selected]').exists()).toBe(false);
+    w.unmount();
+  });
+
+  it('preventDeselect keeps the selected date on re-click', async () => {
+    const selected = new Date(2026, 5, 15);
+    const w = mountCalendar({ defaultValue: selected, defaultPlaceholder: selected, preventDeselect: true });
+    const cell = w.find('[data-value="2026-06-15"]:not([data-outside-view])');
+    await cell.trigger('click');
+    await nextTick();
+    expect(w.find('[data-value="2026-06-15"]:not([data-outside-view])').attributes('data-selected')).toBe('');
+    w.unmount();
+  });
+});
+
+describe('Calendar — multiple mode', () => {
+  it('toggles membership: click adds, re-click removes', async () => {
+    const w = mountCalendar({ multiple: true, defaultPlaceholder: new Date(2026, 5, 1) });
+    const a = () => w.find('[data-value="2026-06-10"]:not([data-outside-view])');
+    const b = () => w.find('[data-value="2026-06-20"]:not([data-outside-view])');
+
+    await a().trigger('click');
+    await b().trigger('click');
+    await nextTick();
+    expect(a().attributes('data-selected')).toBe('');
+    expect(b().attributes('data-selected')).toBe('');
+
+    await a().trigger('click');
+    await nextTick();
+    expect(a().attributes('data-selected')).toBeUndefined();
+    expect(b().attributes('data-selected')).toBe('');
+    w.unmount();
+  });
+
+  it('accepts an array defaultValue and marks each as selected', async () => {
+    const w = mountCalendar({
+      multiple: true,
+      defaultValue: [new Date(2026, 5, 5), new Date(2026, 5, 12)],
+      defaultPlaceholder: new Date(2026, 5, 1),
+    });
+    await nextTick();
+    expect(w.find('[data-value="2026-06-05"]:not([data-outside-view])').attributes('data-selected')).toBe('');
+    expect(w.find('[data-value="2026-06-12"]:not([data-outside-view])').attributes('data-selected')).toBe('');
+    w.unmount();
+  });
+
+  it('preventDeselect in multiple mode blocks removal but allows addition', async () => {
+    const w = mountCalendar({
+      multiple: true,
+      preventDeselect: true,
+      defaultValue: [new Date(2026, 5, 5)],
+      defaultPlaceholder: new Date(2026, 5, 1),
+    });
+    const existing = () => w.find('[data-value="2026-06-05"]:not([data-outside-view])');
+    await existing().trigger('click'); // attempt removal — blocked
+    await nextTick();
+    expect(existing().attributes('data-selected')).toBe('');
+
+    const next = () => w.find('[data-value="2026-06-09"]:not([data-outside-view])');
+    await next().trigger('click'); // addition allowed
+    await nextTick();
+    expect(next().attributes('data-selected')).toBe('');
+    w.unmount();
+  });
+});
+
+describe('Calendar — disableDaysOutsideCurrentView', () => {
+  it('disables adjacent-month days when enabled', () => {
+    const w = mountCalendar({
+      disableDaysOutsideCurrentView: true,
+      defaultPlaceholder: new Date(2026, 5, 1), // June 2026 starts on a Monday → leading outside days
+    });
+    const outside = w.findAll('[data-primitives-calendar-cell-trigger][data-outside-view]');
+    expect(outside.length).toBeGreaterThan(0);
+    for (const t of outside)
+      expect(t.attributes('data-disabled')).toBe('');
+    w.unmount();
+  });
+
+  it('leaves adjacent-month days enabled by default', () => {
+    const w = mountCalendar({ defaultPlaceholder: new Date(2026, 5, 1) });
+    const outside = w.findAll('[data-primitives-calendar-cell-trigger][data-outside-view]');
+    for (const t of outside)
+      expect(t.attributes('data-disabled')).toBeUndefined();
+    w.unmount();
+  });
+});
+
+describe('Calendar — keyboard skips disabled days', () => {
+  it('ArrowRight jumps over a disabled day to the next available one', async () => {
+    const w = mountCalendar({
+      defaultPlaceholder: new Date(2026, 5, 1),
+      isDateDisabled: (d: Date) => d.getDate() === 11, // disable June 11
+    }, { attachTo: document.body });
+    const from = w.find('[data-value="2026-06-10"]:not([data-outside-view])');
+    (from.element as HTMLElement).focus();
+    press(from.element, 'ArrowRight');
+    await nextTick();
+    await nextTick();
+    expect(document.activeElement?.getAttribute('data-value')).toBe('2026-06-12');
+    w.unmount();
+  });
+
+  it('intra-month arrow navigation does not shift a multi-month visible window', async () => {
+    const w = mountCalendar({
+      defaultPlaceholder: new Date(2026, 5, 1),
+      numberOfMonths: 2,
+    }, { attachTo: document.body });
+    // Both June and July grids are present before navigation.
+    expect(w.findAll('[data-value="2026-06-15"]:not([data-outside-view])').length).toBe(1);
+    expect(w.findAll('[data-value="2026-07-15"]:not([data-outside-view])').length).toBe(1);
+
+    const from = w.find('[data-value="2026-06-15"]:not([data-outside-view])');
+    (from.element as HTMLElement).focus();
+    press(from.element, 'ArrowRight');
+    await nextTick();
+    await nextTick();
+    // Window unchanged: July is still rendered, June 16 received focus.
+    expect(document.activeElement?.getAttribute('data-value')).toBe('2026-06-16');
+    expect(w.findAll('[data-value="2026-07-15"]:not([data-outside-view])').length).toBe(1);
+    w.unmount();
+  });
+});
+
+describe('Calendar — roving fallback tabindex', () => {
+  it('initial tab stop skips disabled leading days and lands on the first available day', () => {
+    // Disable the entire first half of June; tab stop should land on the 16th.
+    const w = mountCalendar({
+      defaultPlaceholder: new Date(2026, 5, 1),
+      isDateDisabled: (d: Date) => d.getMonth() === 5 && d.getDate() < 16,
+    });
+    const focusable = w.findAll('[data-primitives-calendar-cell-trigger][tabindex="0"]');
+    expect(focusable).toHaveLength(1);
+    expect(focusable[0]!.attributes('data-value')).toBe('2026-06-16');
+    w.unmount();
+  });
+});
+
+describe('Calendar — outside-visible-view marker', () => {
+  it('marks single-month padding days (from adjacent months) as outside-visible-view', () => {
+    const w = mountCalendar({ defaultPlaceholder: new Date(2026, 5, 1), numberOfMonths: 1 });
+    // With one visible month, an adjacent-month padding day is both
+    // outside-view and outside-visible-view, and every such pair must agree.
+    const outsideView = w.findAll('[data-primitives-calendar-cell-trigger][data-outside-view]');
+    const outsideVisible = w.findAll('[data-primitives-calendar-cell-trigger][data-outside-visible-view]');
+    expect(outsideVisible.length).toBe(outsideView.length);
+    expect(outsideVisible.length).toBeGreaterThan(0);
+    w.unmount();
+  });
+
+  it('a padding day belonging to a second visible month is outside-view but not outside-visible-view', () => {
+    // June + July 2026 visible. July 1 appears as a padding cell in June's grid:
+    // outside June's view, yet July is a visible month → not outside-visible-view.
+    const w = mountCalendar({ defaultPlaceholder: new Date(2026, 5, 1), numberOfMonths: 2 });
+    const julyFirstPadding = w.findAll('[data-value="2026-07-01"][data-outside-view]');
+    expect(julyFirstPadding.length).toBeGreaterThan(0);
+    for (const t of julyFirstPadding)
+      expect(t.attributes('data-outside-visible-view')).toBeUndefined();
+    w.unmount();
+  });
+});
+
+describe('Calendar — locale-aware week start', () => {
+  it('defaults weekStartsOn from the locale when the prop is omitted', () => {
+    expect(getLocaleWeekStartsOn('en-US')).toBe(0);
+    expect(getLocaleWeekStartsOn('fr-FR')).toBe(1);
+    expect(getLocaleWeekStartsOn('de-DE')).toBe(1);
+  });
+
+  it('an explicit weekStartsOn overrides the locale default', () => {
+    const w = mountCalendar({ defaultPlaceholder: new Date(2026, 5, 1), locale: 'fr-FR', weekStartsOn: 0 });
+    // weekStartsOn=0 (Sunday): first cell of the first week is a Sunday.
+    const firstTrigger = w.find('[data-primitives-calendar-cell-trigger]');
+    const iso = firstTrigger.attributes('data-value')!;
+    expect(new Date(`${iso}T00:00:00`).getDay()).toBe(0);
+    w.unmount();
+  });
+});
+
+describe('findFirstFocusableDate', () => {
+  it('returns the first non-disabled, non-unavailable in-view date', () => {
+    const months = [{ value: new Date(2026, 5, 1), weeks: [] }];
+    const first = findFirstFocusableDate(
+      months,
+      d => d.getDate() < 5,
+      () => false,
+    );
+    expect(first && toIsoDate(first)).toBe('2026-06-05');
+  });
+
+  it('returns undefined when every day is blocked', () => {
+    const months = [{ value: new Date(2026, 5, 1), weeks: [] }];
+    expect(findFirstFocusableDate(months, () => true, () => false)).toBeUndefined();
+  });
+});
diff --git a/vue/primitives/src/display/calendar/__test__/__screenshots__/Calendar.test.ts/Calendar-mounts-cell-triggers-without--expose---should-be-called-only-once--warnings-1.png b/vue/primitives/src/display/calendar/__test__/__screenshots__/Calendar.test.ts/Calendar-mounts-cell-triggers-without--expose---should-be-called-only-once--warnings-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/calendar/__test__/__screenshots__/Calendar.test.ts/Calendar-mounts-cell-triggers-without--expose---should-be-called-only-once--warnings-1.png differ
diff --git a/vue/primitives/src/calendar/__test__/date-utils.test.ts b/vue/primitives/src/display/calendar/__test__/date-utils.test.ts
similarity index 100%
rename from vue/primitives/src/calendar/__test__/date-utils.test.ts
rename to vue/primitives/src/display/calendar/__test__/date-utils.test.ts
diff --git a/vue/primitives/src/calendar/context.ts b/vue/primitives/src/display/calendar/context.ts
similarity index 72%
rename from vue/primitives/src/calendar/context.ts
rename to vue/primitives/src/display/calendar/context.ts
index 81f462b..fd2d523 100644
--- a/vue/primitives/src/calendar/context.ts
+++ b/vue/primitives/src/display/calendar/context.ts
@@ -1,10 +1,13 @@
 import type { ComputedRef, Ref } from 'vue';
+import type { DateAdapter } from '../../utilities/config-provider';
 import type { CalendarMonth, WeekDayFormat } from './utils';
 import { useContextFactory } from '@robonen/vue';
 
 export interface CalendarRootContext {
-  /** Currently selected date (or undefined). */
-  modelValue: Ref<Date | undefined>;
+  /** Resolved date backend (root `dateAdapter` prop or the global `ConfigProvider`). */
+  dateAdapter: ComputedRef<DateAdapter<Date>>;
+  /** Currently selected date, dates (when `multiple`), or undefined. */
+  modelValue: Ref<Date | Date[] | undefined>;
   /** Displayed month anchor. */
   placeholder: Ref<Date>;
   /** Locale identifier for `Intl` formatting. */
@@ -28,6 +31,12 @@ export interface CalendarRootContext {
   disabled: Ref<boolean>;
   readonly: Ref<boolean>;
   pagedNavigation: Ref<boolean>;
+  /** Whether multiple dates may be selected. */
+  multiple: Ref<boolean>;
+  /** Whether re-clicking the last selected date is prevented from deselecting it. */
+  preventDeselect: Ref<boolean>;
+  /** Whether adjacent-month days (outside the current view) are disabled. */
+  disableDaysOutsideCurrentView: Ref<boolean>;
 
   minValue: Ref<Date | undefined>;
   maxValue: Ref<Date | undefined>;
@@ -37,6 +46,10 @@ export interface CalendarRootContext {
   isDateSelected: (date: Date) => boolean;
   isOutsideVisibleView: (date: Date) => boolean;
   isInvalid: ComputedRef<boolean>;
+  /** Whether at least one date is currently selected. */
+  hasSelectedDate: ComputedRef<boolean>;
+  /** First in-view, actionable date — the roving-focus fallback target. */
+  firstFocusableDate: ComputedRef<Date | undefined>;
 
   /** Element hosting the calendar grid(s); used for keyboard focus shifting. */
   parentElement: Ref<HTMLElement | undefined>;
diff --git a/vue/primitives/src/calendar/date-utils.ts b/vue/primitives/src/display/calendar/date-utils.ts
similarity index 61%
rename from vue/primitives/src/calendar/date-utils.ts
rename to vue/primitives/src/display/calendar/date-utils.ts
index c07b3e5..bacfc86 100644
--- a/vue/primitives/src/calendar/date-utils.ts
+++ b/vue/primitives/src/display/calendar/date-utils.ts
@@ -78,6 +78,42 @@ export function startOfWeek(d: Date, weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6 = 0
   return r;
 }
 
+/**
+ * The locale's first day of week (0=Sun … 6=Sat). Uses `Intl.Locale.weekInfo`
+ * when available, otherwise probes a known Monday's index via `Intl` so that
+ * e.g. `'en-US'` resolves to Sunday and `'fr'`/`'de'` to Monday. Falls back to
+ * Sunday for unparseable locales.
+ */
+export function getLocaleWeekStartsOn(locale: string): 0 | 1 | 2 | 3 | 4 | 5 | 6 {
+  try {
+    const info = new Intl.Locale(locale) as Intl.Locale & {
+      weekInfo?: { firstDay?: number };
+      getWeekInfo?: () => { firstDay?: number };
+    };
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay;
+    if (typeof firstDay === 'number')
+      // `weekInfo.firstDay` is 1=Mon … 7=Sun; convert to 0=Sun … 6=Sat.
+      return (firstDay % 7) as 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  }
+  catch {
+    // Ignore — fall through to the Intl probe below.
+  }
+  // Probe: 2025-01-06 is a Monday. Determine its position in the locale week.
+  try {
+    const monday = new Date(2025, 0, 6);
+    const parts = new Intl.DateTimeFormat(locale, { weekday: 'short' });
+    // Compare against an anchored Sunday to derive the offset.
+    const sundayShort = parts.format(new Date(2025, 0, 5));
+    const mondayShort = parts.format(monday);
+    if (sundayShort === mondayShort)
+      return 0;
+    return 1;
+  }
+  catch {
+    return 0;
+  }
+}
+
 /**
  * Returns a 6×7 matrix of dates for the month containing `month`,
  * padded with leading/trailing days from adjacent months.
@@ -118,12 +154,34 @@ export function isDateUnavailable(
   return false;
 }
 
+/**
+ * Cache of `Intl.DateTimeFormat` instances keyed by `locale|JSON(options)`.
+ * Formatter construction is ~1-2 orders of magnitude costlier than `.format()`
+ * on an existing instance, and instances are immutable/reusable. The set of
+ * distinct (locale, options) pairs a calendar uses is tiny (a handful), so the
+ * map stays bounded across the page lifetime.
+ */
+const dateTimeFormatCache = new Map<string, Intl.DateTimeFormat>();
+
+function getDateTimeFormat(
+  locale: string,
+  opts: Intl.DateTimeFormatOptions,
+): Intl.DateTimeFormat {
+  const key = `${locale}|${JSON.stringify(opts)}`;
+  let fmt = dateTimeFormatCache.get(key);
+  if (fmt === undefined) {
+    fmt = new Intl.DateTimeFormat(locale, opts);
+    dateTimeFormatCache.set(key, fmt);
+  }
+  return fmt;
+}
+
 export function formatDate(
   d: Date,
   opts: Intl.DateTimeFormatOptions,
   locale: string,
 ): string {
-  return new Intl.DateTimeFormat(locale, opts).format(d);
+  return getDateTimeFormat(locale, opts).format(d);
 }
 
 export function formatWeekday(
@@ -131,5 +189,5 @@ export function formatWeekday(
   locale: string,
   width: WeekDayFormat = 'short',
 ): string {
-  return new Intl.DateTimeFormat(locale, { weekday: width }).format(d);
+  return getDateTimeFormat(locale, { weekday: width }).format(d);
 }
diff --git a/vue/primitives/src/calendar/demo.vue b/vue/primitives/src/display/calendar/demo.vue
similarity index 71%
rename from vue/primitives/src/calendar/demo.vue
rename to vue/primitives/src/display/calendar/demo.vue
index a90eb6b..2440d44 100644
--- a/vue/primitives/src/calendar/demo.vue
+++ b/vue/primitives/src/display/calendar/demo.vue
@@ -28,19 +28,19 @@ function formatSelected(date: Date | undefined) {
     <CalendarRoot
       v-slot="{ grid, weekDays }"
       v-model="value"
-      class="rounded-xl border border-(--border) bg-(--bg-elevated) p-4 text-(--fg) shadow-sm"
+      class="demo-card p-4 text-fg shadow-sm"
     >
       <CalendarHeader class="mb-3 flex items-center justify-between gap-2">
         <CalendarPrev
           aria-label="Previous month"
-          class="inline-flex size-8 items-center justify-center rounded-lg border border-(--border) bg-(--bg) text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
+          class="inline-flex size-8 items-center justify-center rounded-lg border border-border bg-bg text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
         >
           ‹
         </CalendarPrev>
         <CalendarHeading class="text-sm font-semibold tracking-tight" />
         <CalendarNext
           aria-label="Next month"
-          class="inline-flex size-8 items-center justify-center rounded-lg border border-(--border) bg-(--bg) text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
+          class="inline-flex size-8 items-center justify-center rounded-lg border border-border bg-bg text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
         >
           ›
         </CalendarNext>
@@ -53,11 +53,11 @@ function formatSelected(date: Date | undefined) {
         class="w-full border-collapse select-none"
       >
         <CalendarGridHead>
-          <CalendarGridRow class="mb-1 flex">
+          <CalendarGridRow class="mb-1 grid grid-cols-7">
             <CalendarHeadCell
               v-for="(weekday, i) in weekDays"
               :key="weekday + i"
-              class="w-9 text-center text-xs font-medium text-(--fg-subtle)"
+              class="text-center text-xs font-medium text-fg-subtle"
             >
               {{ weekday }}
             </CalendarHeadCell>
@@ -68,29 +68,29 @@ function formatSelected(date: Date | undefined) {
           <CalendarGridRow
             v-for="(week, w) in month.weeks"
             :key="w"
-            class="flex w-full"
+            class="grid grid-cols-7"
           >
             <CalendarCell
               v-for="day in week"
               :key="day.toString()"
               :date="day"
-              class="p-0.5"
+              class="flex justify-center p-0.5"
             >
               <CalendarCellTrigger
                 v-slot="{ dayValue, selected, today }"
                 :day="day"
                 :month="month.value"
                 class="flex size-8 items-center justify-center rounded-lg text-sm tabular-nums transition outline-none cursor-pointer
-                  focus-visible:ring-2 focus-visible:ring-(--ring)
-                  hover:bg-(--bg-inset)
-                  data-[selected]:bg-(--accent) data-[selected]:font-semibold data-[selected]:text-(--accent-fg) data-[selected]:hover:bg-(--accent-hover)
-                  data-[outside-view]:text-(--fg-subtle) data-[outside-view]:opacity-50
+                  focus-visible:ring-2 focus-visible:ring-ring
+                  hover:bg-bg-inset
+                  data-[selected]:bg-accent data-[selected]:font-semibold data-[selected]:text-accent-fg data-[selected]:hover:bg-accent-hover
+                  data-[outside-view]:text-fg-subtle data-[outside-view]:opacity-50
                   data-[unavailable]:cursor-not-allowed data-[unavailable]:text-red-500 data-[unavailable]:line-through data-[unavailable]:hover:bg-transparent
                   data-[disabled]:cursor-not-allowed data-[disabled]:opacity-30"
               >
                 <span
                   :class="[
-                    today && !selected ? 'relative after:absolute after:bottom-1 after:left-1/2 after:size-1 after:-translate-x-1/2 after:rounded-full after:bg-(--accent)' : '',
+                    today && !selected ? 'relative after:absolute after:bottom-1 after:left-1/2 after:size-1 after:-translate-x-1/2 after:rounded-full after:bg-accent' : '',
                   ]"
                 >
                   {{ dayValue }}
@@ -102,9 +102,9 @@ function formatSelected(date: Date | undefined) {
       </CalendarGrid>
     </CalendarRoot>
 
-    <p class="text-xs text-(--fg-muted)">
+    <p class="text-xs text-fg-muted">
       Selected:
-      <span class="font-medium text-(--fg)">{{ formatSelected(value) }}</span>
+      <span class="font-medium text-fg">{{ formatSelected(value) }}</span>
     </p>
   </div>
 </template>
diff --git a/vue/primitives/src/calendar/index.ts b/vue/primitives/src/display/calendar/index.ts
similarity index 100%
rename from vue/primitives/src/calendar/index.ts
rename to vue/primitives/src/display/calendar/index.ts
diff --git a/vue/primitives/src/calendar/utils.ts b/vue/primitives/src/display/calendar/utils.ts
similarity index 67%
rename from vue/primitives/src/calendar/utils.ts
rename to vue/primitives/src/display/calendar/utils.ts
index ae41e4f..966fe64 100644
--- a/vue/primitives/src/calendar/utils.ts
+++ b/vue/primitives/src/display/calendar/utils.ts
@@ -3,6 +3,7 @@ import {
   addMonths,
   formatDate,
   formatWeekday,
+  getDaysInMonth,
   getWeeks,
   isSameMonth,
   startOfMonth,
@@ -11,15 +12,15 @@ import {
 
 export * from './date-utils';
 
-export interface CalendarMonth {
+export interface CalendarMonth<TDate = Date> {
   /** First day of this month (date-only). */
-  value: Date;
+  value: TDate;
   /** N×7 grid of dates including leading/trailing adjacent-month days. */
-  weeks: Date[][];
+  weeks: TDate[][];
 }
 
-export interface CreateMonthsOptions {
-  date: Date;
+export interface CreateMonthsOptions<TDate = Date> {
+  date: TDate;
   numberOfMonths: number;
   weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
   /** Always render 6 weeks per month. @default true */
@@ -60,6 +61,30 @@ export function getWeekdayLabels(
   return labels;
 }
 
+/**
+ * The first in-view date that is neither disabled nor unavailable, scanning
+ * months in order and honoring `minValue`. Used as the roving-focus fallback
+ * so the initial tab stop is always actionable. Returns `undefined` when every
+ * visible day is blocked.
+ */
+export function findFirstFocusableDate(
+  months: CalendarMonth[],
+  isDisabled: (d: Date) => boolean,
+  isUnavailable: (d: Date) => boolean,
+): Date | undefined {
+  for (const month of months) {
+    const start = startOfMonth(month.value);
+    const total = getDaysInMonth(month.value);
+    for (let day = 1; day <= total; day++) {
+      const date = new Date(start.getFullYear(), start.getMonth(), day);
+      if (isDisabled(date) || isUnavailable(date))
+        continue;
+      return date;
+    }
+  }
+  return undefined;
+}
+
 export function formatMonthYear(d: Date, locale: string): string {
   return formatDate(d, { month: 'long', year: 'numeric' }, locale);
 }
diff --git a/vue/primitives/src/date-picker/DatePickerAnchor.vue b/vue/primitives/src/display/date-picker/DatePickerAnchor.vue
similarity index 86%
rename from vue/primitives/src/date-picker/DatePickerAnchor.vue
rename to vue/primitives/src/display/date-picker/DatePickerAnchor.vue
index ab6f8ea..8f9985f 100644
--- a/vue/primitives/src/date-picker/DatePickerAnchor.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerAnchor.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperAnchorProps } from '../popper';
+import type { PopperAnchorProps } from '../../overlays/popper';
 
 /**
  * Optional custom anchor for positioning the popover against an element other
@@ -11,7 +11,7 @@ export interface DatePickerAnchorProps extends PopperAnchorProps {}
 
 <script setup lang="ts">
 import { onBeforeMount, onUnmounted } from 'vue';
-import { PopperAnchor } from '../popper';
+import { PopperAnchor } from '../../overlays/popper';
 import { useDatePickerRootContext } from './context';
 
 const props = defineProps<DatePickerAnchorProps>();
diff --git a/vue/primitives/src/date-picker/DatePickerArrow.vue b/vue/primitives/src/display/date-picker/DatePickerArrow.vue
similarity index 80%
rename from vue/primitives/src/date-picker/DatePickerArrow.vue
rename to vue/primitives/src/display/date-picker/DatePickerArrow.vue
index a1ff962..fd729d9 100644
--- a/vue/primitives/src/date-picker/DatePickerArrow.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerArrow.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperArrowProps } from '../popper';
+import type { PopperArrowProps } from '../../overlays/popper';
 
 /**
  * An optional arrow rendered inside `DatePickerContent` that points back at the
@@ -9,7 +9,7 @@ export interface DatePickerArrowProps extends PopperArrowProps {}
 </script>
 
 <script setup lang="ts">
-import { PopperArrow } from '../popper';
+import { PopperArrow } from '../../overlays/popper';
 
 const { width = 10, height = 5 } = defineProps<DatePickerArrowProps>();
 </script>
diff --git a/vue/primitives/src/date-picker/DatePickerCalendar.vue b/vue/primitives/src/display/date-picker/DatePickerCalendar.vue
similarity index 84%
rename from vue/primitives/src/date-picker/DatePickerCalendar.vue
rename to vue/primitives/src/display/date-picker/DatePickerCalendar.vue
index 38d14f6..1535906 100644
--- a/vue/primitives/src/date-picker/DatePickerCalendar.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerCalendar.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A styling wrapper for the calendar grid rendered inside the popover. The
@@ -11,7 +11,7 @@ export interface DatePickerCalendarProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'div' } = defineProps<DatePickerCalendarProps>();
 </script>
diff --git a/vue/primitives/src/date-picker/DatePickerClose.vue b/vue/primitives/src/display/date-picker/DatePickerClose.vue
similarity index 84%
rename from vue/primitives/src/date-picker/DatePickerClose.vue
rename to vue/primitives/src/display/date-picker/DatePickerClose.vue
index c5c3ccc..baebf68 100644
--- a/vue/primitives/src/date-picker/DatePickerClose.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerClose.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that closes the picker popover when clicked. Render it inside
@@ -9,7 +9,7 @@ export interface DatePickerCloseProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useDatePickerRootContext } from './context';
 
 const { as = 'button' } = defineProps<DatePickerCloseProps>();
diff --git a/vue/primitives/src/date-picker/DatePickerContent.vue b/vue/primitives/src/display/date-picker/DatePickerContent.vue
similarity index 84%
rename from vue/primitives/src/date-picker/DatePickerContent.vue
rename to vue/primitives/src/display/date-picker/DatePickerContent.vue
index a699381..319a0ac 100644
--- a/vue/primitives/src/date-picker/DatePickerContent.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerContent.vue
@@ -1,7 +1,7 @@
 <script lang="ts">
-import type { DismissableLayerEmits } from '../dismissable-layer';
-import type { FocusScopeEmits } from '../focus-scope';
-import type { PopperContentProps } from '../popper';
+import type { DismissableLayerEmits } from '../../utilities/dismissable-layer';
+import type { FocusScopeEmits } from '../../utilities/focus-scope';
+import type { PopperContentProps } from '../../overlays/popper';
 
 /**
  * The popover panel that holds the calendar. Handles Popper positioning,
@@ -26,10 +26,10 @@ export interface DatePickerContentEmits {
 </script>
 
 <script setup lang="ts">
-import { DismissableLayer } from '../dismissable-layer';
-import { FocusScope } from '../focus-scope';
-import { PopperContent } from '../popper';
-import { Presence } from '../presence';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
+import { FocusScope } from '../../utilities/focus-scope';
+import { PopperContent } from '../../overlays/popper';
+import { Presence } from '../../utilities/presence';
 import { useDatePickerRootContext } from './context';
 
 const {
diff --git a/vue/primitives/src/date-picker/DatePickerField.vue b/vue/primitives/src/display/date-picker/DatePickerField.vue
similarity index 83%
rename from vue/primitives/src/date-picker/DatePickerField.vue
rename to vue/primitives/src/display/date-picker/DatePickerField.vue
index e8f6049..010de6a 100644
--- a/vue/primitives/src/date-picker/DatePickerField.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerField.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A text input that renders the selected date and, when `editable`, lets users
@@ -18,7 +18,6 @@ export interface DatePickerFieldProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue';
-import { formatDate } from '../calendar';
 import { useDatePickerRootContext } from './context';
 
 const {
@@ -29,10 +28,11 @@ const {
 } = defineProps<DatePickerFieldProps>();
 
 const ctx = useDatePickerRootContext();
+const adapter = ctx.dateAdapter;
 
 const displayValue = computed(() => {
   if (!ctx.modelValue.value) return '';
-  return formatDate(ctx.modelValue.value, format, ctx.locale.value);
+  return adapter.value.format(ctx.modelValue.value, format, ctx.locale.value);
 });
 
 const draft = ref(displayValue.value);
@@ -47,9 +47,9 @@ function commit() {
     ctx.modelValue.value = undefined;
     return;
   }
-  const parsed = new Date(text);
-  if (!Number.isNaN(parsed.getTime()))
-    ctx.modelValue.value = new Date(parsed.getFullYear(), parsed.getMonth(), parsed.getDate());
+  const parsed = adapter.value.parse(text);
+  if (parsed)
+    ctx.modelValue.value = adapter.value.toDateOnly(parsed);
   else
     draft.value = displayValue.value;
 }
diff --git a/vue/primitives/src/display/date-picker/DatePickerFieldRoot.vue b/vue/primitives/src/display/date-picker/DatePickerFieldRoot.vue
new file mode 100644
index 0000000..1e2e415
--- /dev/null
+++ b/vue/primitives/src/display/date-picker/DatePickerFieldRoot.vue
@@ -0,0 +1,168 @@
+<script lang="ts">
+import type { SegmentContent, SegmentPart, SegmentValues } from './use-date-field';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A segmented date field: a `role="group"` of individually-focusable
+ * `role="spinbutton"` segments (`DatePickerFieldSegment`) that edit one part of
+ * the date each. It reads the picker's value, placeholder, locale, granularity,
+ * and hour cycle from `DatePickerRoot`, and commits a complete date back to the
+ * picker. This is the accessible, keyboard-driven alternative to the plain
+ * `DatePickerField` text input.
+ *
+ * The default slot receives the ordered `segments` descriptors (including
+ * literals) and the current `modelValue`, so the consumer renders a
+ * `DatePickerFieldSegment` per segment.
+ */
+export interface DatePickerFieldRootProps extends PrimitiveProps {}
+
+export interface DatePickerFieldRootSlot {
+  default?: (props: {
+    segments: SegmentContent[];
+    modelValue: Date | undefined;
+    isInvalid: boolean;
+  }) => unknown;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, markRaw, shallowRef, triggerRef, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useDatePickerRootContext } from './context';
+import { provideDatePickerFieldContext } from './field-context';
+import {
+  createSegmentContents,
+  initializeSegmentValues,
+  isSegmentValuesComplete,
+  segmentValuesToDate,
+  syncSegmentValues,
+} from './use-date-field';
+
+const { as = 'div' } = defineProps<DatePickerFieldRootProps>();
+defineSlots<DatePickerFieldRootSlot>();
+defineOptions({ inheritAttrs: false });
+
+const ctx = useDatePickerRootContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const adapter = ctx.dateAdapter;
+const granularity = ctx.granularity;
+const hourCycle = ctx.hourCycle;
+
+const segmentValues = shallowRef<SegmentValues>(
+  ctx.modelValue.value
+    ? syncSegmentValues(adapter.value, ctx.modelValue.value, granularity.value)
+    : initializeSegmentValues(granularity.value),
+);
+
+// Re-seed when the model or granularity changes from the outside.
+watch([() => ctx.modelValue.value, granularity], ([value, gran]) => {
+  if (value) {
+    segmentValues.value = syncSegmentValues(adapter.value, value, gran);
+  }
+  else if (Object.values(segmentValues.value).every(v => v !== null)) {
+    // Only reset when the field was fully populated; preserve mid-edit state.
+    segmentValues.value = initializeSegmentValues(gran);
+  }
+});
+
+const segmentContents = computed<SegmentContent[]>(() => createSegmentContents(
+  segmentValues.value,
+  ctx.placeholder.value,
+  granularity.value,
+  hourCycle.value,
+  ctx.locale.value,
+));
+
+// Ordered registry of focusable segment elements (DOM order via querySelectorAll).
+// `shallowRef` so element keys stay raw (a deep `ref` would proxy the Map and
+// its entries); mutated in place, so `triggerRef` after each change.
+const segmentMap = shallowRef<Map<HTMLElement, SegmentPart>>(new Map());
+
+function registerSegment(el: HTMLElement, part: SegmentPart): () => void {
+  const key = markRaw(el);
+  segmentMap.value.set(key, part);
+  triggerRef(segmentMap);
+  return () => {
+    segmentMap.value.delete(key);
+    triggerRef(segmentMap);
+  };
+}
+
+function orderedSegments(): HTMLElement[] {
+  const root = currentElement.value;
+  if (!root) return [];
+  return Array.from(
+    root.querySelectorAll<HTMLElement>('[data-primitives-date-picker-segment]:not([data-readonly])'),
+  );
+}
+
+function focusSegment(from: HTMLElement, direction: 1 | -1) {
+  const sign = ctx.dir.value === 'rtl' ? -direction : direction;
+  const els = orderedSegments();
+  const index = els.indexOf(from);
+  if (index < 0) return;
+  const next = els[index + sign];
+  next?.focus();
+}
+
+function focusNext(from: HTMLElement) {
+  const els = orderedSegments();
+  const index = els.indexOf(from);
+  if (index < 0) return;
+  els[index + 1]?.focus();
+}
+
+function commit() {
+  if (ctx.readonly.value || ctx.disabled.value) return;
+  if (!isSegmentValuesComplete(segmentValues.value, granularity.value)) return;
+  ctx.onDateChange(segmentValuesToDate(adapter.value, segmentValues.value, granularity.value));
+}
+
+function updateSegment(part: SegmentPart, value: number | string | null) {
+  // Replace wholesale so shallowRef triggers without deep tracking.
+  segmentValues.value = { ...segmentValues.value, [part]: value };
+}
+
+provideDatePickerFieldContext({
+  dateAdapter: adapter,
+  locale: ctx.locale,
+  dir: ctx.dir,
+  placeholder: ctx.placeholder,
+  disabled: ctx.disabled,
+  readonly: ctx.readonly,
+  isInvalid: ctx.isInvalid,
+  hourCycle,
+  granularity,
+  segmentValues,
+  segmentContents,
+  registerSegment,
+  focusSegment,
+  focusNext,
+  updateSegment,
+  commit,
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    v-bind="$attrs"
+    :as="as"
+    role="group"
+    :data-primitives-date-picker-field-root="''"
+    :aria-disabled="ctx.disabled.value ? true : undefined"
+    :aria-invalid="ctx.isInvalid.value ? true : undefined"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+    :data-readonly="ctx.readonly.value ? '' : undefined"
+    :data-invalid="ctx.isInvalid.value ? '' : undefined"
+    :dir="ctx.dir.value"
+  >
+    <slot
+      :segments="segmentContents"
+      :model-value="ctx.modelValue.value"
+      :is-invalid="ctx.isInvalid.value"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/display/date-picker/DatePickerFieldSegment.vue b/vue/primitives/src/display/date-picker/DatePickerFieldSegment.vue
new file mode 100644
index 0000000..e9594b5
--- /dev/null
+++ b/vue/primitives/src/display/date-picker/DatePickerFieldSegment.vue
@@ -0,0 +1,191 @@
+<script lang="ts">
+import type { DayPeriod, SegmentPart } from './use-date-field';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A single segment of a `DatePickerFieldRoot`. Editable parts (`day`, `month`,
+ * `year`, `hour`, `minute`, `second`, `dayPeriod`) render as a focusable
+ * `role="spinbutton"` with `aria-valuemin/max/now/valuetext`; `literal` parts
+ * render as inert separators. Supports arrow increment/decrement, numeric
+ * type-ahead with auto-advance, Backspace to clear, and `a`/`p` for AM/PM.
+ */
+export interface DatePickerFieldSegmentProps extends PrimitiveProps {
+  /** The date part this segment edits. */
+  part: SegmentPart;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useDatePickerFieldContext } from './field-context';
+import {
+  applySegmentKeydown,
+  isEditableSegmentPart,
+  resolveHourCycle,
+} from './use-date-field';
+
+const { part, as = 'div' } = defineProps<DatePickerFieldSegmentProps>();
+
+const ctx = useDatePickerFieldContext();
+const adapter = ctx.dateAdapter;
+const { forwardRef, currentElement } = useForwardExpose();
+
+const isLiteral = computed(() => part === 'literal');
+const isEditable = computed(() => isEditableSegmentPart(part));
+
+const displayValue = computed(() => {
+  // Find this part's current content. For repeated literals we just show value.
+  const match = ctx.segmentContents.value.find(s => s.part === part);
+  return match?.value ?? '';
+});
+
+const isEmpty = computed(() => {
+  if (!isEditable.value || part === 'dayPeriod') return false;
+  const v = (ctx.segmentValues.value as Record<string, unknown>)[part];
+  return v === null || v === undefined;
+});
+
+// Type-ahead state lives per segment instance.
+const typeState = { hasLeftFocus: true, lastKeyZero: false };
+
+const ariaValues = computed(() => {
+  const values = ctx.segmentValues.value;
+  switch (part) {
+    case 'day': {
+      // Use the placeholder's real year so `aria-valuemax` matches the editing
+      // cap in `applySegmentKeydown` (February differs across leap/non-leap years).
+      const year = adapter.value.getParts(ctx.placeholder.value).year;
+      const monthDays = values.month
+        ? adapter.value.getDaysInMonth(adapter.value.fromParts({ year, month: values.month, day: 1 }))
+        : 31;
+      return { min: 1, max: monthDays, now: values.day ?? undefined, label: 'day' };
+    }
+    case 'month':
+      return { min: 1, max: 12, now: values.month ?? undefined, label: 'month' };
+    case 'year':
+      return { min: 1, max: 9999, now: values.year ?? undefined, label: 'year' };
+    case 'hour': {
+      const is12 = resolveHourCycle(ctx.hourCycle.value, ctx.locale.value) === 12;
+      return {
+        min: is12 ? 1 : 0,
+        max: is12 ? 12 : 23,
+        now: values.hour ?? undefined,
+        label: 'hour',
+      };
+    }
+    case 'minute':
+      return { min: 0, max: 59, now: values.minute ?? undefined, label: 'minute' };
+    case 'second':
+      return { min: 0, max: 59, now: values.second ?? undefined, label: 'second' };
+    case 'dayPeriod':
+      return { min: 0, max: 12, now: (values.hour ?? 0) % 12, label: 'AM/PM' };
+    default:
+      return { min: undefined, max: undefined, now: undefined, label: undefined };
+  }
+});
+
+const ariaValueText = computed(() => {
+  if (isEmpty.value) return 'Empty';
+  if (part === 'dayPeriod') return ctx.segmentValues.value.dayPeriod ?? 'AM';
+  return displayValue.value;
+});
+
+let cleanup: (() => void) | undefined;
+onMounted(() => {
+  if (isEditable.value && !ctx.readonly.value && currentElement.value)
+    cleanup = ctx.registerSegment(currentElement.value, part);
+});
+onBeforeUnmount(() => cleanup?.());
+
+const disabled = computed(() => ctx.disabled.value);
+const readonly = computed(() => ctx.readonly.value);
+
+function handleKeydown(e: KeyboardEvent) {
+  if (!isEditable.value) return;
+  if (disabled.value || readonly.value) return;
+
+  if (e.key === 'ArrowLeft') {
+    e.preventDefault();
+    ctx.focusSegment(currentElement.value!, -1);
+    return;
+  }
+  if (e.key === 'ArrowRight') {
+    e.preventDefault();
+    ctx.focusSegment(currentElement.value!, 1);
+    return;
+  }
+  if (e.key === 'Tab' || e.key === 'Shift')
+    return;
+
+  e.preventDefault();
+  typeState.hasLeftFocus = false;
+
+  const result = applySegmentKeydown(e, {
+    adapter: adapter.value,
+    part: part as Exclude<SegmentPart, 'literal'>,
+    values: ctx.segmentValues.value,
+    placeholder: ctx.placeholder.value,
+    granularity: ctx.granularity.value,
+    hourCycle: ctx.hourCycle.value,
+    locale: ctx.locale.value,
+    state: typeState,
+    focusNext: () => ctx.focusNext(currentElement.value!),
+  });
+
+  if (!result) return;
+
+  ctx.updateSegment(result.part, result.value);
+  if ('dayPeriod' in result && result.dayPeriod !== undefined)
+    ctx.updateSegment('dayPeriod', result.dayPeriod as DayPeriod);
+  if ('hour' in result && typeof (result as { hour?: number }).hour === 'number')
+    ctx.updateSegment('hour', (result as { hour: number }).hour);
+
+  ctx.commit();
+}
+
+function handleFocusOut() {
+  typeState.hasLeftFocus = true;
+}
+</script>
+
+<template>
+  <Primitive
+    v-if="isLiteral"
+    :as="as"
+    aria-hidden="true"
+    :data-primitives-date-picker-segment="part"
+    data-readonly=""
+  >
+    <slot :value="displayValue">{{ displayValue }}</slot>
+  </Primitive>
+  <Primitive
+    v-else
+    :ref="forwardRef"
+    :as="as"
+    role="spinbutton"
+    :contenteditable="false"
+    :tabindex="disabled ? undefined : 0"
+    :aria-label="ariaValues.label"
+    :aria-valuemin="ariaValues.min"
+    :aria-valuemax="ariaValues.max"
+    :aria-valuenow="ariaValues.now"
+    :aria-valuetext="ariaValueText"
+    :aria-disabled="disabled ? true : undefined"
+    :aria-readonly="readonly ? true : undefined"
+    :aria-invalid="ctx.isInvalid.value ? true : undefined"
+    :data-primitives-date-picker-segment="part"
+    :data-placeholder="isEmpty ? '' : undefined"
+    :data-disabled="disabled ? '' : undefined"
+    :data-readonly="readonly ? '' : undefined"
+    :data-invalid="ctx.isInvalid.value ? '' : undefined"
+    spellcheck="false"
+    autocorrect="off"
+    inputmode="numeric"
+    @keydown="handleKeydown"
+    @focusout="handleFocusOut"
+  >
+    <slot :value="displayValue">{{ displayValue }}</slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/date-picker/DatePickerPortal.vue b/vue/primitives/src/display/date-picker/DatePickerPortal.vue
similarity index 79%
rename from vue/primitives/src/date-picker/DatePickerPortal.vue
rename to vue/primitives/src/display/date-picker/DatePickerPortal.vue
index 67b0c23..bd835e0 100644
--- a/vue/primitives/src/date-picker/DatePickerPortal.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { TeleportPrimitiveProps } from '../teleport';
+import type { TeleportPrimitiveProps } from '../../utilities/teleport';
 
 /**
  * Teleports the popover content into a different part of the DOM (the body by
@@ -11,7 +11,7 @@ export interface DatePickerPortalProps extends TeleportPrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import PortalPrimitive from '../teleport/Teleport.vue';
+import PortalPrimitive from '../../utilities/teleport/Teleport.vue';
 
 const props = defineProps<DatePickerPortalProps>();
 </script>
diff --git a/vue/primitives/src/display/date-picker/DatePickerRoot.vue b/vue/primitives/src/display/date-picker/DatePickerRoot.vue
new file mode 100644
index 0000000..e9789a0
--- /dev/null
+++ b/vue/primitives/src/display/date-picker/DatePickerRoot.vue
@@ -0,0 +1,479 @@
+<script lang="ts">
+import type { CalendarMonth, CalendarRootProps, WeekDayFormat } from '../calendar';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Granularity, HourCycle } from './use-date-field';
+
+/**
+ * A single-date picker that pairs a popover-anchored calendar with an optional
+ * trigger, field, and hidden form input. Owns the selected date, placeholder
+ * month, and open state, and provides both date-picker and calendar context to
+ * its parts. Use it when you need a compact, accessible "pick one date" control
+ * (e.g. a form field) rather than an always-visible `Calendar`.
+ */
+export interface DatePickerRootProps extends PrimitiveProps,
+  Omit<CalendarRootProps, 'as' | 'asChild'> {
+  /** Uncontrolled initial open state. */
+  defaultOpen?: boolean;
+  /** Modal popover (traps focus + blocks outside pointer). @default false */
+  modal?: boolean;
+  /** Hidden form input name for submission. */
+  name?: string;
+  /** Id forwarded to the focusable form control / first segment. */
+  id?: string;
+  /** Marks the form control as required for native constraint validation. @default false */
+  required?: boolean;
+  /** Format used to serialize the hidden input value. @default 'iso' */
+  valueFormat?: 'iso' | ((d: Date) => string);
+  /** Close popover on selection. @default true */
+  closeOnSelect?: boolean;
+  /**
+   * Keep the current value selected when the already-selected date is picked
+   * again (otherwise re-selecting clears it). @default false
+   */
+  preventDeselect?: boolean;
+  /**
+   * Smallest unit the field edits. `'day'` is date-only; `'hour'`/`'minute'`/
+   * `'second'` add time segments and preserve the time-of-day. @default 'day'
+   */
+  granularity?: Granularity;
+  /** Hour cycle for the time segments (12 or 24). Inferred from locale if omitted. */
+  hourCycle?: HourCycle;
+}
+
+export interface DatePickerRootEmits {
+  'update:modelValue': [date: Date | undefined];
+  'update:placeholder': [date: Date];
+  'update:open': [open: boolean];
+}
+</script>
+
+<script setup lang="ts">
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+import { computed, onMounted, ref, shallowRef, toRef, watch } from 'vue';
+import { provideCalendarRootContext } from '../calendar';
+import { useDateAdapter, useId } from '../../utilities/config-provider';
+import { PopperRoot } from '../../overlays/popper';
+import { Primitive } from '../../internal/primitive';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+import { provideDatePickerRootContext } from './context';
+import { hasTimeGranularity } from './use-date-field';
+
+defineOptions({ inheritAttrs: false });
+
+const {
+  as = 'div',
+  defaultOpen = false,
+  modal = false,
+  name,
+  id,
+  required = false,
+  valueFormat = 'iso',
+  closeOnSelect = true,
+  preventDeselect = false,
+  granularity: propsGranularity = 'day',
+  hourCycle: propsHourCycle,
+  defaultValue,
+  defaultPlaceholder,
+  minValue,
+  maxValue,
+  isDateUnavailable: propsIsDateUnavailable,
+  isDateDisabled: propsIsDateDisabled,
+  pagedNavigation = false,
+  weekStartsOn = 0,
+  weekdayFormat = 'short',
+  fixedWeeks = true,
+  numberOfMonths = 1,
+  disableDaysOutsideCurrentView = false,
+  disabled = false,
+  readonly = false,
+  initialFocus = false,
+  locale = 'en',
+  dir = 'ltr',
+  nextPage: propsNextPage,
+  prevPage: propsPrevPage,
+  calendarLabel = 'Calendar',
+  dateAdapter,
+} = defineProps<DatePickerRootProps>();
+
+defineEmits<DatePickerRootEmits>();
+
+const { forwardRef, currentElement: parentElement } = useForwardExpose();
+
+// Resolve the effective date backend: per-instance prop wins over the global
+// `ConfigProvider` adapter, falling back to the native `Date` adapter.
+const adapter = useDateAdapter(() => dateAdapter);
+
+const localOpen = ref<boolean>(defaultOpen);
+const open = defineModel<boolean>('open', {
+  default: undefined,
+  get: v => v ?? localOpen.value,
+  set: (v) => {
+    localOpen.value = v;
+    return v;
+  },
+});
+
+const localValue = ref<Date | undefined>(defaultValue);
+const modelValue = defineModel<Date | undefined>('modelValue', {
+  default: undefined,
+  get: v => v ?? localValue.value,
+  set: (v) => {
+    localValue.value = v;
+    return v;
+  },
+});
+
+const localPlaceholder = ref<Date>(
+  adapter.value.toDateOnly(defaultPlaceholder ?? modelValue.value ?? adapter.value.now()),
+);
+const placeholder = defineModel<Date>('placeholder', {
+  default: undefined,
+  get: v => v ?? localPlaceholder.value,
+  set: (v) => {
+    localPlaceholder.value = adapter.value.toDateOnly(v);
+    return localPlaceholder.value;
+  },
+});
+
+const triggerId = useId(undefined, 'date-picker-trigger');
+const contentId = useId(undefined, 'date-picker-content');
+const generatedFieldId = useId(undefined, 'date-picker-field');
+const fieldId = computed(() => id ?? generatedFieldId.value);
+const triggerElement = shallowRef<HTMLElement>();
+const hasCustomAnchor = ref(false);
+const focusedDate = ref<Date | undefined>();
+
+const localeRef = toRef(() => locale);
+const dirRef = toRef(() => dir);
+const modalRef = toRef(() => modal);
+const nameRef = toRef(() => name);
+const weekStartsOnRef = toRef(() => weekStartsOn);
+const weekdayFormatRef = toRef(() => weekdayFormat as WeekDayFormat);
+const fixedWeeksRef = toRef(() => fixedWeeks);
+const numberOfMonthsRef = toRef(() => numberOfMonths);
+const disabledRef = toRef(() => disabled);
+const readonlyRef = toRef(() => readonly);
+const pagedNavigationRef = toRef(() => pagedNavigation);
+const minValueRef = toRef(() => minValue);
+const maxValueRef = toRef(() => maxValue);
+const requiredRef = toRef(() => required);
+const granularityRef = computed<Granularity>(() => propsGranularity);
+const hourCycleRef = toRef(() => propsHourCycle);
+const preventDeselectRef = toRef(() => preventDeselect);
+const multipleRef = toRef(() => false);
+const disableDaysOutsideCurrentViewRef = toRef(() => disableDaysOutsideCurrentView);
+
+/** Strip time for `day` granularity; preserve full time-of-day otherwise. */
+function normalizeValue(date: Date): Date {
+  return hasTimeGranularity(propsGranularity)
+    ? adapter.value.clone(date)
+    : adapter.value.toDateOnly(date);
+}
+
+const grid = computed<CalendarMonth[]>(() => adapter.value.createMonths({
+  date: placeholder.value,
+  numberOfMonths,
+  weekStartsOn,
+}));
+
+const weekDays = computed(() => adapter.value.getWeekdayLabels(weekStartsOn, locale, weekdayFormat));
+
+const headingValue = computed(() => {
+  const months = grid.value;
+  if (!months.length) return '';
+  if (months.length === 1) return adapter.value.formatMonthYear(months[0]!.value, locale);
+  const first = adapter.value.formatMonthYear(months[0]!.value, locale);
+  const last = adapter.value.formatMonthYear(months[months.length - 1]!.value, locale);
+  return `${first} - ${last}`;
+});
+
+const fullCalendarLabel = computed(() => `${calendarLabel}, ${headingValue.value}`);
+
+function isDateDisabled(date: Date): boolean {
+  if (disabled) return true;
+  if (propsIsDateDisabled?.(date)) return true;
+  if (minValue && adapter.value.isBefore(date, minValue)) return true;
+  if (maxValue && adapter.value.isAfter(date, maxValue)) return true;
+  return false;
+}
+
+function isDateUnavailableLocal(date: Date): boolean {
+  return adapter.value.isDateUnavailable(date, propsIsDateUnavailable, minValue, maxValue);
+}
+
+function isDateSelected(date: Date): boolean {
+  return modelValue.value ? adapter.value.isSameDay(modelValue.value, date) : false;
+}
+
+const hasSelectedDate = computed(() => modelValue.value !== undefined);
+const firstFocusableDate = computed(() =>
+  adapter.value.findFirstFocusableDate(grid.value, isDateDisabled, isDateUnavailableLocal),
+);
+
+function isOutsideVisibleView(date: Date): boolean {
+  return !grid.value.some(m => adapter.value.isSameMonth(m.value, date));
+}
+
+const isInvalid = computed(() => {
+  if (!modelValue.value) return false;
+  return isDateDisabled(modelValue.value) || isDateUnavailableLocal(modelValue.value);
+});
+
+/**
+ * Unified commit path for any selection source. Honors readonly/disabled,
+ * disabled-date guards, and `preventDeselect` toggle-off. When `keepTime` is set
+ * (calendar day pick under a time granularity) the existing time-of-day is
+ * carried onto the picked day; the segmented field passes a full datetime and
+ * commits it verbatim.
+ */
+function onDateChange(date: Date | undefined, options?: { keepTime?: boolean }) {
+  if (readonly || disabled) return;
+  if (!date) {
+    modelValue.value = undefined;
+    return;
+  }
+  if (isDateDisabled(date) || isDateUnavailableLocal(date)) return;
+
+  let next = date;
+  if (options?.keepTime && hasTimeGranularity(propsGranularity) && modelValue.value) {
+    const day = adapter.value.getParts(date);
+    const time = adapter.value.getParts(modelValue.value);
+    next = adapter.value.fromParts({
+      year: day.year,
+      month: day.month,
+      day: day.day,
+      hour: time.hour,
+      minute: time.minute,
+      second: time.second,
+    });
+  }
+  else if (!hasTimeGranularity(propsGranularity)) {
+    next = normalizeValue(next);
+  }
+
+  if (!preventDeselect && modelValue.value
+    && adapter.value.compare(modelValue.value, next) === 0) {
+    modelValue.value = undefined;
+    return;
+  }
+
+  modelValue.value = next;
+  if (closeOnSelect) open.value = false;
+}
+
+function setDate(date: Date | undefined) {
+  onDateChange(date, { keepTime: true });
+}
+
+function onPlaceholderChange(date: Date) {
+  placeholder.value = date;
+}
+
+function setPlaceholder(date: Date) {
+  placeholder.value = adapter.value.clamp(date, minValue, maxValue);
+}
+
+function pageStep(): number {
+  return pagedNavigation ? numberOfMonths : 1;
+}
+function nextPage(fn?: (placeholder: Date) => Date) {
+  const fnToUse = fn ?? propsNextPage;
+  placeholder.value = fnToUse
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(placeholder.value, pageStep());
+}
+function prevPage(fn?: (placeholder: Date) => Date) {
+  const fnToUse = fn ?? propsPrevPage;
+  placeholder.value = fnToUse
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(placeholder.value, -pageStep());
+}
+function nextYear() {
+  placeholder.value = adapter.value.addYears(placeholder.value, 1);
+}
+function prevYear() {
+  placeholder.value = adapter.value.addYears(placeholder.value, -1);
+}
+
+function isNextButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
+  if (disabled) return true;
+  if (!maxValue) return false;
+  const lastMonth = grid.value[grid.value.length - 1]?.value;
+  if (!lastMonth) return false;
+  const fnToUse = fn ?? propsNextPage;
+  const probe = fnToUse
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(lastMonth, 1);
+  return adapter.value.isAfter(probe, maxValue);
+}
+function isPrevButtonDisabled(fn?: (placeholder: Date) => Date): boolean {
+  if (disabled) return true;
+  if (!minValue) return false;
+  const firstMonth = grid.value[0]?.value;
+  if (!firstMonth) return false;
+  const fnToUse = fn ?? propsPrevPage;
+  const probe = fnToUse
+    ? adapter.value.toDateOnly(fnToUse(placeholder.value))
+    : adapter.value.addMonths(firstMonth, -1);
+  return adapter.value.isBefore(probe, minValue);
+}
+
+watch(modelValue, (v) => {
+  if (v && !adapter.value.isSameMonth(v, placeholder.value))
+    placeholder.value = adapter.value.toDateOnly(v);
+});
+
+onMounted(() => {
+  if (!initialFocus || !open.value || !parentElement.value) return;
+  const target = parentElement.value.querySelector<HTMLElement>(
+    '[data-primitives-calendar-cell-trigger][data-selected]'
+    + ',[data-primitives-calendar-cell-trigger][data-today]'
+    + ',[data-primitives-calendar-cell-trigger]:not([data-outside-view]):not([data-disabled])',
+  );
+  target?.focus();
+});
+
+useEventListener(parentElement, 'focusout', (e) => {
+  if (!parentElement.value?.contains(e.relatedTarget as Node | null))
+    focusedDate.value = undefined;
+});
+
+const hiddenValue = computed(() => {
+  if (!modelValue.value) return '';
+  if (typeof valueFormat === 'function') return valueFormat(modelValue.value);
+  return adapter.value.toISO(modelValue.value).slice(0, 10);
+});
+
+const hasTime = computed(() => hasTimeGranularity(propsGranularity));
+const nativeInputType = computed(() => hasTime.value ? 'datetime-local' : 'date');
+
+/** Local (not UTC) value string for the native validation input. */
+function toNativeInputValue(d: Date | undefined): string {
+  if (!d) return '';
+  const pad = (n: number, len = 2) => String(n).padStart(len, '0');
+  const p = adapter.value.getParts(d);
+  const date = `${pad(p.year, 4)}-${pad(p.month)}-${pad(p.day)}`;
+  if (!hasTime.value) return date;
+  const time = propsGranularity === 'second'
+    ? `${pad(p.hour)}:${pad(p.minute)}:${pad(p.second)}`
+    : `${pad(p.hour)}:${pad(p.minute)}`;
+  return `${date}T${time}`;
+}
+
+const nativeValue = computed(() => toNativeInputValue(modelValue.value));
+const nativeMin = computed(() => minValue ? toNativeInputValue(minValue) : undefined);
+const nativeMax = computed(() => maxValue ? toNativeInputValue(maxValue) : undefined);
+
+function focusFirstSegment() {
+  if (disabled || readonly) return;
+  const first = parentElement.value?.querySelector<HTMLElement>('[data-primitives-date-picker-segment]:not([data-readonly])');
+  first?.focus();
+}
+
+provideDatePickerRootContext({
+  dateAdapter: adapter,
+  open,
+  modal: modalRef,
+  name: nameRef,
+  modelValue,
+  placeholder,
+  locale: localeRef,
+  dir: dirRef,
+  disabled: disabledRef,
+  readonly: readonlyRef,
+  required: requiredRef,
+  isInvalid,
+  granularity: granularityRef,
+  hourCycle: hourCycleRef,
+  minValue: minValueRef,
+  maxValue: maxValueRef,
+  triggerId,
+  contentId,
+  fieldId,
+  triggerElement,
+  hasCustomAnchor,
+  onDateChange,
+  onPlaceholderChange,
+  onOpenChange: (v) => { open.value = v; },
+  onOpenToggle: () => { open.value = !open.value; },
+});
+
+provideCalendarRootContext({
+  dateAdapter: adapter,
+  modelValue,
+  placeholder,
+  locale: localeRef,
+  dir: dirRef,
+  grid,
+  weekDays,
+  headingValue,
+  fullCalendarLabel,
+  weekStartsOn: weekStartsOnRef,
+  weekdayFormat: weekdayFormatRef,
+  fixedWeeks: fixedWeeksRef,
+  numberOfMonths: numberOfMonthsRef,
+  disabled: disabledRef,
+  readonly: readonlyRef,
+  pagedNavigation: pagedNavigationRef,
+  multiple: multipleRef,
+  preventDeselect: preventDeselectRef,
+  disableDaysOutsideCurrentView: disableDaysOutsideCurrentViewRef,
+  minValue: minValueRef,
+  maxValue: maxValueRef,
+  isDateDisabled,
+  isDateUnavailable: isDateUnavailableLocal,
+  isDateSelected,
+  isOutsideVisibleView,
+  isInvalid,
+  hasSelectedDate,
+  firstFocusableDate,
+  parentElement,
+  focusedDate,
+  setDate,
+  setPlaceholder,
+  nextPage,
+  prevPage,
+  nextYear,
+  prevYear,
+  isNextButtonDisabled,
+  isPrevButtonDisabled,
+});
+</script>
+
+<template>
+  <PopperRoot>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :data-primitives-date-picker-root="''"
+      :data-state="open ? 'open' : 'closed'"
+      :data-disabled="disabled ? '' : undefined"
+    >
+      <slot :open="open" :model-value="modelValue" />
+      <input
+        v-if="name"
+        type="hidden"
+        :name="name"
+        :value="hiddenValue"
+        :disabled="disabled"
+        aria-hidden="true"
+        tabindex="-1"
+        style="display: none"
+      >
+      <VisuallyHidden
+        v-if="required || minValue || maxValue"
+        :id="fieldId"
+        as="input"
+        feature="focusable"
+        tabindex="-1"
+        :type="nativeInputType"
+        :value="nativeValue"
+        :required="required"
+        :min="nativeMin"
+        :max="nativeMax"
+        :disabled="disabled"
+        @focus="focusFirstSegment"
+      />
+    </Primitive>
+  </PopperRoot>
+</template>
diff --git a/vue/primitives/src/date-picker/DatePickerTrigger.vue b/vue/primitives/src/display/date-picker/DatePickerTrigger.vue
similarity index 69%
rename from vue/primitives/src/date-picker/DatePickerTrigger.vue
rename to vue/primitives/src/display/date-picker/DatePickerTrigger.vue
index 711323f..f67d59c 100644
--- a/vue/primitives/src/date-picker/DatePickerTrigger.vue
+++ b/vue/primitives/src/display/date-picker/DatePickerTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button that toggles the picker popover open and closed. Acts as the
@@ -11,9 +11,9 @@ export interface DatePickerTriggerProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
-import { onMounted } from 'vue';
-import { PopperAnchor } from '../popper';
-import { Primitive } from '../primitive';
+import { computed, onMounted } from 'vue';
+import { PopperAnchor } from '../../overlays/popper';
+import { Primitive } from '../../internal/primitive';
 import { useDatePickerRootContext } from './context';
 
 const { as = 'button' } = defineProps<DatePickerTriggerProps>();
@@ -21,6 +21,13 @@ const { as = 'button' } = defineProps<DatePickerTriggerProps>();
 const ctx = useDatePickerRootContext();
 const { forwardRef, currentElement } = useForwardExpose();
 
+const disabled = computed(() => ctx.disabled.value);
+
+function onClick() {
+  if (disabled.value) return;
+  ctx.onOpenToggle();
+}
+
 onMounted(() => {
   ctx.triggerElement.value = currentElement.value;
 });
@@ -36,9 +43,12 @@ onMounted(() => {
       aria-haspopup="dialog"
       :aria-expanded="ctx.open.value"
       :aria-controls="ctx.contentId.value"
+      :disabled="as === 'button' && disabled ? true : undefined"
+      :aria-disabled="disabled ? true : undefined"
       :data-state="ctx.open.value ? 'open' : 'closed'"
+      :data-disabled="disabled ? '' : undefined"
       :data-primitives-date-picker-trigger="''"
-      @click="ctx.onOpenToggle"
+      @click="onClick"
     >
       <slot />
     </Primitive>
diff --git a/vue/primitives/src/display/date-picker/__test__/DatePicker.test.ts b/vue/primitives/src/display/date-picker/__test__/DatePicker.test.ts
new file mode 100644
index 0000000..c6e6995
--- /dev/null
+++ b/vue/primitives/src/display/date-picker/__test__/DatePicker.test.ts
@@ -0,0 +1,406 @@
+import type { SegmentContent } from '../use-date-field';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import {
+  DatePickerCalendar,
+  DatePickerCell,
+  DatePickerCellTrigger,
+  DatePickerContent,
+  DatePickerFieldRoot,
+  DatePickerFieldSegment,
+  DatePickerGrid,
+  DatePickerGridBody,
+  DatePickerGridRow,
+  DatePickerRoot,
+  DatePickerTrigger,
+} from '../index';
+
+function press(el: Element, key: string) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+}
+
+function mountField(rootProps: Record<string, unknown> = {}, options: Record<string, unknown> = {}) {
+  return mount(defineComponent({
+    setup: () => () => h(DatePickerRoot, rootProps, {
+      default: () => h(DatePickerFieldRoot, null, {
+        default: ({ segments }: { segments: SegmentContent[] }) =>
+          segments.map((seg, i) => h(DatePickerFieldSegment, { key: i, part: seg.part }, {
+            default: () => seg.value,
+          })),
+      }),
+    }),
+  }), { attachTo: document.body, ...options });
+}
+
+function segments(wrapper: ReturnType<typeof mount>, part?: string) {
+  const sel = part
+    ? `[data-primitives-date-picker-segment="${part}"]`
+    : '[role="spinbutton"]';
+  return Array.from(wrapper.element.querySelectorAll<HTMLElement>(sel));
+}
+
+describe('DatePicker field ARIA skeleton', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  it('renders a role=group with role=spinbutton segments', () => {
+    w = mountField();
+    expect(w.element.querySelector('[role="group"]')).toBeTruthy();
+    const spin = segments(w);
+    // day/month/year for default day granularity
+    expect(spin.length).toBe(3);
+    for (const s of spin) {
+      expect(s.getAttribute('role')).toBe('spinbutton');
+      expect(s.getAttribute('tabindex')).toBe('0');
+    }
+  });
+
+  it('marks empty segments with data-placeholder and aria-valuetext=Empty', () => {
+    w = mountField();
+    const day = segments(w, 'day')[0]!;
+    expect(day.getAttribute('data-placeholder')).toBe('');
+    expect(day.getAttribute('aria-valuetext')).toBe('Empty');
+    expect(day.getAttribute('aria-valuemin')).toBe('1');
+  });
+
+  it('reflects the controlled value into segment aria-valuenow', async () => {
+    w = mountField({ modelValue: new Date(2024, 2, 15) });
+    await nextTick();
+    const day = segments(w, 'day')[0]!;
+    const month = segments(w, 'month')[0]!;
+    const year = segments(w, 'year')[0]!;
+    expect(day.getAttribute('aria-valuenow')).toBe('15');
+    expect(month.getAttribute('aria-valuenow')).toBe('3');
+    expect(year.getAttribute('aria-valuenow')).toBe('2024');
+  });
+});
+
+describe('DatePicker segment keyboard editing', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  it('ArrowUp increments a segment, ArrowDown decrements', async () => {
+    w = mountField({ modelValue: new Date(2024, 2, 15) });
+    await nextTick();
+    const day = segments(w, 'day')[0]!;
+    press(day, 'ArrowUp');
+    await nextTick();
+    expect(segments(w, 'day')[0]!.getAttribute('aria-valuenow')).toBe('16');
+    press(segments(w, 'day')[0]!, 'ArrowDown');
+    press(segments(w, 'day')[0]!, 'ArrowDown');
+    await nextTick();
+    expect(segments(w, 'day')[0]!.getAttribute('aria-valuenow')).toBe('14');
+  });
+
+  it('ArrowUp on an empty segment seeds a sensible value', async () => {
+    w = mountField();
+    await nextTick();
+    const month = segments(w, 'month')[0]!;
+    press(month, 'ArrowUp');
+    await nextTick();
+    expect(segments(w, 'month')[0]!.getAttribute('aria-valuenow')).toBe('1');
+  });
+
+  it('numeric type-ahead fills a segment and auto-advances to the next', async () => {
+    w = mountField();
+    await nextTick();
+    const order = segments(w);
+    const monthSeg = segments(w, 'month')[0]!;
+    monthSeg.focus();
+    // typing 2 for month — month max 12, maxStart=1, so 2 > 1 → completes and advances
+    press(monthSeg, '2');
+    await nextTick();
+    expect(segments(w, 'month')[0]!.getAttribute('aria-valuenow')).toBe('2');
+    // focus advanced to the next focusable segment
+    expect(document.activeElement).not.toBe(monthSeg);
+    expect(order.length).toBeGreaterThan(1);
+  });
+
+  it('typing two digits builds a two-digit value before advancing', async () => {
+    w = mountField();
+    await nextTick();
+    const year = segments(w, 'year')[0]!;
+    year.focus();
+    press(year, '2');
+    press(segments(w, 'year')[0]!, '0');
+    press(segments(w, 'year')[0]!, '2');
+    press(segments(w, 'year')[0]!, '4');
+    await nextTick();
+    expect(segments(w, 'year')[0]!.getAttribute('aria-valuenow')).toBe('2024');
+  });
+
+  it('Backspace clears a digit / empties the segment', async () => {
+    w = mountField({ modelValue: new Date(2024, 2, 5) });
+    await nextTick();
+    const day = segments(w, 'day')[0]!;
+    // day=5 single digit → backspace empties it
+    press(day, 'Backspace');
+    await nextTick();
+    expect(segments(w, 'day')[0]!.getAttribute('aria-valuetext')).toBe('Empty');
+  });
+
+  it('commits a full date once all segments are filled', async () => {
+    w = mountField();
+    await nextTick();
+    const month = segments(w, 'month')[0]!;
+    const day = segments(w, 'day')[0]!;
+    const year = segments(w, 'year')[0]!;
+    // Fill in any order; commit fires when complete.
+    press(month, '5');
+    press(day, '6');
+    press(year, '2');
+    press(segments(w, 'year')[0]!, '0');
+    press(segments(w, 'year')[0]!, '2');
+    press(segments(w, 'year')[0]!, '0');
+    await nextTick();
+    const emitted = w.findComponent(DatePickerRoot).emitted('update:modelValue');
+    expect(emitted).toBeTruthy();
+    const last = emitted!.at(-1)![0] as Date;
+    expect(last.getFullYear()).toBe(2020);
+    expect(last.getMonth()).toBe(4);
+    expect(last.getDate()).toBe(6);
+  });
+});
+
+describe('DatePicker RTL-aware segment navigation', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  it('ArrowRight moves to the next segment in LTR', async () => {
+    w = mountField({ locale: 'en-US' });
+    await nextTick();
+    const order = segments(w);
+    const first = order[0]!;
+    first.focus();
+    press(first, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(order[1]);
+  });
+
+  it('ArrowRight moves to the previous segment in RTL', async () => {
+    w = mountField({ locale: 'en-US', dir: 'rtl' });
+    await nextTick();
+    const order = segments(w);
+    const second = order[1]!;
+    second.focus();
+    press(second, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(order[0]);
+  });
+});
+
+describe('DatePicker time granularity', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  it('renders hour/minute segments for granularity=minute', async () => {
+    w = mountField({ granularity: 'minute', hourCycle: 24, modelValue: new Date(2024, 0, 1, 13, 30) });
+    await nextTick();
+    expect(segments(w, 'hour').length).toBe(1);
+    expect(segments(w, 'minute').length).toBe(1);
+    expect(segments(w, 'hour')[0]!.getAttribute('aria-valuenow')).toBe('13');
+    expect(segments(w, 'minute')[0]!.getAttribute('aria-valuenow')).toBe('30');
+  });
+
+  it('renders a dayPeriod segment for a 12-hour cycle and toggles with a/p', async () => {
+    w = mountField({ granularity: 'minute', hourCycle: 12, modelValue: new Date(2024, 0, 1, 9, 0) });
+    await nextTick();
+    const period = segments(w, 'dayPeriod')[0]!;
+    expect(period).toBeTruthy();
+    expect(period.getAttribute('aria-valuetext')).toBe('AM');
+    press(period, 'p');
+    await nextTick();
+    expect(segments(w, 'dayPeriod')[0]!.getAttribute('aria-valuetext')).toBe('PM');
+    expect(segments(w, 'hour')[0]!.getAttribute('aria-valuenow')).toBe('21');
+  });
+
+  it('preserves time-of-day when picking a calendar day', async () => {
+    w = mountField({ granularity: 'minute', hourCycle: 24, modelValue: new Date(2024, 0, 10, 8, 45) });
+    await nextTick();
+    // bump the hour segment then ensure minute kept
+    const hour = segments(w, 'hour')[0]!;
+    press(hour, 'ArrowUp');
+    await nextTick();
+    const emitted = w.findComponent(DatePickerRoot).emitted('update:modelValue');
+    const last = emitted!.at(-1)![0] as Date;
+    expect(last.getHours()).toBe(9);
+    expect(last.getMinutes()).toBe(45);
+  });
+});
+
+describe('DatePicker disabled / readonly guards', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  it('disabled blocks segment mutation and marks aria-disabled', async () => {
+    w = mountField({ disabled: true, modelValue: new Date(2024, 2, 15) });
+    await nextTick();
+    const day = segments(w, 'day')[0]!;
+    expect(day.getAttribute('aria-disabled')).toBe('true');
+    press(day, 'ArrowUp');
+    await nextTick();
+    expect(segments(w, 'day')[0]!.getAttribute('aria-valuenow')).toBe('15');
+  });
+
+  it('readonly blocks segment mutation', async () => {
+    w = mountField({ readonly: true, modelValue: new Date(2024, 2, 15) });
+    await nextTick();
+    const day = segments(w, 'day')[0]!;
+    press(day, 'ArrowUp');
+    await nextTick();
+    expect(segments(w, 'day')[0]!.getAttribute('aria-valuenow')).toBe('15');
+  });
+});
+
+describe('DatePicker trigger honors disabled', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  function mountTrigger(rootProps: Record<string, unknown> = {}) {
+    return mount(defineComponent({
+      setup: () => () => h(DatePickerRoot, rootProps, {
+        default: () => [
+          h(DatePickerTrigger, null, { default: () => 'open' }),
+          h(DatePickerContent, null, { default: () => h(DatePickerCalendar) }),
+        ],
+      }),
+    }), { attachTo: document.body });
+  }
+
+  it('does not open when disabled', async () => {
+    w = mountTrigger({ disabled: true });
+    await nextTick();
+    const trigger = w.element.querySelector<HTMLElement>('[data-primitives-date-picker-trigger]')!;
+    expect(trigger.getAttribute('data-disabled')).toBe('');
+    expect((trigger as HTMLButtonElement).disabled).toBe(true);
+    trigger.click();
+    await nextTick();
+    expect(w.findComponent(DatePickerRoot).emitted('update:open')).toBeFalsy();
+  });
+
+  it('opens normally when enabled', async () => {
+    w = mountTrigger();
+    await nextTick();
+    const trigger = w.element.querySelector<HTMLElement>('[data-primitives-date-picker-trigger]')!;
+    trigger.click();
+    await nextTick();
+    const emitted = w.findComponent(DatePickerRoot).emitted('update:open');
+    expect(emitted).toBeTruthy();
+    expect(emitted!.at(-1)![0]).toBe(true);
+  });
+});
+
+describe('DatePicker preventDeselect', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  function findCell(wrapper: ReturnType<typeof mount>, date: Date): HTMLElement {
+    const iso = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+    const triggers = Array.from(
+      wrapper.element.querySelectorAll<HTMLElement>('[data-primitives-calendar-cell-trigger][data-value]'),
+    );
+    const match = triggers.find(t => t.getAttribute('data-value') === iso);
+    return match ?? triggers[0]!;
+  }
+
+  function mountWithCalendar(rootProps: Record<string, unknown> = {}) {
+    return mount(defineComponent({
+      setup: () => () => h(DatePickerRoot, rootProps, {
+        default: () => h(DatePickerCalendar, null, {
+          default: () => h(DatePickerGrid, { month: new Date(2024, 2, 1) }, {
+            default: () => h(DatePickerGridBody, null, {
+              default: () => h(DatePickerGridRow, null, {
+                default: () => h(DatePickerCell, { date: new Date(2024, 2, 15) }, {
+                  default: () => h(DatePickerCellTrigger, {
+                    day: new Date(2024, 2, 15),
+                    month: new Date(2024, 2, 1),
+                  }),
+                }),
+              }),
+            }),
+          }),
+        }),
+      }),
+    }), { attachTo: document.body });
+  }
+
+  it('re-selecting the same date clears it by default', async () => {
+    w = mountWithCalendar({ modelValue: new Date(2024, 2, 15), closeOnSelect: false });
+    await nextTick();
+    const cell = findCell(w, new Date(2024, 2, 15));
+    cell.click();
+    await nextTick();
+    const emitted = w.findComponent(DatePickerRoot).emitted('update:modelValue');
+    expect(emitted).toBeTruthy();
+    expect(emitted!.at(-1)![0]).toBeUndefined();
+  });
+
+  it('keeps the date selected when preventDeselect is set', async () => {
+    w = mountWithCalendar({
+      modelValue: new Date(2024, 2, 15),
+      preventDeselect: true,
+      closeOnSelect: false,
+    });
+    await nextTick();
+    const cell = findCell(w, new Date(2024, 2, 15));
+    cell.click();
+    await nextTick();
+    const emitted = w.findComponent(DatePickerRoot).emitted('update:modelValue');
+    if (emitted) {
+      const last = emitted.at(-1)![0] as Date | undefined;
+      expect(last).toBeInstanceOf(Date);
+    }
+  });
+});
+
+describe('DatePicker form validation input', () => {
+  let w: ReturnType<typeof mount> | undefined;
+  afterEach(() => {
+    w?.unmount();
+    w = undefined;
+  });
+
+  it('renders a focusable native input when required', async () => {
+    w = mountField({ required: true, name: 'date' });
+    await nextTick();
+    const input = w.element.querySelector<HTMLInputElement>('input[type="date"]');
+    expect(input).toBeTruthy();
+    expect(input!.required).toBe(true);
+  });
+
+  it('uses datetime-local type for time granularity with min/max', async () => {
+    w = mountField({
+      granularity: 'minute',
+      hourCycle: 24,
+      minValue: new Date(2024, 0, 1, 8, 0),
+      maxValue: new Date(2024, 11, 31, 18, 0),
+    });
+    await nextTick();
+    const input = w.element.querySelector<HTMLInputElement>('input[type="datetime-local"]');
+    expect(input).toBeTruthy();
+    expect(input!.min).toBe('2024-01-01T08:00');
+    expect(input!.max).toBe('2024-12-31T18:00');
+  });
+});
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-disabled---readonly-guards-disabled-blocks-segment-mutation-and-marks-aria-disabled-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-disabled---readonly-guards-disabled-blocks-segment-mutation-and-marks-aria-disabled-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-disabled---readonly-guards-disabled-blocks-segment-mutation-and-marks-aria-disabled-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-disabled---readonly-guards-readonly-blocks-segment-mutation-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-disabled---readonly-guards-readonly-blocks-segment-mutation-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-disabled---readonly-guards-readonly-blocks-segment-mutation-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-field-ARIA-skeleton-reflects-the-controlled-value-into-segment-aria-valuenow-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-field-ARIA-skeleton-reflects-the-controlled-value-into-segment-aria-valuenow-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-field-ARIA-skeleton-reflects-the-controlled-value-into-segment-aria-valuenow-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-preventDeselect-keeps-the-date-selected-when-preventDeselect-is-set-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-preventDeselect-keeps-the-date-selected-when-preventDeselect-is-set-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-preventDeselect-keeps-the-date-selected-when-preventDeselect-is-set-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-preventDeselect-re-selecting-the-same-date-clears-it-by-default-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-preventDeselect-re-selecting-the-same-date-clears-it-by-default-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-preventDeselect-re-selecting-the-same-date-clears-it-by-default-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-ArrowUp-increments-a-segment--ArrowDown-decrements-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-ArrowUp-increments-a-segment--ArrowDown-decrements-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-ArrowUp-increments-a-segment--ArrowDown-decrements-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-ArrowUp-on-an-empty-segment-seeds-a-sensible-value-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-ArrowUp-on-an-empty-segment-seeds-a-sensible-value-1.png
new file mode 100644
index 0000000..1bb1423
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-ArrowUp-on-an-empty-segment-seeds-a-sensible-value-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-Backspace-clears-a-digit---empties-the-segment-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-Backspace-clears-a-digit---empties-the-segment-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-Backspace-clears-a-digit---empties-the-segment-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-commits-a-full-date-once-all-segments-are-filled-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-commits-a-full-date-once-all-segments-are-filled-1.png
new file mode 100644
index 0000000..1bb1423
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-commits-a-full-date-once-all-segments-are-filled-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-numeric-type-ahead-fills-a-segment-and-auto-advances-to-the-next-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-numeric-type-ahead-fills-a-segment-and-auto-advances-to-the-next-1.png
new file mode 100644
index 0000000..45ac9e5
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-numeric-type-ahead-fills-a-segment-and-auto-advances-to-the-next-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-typing-two-digits-builds-a-two-digit-value-before-advancing-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-typing-two-digits-builds-a-two-digit-value-before-advancing-1.png
new file mode 100644
index 0000000..f14d659
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-segment-keyboard-editing-typing-two-digits-builds-a-two-digit-value-before-advancing-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-preserves-time-of-day-when-picking-a-calendar-day-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-preserves-time-of-day-when-picking-a-calendar-day-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-preserves-time-of-day-when-picking-a-calendar-day-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-renders-a-dayPeriod-segment-for-a-12-hour-cycle-and-toggles-with-a-p-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-renders-a-dayPeriod-segment-for-a-12-hour-cycle-and-toggles-with-a-p-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-renders-a-dayPeriod-segment-for-a-12-hour-cycle-and-toggles-with-a-p-1.png differ
diff --git a/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-renders-hour-minute-segments-for-granularity-minute-1.png b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-renders-hour-minute-segments-for-granularity-minute-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/date-picker/__test__/__screenshots__/DatePicker.test.ts/DatePicker-time-granularity-renders-hour-minute-segments-for-granularity-minute-1.png differ
diff --git a/vue/primitives/src/display/date-picker/context.ts b/vue/primitives/src/display/date-picker/context.ts
new file mode 100644
index 0000000..a5f1512
--- /dev/null
+++ b/vue/primitives/src/display/date-picker/context.ts
@@ -0,0 +1,38 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { DateAdapter } from '../../utilities/config-provider';
+import type { Granularity, HourCycle } from './use-date-field';
+import { useContextFactory } from '@robonen/vue';
+
+export interface DatePickerRootContext {
+  /** Resolved date backend (root `dateAdapter` prop or the global `ConfigProvider`). */
+  dateAdapter: ComputedRef<DateAdapter<Date>>;
+  open: Ref<boolean>;
+  modal: Ref<boolean>;
+  name: Ref<string | undefined>;
+  modelValue: Ref<Date | undefined>;
+  placeholder: Ref<Date>;
+  locale: Ref<string>;
+  dir: Ref<'ltr' | 'rtl'>;
+  disabled: Ref<boolean>;
+  readonly: Ref<boolean>;
+  required: Ref<boolean>;
+  isInvalid: ComputedRef<boolean>;
+  granularity: ComputedRef<Granularity>;
+  hourCycle: Ref<HourCycle>;
+  minValue: Ref<Date | undefined>;
+  maxValue: Ref<Date | undefined>;
+  triggerId: ComputedRef<string>;
+  contentId: ComputedRef<string>;
+  fieldId: ComputedRef<string>;
+  triggerElement: Ref<HTMLElement | undefined>;
+  hasCustomAnchor: Ref<boolean>;
+  /** Commit a date from any source (calendar cell or field), honoring readonly/granularity/preventDeselect. */
+  onDateChange: (date: Date | undefined) => void;
+  onPlaceholderChange: (date: Date) => void;
+  onOpenChange: (value: boolean) => void;
+  onOpenToggle: () => void;
+}
+
+const ctx = useContextFactory<DatePickerRootContext>('DatePickerRoot');
+export const provideDatePickerRootContext = ctx.provide;
+export const useDatePickerRootContext = ctx.inject;
diff --git a/vue/primitives/src/date-picker/demo.vue b/vue/primitives/src/display/date-picker/demo.vue
similarity index 69%
rename from vue/primitives/src/date-picker/demo.vue
rename to vue/primitives/src/display/date-picker/demo.vue
index d2b9e1d..5b25c9a 100644
--- a/vue/primitives/src/date-picker/demo.vue
+++ b/vue/primitives/src/display/date-picker/demo.vue
@@ -27,7 +27,7 @@ const CalendarBody = defineComponent({
           { class: 'mb-1 flex' },
           () => ctx.weekDays.value.map((weekday, i) => h(
             DatePickerHeadCell,
-            { key: weekday + i, class: 'w-9 text-center text-xs font-medium text-(--fg-subtle)' },
+            { key: weekday + i, class: 'w-9 text-center text-xs font-medium text-fg-subtle' },
             () => weekday,
           )),
         )),
@@ -43,10 +43,10 @@ const CalendarBody = defineComponent({
                 day,
                 month: month.value,
                 class: `flex size-8 items-center justify-center rounded-lg text-sm tabular-nums transition outline-none cursor-pointer
-                  focus-visible:ring-2 focus-visible:ring-(--ring)
-                  hover:bg-(--bg-inset)
-                  data-[selected]:bg-(--accent) data-[selected]:font-semibold data-[selected]:text-(--accent-fg) data-[selected]:hover:bg-(--accent-hover)
-                  data-[outside-view]:text-(--fg-subtle) data-[outside-view]:opacity-50
+                  focus-visible:ring-2 focus-visible:ring-ring
+                  hover:bg-bg-inset
+                  data-[selected]:bg-accent data-[selected]:font-semibold data-[selected]:text-accent-fg data-[selected]:hover:bg-accent-hover
+                  data-[outside-view]:text-fg-subtle data-[outside-view]:opacity-50
                   data-[disabled]:cursor-not-allowed data-[disabled]:opacity-30`,
               },
             ),
@@ -79,18 +79,18 @@ const value = ref<Date>();
 
 <template>
   <div class="flex w-full max-w-xs flex-col gap-2">
-    <span class="text-xs font-medium text-(--fg-muted)">Departure date</span>
+    <span class="text-xs font-medium text-fg-muted">Departure date</span>
 
     <DatePickerRoot v-slot="{ open }" v-model="value" :close-on-select="true">
       <div class="flex items-stretch gap-1.5">
         <DatePickerField
           :format="{ weekday: 'short', month: 'short', day: 'numeric', year: 'numeric' }"
           placeholder-text="Select a date"
-          class="min-w-0 flex-1 rounded-lg border border-(--border) bg-(--bg) px-3 py-2 text-sm text-(--fg) outline-none placeholder:text-(--fg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="min-w-0 flex-1 rounded-lg border border-border bg-bg px-3 py-2 text-sm text-fg outline-none placeholder:text-fg-subtle focus-visible:ring-2 focus-visible:ring-ring"
         />
         <DatePickerTrigger
           aria-label="Open calendar"
-          class="inline-flex size-9 shrink-0 items-center justify-center rounded-lg border border-(--border) bg-(--bg) text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer data-[state=open]:bg-(--bg-inset) data-[state=open]:text-(--fg)"
+          class="inline-flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-bg text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer data-[state=open]:bg-bg-inset data-[state=open]:text-fg"
         >
           <svg
             class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor"
@@ -104,20 +104,20 @@ const value = ref<Date>();
 
       <DatePickerContent
         :side-offset="6"
-        class="z-50 rounded-xl border border-(--border) bg-(--bg-elevated) p-3 text-(--fg) shadow-lg data-[state=closed]:opacity-0"
+        class="demo-card z-50 p-3 text-fg shadow-lg data-[state=closed]:opacity-0"
       >
         <DatePickerCalendar>
           <div class="mb-3 flex items-center justify-between gap-2">
             <DatePickerPrev
               aria-label="Previous month"
-              class="inline-flex size-8 items-center justify-center rounded-lg border border-(--border) bg-(--bg) text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
+              class="inline-flex size-8 items-center justify-center rounded-lg border border-border bg-bg text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
             >
               ‹
             </DatePickerPrev>
             <DatePickerHeading class="text-sm font-semibold tracking-tight" />
             <DatePickerNext
               aria-label="Next month"
-              class="inline-flex size-8 items-center justify-center rounded-lg border border-(--border) bg-(--bg) text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
+              class="inline-flex size-8 items-center justify-center rounded-lg border border-border bg-bg text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
             >
               ›
             </DatePickerNext>
@@ -126,16 +126,16 @@ const value = ref<Date>();
           <CalendarBody />
         </DatePickerCalendar>
 
-        <div class="mt-3 flex items-center justify-between border-t border-(--border) pt-3">
+        <div class="mt-3 flex items-center justify-between border-t border-border pt-3">
           <button
             type="button"
-            class="rounded-md px-2 py-1 text-xs font-medium text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) cursor-pointer"
+            class="rounded-md px-2 py-1 text-xs font-medium text-fg-muted transition hover:bg-bg-inset hover:text-fg cursor-pointer"
             @click="value = undefined"
           >
             Clear
           </button>
           <DatePickerClose
-            class="rounded-md bg-(--accent) px-3 py-1 text-xs font-medium text-(--accent-fg) transition hover:bg-(--accent-hover) active:scale-95 cursor-pointer"
+            class="rounded-md bg-accent px-3 py-1 text-xs font-medium text-accent-fg transition hover:bg-accent-hover active:scale-95 cursor-pointer"
           >
             Done
           </DatePickerClose>
@@ -145,10 +145,10 @@ const value = ref<Date>();
       <p v-if="false">{{ open }}</p>
     </DatePickerRoot>
 
-    <p class="text-xs text-(--fg-subtle)">
+    <p class="text-xs text-fg-subtle">
       <template v-if="value">
         Selected
-        <span class="font-medium text-(--fg-muted)">{{ value.toLocaleDateString('en', { dateStyle: 'medium' }) }}</span>
+        <span class="font-medium text-fg-muted">{{ value.toLocaleDateString('en', { dateStyle: 'medium' }) }}</span>
       </template>
       <template v-else>
         No date selected yet
diff --git a/vue/primitives/src/display/date-picker/field-context.ts b/vue/primitives/src/display/date-picker/field-context.ts
new file mode 100644
index 0000000..db5bc00
--- /dev/null
+++ b/vue/primitives/src/display/date-picker/field-context.ts
@@ -0,0 +1,34 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { DateAdapter } from '../../utilities/config-provider';
+import type { Granularity, HourCycle, SegmentContent, SegmentPart, SegmentValues } from './use-date-field';
+import { useContextFactory } from '@robonen/vue';
+
+export interface DatePickerFieldContext {
+  /** Resolved date backend, inherited from `DatePickerRoot`. */
+  dateAdapter: ComputedRef<DateAdapter<Date>>;
+  locale: Ref<string>;
+  dir: Ref<'ltr' | 'rtl'>;
+  placeholder: Ref<Date>;
+  disabled: Ref<boolean>;
+  readonly: Ref<boolean>;
+  isInvalid: Ref<boolean>;
+  hourCycle: Ref<HourCycle>;
+  granularity: ComputedRef<Granularity>;
+  /** Live per-part numeric/string values (null when empty). */
+  segmentValues: Ref<SegmentValues>;
+  /** Ordered, formatted segment descriptors (incl. literals) for rendering. */
+  segmentContents: ComputedRef<SegmentContent[]>;
+  /** Registered focusable segment elements in DOM order. */
+  registerSegment: (el: HTMLElement, part: SegmentPart) => () => void;
+  /** Move focus to the next/previous focusable segment (RTL-aware). */
+  focusSegment: (from: HTMLElement, direction: 1 | -1) => void;
+  focusNext: (from: HTMLElement) => void;
+  /** Mutate a single part value and recompute the committed model value. */
+  updateSegment: (part: SegmentPart, value: number | string | null) => void;
+  /** Commit current segment values into the picker model if complete. */
+  commit: () => void;
+}
+
+const ctx = useContextFactory<DatePickerFieldContext>('date-picker-field');
+export const provideDatePickerFieldContext = ctx.provide;
+export const useDatePickerFieldContext = ctx.inject;
diff --git a/vue/primitives/src/date-picker/index.ts b/vue/primitives/src/display/date-picker/index.ts
similarity index 78%
rename from vue/primitives/src/date-picker/index.ts
rename to vue/primitives/src/display/date-picker/index.ts
index 6e20b6c..3cbe936 100644
--- a/vue/primitives/src/date-picker/index.ts
+++ b/vue/primitives/src/display/date-picker/index.ts
@@ -8,6 +8,8 @@ export { default as DatePickerClose } from './DatePickerClose.vue';
 export { default as DatePickerCalendar } from './DatePickerCalendar.vue';
 export { default as DatePickerField } from './DatePickerField.vue';
 export { default as DatePickerInput } from './DatePickerField.vue';
+export { default as DatePickerFieldRoot } from './DatePickerFieldRoot.vue';
+export { default as DatePickerFieldSegment } from './DatePickerFieldSegment.vue';
 
 // Calendar subparts re-exported as DatePicker* aliases (share CalendarRootContext provided by DatePickerRoot).
 export { default as DatePickerHeader } from '../calendar/CalendarHeader.vue';
@@ -25,6 +27,20 @@ export { default as DatePickerCellTrigger } from '../calendar/CalendarCellTrigge
 export { provideDatePickerRootContext, useDatePickerRootContext } from './context';
 export type { DatePickerRootContext } from './context';
 
+export { provideDatePickerFieldContext, useDatePickerFieldContext } from './field-context';
+export type { DatePickerFieldContext } from './field-context';
+
+export type {
+  DateSegmentPart,
+  EditableSegmentPart,
+  Granularity,
+  HourCycle,
+  SegmentContent,
+  SegmentPart,
+  SegmentValues,
+  TimeSegmentPart,
+} from './use-date-field';
+
 export type { DatePickerRootEmits, DatePickerRootProps } from './DatePickerRoot.vue';
 export type { DatePickerTriggerProps } from './DatePickerTrigger.vue';
 export type { DatePickerAnchorProps } from './DatePickerAnchor.vue';
@@ -34,3 +50,5 @@ export type { DatePickerArrowProps } from './DatePickerArrow.vue';
 export type { DatePickerCloseProps } from './DatePickerClose.vue';
 export type { DatePickerCalendarProps } from './DatePickerCalendar.vue';
 export type { DatePickerFieldProps } from './DatePickerField.vue';
+export type { DatePickerFieldRootProps, DatePickerFieldRootSlot } from './DatePickerFieldRoot.vue';
+export type { DatePickerFieldSegmentProps } from './DatePickerFieldSegment.vue';
diff --git a/vue/primitives/src/display/date-picker/use-date-field.ts b/vue/primitives/src/display/date-picker/use-date-field.ts
new file mode 100644
index 0000000..553bc77
--- /dev/null
+++ b/vue/primitives/src/display/date-picker/use-date-field.ts
@@ -0,0 +1,510 @@
+import type { DateAdapter } from '../../utilities/config-provider';
+
+export type Granularity = 'day' | 'hour' | 'minute' | 'second';
+export type HourCycle = 12 | 24 | undefined;
+
+export type DateSegmentPart = 'day' | 'month' | 'year';
+export type TimeSegmentPart = 'hour' | 'minute' | 'second' | 'dayPeriod';
+export type EditableSegmentPart = DateSegmentPart | TimeSegmentPart;
+export type SegmentPart = EditableSegmentPart | 'literal';
+
+export type DayPeriod = 'AM' | 'PM';
+
+export interface SegmentValues {
+  day: number | null;
+  month: number | null;
+  year: number | null;
+  hour?: number | null;
+  minute?: number | null;
+  second?: number | null;
+  dayPeriod?: DayPeriod;
+}
+
+export interface SegmentContent {
+  part: SegmentPart;
+  value: string;
+}
+
+export const DATE_SEGMENT_PARTS: DateSegmentPart[] = ['day', 'month', 'year'];
+export const TIME_SEGMENT_PARTS: TimeSegmentPart[] = ['hour', 'minute', 'second', 'dayPeriod'];
+export const EDITABLE_SEGMENT_PARTS: EditableSegmentPart[] = [...DATE_SEGMENT_PARTS, ...TIME_SEGMENT_PARTS];
+
+export function isEditableSegmentPart(part: string): part is EditableSegmentPart {
+  return (EDITABLE_SEGMENT_PARTS as string[]).includes(part);
+}
+
+export function hasTimeGranularity(granularity: Granularity): boolean {
+  return granularity === 'hour' || granularity === 'minute' || granularity === 'second';
+}
+
+export function isSegmentNavigationKey(key: string): boolean {
+  return key === 'ArrowLeft' || key === 'ArrowRight';
+}
+
+export function isNumberKey(key: string): boolean {
+  return key.length === 1 && key >= '0' && key <= '9';
+}
+
+export function isAcceptableSegmentKey(key: string): boolean {
+  if (isNumberKey(key))
+    return true;
+  switch (key) {
+    case 'Enter':
+    case 'ArrowUp':
+    case 'ArrowDown':
+    case 'ArrowLeft':
+    case 'ArrowRight':
+    case 'Backspace':
+    case 'Delete':
+    case ' ':
+    case 'a':
+    case 'A':
+    case 'p':
+    case 'P':
+      return true;
+    default:
+      return false;
+  }
+}
+
+/** Empty value set for the requested granularity. */
+export function initializeSegmentValues(granularity: Granularity): SegmentValues {
+  const base: SegmentValues = { day: null, month: null, year: null };
+  if (!hasTimeGranularity(granularity))
+    return base;
+  base.hour = null;
+  base.dayPeriod = 'AM';
+  if (granularity === 'minute' || granularity === 'second')
+    base.minute = null;
+  if (granularity === 'second')
+    base.second = null;
+  return base;
+}
+
+/** Extract segment values from a concrete date for the requested granularity. */
+export function syncSegmentValues(
+  adapter: DateAdapter<Date>,
+  date: Date,
+  granularity: Granularity,
+): SegmentValues {
+  const parts = adapter.getParts(date);
+  const values: SegmentValues = {
+    day: parts.day,
+    month: parts.month,
+    year: parts.year,
+  };
+  if (hasTimeGranularity(granularity)) {
+    const h = parts.hour;
+    values.hour = h;
+    values.dayPeriod = h >= 12 ? 'PM' : 'AM';
+    if (granularity === 'minute' || granularity === 'second')
+      values.minute = parts.minute;
+    if (granularity === 'second')
+      values.second = parts.second;
+  }
+  return values;
+}
+
+/** True when every editable part for the granularity has a value. */
+export function isSegmentValuesComplete(values: SegmentValues, granularity: Granularity): boolean {
+  if (values.day === null || values.month === null || values.year === null)
+    return false;
+  if (!hasTimeGranularity(granularity))
+    return true;
+  if (values.hour === null || values.hour === undefined)
+    return false;
+  if ((granularity === 'minute' || granularity === 'second') && (values.minute === null || values.minute === undefined))
+    return false;
+  if (granularity === 'second' && (values.second === null || values.second === undefined))
+    return false;
+  return true;
+}
+
+/** Build a date from complete segment values (caller guarantees completeness). */
+export function segmentValuesToDate(
+  adapter: DateAdapter<Date>,
+  values: SegmentValues,
+  granularity: Granularity,
+): Date {
+  const year = values.year as number;
+  const month = values.month as number;
+  const day = values.day as number;
+  if (!hasTimeGranularity(granularity))
+    return adapter.fromParts({ year, month, day });
+  const hour = (values.hour as number) ?? 0;
+  const minute = (granularity === 'minute' || granularity === 'second') ? ((values.minute as number) ?? 0) : 0;
+  const second = granularity === 'second' ? ((values.second as number) ?? 0) : 0;
+  return adapter.fromParts({ year, month, day, hour, minute, second });
+}
+
+interface FormatPartOptions {
+  hourCycle: HourCycle;
+  locale: string;
+}
+
+/** Render the live string for a single segment, falling back to a placeholder. */
+export function formatSegment(
+  part: SegmentPart,
+  values: SegmentValues,
+  placeholder: Date,
+  opts: FormatPartOptions,
+): string {
+  switch (part) {
+    case 'day':
+      return values.day === null ? 'dd' : String(values.day).padStart(2, '0');
+    case 'month':
+      return values.month === null ? 'mm' : String(values.month).padStart(2, '0');
+    case 'year':
+      return values.year === null ? 'yyyy' : String(values.year).padStart(4, '0');
+    case 'hour': {
+      if (values.hour === null || values.hour === undefined)
+        return 'hh';
+      const is12 = resolveHourCycle(opts.hourCycle, opts.locale) === 12;
+      if (!is12)
+        return String(values.hour).padStart(2, '0');
+      const h = values.hour % 12 === 0 ? 12 : values.hour % 12;
+      return String(h).padStart(2, '0');
+    }
+    case 'minute':
+      return values.minute === null || values.minute === undefined ? 'mm' : String(values.minute).padStart(2, '0');
+    case 'second':
+      return values.second === null || values.second === undefined ? 'ss' : String(values.second).padStart(2, '0');
+    case 'dayPeriod':
+      return values.dayPeriod ?? 'AM';
+    default:
+      return '';
+  }
+}
+
+let cachedLocale: string | undefined;
+let cachedHourCycleIs12: boolean | undefined;
+
+/** Resolve the effective hour cycle: explicit prop wins, else infer from locale. */
+export function resolveHourCycle(hourCycle: HourCycle, locale: string): 12 | 24 {
+  if (hourCycle === 12 || hourCycle === 24)
+    return hourCycle;
+  if (cachedLocale !== locale) {
+    cachedLocale = locale;
+    try {
+      const resolved = new Intl.DateTimeFormat(locale, { hour: 'numeric' }).resolvedOptions().hourCycle;
+      cachedHourCycleIs12 = resolved === 'h11' || resolved === 'h12';
+    }
+    catch {
+      cachedHourCycleIs12 = false;
+    }
+  }
+  return cachedHourCycleIs12 ? 12 : 24;
+}
+
+/**
+ * Ordered list of segment descriptors (incl. literals) honoring locale order
+ * for the date parts and a fixed time order, mirroring native formatting.
+ */
+export function createSegmentContents(
+  values: SegmentValues,
+  placeholder: Date,
+  granularity: Granularity,
+  hourCycle: HourCycle,
+  locale: string,
+): SegmentContent[] {
+  const dateOrder = resolveDatePartOrder(locale);
+  const dateLiteral = resolveDateLiteral(locale);
+  const out: SegmentContent[] = [];
+
+  dateOrder.forEach((part, index) => {
+    if (index > 0)
+      out.push({ part: 'literal', value: dateLiteral });
+    out.push({ part, value: formatSegment(part, values, placeholder, { hourCycle, locale }) });
+  });
+
+  if (hasTimeGranularity(granularity)) {
+    out.push({ part: 'literal', value: ', ' });
+    out.push({ part: 'hour', value: formatSegment('hour', values, placeholder, { hourCycle, locale }) });
+    if (granularity === 'minute' || granularity === 'second') {
+      out.push({ part: 'literal', value: ':' });
+      out.push({ part: 'minute', value: formatSegment('minute', values, placeholder, { hourCycle, locale }) });
+    }
+    if (granularity === 'second') {
+      out.push({ part: 'literal', value: ':' });
+      out.push({ part: 'second', value: formatSegment('second', values, placeholder, { hourCycle, locale }) });
+    }
+    if (resolveHourCycle(hourCycle, locale) === 12) {
+      out.push({ part: 'literal', value: ' ' });
+      out.push({ part: 'dayPeriod', value: formatSegment('dayPeriod', values, placeholder, { hourCycle, locale }) });
+    }
+  }
+
+  return out;
+}
+
+const datePartOrderCache = new Map<string, DateSegmentPart[]>();
+
+/** Derive `[day, month, year]` order from the locale's numeric format. */
+export function resolveDatePartOrder(locale: string): DateSegmentPart[] {
+  const cached = datePartOrderCache.get(locale);
+  if (cached)
+    return cached;
+  let order: DateSegmentPart[] = ['month', 'day', 'year'];
+  try {
+    const parts = new Intl.DateTimeFormat(locale, { day: '2-digit', month: '2-digit', year: 'numeric' })
+      .formatToParts(new Date(2000, 0, 2));
+    const derived = parts
+      .map(p => p.type)
+      .filter((t): t is DateSegmentPart => t === 'day' || t === 'month' || t === 'year');
+    if (derived.length === 3)
+      order = derived;
+  }
+  catch {
+    // keep default
+  }
+  datePartOrderCache.set(locale, order);
+  return order;
+}
+
+function resolveDateLiteral(locale: string): string {
+  try {
+    const parts = new Intl.DateTimeFormat(locale, { day: '2-digit', month: '2-digit', year: 'numeric' })
+      .formatToParts(new Date(2000, 0, 2));
+    const literal = parts.find(p => p.type === 'literal');
+    if (literal && literal.value.trim().length <= 1)
+      return literal.value;
+  }
+  catch {
+    // keep default
+  }
+  return '/';
+}
+
+interface TypeAheadState {
+  hasLeftFocus: boolean;
+  lastKeyZero: boolean;
+}
+
+interface UpdateResult {
+  value: number | null;
+  moveToNext: boolean;
+}
+
+/** Numeric type-ahead for capped two-digit fields (day/month/hour/minute/second). */
+function updateCappedField(
+  max: number,
+  num: number,
+  prev: number | null,
+  state: TypeAheadState,
+  allowZeroValue: boolean,
+): UpdateResult {
+  const maxStart = Math.floor(max / 10);
+
+  if (state.hasLeftFocus) {
+    state.hasLeftFocus = false;
+    state.lastKeyZero = false;
+    prev = null;
+  }
+
+  if (prev === null || prev === undefined) {
+    if (num === 0) {
+      state.lastKeyZero = true;
+      return { value: allowZeroValue ? 0 : null, moveToNext: false };
+    }
+    const moveToNext = state.lastKeyZero || num > maxStart;
+    state.lastKeyZero = false;
+    return { value: num, moveToNext };
+  }
+
+  const digits = prev.toString().length;
+  const total = Number.parseInt(prev.toString() + num.toString(), 10);
+
+  if (digits === 2 || total > max) {
+    const moveToNext = num > maxStart || total > max;
+    return { value: num, moveToNext };
+  }
+  return { value: total, moveToNext: true };
+}
+
+function updateYear(num: number, prev: number | null, state: TypeAheadState): UpdateResult {
+  if (state.hasLeftFocus) {
+    state.hasLeftFocus = false;
+    prev = null;
+  }
+  if (prev === null || prev === undefined)
+    return { value: num === 0 ? 1 : num, moveToNext: false };
+  const str = prev.toString() + num.toString();
+  if (str.length > 4)
+    return { value: num === 0 ? 1 : num, moveToNext: false };
+  return { value: Number.parseInt(str, 10), moveToNext: str.length === 4 };
+}
+
+function cycle(value: number | null, delta: number, min: number, max: number, fallback: number): number {
+  if (value === null || value === undefined)
+    return delta > 0 ? min : fallback;
+  let next = value + delta;
+  const range = max - min + 1;
+  if (next > max)
+    next = min + ((next - min) % range);
+  if (next < min)
+    next = max - ((min - next - 1) % range);
+  return next;
+}
+
+export interface SegmentKeydownContext {
+  adapter: DateAdapter<Date>;
+  part: EditableSegmentPart;
+  values: SegmentValues;
+  placeholder: Date;
+  granularity: Granularity;
+  hourCycle: HourCycle;
+  locale: string;
+  state: TypeAheadState;
+  focusNext: () => void;
+}
+
+/**
+ * Apply a keydown to a single segment, returning the new value for that part
+ * (and, for hour edits, the synchronized day-period). Returns `null` value to
+ * clear. The caller writes the result into `segmentValues` and commits.
+ */
+export function applySegmentKeydown(
+  e: KeyboardEvent,
+  ctx: SegmentKeydownContext,
+): { part: EditableSegmentPart; value: number | string | null; dayPeriod?: DayPeriod } | undefined {
+  const { adapter, part, values, placeholder, state } = ctx;
+  const key = e.key;
+
+  if (!isAcceptableSegmentKey(key) || isSegmentNavigationKey(key))
+    return undefined;
+
+  if (key === 'Backspace' || key === 'Delete') {
+    state.hasLeftFocus = false;
+    return { part, value: deleteDigit(values[part] as number | string | null) };
+  }
+
+  if (part === 'dayPeriod')
+    return applyDayPeriod(e, values);
+
+  const isArrow = key === 'ArrowUp' || key === 'ArrowDown';
+  const delta = key === 'ArrowUp' ? 1 : -1;
+
+  switch (part) {
+    case 'day': {
+      const monthDays = values.month
+        ? adapter.getDaysInMonth(adapter.fromParts({ year: adapter.getParts(placeholder).year, month: values.month, day: 1 }))
+        : 31;
+      if (isArrow)
+        return { part, value: cycle(values.day, delta, 1, monthDays, monthDays) };
+      if (isNumberKey(key)) {
+        const r = updateCappedField(monthDays, Number.parseInt(key, 10), values.day, state, false);
+        if (r.moveToNext)
+          ctx.focusNext();
+        return { part, value: r.value };
+      }
+      return undefined;
+    }
+    case 'month': {
+      if (isArrow)
+        return { part, value: cycle(values.month, delta, 1, 12, 12) };
+      if (isNumberKey(key)) {
+        const r = updateCappedField(12, Number.parseInt(key, 10), values.month, state, false);
+        if (r.moveToNext)
+          ctx.focusNext();
+        return { part, value: r.value };
+      }
+      return undefined;
+    }
+    case 'year': {
+      if (isArrow)
+        return { part, value: values.year === null ? placeholder.getFullYear() : Math.max(1, values.year + delta) };
+      if (isNumberKey(key)) {
+        const r = updateYear(Number.parseInt(key, 10), values.year, state);
+        if (r.moveToNext)
+          ctx.focusNext();
+        return { part, value: r.value };
+      }
+      return undefined;
+    }
+    case 'hour': {
+      const is12 = resolveHourCycle(ctx.hourCycle, ctx.locale) === 12;
+      if (isArrow) {
+        const next = cycle(values.hour ?? null, delta, 0, 23, 23);
+        return { part, value: next, dayPeriod: next >= 12 ? 'PM' : 'AM' };
+      }
+      if (isNumberKey(key)) {
+        const displayMax = is12 ? 12 : 23;
+        let displayPrev = values.hour ?? null;
+        if (is12 && displayPrev !== null)
+          displayPrev = displayPrev % 12 === 0 ? 0 : (displayPrev > 12 ? displayPrev - 12 : displayPrev);
+        const r = updateCappedField(displayMax, Number.parseInt(key, 10), displayPrev, state, true);
+        let internal = r.value;
+        if (is12 && internal !== null) {
+          const period = values.dayPeriod ?? 'AM';
+          internal = internal === 12
+            ? (period === 'AM' ? 0 : 12)
+            : (period === 'PM' ? internal + 12 : internal);
+        }
+        if (r.moveToNext)
+          ctx.focusNext();
+        return { part, value: internal, dayPeriod: internal === null ? undefined : (internal >= 12 ? 'PM' : 'AM') };
+      }
+      return undefined;
+    }
+    case 'minute': {
+      if (isArrow)
+        return { part, value: cycle(values.minute ?? null, delta, 0, 59, 59) };
+      if (isNumberKey(key)) {
+        const r = updateCappedField(59, Number.parseInt(key, 10), values.minute ?? null, state, true);
+        if (r.moveToNext)
+          ctx.focusNext();
+        return { part, value: r.value };
+      }
+      return undefined;
+    }
+    case 'second': {
+      if (isArrow)
+        return { part, value: cycle(values.second ?? null, delta, 0, 59, 59) };
+      if (isNumberKey(key)) {
+        const r = updateCappedField(59, Number.parseInt(key, 10), values.second ?? null, state, true);
+        if (r.moveToNext)
+          ctx.focusNext();
+        return { part, value: r.value };
+      }
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+function applyDayPeriod(
+  e: KeyboardEvent,
+  values: SegmentValues,
+): { part: 'dayPeriod'; value: DayPeriod; hour?: number } | undefined {
+  const key = e.key;
+  const current = values.dayPeriod ?? 'AM';
+  const hour = values.hour ?? null;
+
+  const setPeriod = (period: DayPeriod): { part: 'dayPeriod'; value: DayPeriod; hour?: number } => {
+    if (hour === null)
+      return { part: 'dayPeriod', value: period };
+    if (period === 'PM' && hour < 12)
+      return { part: 'dayPeriod', value: period, hour: hour + 12 };
+    if (period === 'AM' && hour >= 12)
+      return { part: 'dayPeriod', value: period, hour: hour - 12 };
+    return { part: 'dayPeriod', value: period };
+  };
+
+  if (key === 'ArrowUp' || key === 'ArrowDown')
+    return setPeriod(current === 'AM' ? 'PM' : 'AM');
+  if (key === 'a' || key === 'A')
+    return setPeriod('AM');
+  if (key === 'p' || key === 'P')
+    return setPeriod('PM');
+  return undefined;
+}
+
+function deleteDigit(prev: number | string | null): number | null {
+  if (prev === null || prev === undefined)
+    return null;
+  const str = prev.toString();
+  if (str.length <= 1)
+    return null;
+  return Number.parseInt(str.slice(0, -1), 10);
+}
diff --git a/vue/primitives/src/progress/ProgressIndicator.vue b/vue/primitives/src/display/progress/ProgressIndicator.vue
similarity index 74%
rename from vue/primitives/src/progress/ProgressIndicator.vue
rename to vue/primitives/src/display/progress/ProgressIndicator.vue
index 1bb98ee..51b7eef 100644
--- a/vue/primitives/src/progress/ProgressIndicator.vue
+++ b/vue/primitives/src/display/progress/ProgressIndicator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The visual fill of the progress bar, rendered inside `ProgressRoot`. It reads
@@ -11,7 +11,7 @@ export interface ProgressIndicatorProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useProgressContext } from './context';
 
@@ -30,6 +30,12 @@ const ctx = useProgressContext();
     :data-value="ctx.value.value ?? undefined"
     :data-max="ctx.max.value"
   >
-    <slot :value="ctx.value.value" :max="ctx.max.value" :state="ctx.state.value" />
+    <slot
+      :value="ctx.value.value"
+      :max="ctx.max.value"
+      :state="ctx.state.value"
+      :progress="ctx.progress.value"
+      :percentage="ctx.percentage.value"
+    />
   </Primitive>
 </template>
diff --git a/vue/primitives/src/display/progress/ProgressRoot.vue b/vue/primitives/src/display/progress/ProgressRoot.vue
new file mode 100644
index 0000000..80de869
--- /dev/null
+++ b/vue/primitives/src/display/progress/ProgressRoot.vue
@@ -0,0 +1,133 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { ProgressState } from './context';
+
+/**
+ * A bar that shows the completion progress of a task, typically a horizontal
+ * fill that grows from empty to full. Use it for file uploads, multi-step form
+ * progress, loading indicators, or any operation whose progress you can measure
+ * (or, with a `null` value, signal as indeterminate).
+ *
+ * The root renders the accessible `progressbar` (wiring up `aria-valuemin`,
+ * `aria-valuemax`, `aria-valuenow`, `aria-valuetext`, and an `aria-label`
+ * accessible name) and derives the current `state` — `indeterminate`,
+ * `loading`, or `complete` — which it provides via context and exposes on the
+ * `data-state` attribute. Pair it with `ProgressIndicator` for the visual fill.
+ *
+ * Both `modelValue` and `max` are two-way (`v-model` / `v-model:max`): bad
+ * inputs (`NaN`, negatives, out-of-range, `max <= 0`) are validated, clamped,
+ * and reported in development, so the rendered ARIA is always valid.
+ */
+export interface ProgressRootProps extends PrimitiveProps {
+  /** Current value. `null` denotes an indeterminate progress bar. Two-way via `v-model`. */
+  modelValue?: number | null;
+  /** Maximum value. Two-way via `v-model:max`. @default 100 */
+  max?: number;
+  /**
+   * Builds the `aria-valuetext` describing the current value in a human-readable
+   * form. Receives the resolved value (`null` when indeterminate) and max.
+   * @default `(v, m) => v == null ? undefined : `${Math.round((v / m) * 100)}%``
+   */
+  getValueLabel?: (value: number | null, max: number) => string | undefined;
+  /**
+   * Accessible name for the progressbar, rendered as `aria-label`. Accepts a
+   * static string or a function of the resolved value and max. Provide this (or
+   * an external `aria-labelledby`) so screen readers announce a meaningful name.
+   */
+  accessibleLabel?: string | ((value: number | null, max: number) => string | undefined);
+}
+
+export interface ProgressRootEmits {
+  /** Emitted when the value changes (after validation/clamping). */
+  'update:modelValue': [value: number | null];
+  /** Emitted when the max changes (after validation). */
+  'update:max': [value: number];
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed, ref } from 'vue';
+import { provideProgressContext } from './context';
+import { isFiniteNumber, resolveMax, resolveValue } from './utils';
+import { useForwardExpose } from '@robonen/vue';
+
+const {
+  max: maxProp,
+  getValueLabel = (v: number | null, m: number) => v === null ? undefined : `${Math.round((v / m) * 100)}%`,
+  accessibleLabel,
+  as = 'div',
+} = defineProps<ProgressRootProps>();
+
+defineEmits<ProgressRootEmits>();
+
+const { forwardRef } = useForwardExpose();
+
+const localValue = ref<number | null>(null);
+const localMax = ref<number>(resolveMax(maxProp));
+
+const max = defineModel<number>('max', {
+  get: external => resolveMax(external ?? localMax.value),
+  set: (value) => {
+    const next = resolveMax(value);
+    localMax.value = next;
+    return next;
+  },
+});
+
+const value = defineModel<number | null>({
+  get: external => resolveValue(external === undefined ? localValue.value : external, max.value),
+  set: (raw) => {
+    const next = resolveValue(raw, max.value);
+    localValue.value = next;
+    return next;
+  },
+});
+
+const state = computed<ProgressState>(() => {
+  const v = value.value;
+  if (v === null) return 'indeterminate';
+  if (v >= max.value) return 'complete';
+  return 'loading';
+});
+
+const progress = computed<number | null>(() => value.value === null ? null : value.value / max.value);
+const percentage = computed<number | null>(() => progress.value === null ? null : Math.round(progress.value * 100));
+
+const valueText = computed(() => getValueLabel(value.value, max.value));
+const ariaLabel = computed(() => typeof accessibleLabel === 'function'
+  ? accessibleLabel(value.value, max.value)
+  : accessibleLabel);
+
+provideProgressContext({
+  value,
+  max,
+  state,
+  progress,
+  percentage,
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="progressbar"
+    :aria-valuemin="0"
+    :aria-valuemax="max"
+    :aria-valuenow="isFiniteNumber(value) ? value : undefined"
+    :aria-valuetext="valueText"
+    :aria-label="ariaLabel"
+    :data-state="state"
+    :data-value="value ?? undefined"
+    :data-max="max"
+  >
+    <slot
+      :value="value"
+      :max="max"
+      :state="state"
+      :progress="progress"
+      :percentage="percentage"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/display/progress/__test__/Progress.test.ts b/vue/primitives/src/display/progress/__test__/Progress.test.ts
new file mode 100644
index 0000000..f13821a
--- /dev/null
+++ b/vue/primitives/src/display/progress/__test__/Progress.test.ts
@@ -0,0 +1,277 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { ProgressIndicator, ProgressRoot } from '../index';
+
+function mountProgress(props: Record<string, unknown> = {}, slot?: (scope: Record<string, unknown>) => unknown) {
+  return mount(defineComponent({
+    setup: () => () => h(ProgressRoot, props, {
+      default: (scope: Record<string, unknown>) =>
+        slot ? slot(scope) : h(ProgressIndicator, { class: 'ind' }),
+    }),
+  }), { attachTo: document.body });
+}
+
+describe('Progress', () => {
+  it('has role="progressbar" with aria attributes', () => {
+    const wrapper = mountProgress({ modelValue: 40 });
+    expect(wrapper.attributes('role')).toBe('progressbar');
+    expect(wrapper.attributes('aria-valuemin')).toBe('0');
+    expect(wrapper.attributes('aria-valuemax')).toBe('100');
+    expect(wrapper.attributes('aria-valuenow')).toBe('40');
+    expect(wrapper.attributes('aria-valuetext')).toBe('40%');
+    wrapper.unmount();
+  });
+
+  it('is indeterminate when value is null', () => {
+    const wrapper = mountProgress({ modelValue: null });
+    expect(wrapper.attributes('data-state')).toBe('indeterminate');
+    expect(wrapper.attributes('aria-valuenow')).toBeUndefined();
+    wrapper.unmount();
+  });
+
+  it('is complete when value reaches max', () => {
+    const wrapper = mountProgress({ modelValue: 100 });
+    expect(wrapper.attributes('data-state')).toBe('complete');
+    wrapper.unmount();
+  });
+
+  it('custom max', () => {
+    const wrapper = mountProgress({ modelValue: 5, max: 10 });
+    expect(wrapper.attributes('aria-valuemax')).toBe('10');
+    expect(wrapper.attributes('aria-valuetext')).toBe('50%');
+    wrapper.unmount();
+  });
+
+  it('indicator receives matching data-state', () => {
+    const wrapper = mountProgress({ modelValue: 70 });
+    const ind = wrapper.find('.ind');
+    expect(ind.attributes('data-state')).toBe('loading');
+    expect(ind.attributes('data-value')).toBe('70');
+    wrapper.unmount();
+  });
+
+  it('getValueLabel override', () => {
+    const wrapper = mountProgress({ modelValue: 3, max: 10, getValueLabel: (v: number | null, m: number) => `${v} of ${m}` });
+    expect(wrapper.attributes('aria-valuetext')).toBe('3 of 10');
+    wrapper.unmount();
+  });
+
+  // ---- accessible name (aria-label) ----
+  describe('accessible name', () => {
+    it('renders no aria-label by default', () => {
+      const wrapper = mountProgress({ modelValue: 40 });
+      expect(wrapper.attributes('aria-label')).toBeUndefined();
+      wrapper.unmount();
+    });
+
+    it('accepts a static string accessibleLabel as aria-label', () => {
+      const wrapper = mountProgress({ modelValue: 40, accessibleLabel: 'Upload progress' });
+      expect(wrapper.attributes('aria-label')).toBe('Upload progress');
+      // value text is independent
+      expect(wrapper.attributes('aria-valuetext')).toBe('40%');
+      wrapper.unmount();
+    });
+
+    it('accepts a function accessibleLabel that receives value/max', () => {
+      const wrapper = mountProgress({
+        modelValue: 30,
+        max: 60,
+        accessibleLabel: (v: number | null, m: number) => `${v}/${m} done`,
+      });
+      expect(wrapper.attributes('aria-label')).toBe('30/60 done');
+      wrapper.unmount();
+    });
+  });
+
+  // ---- input validation / clamping ----
+  describe('input validation', () => {
+    let errorSpy: ReturnType<typeof vi.spyOn>;
+    beforeEach(() => {
+      errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+    afterEach(() => {
+      errorSpy.mockRestore();
+    });
+
+    it('clamps a value above max', () => {
+      const wrapper = mountProgress({ modelValue: 150, max: 100 });
+      expect(wrapper.attributes('aria-valuenow')).toBe('100');
+      expect(wrapper.attributes('data-state')).toBe('complete');
+      wrapper.unmount();
+    });
+
+    it('clamps a negative value to 0', () => {
+      const wrapper = mountProgress({ modelValue: -20 });
+      expect(wrapper.attributes('aria-valuenow')).toBe('0');
+      wrapper.unmount();
+    });
+
+    it('coerces NaN value to indeterminate and warns', () => {
+      const wrapper = mountProgress({ modelValue: Number.NaN });
+      expect(wrapper.attributes('aria-valuenow')).toBeUndefined();
+      expect(wrapper.attributes('data-state')).toBe('indeterminate');
+      expect(errorSpy).toHaveBeenCalled();
+      wrapper.unmount();
+    });
+
+    it('falls back to default max when max <= 0 and warns', () => {
+      const wrapper = mountProgress({ modelValue: 50, max: 0 });
+      expect(wrapper.attributes('aria-valuemax')).toBe('100');
+      // value text uses the corrected max — no Infinity%
+      expect(wrapper.attributes('aria-valuetext')).toBe('50%');
+      expect(errorSpy).toHaveBeenCalled();
+      wrapper.unmount();
+    });
+
+    it('falls back to default max when max is NaN', () => {
+      const wrapper = mountProgress({ modelValue: 50, max: Number.NaN });
+      expect(wrapper.attributes('aria-valuemax')).toBe('100');
+      wrapper.unmount();
+    });
+
+    it('does not render NaN aria-valuenow for non-finite input', () => {
+      const wrapper = mountProgress({ modelValue: Number.POSITIVE_INFINITY });
+      expect(wrapper.attributes('aria-valuenow')).toBeUndefined();
+      wrapper.unmount();
+    });
+  });
+
+  // ---- controlled two-way v-model ----
+  describe('controlled v-model', () => {
+    it('updates DOM when bound value changes', async () => {
+      const value = ref<number | null>(20);
+      const wrapper = mount(defineComponent({
+        setup: () => () => h(ProgressRoot, {
+          modelValue: value.value,
+          'onUpdate:modelValue': (v: number | null) => { value.value = v; },
+        }, { default: () => h(ProgressIndicator, { class: 'ind' }) }),
+      }), { attachTo: document.body });
+      expect(wrapper.attributes('aria-valuenow')).toBe('20');
+      value.value = 80;
+      await nextTick();
+      expect(wrapper.attributes('aria-valuenow')).toBe('80');
+      wrapper.unmount();
+    });
+
+    it('clamps an out-of-range bound value on read without mutating the parent', async () => {
+      // One-way bind (no update listener): the bar displays a clamped value but
+      // never writes back to a source the parent did not opt into mutating.
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const wrapper = mountProgress({ modelValue: 250, max: 100 });
+      expect(wrapper.attributes('aria-valuenow')).toBe('100');
+      expect(wrapper.attributes('data-state')).toBe('complete');
+      errorSpy.mockRestore();
+      wrapper.unmount();
+    });
+
+    it('declares the update:modelValue emit so v-model is a true two-way contract', async () => {
+      const value = ref<number | null>(40);
+      const wrapper = mount(defineComponent({
+        setup: () => () => h(ProgressRoot, {
+          modelValue: value.value,
+          'onUpdate:modelValue': (v: number | null) => { value.value = v; },
+        }, { default: () => h(ProgressIndicator) }),
+      }), { attachTo: document.body });
+      expect(wrapper.attributes('aria-valuenow')).toBe('40');
+      // parent remains the source of truth and drives the bar
+      value.value = 90;
+      await nextTick();
+      expect(wrapper.attributes('aria-valuenow')).toBe('90');
+      wrapper.unmount();
+    });
+  });
+
+  // ---- uncontrolled mode ----
+  describe('uncontrolled mode', () => {
+    it('starts indeterminate when no modelValue is provided', () => {
+      const wrapper = mount(ProgressRoot, {
+        attachTo: document.body,
+        slots: { default: () => h(ProgressIndicator) },
+      });
+      expect(wrapper.attributes('data-state')).toBe('indeterminate');
+      expect(wrapper.attributes('aria-valuenow')).toBeUndefined();
+      wrapper.unmount();
+    });
+  });
+
+  // ---- two-way max ----
+  describe('two-way max', () => {
+    it('reacts to bound max changes', async () => {
+      const max = ref(100);
+      const wrapper = mount(defineComponent({
+        setup: () => () => h(ProgressRoot, {
+          modelValue: 50,
+          max: max.value,
+          'onUpdate:max': (m: number) => { max.value = m; },
+        }, { default: () => h(ProgressIndicator) }),
+      }), { attachTo: document.body });
+      expect(wrapper.attributes('aria-valuetext')).toBe('50%');
+      max.value = 200;
+      await nextTick();
+      expect(wrapper.attributes('aria-valuemax')).toBe('200');
+      expect(wrapper.attributes('aria-valuetext')).toBe('25%');
+      wrapper.unmount();
+    });
+  });
+
+  // ---- slot scope ----
+  describe('slot scope', () => {
+    it('exposes progress and percentage on the root slot', () => {
+      const seen: Record<string, unknown> = {};
+      const wrapper = mountProgress({ modelValue: 25, max: 50 }, (scope) => {
+        Object.assign(seen, scope);
+        return h('span');
+      });
+      expect(seen.value).toBe(25);
+      expect(seen.max).toBe(50);
+      expect(seen.state).toBe('loading');
+      expect(seen.progress).toBe(0.5);
+      expect(seen.percentage).toBe(50);
+      wrapper.unmount();
+    });
+
+    it('exposes progress/percentage as null when indeterminate', () => {
+      const seen: Record<string, unknown> = {};
+      const wrapper = mountProgress({ modelValue: null }, (scope) => {
+        Object.assign(seen, scope);
+        return h('span');
+      });
+      expect(seen.progress).toBeNull();
+      expect(seen.percentage).toBeNull();
+      wrapper.unmount();
+    });
+
+    it('exposes progress/percentage on the indicator slot', () => {
+      const indSeen: Record<string, unknown> = {};
+      const wrapper = mount(defineComponent({
+        setup: () => () => h(ProgressRoot, { modelValue: 30, max: 60 }, {
+          default: () => h(ProgressIndicator, null, {
+            default: (scope: Record<string, unknown>) => {
+              Object.assign(indSeen, scope);
+              return h('span');
+            },
+          }),
+        }),
+      }), { attachTo: document.body });
+      expect(indSeen.progress).toBe(0.5);
+      expect(indSeen.percentage).toBe(50);
+      wrapper.unmount();
+    });
+  });
+
+  // ---- overshoot complete (robonen's preserved strength) ----
+  it('keeps complete state when value overshoots after clamp', () => {
+    const wrapper = mountProgress({ modelValue: 105, max: 100 });
+    // clamped to 100 -> still complete
+    expect(wrapper.attributes('data-state')).toBe('complete');
+    wrapper.unmount();
+  });
+
+  it('renders data-value/data-max on the root', () => {
+    const wrapper = mountProgress({ modelValue: 42, max: 84 });
+    expect(wrapper.attributes('data-value')).toBe('42');
+    expect(wrapper.attributes('data-max')).toBe('84');
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/display/progress/context.ts b/vue/primitives/src/display/progress/context.ts
new file mode 100644
index 0000000..6432312
--- /dev/null
+++ b/vue/primitives/src/display/progress/context.ts
@@ -0,0 +1,22 @@
+import type { ComputedRef, Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+export type ProgressState = 'indeterminate' | 'loading' | 'complete';
+
+export interface ProgressContext {
+  /** Resolved (validated/clamped) value; `null` when indeterminate. */
+  value: Ref<number | null>;
+  /** Resolved (validated) maximum. */
+  max: Ref<number>;
+  /** Derived progress state. */
+  state: Ref<ProgressState>;
+  /** Completion ratio in `[0, 1]`, or `null` when indeterminate. */
+  progress: ComputedRef<number | null>;
+  /** Completion percentage in `[0, 100]`, or `null` when indeterminate. */
+  percentage: ComputedRef<number | null>;
+}
+
+const ctx = useContextFactory<ProgressContext>('ProgressContext');
+
+export const provideProgressContext = ctx.provide;
+export const useProgressContext = ctx.inject;
diff --git a/vue/primitives/src/progress/demo.vue b/vue/primitives/src/display/progress/demo.vue
similarity index 74%
rename from vue/primitives/src/progress/demo.vue
rename to vue/primitives/src/display/progress/demo.vue
index 6886727..8f73a7a 100644
--- a/vue/primitives/src/progress/demo.vue
+++ b/vue/primitives/src/display/progress/demo.vue
@@ -26,31 +26,31 @@ onBeforeUnmount(stop);
 </script>
 
 <template>
-  <div class="w-full max-w-sm space-y-6 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 text-(--fg)">
+  <div class="demo-card w-full max-w-sm space-y-6 p-5 text-fg">
     <!-- Determinate: a simulated upload -->
     <div class="space-y-2">
       <div class="flex items-baseline justify-between text-sm">
         <span class="font-medium">Uploading build.zip</span>
-        <span class="font-mono text-(--fg-muted)">{{ value }}%</span>
+        <span class="font-mono text-fg-muted">{{ value }}%</span>
       </div>
 
       <ProgressRoot
         v-slot="{ state }"
         :model-value="value"
-        class="h-2 w-full overflow-hidden rounded-full bg-(--bg-inset)"
+        class="h-2 w-full overflow-hidden rounded-full bg-bg-inset"
       >
         <ProgressIndicator
           class="h-full rounded-full transition-transform duration-500 ease-out"
           :class="state === 'complete'
             ? 'bg-emerald-500 dark:bg-emerald-400'
-            : 'bg-(--accent)'"
+            : 'bg-accent'"
           :style="{ transform: `translateX(-${100 - value}%)` }"
         />
       </ProgressRoot>
 
       <button
         type="button"
-        class="rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm text-(--fg) transition hover:bg-(--bg-inset) active:scale-95 cursor-pointer"
+        class="rounded-md border border-border bg-bg px-3 py-1.5 text-sm text-fg transition hover:bg-bg-inset active:scale-95 cursor-pointer"
         @click="start"
       >
         {{ value === 0 ? 'Start upload' : 'Restart' }}
@@ -63,9 +63,9 @@ onBeforeUnmount(stop);
 
       <ProgressRoot
         :model-value="null"
-        class="h-2 w-full overflow-hidden rounded-full bg-(--bg-inset)"
+        class="h-2 w-full overflow-hidden rounded-full bg-bg-inset"
       >
-        <ProgressIndicator class="h-full w-2/5 animate-pulse rounded-full bg-(--accent)" />
+        <ProgressIndicator class="h-full w-2/5 animate-pulse rounded-full bg-accent" />
       </ProgressRoot>
     </div>
   </div>
diff --git a/vue/primitives/src/progress/index.ts b/vue/primitives/src/display/progress/index.ts
similarity index 81%
rename from vue/primitives/src/progress/index.ts
rename to vue/primitives/src/display/progress/index.ts
index fbd2217..4ae7d27 100644
--- a/vue/primitives/src/progress/index.ts
+++ b/vue/primitives/src/display/progress/index.ts
@@ -1,6 +1,6 @@
 export { default as ProgressRoot } from './ProgressRoot.vue';
 export { default as ProgressIndicator } from './ProgressIndicator.vue';
-export type { ProgressRootProps } from './ProgressRoot.vue';
+export type { ProgressRootProps, ProgressRootEmits } from './ProgressRoot.vue';
 export type { ProgressIndicatorProps } from './ProgressIndicator.vue';
 export { provideProgressContext, useProgressContext } from './context';
 export type { ProgressState, ProgressContext } from './context';
diff --git a/vue/primitives/src/display/progress/utils.ts b/vue/primitives/src/display/progress/utils.ts
new file mode 100644
index 0000000..5bf129c
--- /dev/null
+++ b/vue/primitives/src/display/progress/utils.ts
@@ -0,0 +1,54 @@
+import { isNull, isNumber, isUndefined } from '@robonen/stdlib';
+
+/** Fallback maximum used when `max` is omitted or invalid. */
+export const DEFAULT_MAX = 100;
+
+/** `null`/`undefined` mark an indeterminate progress bar. */
+export function isNullish(value: unknown): value is null | undefined {
+  return isNull(value) || isUndefined(value);
+}
+
+/** A real, finite numeric value (filters `NaN`/`Infinity`). */
+export function isFiniteNumber(value: unknown): value is number {
+  return isNumber(value) && Number.isFinite(value);
+}
+
+const VALUE_MESSAGE = (value: unknown, max: number): string =>
+  `Invalid \`modelValue\` of \`${String(value)}\` supplied to ProgressRoot. `
+  + `The value must be a finite number between 0 and \`max\` (${max}), `
+  + 'or `null`/`undefined` for an indeterminate bar. Defaulting to `null`.';
+
+const MAX_MESSAGE = (max: unknown): string =>
+  `Invalid \`max\` of \`${String(max)}\` supplied to ProgressRoot. `
+  + `Only finite numbers greater than 0 are valid. Defaulting to \`${DEFAULT_MAX}\`.`;
+
+/**
+ * Resolve a usable `max`: a finite number greater than `0`, otherwise the
+ * default. Warns once in dev when an invalid value is supplied. Compiled out of
+ * production via the `__DEV__` global.
+ */
+export function resolveMax(max: number | undefined): number {
+  if (isUndefined(max)) return DEFAULT_MAX;
+  if (isFiniteNumber(max) && max > 0) return max;
+
+  if (__DEV__) console.error(MAX_MESSAGE(max));
+  return DEFAULT_MAX;
+}
+
+/**
+ * Resolve a usable value against an already-resolved `max`: pass through
+ * nullish (indeterminate) values, clamp finite numbers into `[0, max]`, and
+ * coerce anything else (`NaN`, non-numbers) to `null`. Warns once in dev when
+ * coercing an unusable value. Compiled out of production via `__DEV__`.
+ */
+export function resolveValue(value: number | null | undefined, max: number): number | null {
+  if (isNullish(value)) return null;
+  if (isFiniteNumber(value)) {
+    if (value < 0) return 0;
+    if (value > max) return max;
+    return value;
+  }
+
+  if (__DEV__) console.error(VALUE_MESSAGE(value, max));
+  return null;
+}
diff --git a/vue/primitives/src/qr-code/QrCodeBackground.vue b/vue/primitives/src/display/qr-code/QrCodeBackground.vue
similarity index 91%
rename from vue/primitives/src/qr-code/QrCodeBackground.vue
rename to vue/primitives/src/display/qr-code/QrCodeBackground.vue
index b3b8156..42f6e9c 100644
--- a/vue/primitives/src/qr-code/QrCodeBackground.vue
+++ b/vue/primitives/src/display/qr-code/QrCodeBackground.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A rectangle covering the entire code, quiet zone included. Use it for a solid
@@ -17,7 +17,7 @@ export interface QrCodeBackgroundProps extends PrimitiveProps {
 <script setup lang="ts">
 import { computed } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useQrCodeContext } from './context';
 
 const { as = 'rect', fill = 'none', radius = 0 } = defineProps<QrCodeBackgroundProps>();
diff --git a/vue/primitives/src/qr-code/QrCodeCells.vue b/vue/primitives/src/display/qr-code/QrCodeCells.vue
similarity index 94%
rename from vue/primitives/src/qr-code/QrCodeCells.vue
rename to vue/primitives/src/display/qr-code/QrCodeCells.vue
index 18f8dde..c5f48d6 100644
--- a/vue/primitives/src/qr-code/QrCodeCells.vue
+++ b/vue/primitives/src/display/qr-code/QrCodeCells.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { QrCellPattern } from './utils';
 
 /**
@@ -27,7 +27,7 @@ export interface QrCodeCellsProps extends PrimitiveProps {
 <script setup lang="ts">
 import { computed, useSlots } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useQrCodeContext } from './context';
 import { cellList, cellsPath } from './utils';
 
diff --git a/vue/primitives/src/qr-code/QrCodeLogo.vue b/vue/primitives/src/display/qr-code/QrCodeLogo.vue
similarity index 95%
rename from vue/primitives/src/qr-code/QrCodeLogo.vue
rename to vue/primitives/src/display/qr-code/QrCodeLogo.vue
index 5e8fc39..6d55ee6 100644
--- a/vue/primitives/src/qr-code/QrCodeLogo.vue
+++ b/vue/primitives/src/display/qr-code/QrCodeLogo.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Overlays a logo at the center of the code (or anywhere via `x`/`y`). Pass an
@@ -29,7 +29,7 @@ export interface QrCodeLogoProps extends PrimitiveProps {
 <script setup lang="ts">
 import { computed, onScopeDispose, watchEffect } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useQrCodeContext } from './context';
 
 const {
diff --git a/vue/primitives/src/qr-code/QrCodeMarker.vue b/vue/primitives/src/display/qr-code/QrCodeMarker.vue
similarity index 95%
rename from vue/primitives/src/qr-code/QrCodeMarker.vue
rename to vue/primitives/src/display/qr-code/QrCodeMarker.vue
index 91926f2..2bbc321 100644
--- a/vue/primitives/src/qr-code/QrCodeMarker.vue
+++ b/vue/primitives/src/display/qr-code/QrCodeMarker.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { MarkerCorner, QrMarkerBall, QrMarkerFrame } from './utils';
 
 /**
@@ -27,7 +27,7 @@ export interface QrCodeMarkerProps extends PrimitiveProps {
 <script setup lang="ts">
 import { computed } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useQrCodeContext } from './context';
 import { markerBallPath, markerFramePath } from './utils';
 
diff --git a/vue/primitives/src/qr-code/QrCodeMarkers.vue b/vue/primitives/src/display/qr-code/QrCodeMarkers.vue
similarity index 94%
rename from vue/primitives/src/qr-code/QrCodeMarkers.vue
rename to vue/primitives/src/display/qr-code/QrCodeMarkers.vue
index ac2764b..75e9d22 100644
--- a/vue/primitives/src/qr-code/QrCodeMarkers.vue
+++ b/vue/primitives/src/display/qr-code/QrCodeMarkers.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { QrMarkerBall, QrMarkerFrame } from './utils';
 
 /**
@@ -21,7 +21,7 @@ export interface QrCodeMarkersProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import QrCodeMarker from './QrCodeMarker.vue';
 import { useQrCodeContext } from './context';
 
diff --git a/vue/primitives/src/qr-code/QrCodeRoot.vue b/vue/primitives/src/display/qr-code/QrCodeRoot.vue
similarity index 97%
rename from vue/primitives/src/qr-code/QrCodeRoot.vue
rename to vue/primitives/src/display/qr-code/QrCodeRoot.vue
index 8e21d5b..44e1b61 100644
--- a/vue/primitives/src/qr-code/QrCodeRoot.vue
+++ b/vue/primitives/src/display/qr-code/QrCodeRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { QrCodeErrorCorrection, QrCodeMargin } from './context';
 
 /**
@@ -43,7 +43,7 @@ export interface QrCodeRootProps extends PrimitiveProps {
 import { computed, reactive } from 'vue';
 import { EccMap, QrCodeDataType, encodeSegments, makeSegments } from '@robonen/encoding';
 import { useForwardExpose, useId } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { provideQrCodeContext } from './context';
 import type { QrCodeRegion } from './utils';
 import { markerPlacements } from './utils';
diff --git a/vue/primitives/src/qr-code/__test__/QrCode.test.ts b/vue/primitives/src/display/qr-code/__test__/QrCode.test.ts
similarity index 100%
rename from vue/primitives/src/qr-code/__test__/QrCode.test.ts
rename to vue/primitives/src/display/qr-code/__test__/QrCode.test.ts
diff --git a/vue/primitives/src/qr-code/__test__/__screenshots__/QrCode.test.ts/QrCodeLogo-renders-an--image--for-src-and-knocks-out-the-modules-behind-it-1.png b/vue/primitives/src/display/qr-code/__test__/__screenshots__/QrCode.test.ts/QrCodeLogo-renders-an--image--for-src-and-knocks-out-the-modules-behind-it-1.png
similarity index 100%
rename from vue/primitives/src/qr-code/__test__/__screenshots__/QrCode.test.ts/QrCodeLogo-renders-an--image--for-src-and-knocks-out-the-modules-behind-it-1.png
rename to vue/primitives/src/display/qr-code/__test__/__screenshots__/QrCode.test.ts/QrCodeLogo-renders-an--image--for-src-and-knocks-out-the-modules-behind-it-1.png
diff --git a/vue/primitives/src/qr-code/context.ts b/vue/primitives/src/display/qr-code/context.ts
similarity index 100%
rename from vue/primitives/src/qr-code/context.ts
rename to vue/primitives/src/display/qr-code/context.ts
diff --git a/vue/primitives/src/qr-code/demo.vue b/vue/primitives/src/display/qr-code/demo.vue
similarity index 81%
rename from vue/primitives/src/qr-code/demo.vue
rename to vue/primitives/src/display/qr-code/demo.vue
index b5e44f8..40d2f26 100644
--- a/vue/primitives/src/qr-code/demo.vue
+++ b/vue/primitives/src/display/qr-code/demo.vue
@@ -22,26 +22,26 @@ const balls: QrMarkerBall[] = ['square', 'rounded', 'circle', 'diamond'];
 </script>
 
 <template>
-  <div class="flex flex-col gap-6 text-(--fg)">
+  <div class="flex flex-col gap-6 text-fg">
     <!-- Interactive playground -->
-    <div class="flex flex-col items-center gap-5 rounded-xl border border-(--border) bg-(--bg-elevated) p-6 sm:flex-row sm:items-start">
+    <div class="demo-card flex flex-col items-center gap-5 p-6 sm:flex-row sm:items-start">
       <QrCodeRoot
         :value="value"
         error-correction="H"
-        class="size-48 shrink-0 text-(--fg)"
+        class="size-48 shrink-0 text-fg"
       >
         <QrCodeBackground fill="transparent" :radius="2" />
         <QrCodeCells :pattern="pattern" :radius="0.6" class="fill-current" />
-        <QrCodeMarkers :frame="frame" :ball="ball" :radius="0.5" class="fill-(--accent)" />
+        <QrCodeMarkers :frame="frame" :ball="ball" :radius="0.5" class="fill-accent" />
         <QrCodeLogo v-slot="{ cx, cy, width }" :size="0.22" :padding="1.5">
-          <circle :cx="cx" :cy="cy" :r="width / 2" class="fill-(--bg-elevated)" />
+          <circle :cx="cx" :cy="cy" :r="width / 2" class="fill-bg-elevated" />
           <text
             :x="cx"
             :y="cy"
             text-anchor="middle"
             dominant-baseline="central"
             :font-size="width * 0.7"
-            class="fill-(--accent)"
+            class="fill-accent"
             style="font-family: ui-sans-serif, system-ui; font-weight: 700"
           >
             R
@@ -51,28 +51,28 @@ const balls: QrMarkerBall[] = ['square', 'rounded', 'circle', 'diamond'];
 
       <div class="flex w-full flex-col gap-3 text-sm">
         <label class="flex flex-col gap-1">
-          <span class="text-(--fg-muted)">Value</span>
+          <span class="text-fg-muted">Value</span>
           <input
             v-model="value"
-            class="rounded-md border border-(--border) bg-(--bg-inset) px-2 py-1"
+            class="rounded-md border border-border bg-bg-inset px-2 py-1"
           >
         </label>
         <label class="flex flex-col gap-1">
-          <span class="text-(--fg-muted)">Pattern</span>
-          <select v-model="pattern" class="rounded-md border border-(--border) bg-(--bg-inset) px-2 py-1">
+          <span class="text-fg-muted">Pattern</span>
+          <select v-model="pattern" class="rounded-md border border-border bg-bg-inset px-2 py-1">
             <option v-for="p in patterns" :key="p" :value="p">{{ p }}</option>
           </select>
         </label>
         <div class="flex gap-3">
           <label class="flex flex-1 flex-col gap-1">
-            <span class="text-(--fg-muted)">Frame</span>
-            <select v-model="frame" class="rounded-md border border-(--border) bg-(--bg-inset) px-2 py-1">
+            <span class="text-fg-muted">Frame</span>
+            <select v-model="frame" class="rounded-md border border-border bg-bg-inset px-2 py-1">
               <option v-for="f in frames" :key="f" :value="f">{{ f }}</option>
             </select>
           </label>
           <label class="flex flex-1 flex-col gap-1">
-            <span class="text-(--fg-muted)">Ball</span>
-            <select v-model="ball" class="rounded-md border border-(--border) bg-(--bg-inset) px-2 py-1">
+            <span class="text-fg-muted">Ball</span>
+            <select v-model="ball" class="rounded-md border border-border bg-bg-inset px-2 py-1">
               <option v-for="b in balls" :key="b" :value="b">{{ b }}</option>
             </select>
           </label>
diff --git a/vue/primitives/src/qr-code/index.ts b/vue/primitives/src/display/qr-code/index.ts
similarity index 100%
rename from vue/primitives/src/qr-code/index.ts
rename to vue/primitives/src/display/qr-code/index.ts
diff --git a/vue/primitives/src/qr-code/utils.ts b/vue/primitives/src/display/qr-code/utils.ts
similarity index 98%
rename from vue/primitives/src/qr-code/utils.ts
rename to vue/primitives/src/display/qr-code/utils.ts
index f6d6547..71ae409 100644
--- a/vue/primitives/src/qr-code/utils.ts
+++ b/vue/primitives/src/display/qr-code/utils.ts
@@ -1,5 +1,6 @@
 import type { QrCode } from '@robonen/encoding';
 import { QrCodeDataType } from '@robonen/encoding';
+import { clamp } from '@robonen/stdlib';
 
 /**
  * Geometry helpers for rendering a {@link QrCode} matrix to SVG paths.
@@ -62,10 +63,6 @@ export function markerPlacements(size: number): MarkerPlacement[] {
   ];
 }
 
-function clamp(value: number, min: number, max: number): number {
-  return value < min ? min : value > max ? max : value;
-}
-
 /** Rounds to 4 decimals and strips trailing zeros to keep generated path strings compact. */
 function fmt(value: number): string {
   return String(Math.round(value * 1e4) / 1e4);
diff --git a/vue/primitives/src/scroll-area/ScrollAreaCorner.vue b/vue/primitives/src/display/scroll-area/ScrollAreaCorner.vue
similarity index 80%
rename from vue/primitives/src/scroll-area/ScrollAreaCorner.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaCorner.vue
index 33d5a4e..e700e2a 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaCorner.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaCorner.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Fills the square where the horizontal and vertical scrollbars meet. It only renders when
@@ -10,7 +10,7 @@ export type ScrollAreaCornerProps = PrimitiveProps;
 
 <script setup lang="ts">
 import { computed, onMounted, onScopeDispose, ref, watch } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useScrollAreaRootContext } from './context';
 
@@ -25,7 +25,12 @@ const width = ref(0);
 const height = ref(0);
 
 const hasSize = computed(() => width.value > 0 && height.value > 0);
-const hasBoth = computed(() => ctx.scrollbarXEnabled.value && ctx.scrollbarYEnabled.value);
+// For `type='scroll'` the bars overlay the content, so no corner is needed.
+const hasBoth = computed(() =>
+  ctx.type.value !== 'scroll'
+  && ctx.scrollbarXEnabled.value
+  && ctx.scrollbarYEnabled.value,
+);
 
 function measure() {
   const x = ctx.scrollbarX.value;
@@ -72,7 +77,8 @@ onScopeDispose(() => {
       width: `${width}px`,
       height: `${height}px`,
       position: 'absolute',
-      right: 0,
+      right: ctx.dir.value === 'rtl' ? undefined : 0,
+      left: ctx.dir.value === 'rtl' ? 0 : undefined,
       bottom: 0,
     }"
     v-bind="$attrs"
diff --git a/vue/primitives/src/scroll-area/ScrollAreaRoot.vue b/vue/primitives/src/display/scroll-area/ScrollAreaRoot.vue
similarity index 72%
rename from vue/primitives/src/scroll-area/ScrollAreaRoot.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaRoot.vue
index 8ef5caf..94b392a 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaRoot.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { ScrollAreaType } from './types';
 
 /**
@@ -17,6 +17,8 @@ export interface ScrollAreaRootProps extends PrimitiveProps {
    * - `always`: always visible.
    * - `scroll`: visible while the user is scrolling, then hides after `scrollHideDelay`.
    * - `hover`: visible while the pointer is over the root, then hides after `scrollHideDelay`.
+   * - `glimpse`: briefly revealed when the pointer enters the root, then auto-hides;
+   *   behaves like `scroll` once the user scrolls or interacts with the bar.
    * @default 'hover'
    */
   type?: ScrollAreaType;
@@ -32,10 +34,10 @@ export interface ScrollAreaRootProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { computed, ref, toRef } from 'vue';
-import { Primitive } from '../primitive';
+import { computed, ref, shallowRef, toRef } from 'vue';
+import { Primitive } from '../../internal/primitive';
 import { provideScrollAreaRootContext } from './context';
-import { useConfig, useId } from '../config-provider';
+import { useConfig, useId } from '../../utilities/config-provider';
 import { useForwardExpose } from '@robonen/vue';
 
 defineOptions({ inheritAttrs: false });
@@ -47,10 +49,10 @@ const props = withDefaults(defineProps<ScrollAreaRootProps>(), {
 
 const config = useConfig();
 
-const viewport = ref<HTMLElement | null>(null);
-const content = ref<HTMLElement | null>(null);
-const scrollbarX = ref<HTMLElement | null>(null);
-const scrollbarY = ref<HTMLElement | null>(null);
+const viewport = shallowRef<HTMLElement | null>(null);
+const content = shallowRef<HTMLElement | null>(null);
+const scrollbarX = shallowRef<HTMLElement | null>(null);
+const scrollbarY = shallowRef<HTMLElement | null>(null);
 const scrollbarXEnabled = ref(false);
 const scrollbarYEnabled = ref(false);
 const cornerWidth = ref(0);
@@ -59,6 +61,17 @@ const viewportId = useId(undefined, 'scroll-area-viewport');
 
 const dir = computed(() => props.dir ?? config.dir.value);
 
+// `defineExpose` runs BEFORE `useForwardExpose` so the composable merges these
+// bindings (plus props + `$el`) instead of `defineExpose`'s `expose()`
+// clobbering them and warning "expose() should be called only once". Unlike the
+// other roots, `useForwardExpose` must stay above the provide below because
+// `scrollArea` (its `currentElement`) feeds the context.
+defineExpose({
+  viewport,
+  scrollTop: () => viewport.value?.scrollTo({ top: 0 }),
+  scrollTopLeft: () => viewport.value?.scrollTo({ top: 0, left: 0 }),
+});
+
 const { forwardRef, currentElement: scrollArea } = useForwardExpose();
 
 provideScrollAreaRootContext({
@@ -77,15 +90,11 @@ provideScrollAreaRootContext({
   viewportId,
   onScrollbarXEnabledChange: (v) => { scrollbarXEnabled.value = v; },
   onScrollbarYEnabledChange: (v) => { scrollbarYEnabled.value = v; },
+  onScrollbarXChange: (el) => { scrollbarX.value = el; },
+  onScrollbarYChange: (el) => { scrollbarY.value = el; },
   onCornerWidthChange: (n) => { cornerWidth.value = n; },
   onCornerHeightChange: (n) => { cornerHeight.value = n; },
 });
-
-defineExpose({
-  viewport,
-  scrollTop: () => viewport.value?.scrollTo({ top: 0 }),
-  scrollTopLeft: () => viewport.value?.scrollTo({ top: 0, left: 0 }),
-});
 </script>
 
 <template>
diff --git a/vue/primitives/src/scroll-area/ScrollAreaScrollbar.vue b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbar.vue
similarity index 80%
rename from vue/primitives/src/scroll-area/ScrollAreaScrollbar.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaScrollbar.vue
index 3435fe5..2ac53bc 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaScrollbar.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbar.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A custom scrollbar track for one axis. It picks the appropriate visibility strategy from
@@ -17,7 +17,9 @@ export interface ScrollAreaScrollbarProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed, onBeforeUnmount, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
 import ScrollAreaScrollbarAuto from './ScrollAreaScrollbarAuto.vue';
+import ScrollAreaScrollbarGlimpse from './ScrollAreaScrollbarGlimpse.vue';
 import ScrollAreaScrollbarHover from './ScrollAreaScrollbarHover.vue';
 import ScrollAreaScrollbarScroll from './ScrollAreaScrollbarScroll.vue';
 import ScrollAreaScrollbarVisible from './ScrollAreaScrollbarVisible.vue';
@@ -30,6 +32,7 @@ const props = withDefaults(defineProps<ScrollAreaScrollbarProps>(), {
 });
 
 const ctx = useScrollAreaRootContext();
+const { forwardRef } = useForwardExpose();
 const isHorizontal = computed(() => props.orientation === 'horizontal');
 
 watch(isHorizontal, (h) => {
@@ -50,6 +53,7 @@ onBeforeUnmount(() => {
 <template>
   <ScrollAreaScrollbarHover
     v-if="ctx.type.value === 'hover'"
+    :ref="forwardRef"
     v-bind="$attrs"
     :orientation="orientation"
     :force-mount="forceMount"
@@ -59,6 +63,7 @@ onBeforeUnmount(() => {
   </ScrollAreaScrollbarHover>
   <ScrollAreaScrollbarScroll
     v-else-if="ctx.type.value === 'scroll'"
+    :ref="forwardRef"
     v-bind="$attrs"
     :orientation="orientation"
     :force-mount="forceMount"
@@ -66,8 +71,19 @@ onBeforeUnmount(() => {
   >
     <slot />
   </ScrollAreaScrollbarScroll>
+  <ScrollAreaScrollbarGlimpse
+    v-else-if="ctx.type.value === 'glimpse'"
+    :ref="forwardRef"
+    v-bind="$attrs"
+    :orientation="orientation"
+    :force-mount="forceMount"
+    :as="as"
+  >
+    <slot />
+  </ScrollAreaScrollbarGlimpse>
   <ScrollAreaScrollbarAuto
     v-else-if="ctx.type.value === 'auto'"
+    :ref="forwardRef"
     v-bind="$attrs"
     :orientation="orientation"
     :force-mount="forceMount"
@@ -77,6 +93,7 @@ onBeforeUnmount(() => {
   </ScrollAreaScrollbarAuto>
   <ScrollAreaScrollbarVisible
     v-else
+    :ref="forwardRef"
     v-bind="$attrs"
     :orientation="orientation"
     :as="as"
diff --git a/vue/primitives/src/scroll-area/ScrollAreaScrollbarAuto.vue b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarAuto.vue
similarity index 86%
rename from vue/primitives/src/scroll-area/ScrollAreaScrollbarAuto.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaScrollbarAuto.vue
index 21ac6c0..89c5355 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaScrollbarAuto.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarAuto.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 export interface ScrollAreaScrollbarAutoProps extends PrimitiveProps {
   orientation?: 'horizontal' | 'vertical';
@@ -9,9 +9,10 @@ export interface ScrollAreaScrollbarAutoProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed, onMounted, onScopeDispose, ref, watch } from 'vue';
-import { Presence } from '../presence';
+import { debounce } from '@robonen/stdlib';
+import { useForwardExpose } from '@robonen/vue';
+import { Presence } from '../../utilities/presence';
 import ScrollAreaScrollbarVisible from './ScrollAreaScrollbarVisible.vue';
-import { debounceCallback } from './utils';
 import { useScrollAreaRootContext } from './context';
 
 defineOptions({ inheritAttrs: false });
@@ -21,10 +22,11 @@ const props = withDefaults(defineProps<ScrollAreaScrollbarAutoProps>(), {
 });
 
 const ctx = useScrollAreaRootContext();
+const { forwardRef } = useForwardExpose();
 const visible = ref(false);
 const isHorizontal = computed(() => props.orientation === 'horizontal');
 
-const handleResize = debounceCallback(() => {
+const handleResize = debounce(() => {
   const vp = ctx.viewport.value;
   if (!vp)
     return;
@@ -69,6 +71,7 @@ onScopeDispose(() => {
 <template>
   <Presence :present="forceMount || visible">
     <ScrollAreaScrollbarVisible
+      :ref="forwardRef"
       v-bind="$attrs"
       :orientation="orientation"
       :as="as"
diff --git a/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarGlimpse.vue b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarGlimpse.vue
new file mode 100644
index 0000000..b1902b4
--- /dev/null
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarGlimpse.vue
@@ -0,0 +1,122 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A hybrid visibility strategy used for `type='glimpse'`: scrollbars briefly
+ * reveal themselves when the pointer enters the scroll area, then auto-hide
+ * after `scrollHideDelay`, and behave like `type='scroll'` once the user
+ * actually scrolls or interacts with the bar.
+ */
+export interface ScrollAreaScrollbarGlimpseProps extends PrimitiveProps {
+  orientation?: 'horizontal' | 'vertical';
+  forceMount?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onScopeDispose, onWatcherCleanup, ref, watch, watchEffect } from 'vue';
+import { debounce } from '@robonen/stdlib';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+import { Presence } from '../../utilities/presence';
+import ScrollAreaScrollbarAuto from './ScrollAreaScrollbarAuto.vue';
+import { useScrollAreaRootContext } from './context';
+import { addUnlinkedScrollListener } from './utils';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(defineProps<ScrollAreaScrollbarGlimpseProps>(), {
+  orientation: 'vertical',
+});
+
+const ctx = useScrollAreaRootContext();
+const { forwardRef } = useForwardExpose();
+
+type GlimpseState = 'hidden' | 'glimpse' | 'scrolling' | 'interacting' | 'idle';
+type GlimpseEvent = 'POINTER_ENTER' | 'POINTER_LEAVE' | 'SCROLL' | 'SCROLL_END' | 'HIDE';
+
+/**
+ * Declarative transition table — keeps the visibility lifecycle flat instead
+ * of branching inline. Unknown events for a state are a no-op.
+ */
+const TRANSITIONS: Record<GlimpseState, Partial<Record<GlimpseEvent, GlimpseState>>> = {
+  hidden: { POINTER_ENTER: 'glimpse', SCROLL: 'scrolling' },
+  glimpse: { HIDE: 'hidden', POINTER_LEAVE: 'hidden', SCROLL: 'scrolling', POINTER_ENTER: 'glimpse' },
+  scrolling: { SCROLL_END: 'idle', POINTER_ENTER: 'interacting' },
+  interacting: { SCROLL: 'interacting', POINTER_LEAVE: 'idle' },
+  idle: { HIDE: 'hidden', SCROLL: 'scrolling', POINTER_ENTER: 'interacting' },
+};
+
+const state = ref<GlimpseState>('hidden');
+const isHorizontal = computed(() => props.orientation === 'horizontal');
+const visible = computed(() => state.value !== 'hidden');
+
+function dispatch(event: GlimpseEvent) {
+  const next = TRANSITIONS[state.value][event];
+  if (next)
+    state.value = next;
+}
+
+const debouncedScrollEnd = debounce(() => dispatch('SCROLL_END'), 100);
+
+function onEnter() {
+  dispatch('POINTER_ENTER');
+}
+function onLeave() {
+  dispatch('POINTER_LEAVE');
+}
+
+// Auto-hide after the delay while glimpsing or idle.
+watchEffect(() => {
+  if (state.value === 'glimpse' || state.value === 'idle') {
+    const id = globalThis.setTimeout(() => dispatch('HIDE'), ctx.scrollHideDelay.value);
+    onWatcherCleanup(() => globalThis.clearTimeout(id));
+  }
+});
+
+let stop: (() => void) | null = null;
+let last = { left: 0, top: 0 };
+
+function attachScroll() {
+  stop?.();
+  const vp = ctx.viewport.value;
+  if (!vp)
+    return;
+  last = { left: vp.scrollLeft, top: vp.scrollTop };
+  stop = addUnlinkedScrollListener(vp, () => {
+    const next = { left: vp.scrollLeft, top: vp.scrollTop };
+    const matches = isHorizontal.value ? last.left !== next.left : last.top !== next.top;
+    if (matches) {
+      dispatch('SCROLL');
+      debouncedScrollEnd();
+    }
+    last = next;
+  });
+}
+
+// Re-attaches automatically when the scroll-area element changes; SSR-safe
+// (the getter resolves to `undefined` on the server).
+useEventListener(() => ctx.scrollArea.value, 'pointerenter', onEnter);
+useEventListener(() => ctx.scrollArea.value, 'pointerleave', onLeave);
+
+watch(() => ctx.viewport.value, attachScroll, { immediate: true });
+
+onScopeDispose(() => {
+  stop?.();
+  debouncedScrollEnd.cancel();
+});
+</script>
+
+<template>
+  <Presence :present="forceMount || visible">
+    <ScrollAreaScrollbarAuto
+      :ref="forwardRef"
+      v-bind="$attrs"
+      :orientation="orientation"
+      :as="as"
+      :data-state="visible ? 'visible' : 'hidden'"
+      force-mount
+    >
+      <slot />
+    </ScrollAreaScrollbarAuto>
+  </Presence>
+</template>
diff --git a/vue/primitives/src/scroll-area/ScrollAreaScrollbarHover.vue b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarHover.vue
similarity index 64%
rename from vue/primitives/src/scroll-area/ScrollAreaScrollbarHover.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaScrollbarHover.vue
index 6b22000..75e573b 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaScrollbarHover.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarHover.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 export interface ScrollAreaScrollbarHoverProps extends PrimitiveProps {
   orientation?: 'horizontal' | 'vertical';
@@ -8,8 +8,9 @@ export interface ScrollAreaScrollbarHoverProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { onScopeDispose, ref, watch } from 'vue';
-import { Presence } from '../presence';
+import { onScopeDispose, ref } from 'vue';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+import { Presence } from '../../utilities/presence';
 import ScrollAreaScrollbarAuto from './ScrollAreaScrollbarAuto.vue';
 import { useScrollAreaRootContext } from './context';
 
@@ -20,9 +21,9 @@ withDefaults(defineProps<ScrollAreaScrollbarHoverProps>(), {
 });
 
 const ctx = useScrollAreaRootContext();
+const { forwardRef } = useForwardExpose();
 const visible = ref(false);
 let hideTimer: ReturnType<typeof setTimeout> | null = null;
-let scrollArea: HTMLElement | null = null;
 
 function clearTimer() {
   if (hideTimer !== null) {
@@ -42,32 +43,18 @@ function onLeave() {
   }, ctx.scrollHideDelay.value);
 }
 
-function attach(el: HTMLElement | null) {
-  detach();
-  if (!el)
-    return;
-  scrollArea = el;
-  el.addEventListener('pointerenter', onEnter);
-  el.addEventListener('pointerleave', onLeave);
-}
-function detach() {
-  if (!scrollArea)
-    return;
-  scrollArea.removeEventListener('pointerenter', onEnter);
-  scrollArea.removeEventListener('pointerleave', onLeave);
-  scrollArea = null;
-}
+// Re-attaches automatically when the scroll-area element changes; SSR-safe
+// (the getter resolves to `undefined` on the server).
+useEventListener(() => ctx.scrollArea.value, 'pointerenter', onEnter);
+useEventListener(() => ctx.scrollArea.value, 'pointerleave', onLeave);
 
-watch(() => ctx.scrollArea.value, attach, { immediate: true });
-onScopeDispose(() => {
-  clearTimer();
-  detach();
-});
+onScopeDispose(clearTimer);
 </script>
 
 <template>
   <Presence :present="forceMount || visible">
     <ScrollAreaScrollbarAuto
+      :ref="forwardRef"
       v-bind="$attrs"
       :orientation="orientation"
       :as="as"
diff --git a/vue/primitives/src/scroll-area/ScrollAreaScrollbarImpl.vue b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarImpl.vue
similarity index 62%
rename from vue/primitives/src/scroll-area/ScrollAreaScrollbarImpl.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaScrollbarImpl.vue
index 8f0748d..5060c0a 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaScrollbarImpl.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarImpl.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { ScrollAreaSizes } from './types';
 
 export interface ScrollAreaScrollbarImplProps extends PrimitiveProps {
@@ -11,8 +11,9 @@ export interface ScrollAreaScrollbarImplProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed, onMounted, onScopeDispose, ref, watch } from 'vue';
-import { Primitive } from '../primitive';
-import { toInt } from './utils';
+import { debounce } from '@robonen/stdlib';
+import { Primitive } from '../../internal/primitive';
+import { getThumbSize, toInt } from './utils';
 import { useForwardExpose } from '@robonen/vue';
 import { useScrollAreaRootContext } from './context';
 
@@ -34,6 +35,7 @@ const isHorizontal = computed(() => props.orientation === 'horizontal');
 const rectRef = ref<DOMRect | null>(null);
 const prevWebkitUserSelect = ref('');
 const prevPointerEvents = ref('');
+const prevScrollBehavior = ref('');
 
 /** Live viewport scroll position along this scrollbar's axis. */
 const scrollPos = ref(0);
@@ -51,6 +53,35 @@ const ariaValueNow = computed(() => {
 /** Scrollbar is interactive only when content actually overflows. */
 const isInteractive = computed(() => props.hasThumb && maxScroll.value > 0);
 
+/**
+ * Thumb length along this scrollbar's axis, exposed as the CSS var that
+ * `ScrollAreaThumb` reads. Without this the thumb collapses to zero length.
+ */
+const thumbSize = computed(() => `${getThumbSize(props.sizes)}px`);
+
+/**
+ * Absolute positioning of the track. RTL flips the resting edge: the vertical
+ * bar moves to the left, and the horizontal bar's corner gap swaps sides.
+ */
+const positionStyle = computed(() => {
+  const isRtl = ctx.dir.value === 'rtl';
+  if (isHorizontal.value) {
+    return {
+      bottom: 0,
+      left: isRtl ? 'var(--scroll-area-corner-width)' : 0,
+      right: isRtl ? 0 : 'var(--scroll-area-corner-width)',
+      '--scroll-area-thumb-width': thumbSize.value,
+    };
+  }
+  return {
+    top: 0,
+    right: isRtl ? undefined : 0,
+    left: isRtl ? 0 : undefined,
+    bottom: 'var(--scroll-area-corner-height)',
+    '--scroll-area-thumb-height': thumbSize.value,
+  };
+});
+
 function updateScrollPos() {
   const vp = ctx.viewport.value;
   if (!vp) return;
@@ -75,11 +106,22 @@ function onPointerDown(event: PointerEvent) {
   if (ctx.viewport.value) {
     prevPointerEvents.value = ctx.viewport.value.style.pointerEvents;
     ctx.viewport.value.style.pointerEvents = 'none';
+    // Disable smooth scrolling during the drag so the thumb tracks the
+    // pointer 1:1 instead of lagging behind a `scroll-behavior: smooth`.
+    prevScrollBehavior.value = ctx.viewport.value.style.scrollBehavior;
+    ctx.viewport.value.style.scrollBehavior = 'auto';
   }
   emit('dragScroll', getPointerPosition(event));
 }
 
 function onPointerMove(event: PointerEvent) {
+  // `rectRef` is only set on pointerdown and cleared on pointerup, so it is the
+  // natural drag flag. Without this guard `pointermove` fires on every hover
+  // move over the track: each one emits `dragScroll` with a position of 0
+  // (getPointerPosition returns 0 when `rectRef` is null) and forces the
+  // viewport toward scroll position 0 — both wasted work and a correctness bug.
+  if (!rectRef.value)
+    return;
   emit('dragScroll', getPointerPosition(event));
 }
 
@@ -88,12 +130,24 @@ function onPointerUp(event: PointerEvent) {
   if (target.hasPointerCapture(event.pointerId))
     target.releasePointerCapture(event.pointerId);
   document.body.style.webkitUserSelect = prevWebkitUserSelect.value;
-  if (ctx.viewport.value)
+  if (ctx.viewport.value) {
     ctx.viewport.value.style.pointerEvents = prevPointerEvents.value;
+    ctx.viewport.value.style.scrollBehavior = prevScrollBehavior.value;
+  }
   rectRef.value = null;
 }
 
+/**
+ * Wheeling over the scrollbar scrolls the viewport. The listener must be
+ * non-passive so `preventDefault` inside the handler can stop the page from
+ * scrolling when the viewport is mid-range; an `@wheel.passive` binding would
+ * make that `preventDefault` a no-op. It is scoped to wheels landing on this
+ * scrollbar via `contains`.
+ */
 function onWheel(event: WheelEvent) {
+  const sb = currentElement.value;
+  if (!sb || !sb.contains(event.target as Node))
+    return;
   emit('wheelScroll', event, maxScroll.value);
 }
 
@@ -164,26 +218,54 @@ let sbObs: ResizeObserver | null = null;
 let vpObs: ResizeObserver | null = null;
 let coObs: ResizeObserver | null = null;
 
+/**
+ * A single layout change can resize more than one observed element (scrollbar,
+ * viewport, content), invoking the observer callback multiple times
+ * synchronously — each forcing a `getComputedStyle` + scrollWidth/offsetWidth
+ * read. Debouncing (mirroring `ScrollAreaScrollbarAuto`) coalesces those into
+ * one measure per burst. `attach()` still calls the undebounced `measure()`
+ * once so the initial size is available immediately on mount (no thumb flash).
+ */
+const measureDebounced = debounce(measure, 10);
+
+/** The element the non-passive wheel listener is currently bound to. */
+let wheelEl: HTMLElement | null = null;
+
+function attachWheel() {
+  const sb = currentElement.value ?? null;
+  if (wheelEl === sb)
+    return;
+  wheelEl?.removeEventListener('wheel', onWheel);
+  wheelEl = sb;
+  // Non-passive so `preventDefault` inside `onWheel` can stop the page from
+  // scrolling when the viewport is mid-range. Scoped to the scrollbar element
+  // itself rather than `document`, so unrelated page wheels no longer pay the
+  // non-passive cost or run the handler.
+  wheelEl?.addEventListener('wheel', onWheel, { passive: false });
+}
+
 function attach() {
   detach();
   if (currentElement.value) {
-    sbObs = new ResizeObserver(measure);
+    sbObs = new ResizeObserver(measureDebounced);
     sbObs.observe(currentElement.value);
   }
   if (ctx.viewport.value) {
-    vpObs = new ResizeObserver(measure);
+    vpObs = new ResizeObserver(measureDebounced);
     vpObs.observe(ctx.viewport.value);
   }
   if (ctx.content.value) {
-    coObs = new ResizeObserver(measure);
+    coObs = new ResizeObserver(measureDebounced);
     coObs.observe(ctx.content.value);
   }
+  attachWheel();
   measure();
   updateScrollPos();
   emit('thumbPositionChange');
 }
 
 function detach() {
+  measureDebounced.cancel();
   sbObs?.disconnect();
   sbObs = null;
   vpObs?.disconnect();
@@ -192,8 +274,16 @@ function detach() {
   coObs = null;
 }
 
+function registerScrollbarEl(el: HTMLElement | null) {
+  emit('registerScrollbar', el);
+  if (isHorizontal.value)
+    ctx.onScrollbarXChange(el);
+  else
+    ctx.onScrollbarYChange(el);
+}
+
 onMounted(() => {
-  emit('registerScrollbar', currentElement.value ?? null);
+  registerScrollbarEl(currentElement.value ?? null);
   attach();
 });
 
@@ -206,13 +296,15 @@ function onViewportScroll() {
 
 watch(() => ctx.viewport.value, (vp, prev) => {
   prev?.removeEventListener('scroll', onViewportScroll);
-  vp?.addEventListener('scroll', onViewportScroll);
+  vp?.addEventListener('scroll', onViewportScroll, { passive: true });
 }, { immediate: true });
 
 onScopeDispose(() => {
   detach();
+  wheelEl?.removeEventListener('wheel', onWheel);
+  wheelEl = null;
   ctx.viewport.value?.removeEventListener('scroll', onViewportScroll);
-  emit('registerScrollbar', null);
+  registerScrollbarEl(null);
 });
 </script>
 
@@ -231,14 +323,11 @@ onScopeDispose(() => {
     :data-orientation="orientation"
     :style="{
       position: 'absolute',
-      ...(isHorizontal
-        ? { bottom: 0, left: 0, right: 'var(--scroll-area-corner-width)' }
-        : { top: 0, right: 0, bottom: 'var(--scroll-area-corner-height)' }),
+      ...positionStyle,
     }"
     @pointerdown="onPointerDown"
     @pointermove="onPointerMove"
     @pointerup="onPointerUp"
-    @wheel.passive="onWheel"
     @keydown="onKeyDown"
   >
     <slot />
diff --git a/vue/primitives/src/scroll-area/ScrollAreaScrollbarScroll.vue b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarScroll.vue
similarity index 83%
rename from vue/primitives/src/scroll-area/ScrollAreaScrollbarScroll.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaScrollbarScroll.vue
index f84bebd..2b007c6 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaScrollbarScroll.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarScroll.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 export interface ScrollAreaScrollbarScrollProps extends PrimitiveProps {
   orientation?: 'horizontal' | 'vertical';
@@ -9,10 +9,12 @@ export interface ScrollAreaScrollbarScrollProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed, onMounted, onScopeDispose, ref, watch } from 'vue';
-import { Presence } from '../presence';
+import { debounce } from '@robonen/stdlib';
+import { useForwardExpose } from '@robonen/vue';
+import { Presence } from '../../utilities/presence';
 import { useScrollAreaRootContext } from './context';
 import ScrollAreaScrollbarVisible from './ScrollAreaScrollbarVisible.vue';
-import { addUnlinkedScrollListener, debounceCallback } from './utils';
+import { addUnlinkedScrollListener } from './utils';
 
 defineOptions({ inheritAttrs: false });
 
@@ -21,14 +23,15 @@ const props = withDefaults(defineProps<ScrollAreaScrollbarScrollProps>(), {
 });
 
 const ctx = useScrollAreaRootContext();
+const { forwardRef } = useForwardExpose();
 const isHorizontal = computed(() => props.orientation === 'horizontal');
 const state = ref<'hidden' | 'scrolling' | 'interacting' | 'idle'>('hidden');
 
-const debouncedScrollEnd = debounceCallback(() => {
+const debouncedScrollEnd = debounce(() => {
   state.value = 'idle';
 }, 100);
 
-const debouncedHide = debounceCallback(() => {
+const debouncedHide = debounce(() => {
   state.value = 'hidden';
 }, ctx.scrollHideDelay.value);
 
@@ -75,6 +78,7 @@ const isVisible = computed(() => state.value !== 'hidden');
 <template>
   <Presence :present="forceMount || isVisible">
     <ScrollAreaScrollbarVisible
+      :ref="forwardRef"
       v-bind="$attrs"
       :orientation="orientation"
       :as="as"
diff --git a/vue/primitives/src/scroll-area/ScrollAreaScrollbarVisible.vue b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarVisible.vue
similarity index 90%
rename from vue/primitives/src/scroll-area/ScrollAreaScrollbarVisible.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaScrollbarVisible.vue
index 1655a61..2215280 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaScrollbarVisible.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaScrollbarVisible.vue
@@ -1,10 +1,11 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 </script>
 
 <script setup lang="ts">
 import type { ScrollAreaSizes } from './types';
-import { computed, ref } from 'vue';
+import { computed, ref, shallowRef } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
 import { provideScrollAreaScrollbarContext, useScrollAreaRootContext } from './context';
 import ScrollAreaScrollbarImpl from './ScrollAreaScrollbarImpl.vue';
 import { getScrollPositionFromPointer, getThumbOffsetFromScroll, getThumbRatio, isScrollingWithinScrollbarBounds } from './utils';
@@ -16,6 +17,7 @@ const props = withDefaults(defineProps<PrimitiveProps & { orientation?: 'horizon
 });
 
 const ctx = useScrollAreaRootContext();
+const { forwardRef } = useForwardExpose();
 const sizes = ref<ScrollAreaSizes>({
   content: 0,
   viewport: 0,
@@ -28,8 +30,8 @@ const hasThumb = computed(() => {
   return r > 0 && r < 1;
 });
 
-const thumbEl = ref<HTMLElement | null>(null);
-const scrollbarEl = ref<HTMLElement | null>(null);
+const thumbEl = shallowRef<HTMLElement | null>(null);
+const scrollbarEl = shallowRef<HTMLElement | null>(null);
 const pointerOffset = ref(0);
 
 function onSizesChange(s: ScrollAreaSizes) {
@@ -101,6 +103,7 @@ provideScrollAreaScrollbarContext({
 
 <template>
   <ScrollAreaScrollbarImpl
+    :ref="forwardRef"
     v-bind="$attrs"
     :orientation="orientation"
     :as="as"
diff --git a/vue/primitives/src/scroll-area/ScrollAreaThumb.vue b/vue/primitives/src/display/scroll-area/ScrollAreaThumb.vue
similarity index 89%
rename from vue/primitives/src/scroll-area/ScrollAreaThumb.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaThumb.vue
index 1ff22aa..d0ee9a5 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaThumb.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaThumb.vue
@@ -1,11 +1,11 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 </script>
 
 <script setup lang="ts">
 import { computed, onMounted, onScopeDispose, ref, watch } from 'vue';
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useScrollAreaRootContext, useScrollAreaScrollbarContext } from './context';
 import { addUnlinkedScrollListener } from './utils';
@@ -68,6 +68,7 @@ onScopeDispose(() => {
 });
 
 const present = computed(() => props.forceMount || sb.hasThumb.value);
+const dataState = computed(() => (sb.hasThumb.value ? 'visible' : 'hidden'));
 </script>
 
 <template>
@@ -75,7 +76,7 @@ const present = computed(() => props.forceMount || sb.hasThumb.value);
     <Primitive
       :ref="forwardRef"
       :as="as ?? 'div'"
-      data-state="visible"
+      :data-state="dataState"
       :style="{ width: 'var(--scroll-area-thumb-width)', height: 'var(--scroll-area-thumb-height)' }"
       v-bind="$attrs"
       @pointerdowncapture="handlePointerDown"
diff --git a/vue/primitives/src/scroll-area/ScrollAreaViewport.vue b/vue/primitives/src/display/scroll-area/ScrollAreaViewport.vue
similarity index 58%
rename from vue/primitives/src/scroll-area/ScrollAreaViewport.vue
rename to vue/primitives/src/display/scroll-area/ScrollAreaViewport.vue
index fcf05d4..d8e23df 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaViewport.vue
+++ b/vue/primitives/src/display/scroll-area/ScrollAreaViewport.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The scrollable region that clips and natively scrolls its content while the OS scrollbars
@@ -7,25 +7,49 @@ import type { PrimitiveProps } from '../primitive';
  * `ScrollAreaRoot`.
  */
 export interface ScrollAreaViewportProps extends PrimitiveProps {
-  /** Inline `nonce` attribute applied to the injected style tag (CSP support). */
+  /**
+   * Inline `nonce` attribute applied to the injected style tag (CSP support).
+   * Falls back to the `ConfigProvider` `nonce` when omitted.
+   */
   nonce?: string;
+  /**
+   * `tabindex` applied to the scrollable region so keyboard users can focus the
+   * panel and arrow-scroll natively even when no scrollbar is interactive.
+   * Pass `-1`/`undefined` to opt out.
+   * @default 0
+   */
+  tabindex?: number;
 }
 </script>
 
 <script setup lang="ts">
-import { onMounted, ref, watch } from 'vue';
-import { Primitive } from '../primitive';
+import { computed, onMounted, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
+import { useNonce } from '../../utilities/config-provider';
 import { useScrollAreaRootContext } from './context';
 
 defineOptions({ inheritAttrs: false });
 
-defineProps<ScrollAreaViewportProps>();
+const props = withDefaults(defineProps<ScrollAreaViewportProps>(), {
+  tabindex: 0,
+});
 
 const ctx = useScrollAreaRootContext();
 const { forwardRef, currentElement } = useForwardExpose();
 
-const contentRef = ref<HTMLElement | null>(null);
+const nonce = useNonce(toRef(() => props.nonce));
+
+/**
+ * Only force `fit-content` when horizontal scrolling is enabled. In the common
+ * vertical-only case leaving `minWidth` unset lets the parent constrain width
+ * so `text-overflow: ellipsis` keeps working inside the content wrapper.
+ */
+const contentMinWidth = computed(() =>
+  ctx.scrollbarXEnabled.value ? 'fit-content' : '100%',
+);
+
+const contentRef = shallowRef<HTMLElement | null>(null);
 
 watch(currentElement, (el) => {
   ctx.viewport.value = el ?? null;
@@ -55,6 +79,7 @@ onMounted(() => {
     :as="as"
     :id="($attrs.id as string | undefined) ?? ctx.viewportId.value"
     data-scroll-area-viewport=""
+    :tabindex="tabindex"
     :style="{
       overflowX: ctx.scrollbarXEnabled.value ? 'scroll' : 'hidden',
       overflowY: ctx.scrollbarYEnabled.value ? 'scroll' : 'hidden',
@@ -64,7 +89,7 @@ onMounted(() => {
     <!-- A `min-width: fit-content` inner ensures horizontal content is measurable. -->
     <div
       :ref="(el: any) => { contentRef = el; }"
-      :style="{ minWidth: '100%', display: 'table' }"
+      :style="{ minWidth: contentMinWidth, display: 'table' }"
     >
       <slot />
     </div>
diff --git a/vue/primitives/src/scroll-area/__test__/ScrollArea.a11y.test.ts b/vue/primitives/src/display/scroll-area/__test__/ScrollArea.a11y.test.ts
similarity index 99%
rename from vue/primitives/src/scroll-area/__test__/ScrollArea.a11y.test.ts
rename to vue/primitives/src/display/scroll-area/__test__/ScrollArea.a11y.test.ts
index f9129cf..3315abe 100644
--- a/vue/primitives/src/scroll-area/__test__/ScrollArea.a11y.test.ts
+++ b/vue/primitives/src/display/scroll-area/__test__/ScrollArea.a11y.test.ts
@@ -8,7 +8,7 @@ import {
   ScrollAreaScrollbar,
   ScrollAreaThumb,
   ScrollAreaViewport,
-} from '../../index';
+} from '../../../index';
 
 const wrappers: Array<VueWrapper<any>> = [];
 
diff --git a/vue/primitives/src/display/scroll-area/__test__/ScrollArea.parity.test.ts b/vue/primitives/src/display/scroll-area/__test__/ScrollArea.parity.test.ts
new file mode 100644
index 0000000..4c535b8
--- /dev/null
+++ b/vue/primitives/src/display/scroll-area/__test__/ScrollArea.parity.test.ts
@@ -0,0 +1,198 @@
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+
+import {
+  ScrollAreaCorner,
+  ScrollAreaRoot,
+  ScrollAreaScrollbar,
+  ScrollAreaThumb,
+  ScrollAreaViewport,
+} from '../../../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  document.body.removeAttribute('style');
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function makeApp(rootProps: Record<string, unknown> = {}, opts: { scrollbarRef?: any } = {}) {
+  return defineComponent({
+    setup() {
+      return () => h(
+        ScrollAreaRoot,
+        { ...rootProps, style: { width: '100px', height: '100px' } },
+        {
+          default: () => [
+            h(ScrollAreaViewport, { style: { width: '100%', height: '100%' } }, {
+              default: () => h('div', { style: { width: '500px', height: '500px' } }, 'content'),
+            }),
+            h(ScrollAreaScrollbar, { orientation: 'vertical', ...(opts.scrollbarRef ? { ref: opts.scrollbarRef } : {}) }, {
+              default: () => h(ScrollAreaThumb),
+            }),
+            h(ScrollAreaScrollbar, { orientation: 'horizontal' }, {
+              default: () => h(ScrollAreaThumb),
+            }),
+            h(ScrollAreaCorner),
+          ],
+        },
+      );
+    },
+  });
+}
+
+async function waitFrames(n = 3) {
+  for (let i = 0; i < n; i++) {
+    await new Promise<void>(r => requestAnimationFrame(() => r()));
+    await nextTick();
+  }
+}
+
+function getScrollbar(orientation: 'horizontal' | 'vertical'): HTMLElement {
+  return document.querySelector(`[role="scrollbar"][aria-orientation="${orientation}"]`) as HTMLElement;
+}
+
+function getViewport(): HTMLElement {
+  return document.querySelector('[data-scroll-area-viewport]') as HTMLElement;
+}
+
+describe('scroll-area — thumb sizing', () => {
+  it('sets the thumb-size CSS var on the scrollbar so the thumb has length', async () => {
+    track(mount(makeApp({ type: 'always' }), { attachTo: document.body }));
+    await waitFrames();
+    const v = getScrollbar('vertical');
+    const h2 = getScrollbar('horizontal');
+    // The vars are written inline on the scrollbar element style.
+    expect(v.style.getPropertyValue('--scroll-area-thumb-height')).toMatch(/px$/);
+    expect(h2.style.getPropertyValue('--scroll-area-thumb-width')).toMatch(/px$/);
+  });
+});
+
+describe('scroll-area — viewport keyboard focus', () => {
+  it('viewport is focusable by default (tabindex=0)', async () => {
+    track(mount(makeApp({ type: 'always' }), { attachTo: document.body }));
+    await waitFrames();
+    expect(getViewport().getAttribute('tabindex')).toBe('0');
+  });
+
+  it('viewport tabindex is overridable', async () => {
+    const App = defineComponent({
+      setup() {
+        return () => h(
+          ScrollAreaRoot,
+          { type: 'always', style: { width: '100px', height: '100px' } },
+          {
+            default: () => [
+              h(ScrollAreaViewport, { tabindex: -1, style: { width: '100%', height: '100%' } }, {
+                default: () => h('div', { style: { width: '500px', height: '500px' } }, 'content'),
+              }),
+              h(ScrollAreaScrollbar, { orientation: 'vertical' }, { default: () => h(ScrollAreaThumb) }),
+            ],
+          },
+        );
+      },
+    });
+    track(mount(App, { attachTo: document.body }));
+    await waitFrames();
+    expect(getViewport().getAttribute('tabindex')).toBe('-1');
+  });
+});
+
+describe('scroll-area — RTL scrollbar positioning', () => {
+  it('LTR keeps the vertical bar on the right', async () => {
+    track(mount(makeApp({ type: 'always', dir: 'ltr' }), { attachTo: document.body }));
+    await waitFrames();
+    const v = getScrollbar('vertical');
+    expect(v.style.right).toBe('0px');
+    expect(v.style.left).toBe('');
+  });
+
+  it('RTL flips the vertical bar to the left', async () => {
+    track(mount(makeApp({ type: 'always', dir: 'rtl' }), { attachTo: document.body }));
+    await waitFrames();
+    const v = getScrollbar('vertical');
+    expect(v.style.left).toBe('0px');
+    expect(v.style.right).toBe('');
+  });
+});
+
+describe('scroll-area — thumb data-state', () => {
+  it('reflects hasThumb when content overflows', async () => {
+    track(mount(makeApp({ type: 'always' }), { attachTo: document.body }));
+    await waitFrames();
+    const thumb = document.querySelector('[data-state]') as HTMLElement;
+    expect(thumb).toBeTruthy();
+    // jsdom has no layout; with always type the scrollbar is mounted and
+    // thumb data-state derives from hasThumb (false in jsdom => 'hidden').
+    expect(['visible', 'hidden']).toContain(thumb.getAttribute('data-state'));
+  });
+});
+
+describe('scroll-area — ref forwarding', () => {
+  it('forwards a template ref on ScrollAreaScrollbar to the DOM scrollbar element', async () => {
+    const scrollbarRef = ref<any>(null);
+    track(mount(makeApp({ type: 'always' }, { scrollbarRef }), { attachTo: document.body }));
+    await waitFrames();
+    const el = scrollbarRef.value?.$el ?? scrollbarRef.value;
+    expect(el).toBeTruthy();
+    expect((el as HTMLElement).getAttribute?.('role')).toBe('scrollbar');
+  });
+});
+
+describe('scroll-area — glimpse type', () => {
+  it('accepts type="glimpse" and reveals scrollbars on pointer enter', async () => {
+    track(mount(makeApp({ type: 'glimpse', scrollHideDelay: 5000 }), { attachTo: document.body }));
+    await waitFrames();
+    const root = document.querySelector('[dir]') as HTMLElement;
+    root.dispatchEvent(new PointerEvent('pointerenter'));
+    await waitFrames();
+    expect(document.querySelectorAll('[data-state="visible"]').length).toBeGreaterThan(0);
+  });
+
+  it('glimpse stays hidden before any interaction', async () => {
+    track(mount(makeApp({ type: 'glimpse', scrollHideDelay: 5000 }), { attachTo: document.body }));
+    await waitFrames();
+    // No pointer enter / scroll => no visible scrollbar yet.
+    expect(document.querySelectorAll('[data-state="visible"]').length).toBe(0);
+  });
+});
+
+describe('scroll-area — corner type guard', () => {
+  it('does not render a corner for type="scroll"', async () => {
+    const App = defineComponent({
+      setup() {
+        return () => h(
+          ScrollAreaRoot,
+          { type: 'scroll', style: { width: '100px', height: '100px' } },
+          {
+            default: () => [
+              h(ScrollAreaViewport, { style: { width: '100%', height: '100%' } }, {
+                default: () => h('div', { style: { width: '500px', height: '500px' } }, 'content'),
+              }),
+              h(ScrollAreaScrollbar, { orientation: 'vertical', forceMount: true }, { default: () => h(ScrollAreaThumb) }),
+              h(ScrollAreaScrollbar, { orientation: 'horizontal', forceMount: true }, { default: () => h(ScrollAreaThumb) }),
+              h(ScrollAreaCorner),
+            ],
+          },
+        );
+      },
+    });
+    const w = track(mount(App, { attachTo: document.body }));
+    await waitFrames();
+    // Corner only renders when both bars are present AND type !== 'scroll'.
+    // For type='scroll' the corner must never appear.
+    const corners = w.findAll('div').filter(d => (d.element as HTMLElement).style.position === 'absolute' && (d.element as HTMLElement).getAttribute('role') !== 'scrollbar');
+    // None of the absolutely-positioned non-scrollbar divs should be the corner.
+    // (Corner has both width/height px set and bottom:0 with no role.)
+    const corner = corners.find(d => (d.element as HTMLElement).style.bottom === '0px' && !(d.element as HTMLElement).hasAttribute('aria-orientation'));
+    expect(corner).toBeUndefined();
+  });
+});
diff --git a/vue/primitives/src/scroll-area/__test__/ScrollArea.test.ts b/vue/primitives/src/display/scroll-area/__test__/ScrollArea.test.ts
similarity index 99%
rename from vue/primitives/src/scroll-area/__test__/ScrollArea.test.ts
rename to vue/primitives/src/display/scroll-area/__test__/ScrollArea.test.ts
index 878e3ab..a9cbf6a 100644
--- a/vue/primitives/src/scroll-area/__test__/ScrollArea.test.ts
+++ b/vue/primitives/src/display/scroll-area/__test__/ScrollArea.test.ts
@@ -4,7 +4,7 @@ import {
   ScrollAreaScrollbar,
   ScrollAreaThumb,
   ScrollAreaViewport,
-} from '../../index';
+} from '../../../index';
 import {
   clamp,
   getScrollPositionFromPointer,
diff --git a/vue/primitives/src/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-RTL--ArrowLeft-scrolls-the-horizontal-viewport-forward--visually-reversed--1.png b/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-RTL--ArrowLeft-scrolls-the-horizontal-viewport-forward--visually-reversed--1.png
similarity index 100%
rename from vue/primitives/src/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-RTL--ArrowLeft-scrolls-the-horizontal-viewport-forward--visually-reversed--1.png
rename to vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-RTL--ArrowLeft-scrolls-the-horizontal-viewport-forward--visually-reversed--1.png
diff --git a/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-does-not-call-preventDefault-when-scrollbar-is-non-interactive-1.png b/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-does-not-call-preventDefault-when-scrollbar-is-non-interactive-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-does-not-call-preventDefault-when-scrollbar-is-non-interactive-1.png differ
diff --git a/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-is-a-no-op-when-content-does-not-overflow-1.png b/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-is-a-no-op-when-content-does-not-overflow-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.a11y.test.ts/scroll-area---scrollbar-keyboard-support-keydown-handler-is-a-no-op-when-content-does-not-overflow-1.png differ
diff --git a/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.parity.test.ts/scroll-area---glimpse-type-glimpse-stays-hidden-before-any-interaction-1.png b/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.parity.test.ts/scroll-area---glimpse-type-glimpse-stays-hidden-before-any-interaction-1.png
new file mode 100644
index 0000000..206cb25
Binary files /dev/null and b/vue/primitives/src/display/scroll-area/__test__/__screenshots__/ScrollArea.parity.test.ts/scroll-area---glimpse-type-glimpse-stays-hidden-before-any-interaction-1.png differ
diff --git a/vue/primitives/src/scroll-area/context.ts b/vue/primitives/src/display/scroll-area/context.ts
similarity index 85%
rename from vue/primitives/src/scroll-area/context.ts
rename to vue/primitives/src/display/scroll-area/context.ts
index 718c074..5075856 100644
--- a/vue/primitives/src/scroll-area/context.ts
+++ b/vue/primitives/src/display/scroll-area/context.ts
@@ -19,6 +19,10 @@ export interface ScrollAreaRootContext {
   viewportId: Ref<string>;
   onScrollbarXEnabledChange: (enabled: boolean) => void;
   onScrollbarYEnabledChange: (enabled: boolean) => void;
+  /** Registers the live horizontal scrollbar element so the Corner can measure it. */
+  onScrollbarXChange: (el: HTMLElement | null) => void;
+  /** Registers the live vertical scrollbar element so the Corner can measure it. */
+  onScrollbarYChange: (el: HTMLElement | null) => void;
   onCornerWidthChange: (n: number) => void;
   onCornerHeightChange: (n: number) => void;
 }
diff --git a/vue/primitives/src/scroll-area/demo.vue b/vue/primitives/src/display/scroll-area/demo.vue
similarity index 67%
rename from vue/primitives/src/scroll-area/demo.vue
rename to vue/primitives/src/display/scroll-area/demo.vue
index ea43c6f..cbbbc0f 100644
--- a/vue/primitives/src/scroll-area/demo.vue
+++ b/vue/primitives/src/display/scroll-area/demo.vue
@@ -22,32 +22,32 @@ const releases = [
 <template>
   <ScrollAreaRoot
     type="always"
-    class="h-64 w-full max-w-md overflow-hidden rounded-xl border border-(--border) bg-(--bg-elevated) text-(--fg)"
+    class="demo-card h-64 w-full max-w-md overflow-hidden text-fg"
   >
     <ScrollAreaViewport class="h-full w-full">
-      <div class="border-b border-(--border) px-4 py-3">
+      <div class="border-b border-border px-4 py-3">
         <h3 class="text-sm font-semibold">
           Changelog
         </h3>
-        <p class="text-xs text-(--fg-subtle)">
+        <p class="text-xs text-fg-subtle">
           @robonen/primitives
         </p>
       </div>
 
-      <ul class="divide-y divide-(--border)">
+      <ul class="divide-y divide-border">
         <li
           v-for="release in releases"
           :key="release.tag"
           class="flex gap-3 whitespace-nowrap px-4 py-3"
         >
-          <span class="inline-flex h-fit shrink-0 items-center rounded-md border border-(--border) bg-(--bg-subtle) px-2 py-0.5 font-mono text-xs text-(--accent)">
+          <span class="inline-flex h-fit shrink-0 items-center rounded-md border border-border bg-bg-subtle px-2 py-0.5 font-mono text-xs text-accent">
             {{ release.tag }}
           </span>
           <div class="min-w-0">
-            <p class="text-sm text-(--fg)">
+            <p class="text-sm text-fg">
               {{ release.note }}
             </p>
-            <p class="mt-0.5 text-xs text-(--fg-subtle)">
+            <p class="mt-0.5 text-xs text-fg-subtle">
               {{ release.date }}
             </p>
           </div>
@@ -57,18 +57,18 @@ const releases = [
 
     <ScrollAreaScrollbar
       orientation="vertical"
-      class="flex w-2.5 touch-none select-none bg-(--bg-inset) p-0.5 transition-colors hover:bg-(--bg-subtle)"
+      class="flex w-2.5 touch-none select-none bg-bg-inset p-0.5 transition-colors hover:bg-bg-subtle"
     >
-      <ScrollAreaThumb class="flex-1 rounded-full bg-(--fg-subtle) transition-colors hover:bg-(--fg-muted)" />
+      <ScrollAreaThumb class="flex-1 rounded-full bg-fg-subtle transition-colors hover:bg-fg-muted" />
     </ScrollAreaScrollbar>
 
     <ScrollAreaScrollbar
       orientation="horizontal"
-      class="flex h-2.5 flex-col touch-none select-none bg-(--bg-inset) p-0.5 transition-colors hover:bg-(--bg-subtle)"
+      class="flex h-2.5 flex-col touch-none select-none bg-bg-inset p-0.5 transition-colors hover:bg-bg-subtle"
     >
-      <ScrollAreaThumb class="flex-1 rounded-full bg-(--fg-subtle) transition-colors hover:bg-(--fg-muted)" />
+      <ScrollAreaThumb class="flex-1 rounded-full bg-fg-subtle transition-colors hover:bg-fg-muted" />
     </ScrollAreaScrollbar>
 
-    <ScrollAreaCorner class="bg-(--bg-inset)" />
+    <ScrollAreaCorner class="bg-bg-inset" />
   </ScrollAreaRoot>
 </template>
diff --git a/vue/primitives/src/scroll-area/index.ts b/vue/primitives/src/display/scroll-area/index.ts
similarity index 86%
rename from vue/primitives/src/scroll-area/index.ts
rename to vue/primitives/src/display/scroll-area/index.ts
index bd7851a..60ed1e8 100644
--- a/vue/primitives/src/scroll-area/index.ts
+++ b/vue/primitives/src/display/scroll-area/index.ts
@@ -1,6 +1,7 @@
 export { default as ScrollAreaCorner, type ScrollAreaCornerProps } from './ScrollAreaCorner.vue';
 export { default as ScrollAreaRoot, type ScrollAreaRootProps } from './ScrollAreaRoot.vue';
 export { default as ScrollAreaScrollbar, type ScrollAreaScrollbarProps } from './ScrollAreaScrollbar.vue';
+export { default as ScrollAreaScrollbarGlimpse, type ScrollAreaScrollbarGlimpseProps } from './ScrollAreaScrollbarGlimpse.vue';
 export { default as ScrollAreaThumb, type ScrollAreaThumbProps } from './ScrollAreaThumb.vue';
 export { default as ScrollAreaViewport, type ScrollAreaViewportProps } from './ScrollAreaViewport.vue';
 export {
diff --git a/vue/primitives/src/scroll-area/types.ts b/vue/primitives/src/display/scroll-area/types.ts
similarity index 94%
rename from vue/primitives/src/scroll-area/types.ts
rename to vue/primitives/src/display/scroll-area/types.ts
index 5cdf72d..2139f61 100644
--- a/vue/primitives/src/scroll-area/types.ts
+++ b/vue/primitives/src/display/scroll-area/types.ts
@@ -1,6 +1,6 @@
 export type ScrollDirection = 'ltr' | 'rtl';
 
-export type ScrollAreaType = 'auto' | 'always' | 'scroll' | 'hover';
+export type ScrollAreaType = 'auto' | 'always' | 'scroll' | 'hover' | 'glimpse';
 
 export interface ScrollAreaSizes {
   content: number;
diff --git a/vue/primitives/src/scroll-area/utils.ts b/vue/primitives/src/display/scroll-area/utils.ts
similarity index 77%
rename from vue/primitives/src/scroll-area/utils.ts
rename to vue/primitives/src/display/scroll-area/utils.ts
index bbfa7ef..2b5dded 100644
--- a/vue/primitives/src/scroll-area/utils.ts
+++ b/vue/primitives/src/display/scroll-area/utils.ts
@@ -1,8 +1,8 @@
+import { clamp } from '@robonen/stdlib';
 import type { ScrollAreaSizes, ScrollDirection } from './types';
 
-export function clamp(value: number, min: number, max: number): number {
-  return Math.min(Math.max(value, min), max);
-}
+// Re-exported so the existing public/test import surface (`./utils`) is preserved.
+export { clamp };
 
 export function toInt(value?: string | null): number {
   return value ? Number.parseInt(value, 10) || 0 : 0;
@@ -68,31 +68,22 @@ export function isScrollingWithinScrollbarBounds(scrollPos: number, maxScrollPos
 }
 
 export function addUnlinkedScrollListener(node: HTMLElement, handler: () => void): () => void {
-  let prev = { left: node.scrollLeft, top: node.scrollTop };
+  // Reuse two scratch number locals across ticks instead of allocating a fresh
+  // `{ left, top }` object every frame: this rAF loop runs for the lifetime of
+  // the component (and 2-4 instances per scroll area), so the per-frame object
+  // was steady GC churn even while idle.
+  let prevLeft = node.scrollLeft;
+  let prevTop = node.scrollTop;
   let raf = 0;
   const loop = () => {
-    const pos = { left: node.scrollLeft, top: node.scrollTop };
-    if (prev.left !== pos.left || prev.top !== pos.top)
+    const left = node.scrollLeft;
+    const top = node.scrollTop;
+    if (prevLeft !== left || prevTop !== top)
       handler();
-    prev = pos;
+    prevLeft = left;
+    prevTop = top;
     raf = globalThis.requestAnimationFrame(loop);
   };
   raf = globalThis.requestAnimationFrame(loop);
   return () => globalThis.cancelAnimationFrame(raf);
 }
-
-export function debounceCallback<T extends (...args: never[]) => void>(fn: T, ms: number) {
-  let id: ReturnType<typeof setTimeout> | null = null;
-  const debounced = ((...args: Parameters<T>) => {
-    if (id !== null)
-      globalThis.clearTimeout(id);
-    id = globalThis.setTimeout(() => fn(...args), ms);
-  }) as T & { cancel: () => void };
-  debounced.cancel = () => {
-    if (id !== null) {
-      globalThis.clearTimeout(id);
-      id = null;
-    }
-  };
-  return debounced;
-}
diff --git a/vue/primitives/src/display/separator/Separator.vue b/vue/primitives/src/display/separator/Separator.vue
new file mode 100644
index 0000000..ddfb647
--- /dev/null
+++ b/vue/primitives/src/display/separator/Separator.vue
@@ -0,0 +1,66 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The two valid layout directions a separator can take. Mirrors the binary
+ * orientation contract shared across orientation-aware primitives.
+ */
+export type SeparatorOrientation = 'horizontal' | 'vertical';
+
+/**
+ * A thin visual divider that separates and gives meaning to groups of content,
+ * such as items in a menu, sections of a toolbar, or rows in a list. Renders
+ * horizontally or vertically and, unless marked `decorative`, exposes
+ * `role="separator"` with the matching `aria-orientation` to assistive
+ * technology. Use it to break up related content into distinct regions.
+ *
+ * For slot-merging composition (rendering onto a consumer-provided element
+ * instead of an extra wrapper) pass `as="template"` — the underlying
+ * `Primitive` merges its props/ref onto the single child of the default slot.
+ */
+export interface SeparatorProps extends PrimitiveProps {
+  /**
+   * The orientation of the separator. Any value other than `'vertical'` is
+   * normalized to `'horizontal'`, so `data-orientation` is always a valid
+   * token even when an unexpected value is supplied.
+   * @default 'horizontal'
+   */
+  orientation?: SeparatorOrientation;
+  /**
+   * When `true` the separator is purely decorative and is hidden from
+   * assistive technology (no role, `aria-hidden`). Otherwise it exposes
+   * `role="separator"` and the correct `aria-orientation`.
+   * @default false
+   */
+  decorative?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+
+const { orientation = 'horizontal', decorative = false, as = 'div' } = defineProps<SeparatorProps>();
+
+const { forwardRef } = useForwardExpose();
+
+// Normalize any unexpected runtime value to a valid token. `aria-orientation`
+// defaults to `horizontal`, so it is only emitted when the separator is
+// actually vertical.
+const resolvedOrientation = computed<SeparatorOrientation>(() =>
+  orientation === 'vertical' ? 'vertical' : 'horizontal');
+
+const ariaProps = computed(() => decorative
+  ? { role: 'none' as const }
+  : {
+      role: 'separator' as const,
+      'aria-orientation': resolvedOrientation.value === 'vertical' ? 'vertical' as const : undefined,
+    });
+</script>
+
+<template>
+  <Primitive :ref="forwardRef" :as="as" :data-orientation="resolvedOrientation" v-bind="ariaProps">
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/display/separator/__test__/Separator.test.ts b/vue/primitives/src/display/separator/__test__/Separator.test.ts
new file mode 100644
index 0000000..5335ffc
--- /dev/null
+++ b/vue/primitives/src/display/separator/__test__/Separator.test.ts
@@ -0,0 +1,95 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h } from 'vue';
+import { Separator } from '../index';
+
+describe('Separator', () => {
+  let wrapper: ReturnType<typeof mount> | undefined;
+
+  afterEach(() => {
+    wrapper?.unmount();
+    wrapper = undefined;
+  });
+
+  it('renders with role="separator" by default', () => {
+    wrapper = mount(Separator);
+    expect(wrapper.attributes('role')).toBe('separator');
+    expect(wrapper.attributes('data-orientation')).toBe('horizontal');
+    expect(wrapper.attributes('aria-orientation')).toBeUndefined();
+  });
+
+  it('sets aria-orientation="vertical" for vertical', () => {
+    wrapper = mount(Separator, { props: { orientation: 'vertical' } });
+    expect(wrapper.attributes('aria-orientation')).toBe('vertical');
+    expect(wrapper.attributes('data-orientation')).toBe('vertical');
+  });
+
+  it('is decorative when requested', () => {
+    wrapper = mount(Separator, { props: { decorative: true } });
+    expect(wrapper.attributes('role')).toBe('none');
+    expect(wrapper.attributes('aria-orientation')).toBeUndefined();
+  });
+
+  it('omits aria-orientation when decorative and vertical', () => {
+    wrapper = mount(Separator, { props: { decorative: true, orientation: 'vertical' } });
+    expect(wrapper.attributes('role')).toBe('none');
+    expect(wrapper.attributes('aria-orientation')).toBeUndefined();
+    // data-orientation still reflects the requested layout for styling hooks.
+    expect(wrapper.attributes('data-orientation')).toBe('vertical');
+  });
+
+  it('supports custom element via `as`', () => {
+    wrapper = mount(Separator, { props: { as: 'hr' } });
+    expect(wrapper.element.tagName).toBe('HR');
+  });
+
+  describe('orientation normalization', () => {
+    it('falls back to horizontal for an unexpected runtime value', () => {
+      // Consumers may pass through a stringly-typed value; the rendered token
+      // must remain a valid `horizontal | vertical` orientation.
+      wrapper = mount(Separator, { props: { orientation: 'diagonal' as never } });
+      expect(wrapper.attributes('data-orientation')).toBe('horizontal');
+      expect(wrapper.attributes('aria-orientation')).toBeUndefined();
+      expect(wrapper.attributes('role')).toBe('separator');
+    });
+
+    it('falls back to horizontal for nullish orientation', () => {
+      wrapper = mount(Separator, { props: { orientation: undefined } });
+      expect(wrapper.attributes('data-orientation')).toBe('horizontal');
+    });
+  });
+
+  describe('slot-merging via as="template"', () => {
+    it('merges role/data-orientation onto the consumer element instead of a wrapper', () => {
+      wrapper = mount(Separator, {
+        props: { as: 'template', orientation: 'vertical' },
+        slots: { default: () => h('span', { class: 'custom' }, 'x') },
+      });
+      const el = wrapper.element as HTMLElement;
+      expect(el.tagName).toBe('SPAN');
+      expect(el.getAttribute('role')).toBe('separator');
+      expect(el.getAttribute('aria-orientation')).toBe('vertical');
+      expect(el.getAttribute('data-orientation')).toBe('vertical');
+      expect(el.classList.contains('custom')).toBe(true);
+    });
+  });
+
+  describe('ref / element forwarding', () => {
+    it('forwards the underlying element to the parent', async () => {
+      let resolved: HTMLElement | null = null;
+      const Parent = defineComponent({
+        setup() {
+          const sep = (el: unknown) => {
+            // useForwardExpose exposes the underlying element via $el.
+            resolved = (el as { $el?: HTMLElement } | null)?.$el ?? null;
+          };
+          return () => h(Separator, { ref: sep as never, 'data-test': 'sep' });
+        },
+      });
+      wrapper = mount(Parent, { attachTo: document.body });
+      await wrapper.vm.$nextTick();
+      expect(resolved).not.toBeNull();
+      expect((resolved as unknown as HTMLElement).getAttribute('data-test')).toBe('sep');
+    });
+  });
+});
diff --git a/vue/primitives/src/display/separator/__test__/a11y.test.ts b/vue/primitives/src/display/separator/__test__/a11y.test.ts
new file mode 100644
index 0000000..a0ba456
--- /dev/null
+++ b/vue/primitives/src/display/separator/__test__/a11y.test.ts
@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import axe from 'axe-core';
+import { Separator } from '../index';
+
+async function violations(element: Element) {
+  const results = await axe.run(element);
+  return results.violations;
+}
+
+describe('Separator a11y', () => {
+  let wrapper: ReturnType<typeof mount> | undefined;
+
+  afterEach(() => {
+    wrapper?.unmount();
+    wrapper = undefined;
+  });
+
+  it('has no axe violations when horizontal', async () => {
+    wrapper = mount(Separator, { attachTo: document.body });
+    expect(await violations(wrapper.element)).toHaveLength(0);
+  });
+
+  it('has no axe violations when vertical', async () => {
+    wrapper = mount(Separator, { props: { orientation: 'vertical' }, attachTo: document.body });
+    expect(await violations(wrapper.element)).toHaveLength(0);
+  });
+
+  it('has no axe violations when decorative', async () => {
+    wrapper = mount(Separator, { props: { decorative: true }, attachTo: document.body });
+    expect(await violations(wrapper.element)).toHaveLength(0);
+  });
+});
diff --git a/vue/primitives/src/separator/demo.vue b/vue/primitives/src/display/separator/demo.vue
similarity index 62%
rename from vue/primitives/src/separator/demo.vue
rename to vue/primitives/src/display/separator/demo.vue
index 7375526..7b62b7e 100644
--- a/vue/primitives/src/separator/demo.vue
+++ b/vue/primitives/src/display/separator/demo.vue
@@ -3,47 +3,47 @@ import { Separator } from '@robonen/primitives';
 </script>
 
 <template>
-  <div class="flex w-full max-w-sm flex-col gap-5 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 text-(--fg)">
+  <div class="demo-card flex w-full max-w-sm flex-col gap-5 p-5 text-fg">
     <div>
       <h3 class="text-sm font-semibold">
         Vue Primitives
       </h3>
-      <p class="text-sm text-(--fg-muted)">
+      <p class="text-sm text-fg-muted">
         Headless, accessible building blocks.
       </p>
     </div>
 
-    <Separator class="h-px bg-(--border)" />
+    <Separator class="h-px bg-border" />
 
     <div class="flex flex-col gap-3">
-      <p class="text-sm text-(--fg-subtle)">
+      <p class="text-sm text-fg-subtle">
         Read the docs, browse the source, or join the community.
       </p>
 
       <div class="flex h-5 items-center gap-3 text-sm">
         <a
           href="#"
-          class="text-(--accent) hover:text-(--accent-hover)"
+          class="text-accent hover:text-accent-hover"
           @click.prevent
         >Docs</a>
         <Separator
           orientation="vertical"
           decorative
-          class="w-px bg-(--border)"
+          class="w-px bg-border"
         />
         <a
           href="#"
-          class="text-(--accent) hover:text-(--accent-hover)"
+          class="text-accent hover:text-accent-hover"
           @click.prevent
         >Source</a>
         <Separator
           orientation="vertical"
           decorative
-          class="w-px bg-(--border)"
+          class="w-px bg-border"
         />
         <a
           href="#"
-          class="text-(--accent) hover:text-(--accent-hover)"
+          class="text-accent hover:text-accent-hover"
           @click.prevent
         >Community</a>
       </div>
diff --git a/vue/primitives/src/display/separator/index.ts b/vue/primitives/src/display/separator/index.ts
new file mode 100644
index 0000000..9238fe9
--- /dev/null
+++ b/vue/primitives/src/display/separator/index.ts
@@ -0,0 +1,2 @@
+export { default as Separator } from './Separator.vue';
+export type { SeparatorOrientation, SeparatorProps } from './Separator.vue';
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuContent.vue b/vue/primitives/src/dropdown-menu/DropdownMenuContent.vue
deleted file mode 100644
index 5d69b1b..0000000
--- a/vue/primitives/src/dropdown-menu/DropdownMenuContent.vue
+++ /dev/null
@@ -1,46 +0,0 @@
-<script lang="ts">
-import type { MenuContentEmits, MenuContentProps } from '../menu';
-
-/**
- * The floating surface that holds the menu items, positioned relative to the
- * trigger. Handles focus management, typeahead, and dismissal on outside click
- * or Escape; render it inside a portal so it escapes overflow clipping.
- */
-export interface DropdownMenuContentProps extends MenuContentProps {}
-export type DropdownMenuContentEmits = MenuContentEmits;
-</script>
-
-<script setup lang="ts">
-import { MenuContent } from '../menu';
-import { useDropdownMenuRootContext } from './context';
-
-const props = defineProps<DropdownMenuContentProps>();
-const emit = defineEmits<DropdownMenuContentEmits>();
-const ddCtx = useDropdownMenuRootContext();
-</script>
-
-<template>
-  <MenuContent
-    v-bind="props"
-    :id="ddCtx.contentId.value"
-    :aria-labelledby="ddCtx.triggerId.value"
-    @close-auto-focus="emit('closeAutoFocus', $event)"
-    @escape-key-down="emit('escapeKeyDown', $event)"
-    @pointer-down-outside="(event: PointerEvent | MouseEvent) => {
-      const target = event.target as Node
-      // The trigger owns pointerdown toggling — letting the layer also dismiss
-      // here would close the menu before the trigger handler runs and make its
-      // toggle reopen it.
-      const isTriggerPointerDown = ddCtx.triggerRef.value?.contains(target)
-      if (isTriggerPointerDown) event.preventDefault()
-      emit('pointerDownOutside', event)
-    }"
-    @focus-outside="emit('focusOutside', $event)"
-    @interact-outside="emit('interactOutside', $event)"
-    @dismiss="emit('dismiss')"
-    @entry-focus="emit('entryFocus', $event)"
-    @open-auto-focus="emit('openAutoFocus', $event)"
-  >
-    <slot />
-  </MenuContent>
-</template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSub.vue b/vue/primitives/src/dropdown-menu/DropdownMenuSub.vue
deleted file mode 100644
index 61c8408..0000000
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSub.vue
+++ /dev/null
@@ -1,22 +0,0 @@
-<script lang="ts">
-import type { MenuSubEmits, MenuSubProps } from '../menu';
-
-/**
- * Wraps a nested submenu, pairing a DropdownMenuSubTrigger with its
- * DropdownMenuSubContent. Owns the submenu's open state; bind `v-model:open`
- * to control or observe it.
- */
-export interface DropdownMenuSubProps extends MenuSubProps {}
-export type DropdownMenuSubEmits = MenuSubEmits;
-</script>
-
-<script setup lang="ts">
-import { MenuSub } from '../menu';
-
-const props = defineProps<DropdownMenuSubProps>();
-const emit = defineEmits<DropdownMenuSubEmits>();
-</script>
-
-<template>
-  <MenuSub v-bind="props" @update:open="emit('update:open', $event)"><slot /></MenuSub>
-</template>
diff --git a/vue/primitives/src/dropdown-menu/__test__/DropdownMenu.test.ts b/vue/primitives/src/dropdown-menu/__test__/DropdownMenu.test.ts
deleted file mode 100644
index 0422d88..0000000
--- a/vue/primitives/src/dropdown-menu/__test__/DropdownMenu.test.ts
+++ /dev/null
@@ -1,146 +0,0 @@
-import type { VueWrapper } from '@vue/test-utils';
-import { mount } from '@vue/test-utils';
-import { afterEach, describe, expect, it } from 'vitest';
-import { defineComponent, h, nextTick } from 'vue';
-
-import {
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuPortal,
-  DropdownMenuRoot,
-  DropdownMenuTrigger,
-} from '../index';
-
-const wrappers: Array<VueWrapper<any>> = [];
-
-afterEach(() => {
-  while (wrappers.length) wrappers.pop()!.unmount();
-  document.body.innerHTML = '';
-});
-
-function track<T extends VueWrapper<any>>(w: T): T {
-  wrappers.push(w);
-  return w;
-}
-
-function mountMenu(opts: { modal?: boolean } = {}) {
-  const Harness = defineComponent({
-    setup() {
-      return () => h(
-        DropdownMenuRoot,
-        { modal: opts.modal },
-        {
-          default: () => [
-            h(
-              DropdownMenuTrigger,
-              { 'data-testid': 'trigger', class: 'demo-trigger' },
-              { default: () => 'Open' },
-            ),
-            h(DropdownMenuPortal, null, {
-              default: () => h(DropdownMenuContent, null, {
-                default: () => [
-                  h(DropdownMenuItem, null, { default: () => 'One' }),
-                  h(DropdownMenuItem, null, { default: () => 'Two' }),
-                ],
-              }),
-            }),
-          ],
-        },
-      );
-    },
-  });
-  return track(mount(Harness, { attachTo: document.body }));
-}
-
-function trigger(): HTMLElement {
-  return document.querySelector<HTMLElement>('[data-testid="trigger"]')!;
-}
-
-function menu(): HTMLElement | null {
-  return document.querySelector<HTMLElement>('[role="menu"]');
-}
-
-function pointerDown(el: EventTarget) {
-  el.dispatchEvent(new PointerEvent('pointerdown', {
-    bubbles: true,
-    cancelable: true,
-    composed: true,
-    button: 0,
-    pointerId: 1,
-    pointerType: 'mouse',
-  }));
-}
-
-async function flush() {
-  await nextTick();
-  await nextTick();
-}
-
-describe('dropdownMenu — trigger renders as the anchor itself', () => {
-  it('merges fallthrough attrs onto the trigger button (no anchor wrapper element)', () => {
-    mountMenu();
-    const el = trigger();
-    // Pre-fix, MenuAnchor rendered a real <div> wrapper that swallowed
-    // fallthrough attrs while data-state/aria stayed on the inner button.
-    expect(el.tagName).toBe('BUTTON');
-    expect(el.classList.contains('demo-trigger')).toBe(true);
-    expect(el.getAttribute('aria-haspopup')).toBe('menu');
-    expect(el.getAttribute('data-state')).toBe('closed');
-    expect(el.querySelector('button')).toBeNull();
-  });
-
-  it('flips data-state/aria-expanded on the attr-bearing element when opened', async () => {
-    mountMenu({ modal: false });
-    pointerDown(trigger());
-    await flush();
-    expect(menu()).toBeTruthy();
-    expect(trigger().getAttribute('data-state')).toBe('open');
-    expect(trigger().getAttribute('aria-expanded')).toBe('true');
-  });
-});
-
-describe('dropdownMenu — trigger pointerdown toggling (non-modal)', () => {
-  it('closes on trigger pointerdown while open and does not reopen from the dismiss race', async () => {
-    mountMenu({ modal: false });
-
-    pointerDown(trigger());
-    await flush();
-    expect(menu()).toBeTruthy();
-
-    // The outside-pointerdown dismiss (window capture) runs before the
-    // trigger's own handler — without the content-side guard the menu would
-    // close via dismiss and instantly reopen via the trigger toggle.
-    pointerDown(trigger());
-    await flush();
-    expect(menu()).toBeNull();
-    expect(trigger().getAttribute('data-state')).toBe('closed');
-
-    await flush();
-    expect(menu()).toBeNull();
-  });
-
-  it('reopens on the next trigger pointerdown after a toggle-close', async () => {
-    mountMenu({ modal: false });
-
-    pointerDown(trigger());
-    await flush();
-    pointerDown(trigger());
-    await flush();
-    expect(menu()).toBeNull();
-
-    pointerDown(trigger());
-    await flush();
-    expect(menu()).toBeTruthy();
-    expect(trigger().getAttribute('data-state')).toBe('open');
-  });
-});
-
-describe('dropdownMenu — trigger keyboard open', () => {
-  it('opens the menu on Enter', async () => {
-    mountMenu({ modal: false });
-    trigger().dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
-    await flush();
-    expect(menu()).toBeTruthy();
-    expect(trigger().getAttribute('data-state')).toBe('open');
-  });
-});
diff --git a/vue/primitives/src/dropdown-menu/context.ts b/vue/primitives/src/dropdown-menu/context.ts
deleted file mode 100644
index b8304ac..0000000
--- a/vue/primitives/src/dropdown-menu/context.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import type { ComputedRef, ShallowRef } from 'vue';
-
-import { useContextFactory } from '@robonen/vue';
-
-export interface DropdownMenuRootContext {
-  triggerId: ComputedRef<string>;
-  triggerRef: ShallowRef<HTMLElement | null>;
-  contentId: ComputedRef<string>;
-  onTriggerChange: (el: HTMLElement | null) => void;
-}
-
-export const {
-  inject: useDropdownMenuRootContext,
-  provide: provideDropdownMenuRootContext,
-} = useContextFactory<DropdownMenuRootContext>('DropdownMenuRootContext');
diff --git a/vue/primitives/src/feedback/toast/ToastAction.vue b/vue/primitives/src/feedback/toast/ToastAction.vue
new file mode 100644
index 0000000..a353389
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastAction.vue
@@ -0,0 +1,47 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * An actionable control inside a toast (e.g. "Undo" or "View"). Renders a button by
+ * default and requires `altText` so the action remains understandable to assistive
+ * technology even when the toast is announced out of context — `altText` is read by
+ * the announce region in place of the button's visible label.
+ */
+export interface ToastActionProps extends PrimitiveProps {
+  /**
+   * Accessible description for screen readers (required).
+   * Describes what happens when the user triggers the action.
+   */
+  altText: string;
+}
+</script>
+
+<script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
+
+import { Primitive } from '../../internal/primitive';
+import ToastAnnounceExclude from './ToastAnnounceExclude.vue';
+
+const { as = 'button', altText } = defineProps<ToastActionProps>();
+
+if (!altText)
+  throw new Error('Missing required prop `altText` on `ToastAction`.');
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <ToastAnnounceExclude
+    as="template"
+    :alt-text="altText"
+  >
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :aria-label="altText"
+      data-primitives-toast-action
+    >
+      <slot />
+    </Primitive>
+  </ToastAnnounceExclude>
+</template>
diff --git a/vue/primitives/src/feedback/toast/ToastAnnounce.vue b/vue/primitives/src/feedback/toast/ToastAnnounce.vue
new file mode 100644
index 0000000..39e9797
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastAnnounce.vue
@@ -0,0 +1,67 @@
+<script lang="ts">
+/**
+ * A visually-hidden live region that mirrors a toast's text for screen readers.
+ *
+ * The visible toast is announced via `aria-live` directly, but some screen
+ * readers (notably NVDA) only reliably announce live-region content that is
+ * injected *after* the region is already in the accessibility tree. This part
+ * therefore mounts empty and injects its text on the next frame (double
+ * `requestAnimationFrame`), with a 1s timeout fallback so the announcement
+ * still happens if frames are throttled (e.g. a background tab).
+ */
+export interface ToastAnnounceProps {
+  /** `aria-live` politeness for the announce region. */
+  ariaLive?: 'assertive' | 'polite';
+}
+</script>
+
+<script setup lang="ts">
+import { onScopeDispose, ref } from 'vue';
+
+import { isClient } from '@robonen/platform/multi';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+import { useToastProviderContext } from './context';
+
+defineProps<ToastAnnounceProps>();
+
+const providerCtx = useToastProviderContext();
+
+const renderAnnounceText = ref(false);
+
+let raf1 = 0;
+let raf2 = 0;
+let fallbackTimer: ReturnType<typeof setTimeout> | undefined;
+
+if (isClient) {
+  raf1 = requestAnimationFrame(() => {
+    raf2 = requestAnimationFrame(() => {
+      renderAnnounceText.value = true;
+    });
+  });
+
+  // Fallback in case rAF is throttled (background tab) — still announce.
+  fallbackTimer = setTimeout(() => {
+    renderAnnounceText.value = true;
+  }, 1000);
+
+  onScopeDispose(() => {
+    cancelAnimationFrame(raf1);
+    cancelAnimationFrame(raf2);
+    if (fallbackTimer) clearTimeout(fallbackTimer);
+  });
+}
+</script>
+
+<template>
+  <VisuallyHidden
+    v-if="renderAnnounceText"
+    feature="hidden"
+    role="status"
+    :aria-live="ariaLive"
+    :aria-atomic="true"
+    data-primitives-toast-announce
+  >
+    {{ providerCtx.label.value }}
+    <slot />
+  </VisuallyHidden>
+</template>
diff --git a/vue/primitives/src/feedback/toast/ToastAnnounceExclude.vue b/vue/primitives/src/feedback/toast/ToastAnnounceExclude.vue
new file mode 100644
index 0000000..8f37a27
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastAnnounceExclude.vue
@@ -0,0 +1,30 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Excludes its subtree from the screen-reader announcement harvested by
+ * `ToastAnnounce`. Use it around content whose visible text is meaningless out
+ * of context (e.g. an icon-only button) — optionally provide `altText` to be
+ * announced in its place. `ToastAction` and `ToastClose` use this internally.
+ */
+export interface ToastAnnounceExcludeProps extends PrimitiveProps {
+  /** Text announced in place of the excluded subtree. */
+  altText?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+
+const { as = 'div', altText } = defineProps<ToastAnnounceExcludeProps>();
+</script>
+
+<template>
+  <Primitive
+    :as="as"
+    data-primitives-toast-announce-exclude=""
+    :data-primitives-toast-announce-alt="altText || undefined"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/feedback/toast/ToastClose.vue b/vue/primitives/src/feedback/toast/ToastClose.vue
new file mode 100644
index 0000000..b70151c
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastClose.vue
@@ -0,0 +1,41 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A button that dismisses the toast it lives in. Renders a button by default and
+ * closes the parent `ToastRoot` via toast context on click. Its visible content
+ * is excluded from the screen-reader announcement (an icon-only "×" carries no
+ * meaning out of context).
+ */
+export interface ToastCloseProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useToastContext } from './context';
+import ToastAnnounceExclude from './ToastAnnounceExclude.vue';
+
+const { as = 'button' } = defineProps<ToastCloseProps>();
+const { forwardRef } = useForwardExpose();
+const toastCtx = useToastContext();
+
+// Avoid an implicit form submit when rendered as a native button.
+const buttonType = computed(() => (as === 'button' ? 'button' : undefined));
+</script>
+
+<template>
+  <ToastAnnounceExclude as="template">
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :type="buttonType"
+      data-primitives-toast-close
+      @click="toastCtx.onClose()"
+    >
+      <slot />
+    </Primitive>
+  </ToastAnnounceExclude>
+</template>
diff --git a/vue/primitives/src/toast/ToastDescription.vue b/vue/primitives/src/feedback/toast/ToastDescription.vue
similarity index 82%
rename from vue/primitives/src/toast/ToastDescription.vue
rename to vue/primitives/src/feedback/toast/ToastDescription.vue
index e98c45a..e8f091e 100644
--- a/vue/primitives/src/toast/ToastDescription.vue
+++ b/vue/primitives/src/feedback/toast/ToastDescription.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The toast's supporting text. Renders the longer description beneath the
@@ -11,7 +11,7 @@ export interface ToastDescriptionProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'div' } = defineProps<ToastDescriptionProps>();
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/feedback/toast/ToastFocusProxy.vue b/vue/primitives/src/feedback/toast/ToastFocusProxy.vue
new file mode 100644
index 0000000..3d9dfe1
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastFocusProxy.vue
@@ -0,0 +1,39 @@
+<script lang="ts">
+/**
+ * A visually-hidden focusable sentinel placed at the head and tail of the toast
+ * viewport. Because the viewport is portaled, its tab order does not match the
+ * document; these proxies let `Tab`/`Shift+Tab` re-enter the toast list from the
+ * surrounding document. When focus arrives from outside the viewport, the proxy
+ * emits `focusFromOutsideViewport` so the viewport can redirect focus to a toast.
+ */
+export interface ToastFocusProxyEmits {
+  focusFromOutsideViewport: [event: FocusEvent];
+}
+</script>
+
+<script setup lang="ts">
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+import { useToastProviderContext } from './context';
+
+const emit = defineEmits<ToastFocusProxyEmits>();
+
+const providerCtx = useToastProviderContext();
+
+function handleFocus(event: FocusEvent) {
+  const prevFocused = event.relatedTarget as HTMLElement | null;
+  const isFromOutside = !providerCtx.viewportRef.value?.contains(prevFocused);
+  if (isFromOutside) emit('focusFromOutsideViewport', event);
+}
+</script>
+
+<template>
+  <VisuallyHidden
+    aria-hidden="true"
+    tabindex="0"
+    data-primitives-toast-focus-proxy
+    style="position: fixed"
+    @focus="handleFocus"
+  >
+    <slot />
+  </VisuallyHidden>
+</template>
diff --git a/vue/primitives/src/feedback/toast/ToastPortal.vue b/vue/primitives/src/feedback/toast/ToastPortal.vue
new file mode 100644
index 0000000..cac4e04
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastPortal.vue
@@ -0,0 +1,22 @@
+<script lang="ts">
+import type { TeleportPrimitiveProps } from '../../utilities/teleport';
+
+/**
+ * Renders the toast viewport into a different part of the DOM (a portal), so it
+ * escapes parent overflow/stacking contexts. Wrap `ToastViewport` in this part
+ * to mount it at the document body (default) or a custom container via `to`.
+ */
+export interface ToastPortalProps extends TeleportPrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Teleport as TeleportPrimitive } from '../../utilities/teleport';
+
+const props = defineProps<ToastPortalProps>();
+</script>
+
+<template>
+  <TeleportPrimitive v-bind="props">
+    <slot />
+  </TeleportPrimitive>
+</template>
diff --git a/vue/primitives/src/toast/ToastProvider.vue b/vue/primitives/src/feedback/toast/ToastProvider.vue
similarity index 62%
rename from vue/primitives/src/toast/ToastProvider.vue
rename to vue/primitives/src/feedback/toast/ToastProvider.vue
index fd659ef..2612246 100644
--- a/vue/primitives/src/toast/ToastProvider.vue
+++ b/vue/primitives/src/feedback/toast/ToastProvider.vue
@@ -7,61 +7,63 @@ import type { SwipeDirection } from './context';
  * background events without interrupting the user's flow.
  *
  * `ToastProvider` is the top-level wrapper that holds shared settings (label, default
- * duration) and coordinates timer pausing across all toasts. Wrap your app (or the
- * region that renders toasts) in a single provider, render one `ToastViewport` for
- * placement, and mount a `ToastRoot` per notification.
+ * duration, swipe behaviour) and coordinates timer pausing across all toasts. Wrap
+ * your app (or the region that renders toasts) in a single provider, render one
+ * `ToastViewport` for placement, and mount a `ToastRoot` per notification.
  */
 export interface ToastProviderProps {
   /** Accessible label for the toast region. @default 'Notifications' */
   label?: string;
   /** Auto-dismiss duration in ms. Use `Infinity` to disable auto-dismiss. @default 5000 */
   duration?: number;
-  /**
-   * Swipe direction to dismiss.
-   *
-   * NOTE: swipe-to-dismiss is not yet implemented. This value is stored and exposed via
-   * context for forward compatibility, but no swipe gesture is currently wired up.
-   * @default 'right'
-   */
+  /** Swipe direction that dismisses a toast. @default 'right' */
   swipeDirection?: SwipeDirection;
-  /**
-   * Minimum swipe distance before a dismiss gesture is recognised.
-   *
-   * NOTE: swipe-to-dismiss is not yet implemented (see `swipeDirection`); this value has
-   * no effect until a swipe gesture is added.
-   * @default 50
-   */
+  /** Minimum swipe distance (px) before a dismiss gesture is recognised. @default 50 */
   swipeThreshold?: number;
+  /** Disable swipe-to-dismiss gestures for every toast. @default false */
+  disableSwipe?: boolean;
 }
 </script>
 
 <script setup lang="ts">
 import { ref, shallowRef, toRef } from 'vue';
 
+import { useCollectionProvider } from '../../utilities/collection';
 import { provideToastProviderContext } from './context';
+import { TOAST_COLLECTION_KEY } from './shared';
 
 const {
   label = 'Notifications',
   duration = 5000,
   swipeDirection = 'right',
   swipeThreshold = 50,
+  disableSwipe = false,
 } = defineProps<ToastProviderProps>();
 
+if (typeof label === 'string' && label.trim() === '')
+  throw new Error('Invalid prop `label` supplied to `ToastProvider`. Expected a non-empty string.');
+
 const labelRef = toRef(() => label);
 const durationRef = toRef(() => duration);
 const swipeDirectionRef = toRef(() => swipeDirection);
 const swipeThresholdRef = toRef(() => swipeThreshold);
+const disableSwipeRef = toRef(() => disableSwipe);
 
 const toastCount = ref(0);
 const viewportRef = shallowRef<HTMLElement | undefined>(undefined);
 const isFocusedToastEscapeKeyDownRef = ref(false);
 const isClosePausedRef = ref(false);
 
+// Dedicated collection key so a nested collection provider (or another toast
+// provider) does not shadow this one for descendant toasts/viewports.
+useCollectionProvider(TOAST_COLLECTION_KEY);
+
 provideToastProviderContext({
   label: labelRef,
   duration: durationRef,
   swipeDirection: swipeDirectionRef,
   swipeThreshold: swipeThresholdRef,
+  disableSwipe: disableSwipeRef,
   toastCount,
   viewportRef,
   onViewportChange: (el) => { viewportRef.value = el; },
diff --git a/vue/primitives/src/feedback/toast/ToastRoot.vue b/vue/primitives/src/feedback/toast/ToastRoot.vue
new file mode 100644
index 0000000..09a6f82
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastRoot.vue
@@ -0,0 +1,452 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { SwipeEvent } from './utils';
+
+/**
+ * A single toast notification. Manages its own open state and auto-dismiss timer,
+ * and provides context to its `Title`, `Description`, `Action`, and `Close` children.
+ * Control visibility with `v-model:open`; rendering is gated by `Presence` so exit
+ * transitions can play before the element unmounts.
+ *
+ * The default slot receives `{ open, remaining, duration }` so you can render a
+ * progress bar or countdown synced to the dismiss timer.
+ */
+export interface ToastRootProps extends PrimitiveProps {
+  /** Override the provider's auto-dismiss duration. Use `Infinity` to disable. */
+  duration?: number;
+  /** Toast type — controls the `aria-live` politeness. @default 'background' */
+  type?: 'foreground' | 'background';
+  /** Initial open state for the uncontrolled mode (when `v-model:open` is not bound). @default true */
+  defaultOpen?: boolean;
+  /** Force the toast to stay mounted regardless of `open` (useful with external animation libraries). */
+  forceMount?: boolean;
+  /**
+   * Teleport this toast into the `ToastViewport` and register it for keyboard
+   * focus ordering. Lets toasts be authored anywhere in the tree. When the
+   * viewport is not mounted yet, the toast renders in place as a fallback.
+   * @default false
+   */
+  toViewport?: boolean;
+}
+
+// Stable, stateless once-listener reused across swipe gestures so pointerup does
+// not allocate a fresh closure per gesture end.
+const preventClickOnce = (event: Event) => event.preventDefault();
+
+export interface ToastRootEmits {
+  escapeKeyDown: [event: KeyboardEvent];
+  pause: [];
+  resume: [];
+  swipeStart: [event: SwipeEvent];
+  swipeMove: [event: SwipeEvent];
+  swipeCancel: [event: SwipeEvent];
+  swipeEnd: [event: SwipeEvent];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, toRef, watch } from 'vue';
+
+import { focus, getActiveElement } from '@robonen/platform/browsers';
+import { useForwardExpose, useRafFn } from '@robonen/vue';
+import { useCollectionInjector } from '../../utilities/collection';
+import { useId } from '../../utilities/config-provider';
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
+import { Teleport as TeleportPrimitive } from '../../utilities/teleport';
+import ToastAnnounce from './ToastAnnounce.vue';
+import { provideToastContext, useToastProviderContext } from './context';
+import { TOAST_COLLECTION_KEY } from './shared';
+import {
+  TOAST_SWIPE_CANCEL,
+  TOAST_SWIPE_END,
+  TOAST_SWIPE_MOVE,
+  TOAST_SWIPE_START,
+  VIEWPORT_PAUSE,
+  VIEWPORT_RESUME,
+  getAnnounceTextContent,
+  handleAndDispatchCustomEvent,
+  isDeltaInDirection,
+} from './utils';
+
+defineOptions({
+  inheritAttrs: false,
+});
+
+const {
+  as = 'li',
+  duration,
+  type = 'background',
+  defaultOpen = true,
+  forceMount,
+  toViewport = false,
+} = defineProps<ToastRootProps>();
+
+const emit = defineEmits<ToastRootEmits>();
+
+if (type !== 'foreground' && type !== 'background')
+  throw new Error('Invalid prop `type` supplied to `ToastRoot`. Expected `foreground | background`.');
+
+const { forwardRef, currentElement } = useForwardExpose();
+const providerCtx = useToastProviderContext();
+const { CollectionItem } = useCollectionInjector(TOAST_COLLECTION_KEY);
+const toastId = useId(undefined, 'toast');
+const durationRef = toRef(() => duration);
+
+const localOpen = ref(defaultOpen);
+const open = defineModel<boolean>('open', {
+  default: undefined,
+  get: external => external ?? localOpen.value,
+  set: (value) => {
+    localOpen.value = value;
+    return value;
+  },
+});
+
+const resolvedDuration = computed(() => durationRef.value ?? providerCtx.duration.value);
+
+// Swipe gesture state. Plain mutable locals — read/written only inside the JS
+// pointer handlers, never bound in the template and no computed depends on them,
+// so they need no reactivity. Keeping them non-reactive avoids per-pointer-move
+// proxy wrapping of the fresh {x,y} object and dep track/trigger with zero subscribers.
+let pointerStart: { x: number; y: number } | null = null;
+let swipeDelta: { x: number; y: number } | null = null;
+
+// Elapsed-time-preserving timer state. On pause we bank the remaining time and
+// on resume we continue from it, rather than restarting the full duration.
+let closeTimer: ReturnType<typeof setTimeout> | null = null;
+let closeTimerStartTime = 0;
+let closeTimerRemaining = resolvedDuration.value;
+
+const remaining = ref(resolvedDuration.value);
+
+const remainingRaf = useRafFn(() => {
+  const elapsed = Date.now() - closeTimerStartTime;
+  remaining.value = Math.max(closeTimerRemaining - elapsed, 0);
+}, { immediate: false, fpsLimit: 60 });
+
+function clearTimer() {
+  if (closeTimer) {
+    clearTimeout(closeTimer);
+    closeTimer = null;
+  }
+}
+
+function startTimer(ms: number) {
+  clearTimer();
+  if (ms === Infinity || ms <= 0 || !Number.isFinite(ms)) return;
+  closeTimerStartTime = Date.now();
+  closeTimer = setTimeout(() => {
+    open.value = false;
+  }, ms);
+}
+
+function handleClose() {
+  // Move focus back to the viewport when the closing toast holds focus, so SR
+  // users keep context and focus is not lost to the document body.
+  const active = getActiveElement();
+  const isFocusInToast = !!currentElement.value && !!active && currentElement.value.contains(active);
+  if (isFocusInToast) focus(providerCtx.viewportRef.value);
+
+  providerCtx.isClosePausedRef.value = false;
+  open.value = false;
+}
+
+function handleEscapeKeyDown(event: KeyboardEvent) {
+  emit('escapeKeyDown', event);
+  // Pressing Escape while a toast is focused dismisses it (matches the
+  // ToastClose / auto-dismiss path).
+  if (!event.defaultPrevented) {
+    providerCtx.isFocusedToastEscapeKeyDownRef.value = true;
+    handleClose();
+  }
+}
+
+function pauseTimer() {
+  // Bank the time already elapsed so resume continues from the remainder.
+  const elapsed = Date.now() - closeTimerStartTime;
+  closeTimerRemaining = Math.max(closeTimerRemaining - elapsed, 0);
+  clearTimer();
+  remainingRaf.pause();
+  providerCtx.isClosePausedRef.value = true;
+  emit('pause');
+}
+
+function resumeTimer() {
+  providerCtx.isClosePausedRef.value = false;
+  startTimer(closeTimerRemaining);
+  remainingRaf.resume();
+  emit('resume');
+}
+
+// Restart timer when reactive duration changes (and we are not paused).
+watch(
+  resolvedDuration,
+  (ms) => {
+    closeTimerRemaining = ms;
+    remaining.value = ms;
+    if (!open.value) return;
+    if (providerCtx.isClosePausedRef.value) return;
+    startTimer(ms);
+  },
+);
+
+watch(open, (value) => {
+  if (value) {
+    closeTimerRemaining = resolvedDuration.value;
+    remaining.value = resolvedDuration.value;
+    if (!providerCtx.isClosePausedRef.value) {
+      startTimer(closeTimerRemaining);
+      remainingRaf.resume();
+    }
+  }
+  else {
+    clearTimer();
+    remainingRaf.pause();
+  }
+});
+
+const dataState = computed(() => (open.value ? 'open' : 'closed'));
+const ariaLive = computed(() => (type === 'foreground' ? 'assertive' : 'polite'));
+
+// Harvested text chunks for the dedicated screen-reader announce region. Reading
+// `currentElement` keeps this in sync once the visible toast has mounted; the
+// announce region defers rendering with a double rAF so the harvested text is
+// present by the time it lands in the accessibility tree.
+const announceText = computed(() =>
+  currentElement.value ? getAnnounceTextContent(currentElement.value) : [],
+);
+
+// Swipe gesture handlers — only active when swipe is enabled on the provider.
+function onPointerDown(event: PointerEvent) {
+  if (providerCtx.disableSwipe.value || event.button !== 0) return;
+  pointerStart = { x: event.clientX, y: event.clientY };
+}
+
+function onPointerMove(event: PointerEvent) {
+  if (providerCtx.disableSwipe.value || !pointerStart) return;
+
+  const x = event.clientX - pointerStart.x;
+  const y = event.clientY - pointerStart.y;
+  const hasSwipeMoveStarted = Boolean(swipeDelta);
+  const direction = providerCtx.swipeDirection.value;
+  const isHorizontal = direction === 'left' || direction === 'right';
+  const clamp = direction === 'left' || direction === 'up' ? Math.min : Math.max;
+  const clampedX = isHorizontal ? clamp(0, x) : 0;
+  const clampedY = !isHorizontal ? clamp(0, y) : 0;
+  const moveStartBuffer = event.pointerType === 'touch' ? 10 : 2;
+  const delta = { x: clampedX, y: clampedY };
+  const detail = { originalEvent: event, delta };
+
+  if (hasSwipeMoveStarted) {
+    swipeDelta = delta;
+    handleAndDispatchCustomEvent(TOAST_SWIPE_MOVE, onSwipeMove, detail);
+  }
+  else if (isDeltaInDirection(delta, direction, moveStartBuffer)) {
+    swipeDelta = delta;
+    handleAndDispatchCustomEvent(TOAST_SWIPE_START, onSwipeStart, detail);
+    (event.target as HTMLElement).setPointerCapture(event.pointerId);
+  }
+  else if (Math.abs(x) > moveStartBuffer || Math.abs(y) > moveStartBuffer) {
+    // Swiping in the wrong direction — abandon the gesture for this interaction.
+    pointerStart = null;
+  }
+}
+
+function onPointerUp(event: PointerEvent) {
+  if (providerCtx.disableSwipe.value) return;
+
+  const delta = swipeDelta;
+  const target = event.target as HTMLElement;
+  if (target.hasPointerCapture(event.pointerId))
+    target.releasePointerCapture(event.pointerId);
+
+  swipeDelta = null;
+  pointerStart = null;
+
+  if (!delta) return;
+
+  const toast = event.currentTarget as HTMLElement | null;
+  const detail = { originalEvent: event, delta };
+
+  if (isDeltaInDirection(delta, providerCtx.swipeDirection.value, providerCtx.swipeThreshold.value))
+    handleAndDispatchCustomEvent(TOAST_SWIPE_END, onSwipeEnd, detail);
+  else
+    handleAndDispatchCustomEvent(TOAST_SWIPE_CANCEL, onSwipeCancel, detail);
+
+  // Prevent a click firing on toast contents when pointerup ends a swipe.
+  toast?.addEventListener('click', preventClickOnce, { once: true });
+}
+
+function setSwipeVar(el: HTMLElement, name: string, value: string | null) {
+  if (value === null) el.style.removeProperty(name);
+  else el.style.setProperty(name, value);
+}
+
+// These run as the once-listener inside `handleAndDispatchCustomEvent`. They
+// forward the Vue emit (so consumers can `preventDefault()` the SwipeEvent) and,
+// unless prevented, apply the `data-swipe` state + CSS custom properties used to
+// drive swipe animations.
+function onSwipeStart(event: SwipeEvent) {
+  emit('swipeStart', event);
+  if (event.defaultPrevented) return;
+  event.currentTarget.setAttribute('data-swipe', 'start');
+}
+
+function onSwipeMove(event: SwipeEvent) {
+  emit('swipeMove', event);
+  if (event.defaultPrevented) return;
+  const { x, y } = event.detail.delta;
+  const el = event.currentTarget;
+  el.setAttribute('data-swipe', 'move');
+  setSwipeVar(el, '--primitives-toast-swipe-move-x', `${x}px`);
+  setSwipeVar(el, '--primitives-toast-swipe-move-y', `${y}px`);
+}
+
+function onSwipeCancel(event: SwipeEvent) {
+  emit('swipeCancel', event);
+  if (event.defaultPrevented) return;
+  const el = event.currentTarget;
+  el.setAttribute('data-swipe', 'cancel');
+  setSwipeVar(el, '--primitives-toast-swipe-move-x', null);
+  setSwipeVar(el, '--primitives-toast-swipe-move-y', null);
+  setSwipeVar(el, '--primitives-toast-swipe-end-x', null);
+  setSwipeVar(el, '--primitives-toast-swipe-end-y', null);
+}
+
+function onSwipeEnd(event: SwipeEvent) {
+  emit('swipeEnd', event);
+  if (event.defaultPrevented) return;
+  const { x, y } = event.detail.delta;
+  const el = event.currentTarget;
+  el.setAttribute('data-swipe', 'end');
+  setSwipeVar(el, '--primitives-toast-swipe-move-x', null);
+  setSwipeVar(el, '--primitives-toast-swipe-move-y', null);
+  setSwipeVar(el, '--primitives-toast-swipe-end-x', `${x}px`);
+  setSwipeVar(el, '--primitives-toast-swipe-end-y', `${y}px`);
+  open.value = false;
+}
+
+const swipeStyle = computed(() =>
+  providerCtx.disableSwipe.value ? undefined : { userSelect: 'none', touchAction: 'none' } as const,
+);
+
+const useTeleport = computed(() => toViewport && !!providerCtx.viewportRef.value);
+
+onMounted(() => {
+  providerCtx.onToastAdd();
+  if (open.value && !providerCtx.isClosePausedRef.value) {
+    startTimer(closeTimerRemaining);
+    remainingRaf.resume();
+  }
+
+  const viewport = providerCtx.viewportRef.value;
+  if (viewport) {
+    viewport.addEventListener(VIEWPORT_PAUSE, pauseTimer);
+    viewport.addEventListener(VIEWPORT_RESUME, resumeTimer);
+  }
+});
+
+onBeforeUnmount(() => {
+  providerCtx.onToastRemove();
+  clearTimer();
+  remainingRaf.pause();
+
+  const viewport = providerCtx.viewportRef.value;
+  if (viewport) {
+    viewport.removeEventListener(VIEWPORT_PAUSE, pauseTimer);
+    viewport.removeEventListener(VIEWPORT_RESUME, resumeTimer);
+  }
+});
+
+provideToastContext({
+  onClose: handleClose,
+  duration: durationRef,
+  open,
+  toastId,
+});
+</script>
+
+<template>
+  <ToastAnnounce
+    v-if="open && announceText.length > 0"
+    :aria-live="ariaLive"
+  >
+    <!--
+      Render each harvested chunk as its own text node so screen readers get a
+      natural pause break between the title and description. Interpolating the
+      array directly would route through `toDisplayString` and announce literal
+      brackets/commas instead.
+    -->
+    <template
+      v-for="(text, i) in announceText"
+      :key="i"
+    >
+      {{ text }}
+    </template>
+  </ToastAnnounce>
+
+  <TeleportPrimitive
+    v-if="useTeleport"
+    :to="providerCtx.viewportRef.value"
+    :force-mount="true"
+  >
+    <Presence :present="forceMount || open">
+      <CollectionItem>
+        <Primitive
+          :ref="forwardRef"
+          :as="as"
+          v-bind="$attrs"
+          role="status"
+          :aria-live="ariaLive"
+          :aria-atomic="true"
+          :data-state="dataState"
+          :data-type="type"
+          :data-swipe-direction="providerCtx.swipeDirection.value"
+          tabindex="-1"
+          :style="swipeStyle"
+          @keydown.escape="handleEscapeKeyDown"
+          @pointerdown="onPointerDown"
+          @pointermove="onPointerMove"
+          @pointerup="onPointerUp"
+        >
+          <slot
+            :open="open"
+            :remaining="remaining"
+            :duration="resolvedDuration"
+          />
+        </Primitive>
+      </CollectionItem>
+    </Presence>
+  </TeleportPrimitive>
+
+  <Presence
+    v-else
+    :present="forceMount || open"
+  >
+    <CollectionItem>
+      <Primitive
+        :ref="forwardRef"
+        :as="as"
+        v-bind="$attrs"
+        role="status"
+        :aria-atomic="true"
+        :data-state="dataState"
+        :data-type="type"
+        :data-swipe-direction="providerCtx.swipeDirection.value"
+        tabindex="-1"
+        :style="swipeStyle"
+        @keydown.escape="handleEscapeKeyDown"
+        @pointerdown="onPointerDown"
+        @pointermove="onPointerMove"
+        @pointerup="onPointerUp"
+      >
+        <slot
+          :open="open"
+          :remaining="remaining"
+          :duration="resolvedDuration"
+        />
+      </Primitive>
+    </CollectionItem>
+  </Presence>
+</template>
diff --git a/vue/primitives/src/toast/ToastTitle.vue b/vue/primitives/src/feedback/toast/ToastTitle.vue
similarity index 81%
rename from vue/primitives/src/toast/ToastTitle.vue
rename to vue/primitives/src/feedback/toast/ToastTitle.vue
index b6470a6..6b06823 100644
--- a/vue/primitives/src/toast/ToastTitle.vue
+++ b/vue/primitives/src/feedback/toast/ToastTitle.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The toast's heading. Renders the short, prominent line that names the
@@ -11,7 +11,7 @@ export interface ToastTitleProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'div' } = defineProps<ToastTitleProps>();
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/feedback/toast/ToastViewport.vue b/vue/primitives/src/feedback/toast/ToastViewport.vue
new file mode 100644
index 0000000..33911f1
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/ToastViewport.vue
@@ -0,0 +1,224 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The fixed-position region (an `<ol>`) where toasts are rendered. Provides the
+ * accessible landmark for the toast list, pauses auto-dismiss timers on
+ * hover/focus/window-blur, can be focused via a keyboard hotkey, and manages tab
+ * order across portaled toasts (newest-first) with head/tail focus proxies.
+ * Render exactly one per provider.
+ */
+export interface ToastViewportProps extends PrimitiveProps {
+  /**
+   * Accessible label for the toast region. Overrides the provider label.
+   * The `{hotkey}` placeholder is replaced with the configured hotkey, and a
+   * `(hotkey) => string` function form is also accepted.
+   */
+  label?: string | ((hotkey: string) => string);
+  /** Keyboard shortcut to focus the viewport. @default ['F8'] */
+  hotkey?: string[];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, shallowRef, watchPostEffect } from 'vue';
+
+import { focusFirst, getActiveElement, getTabbableCandidates } from '@robonen/platform/browsers';
+import { unrefElement, useEventListener, useForwardExpose } from '@robonen/vue';
+import { useCollectionInjector } from '../../utilities/collection';
+import { DismissableLayerBranch } from '../../utilities/dismissable-layer';
+import { Primitive } from '../../internal/primitive';
+import { useToastProviderContext } from './context';
+import { TOAST_COLLECTION_KEY } from './shared';
+import ToastFocusProxy from './ToastFocusProxy.vue';
+import { VIEWPORT_PAUSE, VIEWPORT_RESUME } from './utils';
+
+defineOptions({
+  inheritAttrs: false,
+});
+
+const { as = 'ol', hotkey = ['F8'], label } = defineProps<ToastViewportProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const providerCtx = useToastProviderContext();
+const { CollectionSlot, getItems } = useCollectionInjector(TOAST_COLLECTION_KEY);
+
+const hasToasts = computed(() => providerCtx.toastCount.value > 0);
+// Cache the branch style object so the DismissableLayerBranch child receives a
+// stable reference between renders instead of a freshly-allocated literal on
+// every viewport re-render (viewport re-renders on each toast add/remove).
+const branchStyle = computed(() => ({ pointerEvents: hasToasts.value ? undefined : ('none' as const) }));
+const headFocusProxy = shallowRef<HTMLElement>();
+const tailFocusProxy = shallowRef<HTMLElement>();
+
+watchPostEffect(() => providerCtx.onViewportChange(currentElement.value));
+
+const hotkeyMessage = computed(() =>
+  hotkey.join('+').replaceAll('Key', '').replaceAll('Digit', ''),
+);
+
+const viewportLabel = computed(() => {
+  const base = label ?? providerCtx.label.value;
+  if (typeof base === 'function') return base(hotkeyMessage.value);
+  return base.replace('{hotkey}', hotkeyMessage.value);
+});
+
+// Dispatch pause/resume only on an actual state transition. Guarding on the
+// shared `isClosePausedRef` makes repeated `pointermove`/window events idempotent
+// so the per-toast timer is not re-banked on every move.
+function dispatchPause() {
+  if (providerCtx.isClosePausedRef.value) return;
+  providerCtx.isClosePausedRef.value = true;
+  currentElement.value?.dispatchEvent(new CustomEvent(VIEWPORT_PAUSE, { bubbles: true }));
+}
+
+function dispatchResume() {
+  if (!providerCtx.isClosePausedRef.value) return;
+  providerCtx.isClosePausedRef.value = false;
+  currentElement.value?.dispatchEvent(new CustomEvent(VIEWPORT_RESUME, { bubbles: true }));
+}
+
+function handlePointerEnter() {
+  dispatchPause();
+}
+
+function handlePointerLeave() {
+  // Don't resume if focus is still inside the viewport (focus pause wins).
+  if (currentElement.value?.contains(getActiveElement())) return;
+  dispatchResume();
+}
+
+function handleFocusIn() {
+  dispatchPause();
+}
+
+function handleFocusOut(event: FocusEvent) {
+  if (currentElement.value?.contains(event.relatedTarget as Node)) return;
+  dispatchResume();
+}
+
+function handleWindowBlur() {
+  dispatchPause();
+}
+
+function handleWindowFocus() {
+  // Only resume if focus is not parked inside the viewport.
+  if (currentElement.value?.contains(getActiveElement())) return;
+  dispatchResume();
+}
+
+// Newest-to-oldest tab order across portaled toasts. Portals can't influence
+// source order, so we manage Tab/Shift+Tab manually and proxy out at the edges.
+function getSortedTabbableCandidates(direction: 'forwards' | 'backwards') {
+  const toastNodes = getItems(true).map(i => i.ref);
+  const perToast = toastNodes.map((node) => {
+    const candidates = [node, ...getTabbableCandidates(node)];
+    return direction === 'forwards' ? candidates : candidates.reverse();
+  });
+  return (direction === 'forwards' ? perToast.reverse() : perToast).flat();
+}
+
+function handleKeyDown(event: KeyboardEvent) {
+  const viewport = currentElement.value;
+  if (!viewport) return;
+
+  const isModifier = event.altKey || event.ctrlKey || event.metaKey;
+  if (event.key !== 'Tab' || isModifier) return;
+
+  const focused = getActiveElement();
+  const isTabbingBackwards = event.shiftKey;
+  const targetIsViewport = event.target === viewport;
+
+  if (targetIsViewport && isTabbingBackwards) {
+    headFocusProxy.value?.focus();
+    return;
+  }
+
+  const direction = isTabbingBackwards ? 'backwards' : 'forwards';
+  const sorted = getSortedTabbableCandidates(direction);
+  const index = sorted.indexOf(focused);
+
+  if (focusFirst(sorted.slice(index + 1))) {
+    event.preventDefault();
+  }
+  else if (isTabbingBackwards) {
+    // At an edge — proxy out so the browser hands focus to the next document element.
+    headFocusProxy.value?.focus();
+  }
+  else {
+    tailFocusProxy.value?.focus();
+  }
+}
+
+function handleGlobalKeyDown(event: KeyboardEvent) {
+  if (!hotkey || hotkey.length === 0) return;
+  const isHotkey = hotkey.every((key) => {
+    if (key === event.key) return true;
+    if (key === 'altKey') return event.altKey;
+    if (key === 'ctrlKey') return event.ctrlKey;
+    if (key === 'shiftKey') return event.shiftKey;
+    if (key === 'metaKey') return event.metaKey;
+    return false;
+  });
+  if (isHotkey) currentElement.value?.focus();
+}
+
+useEventListener(document, 'keydown', handleGlobalKeyDown);
+useEventListener(globalThis, 'blur', handleWindowBlur);
+useEventListener(globalThis, 'focus', handleWindowFocus);
+
+function setHeadProxy(node: unknown) {
+  headFocusProxy.value = (unrefElement(node as Parameters<typeof unrefElement>[0]) as HTMLElement) ?? undefined;
+}
+
+function setTailProxy(node: unknown) {
+  tailFocusProxy.value = (unrefElement(node as Parameters<typeof unrefElement>[0]) as HTMLElement) ?? undefined;
+}
+
+function focusToastsForwards() {
+  focusFirst(getSortedTabbableCandidates('forwards'));
+}
+
+function focusToastsBackwards() {
+  focusFirst(getSortedTabbableCandidates('backwards'));
+}
+</script>
+
+<template>
+  <DismissableLayerBranch
+    :style="branchStyle"
+  >
+    <ToastFocusProxy
+      v-if="hasToasts"
+      :ref="setHeadProxy"
+      @focus-from-outside-viewport="focusToastsForwards"
+    />
+
+    <CollectionSlot>
+      <Primitive
+        :ref="forwardRef"
+        :as="as"
+        v-bind="$attrs"
+        role="region"
+        :aria-label="viewportLabel"
+        tabindex="-1"
+        style="outline: none"
+        data-primitives-toast-viewport
+        @pointerenter="handlePointerEnter"
+        @pointermove="handlePointerEnter"
+        @pointerleave="handlePointerLeave"
+        @focusin="handleFocusIn"
+        @focusout="handleFocusOut"
+        @keydown="handleKeyDown"
+      >
+        <slot />
+      </Primitive>
+    </CollectionSlot>
+
+    <ToastFocusProxy
+      v-if="hasToasts"
+      :ref="setTailProxy"
+      @focus-from-outside-viewport="focusToastsBackwards"
+    />
+  </DismissableLayerBranch>
+</template>
diff --git a/vue/primitives/src/feedback/toast/__test__/Toast.features.test.ts b/vue/primitives/src/feedback/toast/__test__/Toast.features.test.ts
new file mode 100644
index 0000000..f65db9f
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/__test__/Toast.features.test.ts
@@ -0,0 +1,476 @@
+// Feature/parity tests for the toast primitive's additive capabilities:
+//   - screen-reader announce region (deferred render + text harvesting + exclude)
+//   - ToastAction / ToastClose announce-exclude + ToastClose type=button
+//   - controlled / uncontrolled (defaultOpen) open state
+//   - forceMount keeps the toast mounted while closed
+//   - Escape closes a focused toast and flags isFocusedToastEscapeKeyDownRef
+//   - focus returns to the viewport when a focused toast closes
+//   - viewport {hotkey} label interpolation + function-form label
+//   - swipe-to-dismiss gesture (emits + data-swipe + CSS vars) and disableSwipe
+//   - elapsed-time-preserving pause/resume
+
+import { mount } from '@vue/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  ToastAction,
+  ToastClose,
+  ToastDescription,
+  ToastProvider,
+  ToastRoot,
+  ToastTitle,
+  ToastViewport,
+  useToastProviderContext,
+} from '../index';
+
+function press(el: Element, key: string, init: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+}
+
+function nextFrame() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+  });
+}
+
+function pointer(el: Element, type: string, init: PointerEventInit = {}) {
+  // jsdom lacks PointerEvent; fall back to a MouseEvent-ish CustomEvent carrying coords.
+  const Ctor = (globalThis as { PointerEvent?: typeof PointerEvent }).PointerEvent;
+  let event: Event;
+  if (Ctor) {
+    event = new Ctor(type, { bubbles: true, cancelable: true, ...init });
+  }
+  else {
+    event = new Event(type, { bubbles: true, cancelable: true });
+    Object.assign(event, { button: 0, pointerId: 1, pointerType: 'mouse', ...init });
+  }
+  // Stub pointer-capture methods used by the handlers.
+  Object.assign(el, {
+    setPointerCapture: () => {},
+    releasePointerCapture: () => {},
+    hasPointerCapture: () => false,
+  });
+  el.dispatchEvent(event);
+}
+
+describe('toast — announce region', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('renders a hidden announce region after a frame and harvests toast text', async () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot, ToastTitle, ToastDescription },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity }, {
+                default: () => [
+                  h(ToastTitle, {}, { default: () => 'Saved' }),
+                  h(ToastDescription, {}, { default: () => 'Your changes are stored.' }),
+                ],
+              }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    await nextFrame();
+    await nextTick();
+
+    const announce = document.querySelector('[data-primitives-toast-announce]');
+    expect(announce).not.toBeNull();
+    expect(announce?.textContent).toContain('Saved');
+    expect(announce?.textContent).toContain('Your changes are stored.');
+
+    wrapper.unmount();
+  });
+
+  it('excludes ToastClose / ToastAction visible text and substitutes altText', async () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot, ToastTitle, ToastAction, ToastClose },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity }, {
+                default: () => [
+                  h(ToastTitle, {}, { default: () => 'Archived' }),
+                  h(ToastAction, { altText: 'Undo archiving' }, { default: () => 'Undo' }),
+                  h(ToastClose, {}, { default: () => 'X' }),
+                ],
+              }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    await nextFrame();
+    await nextTick();
+
+    const announce = document.querySelector('[data-primitives-toast-announce]');
+    expect(announce?.textContent).toContain('Archived');
+    // altText is announced in place of the visible "Undo" label.
+    expect(announce?.textContent).toContain('Undo archiving');
+    // The close button's visible "X" is excluded.
+    expect(announce?.textContent).not.toContain('X');
+
+    wrapper.unmount();
+  });
+});
+
+describe('toast — ToastClose / ToastAction', () => {
+  it('ToastClose renders type="button" and carries the announce-exclude attribute', () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot, ToastClose },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity }, {
+                default: () => h(ToastClose, {}, { default: () => 'Close' }),
+              }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    const close = wrapper.find('[data-primitives-toast-close]').element as HTMLButtonElement;
+    expect(close.getAttribute('type')).toBe('button');
+    expect(close.getAttribute('data-primitives-toast-announce-exclude')).toBe('');
+    wrapper.unmount();
+  });
+
+  it('ToastAction carries the announce-exclude alt text', () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot, ToastAction },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity }, {
+                default: () => h(ToastAction, { altText: 'Undo it' }, { default: () => 'Undo' }),
+              }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    const action = wrapper.find('[data-primitives-toast-action]').element as HTMLElement;
+    expect(action.getAttribute('data-primitives-toast-announce-exclude')).toBe('');
+    expect(action.getAttribute('data-primitives-toast-announce-alt')).toBe('Undo it');
+    expect(action.getAttribute('aria-label')).toBe('Undo it');
+    wrapper.unmount();
+  });
+});
+
+describe('toast — open state', () => {
+  it('uncontrolled defaultOpen=false starts closed', async () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity, defaultOpen: false }, { default: () => 'Body' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    expect(wrapper.find('[role="status"]').exists()).toBe(false);
+    wrapper.unmount();
+  });
+
+  it('controlled v-model:open drives visibility', async () => {
+    const open = ref(true);
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot },
+        setup: () => ({ open }),
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, {
+                duration: Infinity,
+                open: this.open,
+                'onUpdate:open': (v: boolean) => { this.open = v; },
+              }, { default: () => 'Body' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    expect(wrapper.find('[role="status"]').exists()).toBe(true);
+
+    open.value = false;
+    await nextTick();
+    await nextTick();
+    expect(wrapper.find('[role="status"]').exists()).toBe(false);
+    wrapper.unmount();
+  });
+
+  it('forceMount keeps the toast mounted while closed', async () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity, open: false, forceMount: true }, { default: () => 'Body' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    const toast = wrapper.find('[role="status"]');
+    expect(toast.exists()).toBe(true);
+    expect(toast.attributes('data-state')).toBe('closed');
+    wrapper.unmount();
+  });
+});
+
+describe('toast — Escape + focus return', () => {
+  it('Escape on a focused toast closes it and flags the provider ref', async () => {
+    let providerCtx: ReturnType<typeof useToastProviderContext> | null = null;
+    const Probe = defineComponent({
+      setup() {
+        providerCtx = useToastProviderContext();
+        return () => null;
+      },
+    });
+
+    const escapeSpy = vi.fn();
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot, Probe },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(Probe),
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity, onEscapeKeyDown: escapeSpy }, { default: () => 'Body' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    const toast = wrapper.find('[role="status"]').element as HTMLElement;
+    toast.focus();
+    press(toast, 'Escape');
+    await nextTick();
+    await nextTick();
+
+    expect(escapeSpy).toHaveBeenCalledOnce();
+    expect(providerCtx!.isFocusedToastEscapeKeyDownRef.value).toBe(true);
+    expect(wrapper.find('[role="status"]').exists()).toBe(false);
+    wrapper.unmount();
+  });
+
+  it('returns focus to the viewport when a focused toast closes via ToastClose', async () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot, ToastClose },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity }, {
+                default: () => h(ToastClose, {}, { default: () => 'Close' }),
+              }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    const viewport = wrapper.find('[role="region"]').element as HTMLElement;
+    const close = wrapper.find('[data-primitives-toast-close]').element as HTMLButtonElement;
+    const focusSpy = vi.spyOn(viewport, 'focus');
+
+    close.focus();
+    close.click();
+    await nextTick();
+
+    expect(focusSpy).toHaveBeenCalled();
+    wrapper.unmount();
+  });
+});
+
+describe('toast — viewport label', () => {
+  it('interpolates the {hotkey} placeholder', () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => h(ToastViewport, { label: 'Alerts ({hotkey})', hotkey: ['F8'] }),
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    expect(wrapper.find('[role="region"]').attributes('aria-label')).toBe('Alerts (F8)');
+    wrapper.unmount();
+  });
+
+  it('supports a function-form label', () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => h(ToastViewport, { label: (hk: string) => `Toasts [${hk}]`, hotkey: ['F8'] }),
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    expect(wrapper.find('[role="region"]').attributes('aria-label')).toBe('Toasts [F8]');
+    wrapper.unmount();
+  });
+});
+
+describe('toast — swipe to dismiss', () => {
+  it('emits swipe events and closes when threshold is exceeded', async () => {
+    const swipeEnd = vi.fn();
+    const open = ref(true);
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot },
+        setup: () => ({ open }),
+        render() {
+          return h(ToastProvider, { swipeDirection: 'right', swipeThreshold: 10 }, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, {
+                duration: Infinity,
+                open: this.open,
+                'onUpdate:open': (v: boolean) => { this.open = v; },
+                onSwipeEnd: swipeEnd,
+              }, { default: () => 'Body' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    const toast = wrapper.find('[role="status"]').element as HTMLElement;
+
+    pointer(toast, 'pointerdown', { clientX: 0, clientY: 0, button: 0, pointerType: 'mouse', pointerId: 1 });
+    // First move past the start buffer in the swipe direction.
+    pointer(toast, 'pointermove', { clientX: 30, clientY: 0, pointerType: 'mouse', pointerId: 1 });
+    pointer(toast, 'pointermove', { clientX: 60, clientY: 0, pointerType: 'mouse', pointerId: 1 });
+    pointer(toast, 'pointerup', { clientX: 60, clientY: 0, pointerType: 'mouse', pointerId: 1 });
+    await nextTick();
+    await nextTick();
+
+    expect(swipeEnd).toHaveBeenCalled();
+    expect(toast.getAttribute('data-swipe')).toBe('end');
+    expect(open.value).toBe(false);
+    wrapper.unmount();
+  });
+
+  it('disableSwipe prevents any swipe handling', async () => {
+    const swipeStart = vi.fn();
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot },
+        render() {
+          return h(ToastProvider, { disableSwipe: true, swipeDirection: 'right' }, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: Infinity, onSwipeStart: swipeStart }, { default: () => 'Body' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    await nextTick();
+    const toast = wrapper.find('[role="status"]').element as HTMLElement;
+    pointer(toast, 'pointerdown', { clientX: 0, clientY: 0, button: 0, pointerType: 'mouse', pointerId: 1 });
+    pointer(toast, 'pointermove', { clientX: 60, clientY: 0, pointerType: 'mouse', pointerId: 1 });
+
+    expect(swipeStart).not.toHaveBeenCalled();
+    expect(toast.getAttribute('data-swipe')).toBeNull();
+    wrapper.unmount();
+  });
+});
+
+describe('toast — elapsed-time-preserving pause/resume', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('resumes from the remaining time instead of restarting the full duration', async () => {
+    const wrapper = mount(
+      defineComponent({
+        components: { ToastProvider, ToastViewport, ToastRoot },
+        render() {
+          return h(ToastProvider, {}, {
+            default: () => [
+              h(ToastViewport),
+              h(ToastRoot, { duration: 1000 }, { default: () => 'Body' }),
+            ],
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+
+    const viewport = wrapper.find('[role="region"]').element as HTMLElement;
+
+    // Elapse 800ms, then pause (banks ~200ms remaining).
+    vi.advanceTimersByTime(800);
+    viewport.dispatchEvent(new CustomEvent('toast.viewportPause', { bubbles: true }));
+    await nextTick();
+
+    // While paused, time passing does not close the toast.
+    vi.advanceTimersByTime(5000);
+    await nextTick();
+    expect(wrapper.find('[role="status"]').exists()).toBe(true);
+
+    // Resume — should close after the remaining ~200ms, not a full 1000ms.
+    viewport.dispatchEvent(new CustomEvent('toast.viewportResume', { bubbles: true }));
+    vi.advanceTimersByTime(250);
+    await nextTick();
+    await nextTick();
+    expect(wrapper.find('[role="status"]').exists()).toBe(false);
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/toast/__test__/Toast.regression.test.ts b/vue/primitives/src/feedback/toast/__test__/Toast.regression.test.ts
similarity index 100%
rename from vue/primitives/src/toast/__test__/Toast.regression.test.ts
rename to vue/primitives/src/feedback/toast/__test__/Toast.regression.test.ts
diff --git a/vue/primitives/src/toast/context.ts b/vue/primitives/src/feedback/toast/context.ts
similarity index 91%
rename from vue/primitives/src/toast/context.ts
rename to vue/primitives/src/feedback/toast/context.ts
index 296851b..4294d82 100644
--- a/vue/primitives/src/toast/context.ts
+++ b/vue/primitives/src/feedback/toast/context.ts
@@ -9,6 +9,8 @@ export interface ToastProviderContext {
   duration: Ref<number>;
   swipeDirection: Ref<SwipeDirection>;
   swipeThreshold: Ref<number>;
+  /** Whether swipe-to-dismiss gestures are disabled for every toast. */
+  disableSwipe: Ref<boolean>;
   toastCount: Ref<number>;
   viewportRef: ShallowRef<HTMLElement | undefined>;
   onViewportChange: (el: HTMLElement | undefined) => void;
diff --git a/vue/primitives/src/toast/demo.vue b/vue/primitives/src/feedback/toast/demo.vue
similarity index 71%
rename from vue/primitives/src/toast/demo.vue
rename to vue/primitives/src/feedback/toast/demo.vue
index 9190dfa..1be58cb 100644
--- a/vue/primitives/src/toast/demo.vue
+++ b/vue/primitives/src/feedback/toast/demo.vue
@@ -43,15 +43,15 @@ function remove(id: number) {
 
 <template>
   <ToastProvider :duration="4000" swipe-direction="right">
-    <div class="flex flex-col items-start gap-3 text-(--fg)">
+    <div class="flex flex-col items-start gap-3 text-fg">
       <button
         type="button"
-        class="inline-flex items-center rounded-md bg-(--accent) px-3 py-1.5 text-sm font-medium text-(--accent-fg) transition-colors hover:bg-(--accent-hover) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex items-center rounded-md bg-accent px-3 py-1.5 text-sm font-medium text-accent-fg transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         @click="notify"
       >
         Archive message
       </button>
-      <p class="text-xs text-(--fg-muted)">
+      <p class="text-xs text-fg-muted">
         Toasts auto-dismiss after 4s. Hover the stack to pause the timer.
       </p>
     </div>
@@ -60,7 +60,7 @@ function remove(id: number) {
       v-for="toast in toasts"
       :key="toast.id"
       v-model:open="toast.open"
-      class="flex items-start gap-3 rounded-lg border border-(--border) bg-(--bg-elevated) p-3 shadow-lg data-[state=closed]:opacity-0 data-[state=open]:opacity-100"
+      class="flex items-start gap-3 rounded-lg border border-border bg-bg-elevated p-3 shadow-lg data-[state=closed]:opacity-0 data-[state=open]:opacity-100"
       @update:open="(open) => !open && remove(toast.id)"
     >
       <div class="mt-0.5 flex size-7 shrink-0 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
@@ -73,10 +73,10 @@ function remove(id: number) {
       </div>
 
       <div class="min-w-0 flex-1">
-        <ToastTitle class="text-sm font-semibold text-(--fg)">
+        <ToastTitle class="text-sm font-semibold text-fg">
           {{ toast.title }}
         </ToastTitle>
-        <ToastDescription class="mt-0.5 text-sm text-(--fg-muted)">
+        <ToastDescription class="mt-0.5 text-sm text-fg-muted">
           {{ toast.description }}
         </ToastDescription>
       </div>
@@ -84,14 +84,14 @@ function remove(id: number) {
       <div class="flex shrink-0 items-center gap-1">
         <ToastAction
           alt-text="Undo archiving this message"
-          class="rounded-md border border-(--border) bg-(--bg) px-2 py-1 text-xs font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="rounded-md border border-border bg-bg px-2 py-1 text-xs font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
           @click="undo(toast.id)"
         >
           Undo
         </ToastAction>
         <ToastClose
           aria-label="Dismiss"
-          class="inline-flex size-6 items-center justify-center rounded-md text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="inline-flex size-6 items-center justify-center rounded-md text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           <svg
             class="size-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor"
diff --git a/vue/primitives/src/toast/index.ts b/vue/primitives/src/feedback/toast/index.ts
similarity index 69%
rename from vue/primitives/src/toast/index.ts
rename to vue/primitives/src/feedback/toast/index.ts
index 90e5511..fd2fade 100644
--- a/vue/primitives/src/toast/index.ts
+++ b/vue/primitives/src/feedback/toast/index.ts
@@ -5,6 +5,9 @@ export { default as ToastDescription } from './ToastDescription.vue';
 export { default as ToastAction } from './ToastAction.vue';
 export { default as ToastClose } from './ToastClose.vue';
 export { default as ToastViewport } from './ToastViewport.vue';
+export { default as ToastAnnounce } from './ToastAnnounce.vue';
+export { default as ToastAnnounceExclude } from './ToastAnnounceExclude.vue';
+export { default as ToastPortal } from './ToastPortal.vue';
 
 export {
   useToastProviderContext,
@@ -12,6 +15,7 @@ export {
 } from './context';
 
 export type { SwipeDirection, ToastProviderContext, ToastContext } from './context';
+export type { SwipeEvent } from './utils';
 export type { ToastProviderProps } from './ToastProvider.vue';
 export type { ToastRootProps, ToastRootEmits } from './ToastRoot.vue';
 export type { ToastTitleProps } from './ToastTitle.vue';
@@ -19,3 +23,6 @@ export type { ToastDescriptionProps } from './ToastDescription.vue';
 export type { ToastActionProps } from './ToastAction.vue';
 export type { ToastCloseProps } from './ToastClose.vue';
 export type { ToastViewportProps } from './ToastViewport.vue';
+export type { ToastAnnounceProps } from './ToastAnnounce.vue';
+export type { ToastAnnounceExcludeProps } from './ToastAnnounceExclude.vue';
+export type { ToastPortalProps } from './ToastPortal.vue';
diff --git a/vue/primitives/src/feedback/toast/shared.ts b/vue/primitives/src/feedback/toast/shared.ts
new file mode 100644
index 0000000..d328a63
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/shared.ts
@@ -0,0 +1,6 @@
+/**
+ * Dedicated collection namespace for the toast primitive. Used so a nested
+ * collection provider between `ToastProvider` and `ToastViewport`/`ToastRoot`
+ * does not shadow the toast collection.
+ */
+export const TOAST_COLLECTION_KEY = 'toast';
diff --git a/vue/primitives/src/feedback/toast/utils.ts b/vue/primitives/src/feedback/toast/utils.ts
new file mode 100644
index 0000000..97e3fb8
--- /dev/null
+++ b/vue/primitives/src/feedback/toast/utils.ts
@@ -0,0 +1,107 @@
+import type { SwipeDirection } from './context';
+
+export const VIEWPORT_PAUSE = 'toast.viewportPause';
+export const VIEWPORT_RESUME = 'toast.viewportResume';
+
+export const TOAST_SWIPE_START = 'toast.swipeStart';
+export const TOAST_SWIPE_MOVE = 'toast.swipeMove';
+export const TOAST_SWIPE_CANCEL = 'toast.swipeCancel';
+export const TOAST_SWIPE_END = 'toast.swipeEnd';
+
+/** Data attribute marking a subtree that should be skipped by the screen-reader announce harvester. */
+export const ANNOUNCE_EXCLUDE_ATTR = 'data-primitives-toast-announce-exclude';
+/** Data attribute carrying alternate text to announce in place of an excluded subtree. */
+export const ANNOUNCE_ALT_ATTR = 'data-primitives-toast-announce-alt';
+
+export interface SwipeEventDetail {
+  originalEvent: PointerEvent;
+  delta: { x: number; y: number };
+}
+
+export type SwipeEvent = { currentTarget: EventTarget & HTMLElement } & Omit<
+  CustomEvent<SwipeEventDetail>,
+  'currentTarget'
+>;
+
+/**
+ * Dispatches a cancelable `CustomEvent` on the originating element and, when a
+ * handler is supplied, attaches it once before dispatch so listeners can call
+ * `preventDefault()`. Mirrors the dispatch pattern used by the focus-scope
+ * helpers but specialised for the swipe gesture detail payload.
+ */
+export function handleAndDispatchCustomEvent(
+  name: string,
+  handler: ((event: SwipeEvent) => void) | undefined,
+  detail: SwipeEventDetail,
+) {
+  const currentTarget = detail.originalEvent.currentTarget as HTMLElement;
+  const event = new CustomEvent(name, {
+    bubbles: false,
+    cancelable: true,
+    detail,
+  });
+
+  if (handler)
+    currentTarget.addEventListener(name, handler as EventListener, { once: true });
+
+  currentTarget.dispatchEvent(event);
+}
+
+/**
+ * Whether a pointer delta is dominant along the swipe axis and past the
+ * threshold. Horizontal directions compare `x`, vertical compare `y`.
+ */
+export function isDeltaInDirection(
+  delta: { x: number; y: number },
+  direction: SwipeDirection,
+  threshold = 0,
+): boolean {
+  const deltaX = Math.abs(delta.x);
+  const deltaY = Math.abs(delta.y);
+  const isDeltaX = deltaX > deltaY;
+
+  if (direction === 'left' || direction === 'right')
+    return isDeltaX && deltaX > threshold;
+
+  return !isDeltaX && deltaY > threshold;
+}
+
+function isHTMLElement(node: Node): node is HTMLElement {
+  return node.nodeType === node.ELEMENT_NODE;
+}
+
+/**
+ * Walks a toast element collecting its visible text as discrete chunks for a
+ * screen-reader live region. Hidden subtrees (`aria-hidden`, `hidden`,
+ * `display: none`) are skipped, and subtrees flagged with
+ * `data-primitives-toast-announce-exclude` are replaced by their
+ * `data-primitives-toast-announce-alt` text (if any).
+ *
+ * Returning an array (rather than a single joined string) lets the live region
+ * render one text node per chunk, giving assistive tech a natural pause break
+ * between the title and description.
+ */
+export function getAnnounceTextContent(container: HTMLElement): string[] {
+  const textContent: string[] = [];
+
+  for (const node of Array.from(container.childNodes)) {
+    if (node.nodeType === node.TEXT_NODE && node.textContent)
+      textContent.push(node.textContent);
+
+    if (isHTMLElement(node)) {
+      const isHidden = node.ariaHidden === 'true' || node.hidden || node.style.display === 'none';
+      if (isHidden) continue;
+
+      const isExcluded = node.getAttribute(ANNOUNCE_EXCLUDE_ATTR) === '';
+      if (isExcluded) {
+        const altText = node.getAttribute(ANNOUNCE_ALT_ATTR);
+        if (altText) textContent.push(altText);
+      }
+      else {
+        textContent.push(...getAnnounceTextContent(node));
+      }
+    }
+  }
+
+  return textContent;
+}
diff --git a/vue/primitives/src/forms/checkbox/CheckboxGroupRoot.vue b/vue/primitives/src/forms/checkbox/CheckboxGroupRoot.vue
new file mode 100644
index 0000000..66a0a86
--- /dev/null
+++ b/vue/primitives/src/forms/checkbox/CheckboxGroupRoot.vue
@@ -0,0 +1,151 @@
+<script lang="ts">
+import type { Direction } from '../../utilities/config-provider';
+import type { Orientation } from '../../utilities/roving-focus';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { AcceptableValue } from './context';
+
+/**
+ * Coordinates a set of related checkboxes behind a single array model. It owns
+ * the list of selected `value`s (`v-model` or uncontrolled `defaultValue`),
+ * applies a group-level `disabled`, optionally wires arrow-key roving focus
+ * across the children, and — when `name` is set inside a `<form>` — submits the
+ * selection through hidden inputs. Each nested `CheckboxRoot` derives its
+ * checked state from membership in this model and toggling adds/removes its
+ * `value`. Reach for it whenever several checkboxes share one logical answer
+ * (a multi-select question, a filter set, a permissions matrix).
+ */
+export interface CheckboxGroupRootProps<T extends AcceptableValue = AcceptableValue> extends PrimitiveProps {
+  /** Uncontrolled initial selection. */
+  defaultValue?: T[];
+  /** Controlled selection. Bind with `v-model`. */
+  modelValue?: T[];
+  /** Disable every checkbox in the group. */
+  disabled?: boolean;
+  /** Mark the submitted group input as required. */
+  required?: boolean;
+  /** Hidden input name; serializes the selection for form submission. */
+  name?: string;
+  /**
+   * Enable arrow-key roving focus across the checkboxes.
+   * @default true
+   */
+  rovingFocus?: boolean;
+  /** Navigation orientation when `rovingFocus` is on. */
+  orientation?: Orientation;
+  /** Writing direction (RTL-aware navigation). Falls back to config `dir`. */
+  dir?: Direction;
+  /**
+   * Wrap focus around the ends.
+   * @default false
+   */
+  loop?: boolean;
+}
+
+export interface CheckboxGroupRootEmits<T extends AcceptableValue = AcceptableValue> {
+  'update:modelValue': [value: T[]];
+  valueChange: [value: T[]];
+}
+</script>
+
+<script setup lang="ts" generic="T extends AcceptableValue = AcceptableValue">
+import type { Ref } from 'vue';
+import { computed, ref, toRef, watch } from 'vue';
+import { isEqual } from '@robonen/stdlib';
+import { Primitive } from '../../internal/primitive';
+import { RovingFocusGroup } from '../../utilities/roving-focus';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
+import { useForwardExpose } from '@robonen/vue';
+import { provideCheckboxGroupContext } from './context';
+
+const {
+  defaultValue,
+  disabled = false,
+  required = false,
+  name,
+  rovingFocus = true,
+  orientation,
+  dir,
+  loop = false,
+  as = 'div',
+} = defineProps<CheckboxGroupRootProps<T>>();
+
+const emit = defineEmits<CheckboxGroupRootEmits<T>>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// `modelValue` is an array replaced wholesale on every toggle, so `shallowRef`
+// avoids deep-tracking each member.
+const localValue = ref<T[]>(defaultValue ?? []) as Ref<T[]>;
+
+const model = defineModel<T[] | undefined>({
+  default: undefined,
+  get: v => v ?? localValue.value,
+  set: (v) => {
+    localValue.value = (v ?? []) as T[];
+    return v;
+  },
+});
+
+const currentValue = computed<T[]>(() => model.value ?? localValue.value);
+
+function isChecked(value: AcceptableValue): boolean {
+  for (const v of currentValue.value) {
+    if (isEqual(v, value)) return true;
+  }
+  return false;
+}
+
+function toggle(value: AcceptableValue): void {
+  if (disabled) return;
+  const next = [...currentValue.value];
+  const index = next.findIndex(v => isEqual(v, value));
+  if (index === -1) next.push(value as T);
+  else next.splice(index, 1);
+  model.value = next;
+  emit('valueChange', next);
+}
+
+const rovingFocusProps = computed(() =>
+  rovingFocus ? { loop, dir, orientation } : {});
+
+// Only submit through the form when inside one; SSR renders so the field
+// submits without JS.
+const isFormControl = computed<boolean>(() => {
+  if (globalThis.document === undefined) return true;
+  const el = currentElement.value;
+  return !!el && !!el.closest('form');
+});
+
+watch(model, (v) => {
+  if (v !== undefined && v !== localValue.value) localValue.value = v;
+});
+
+provideCheckboxGroupContext({
+  modelValue: currentValue as Ref<AcceptableValue[]>,
+  disabled: toRef(() => disabled),
+  rovingFocus: toRef(() => rovingFocus),
+  toggle,
+  isChecked,
+});
+</script>
+
+<template>
+  <component
+    :is="rovingFocus ? RovingFocusGroup : Primitive"
+    :ref="forwardRef"
+    :as="as"
+    role="group"
+    :aria-disabled="disabled || undefined"
+    :data-disabled="disabled ? '' : undefined"
+    v-bind="rovingFocusProps"
+  >
+    <slot :model-value="currentValue" />
+    <VisuallyHiddenInput
+      v-if="isFormControl && name"
+      :name="name"
+      :value="currentValue"
+      :required="required"
+      :disabled="disabled"
+    />
+  </component>
+</template>
diff --git a/vue/primitives/src/checkbox/CheckboxIndicator.vue b/vue/primitives/src/forms/checkbox/CheckboxIndicator.vue
similarity index 52%
rename from vue/primitives/src/checkbox/CheckboxIndicator.vue
rename to vue/primitives/src/forms/checkbox/CheckboxIndicator.vue
index da85c66..7242405 100644
--- a/vue/primitives/src/checkbox/CheckboxIndicator.vue
+++ b/vue/primitives/src/forms/checkbox/CheckboxIndicator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 /**
  * Renders its content only when the parent `CheckboxRoot` is checked or
  * indeterminate, mirroring that state via `data-state`. Place the check/dash
@@ -13,25 +13,33 @@ export interface CheckboxIndicatorProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
+import { Presence } from '../../utilities/presence';
 import { useCheckboxContext } from './context';
+import { getState, isIndeterminate } from './utils';
 import { useForwardExpose } from '@robonen/vue';
 
 const { as = 'span', forceMount = false } = defineProps<CheckboxIndicatorProps>();
 const ctx = useCheckboxContext();
 
+defineOptions({ inheritAttrs: false });
+
 const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    v-if="forceMount || ctx.checked.value !== false"
-    :data-state="ctx.checked.value === 'indeterminate' ? 'indeterminate' : (ctx.checked.value ? 'checked' : 'unchecked')"
-    :data-disabled="ctx.disabled.value ? '' : undefined"
-    style="pointer-events: none;"
+  <Presence
+    :present="forceMount || isIndeterminate(ctx.checked.value) || ctx.checked.value === true"
   >
-    <slot :checked="ctx.checked.value" />
-  </Primitive>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      v-bind="$attrs"
+      :data-state="getState(ctx.checked.value)"
+      :data-disabled="ctx.disabled.value ? '' : undefined"
+      style="pointer-events: none;"
+    >
+      <slot :checked="ctx.checked.value" />
+    </Primitive>
+  </Presence>
 </template>
diff --git a/vue/primitives/src/forms/checkbox/CheckboxRoot.vue b/vue/primitives/src/forms/checkbox/CheckboxRoot.vue
new file mode 100644
index 0000000..a24e2ee
--- /dev/null
+++ b/vue/primitives/src/forms/checkbox/CheckboxRoot.vue
@@ -0,0 +1,188 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { AcceptableValue, CheckedState } from './context';
+
+/**
+ * A toggleable control with checked, unchecked, and `'indeterminate'` states,
+ * built on a native `<button role="checkbox">`. The interactive root: it owns
+ * the checked state (controlled via `v-model:checked` or uncontrolled via
+ * `defaultChecked`), handles toggling, exposes a hidden form input when `name`
+ * is set, and provides context to `CheckboxIndicator`. Use it whenever you need
+ * a styled checkbox that integrates with forms or supports a mixed/partial state.
+ *
+ * The checked value is generic: with the default `trueValue`/`falseValue`
+ * (`true`/`false`) it behaves as a boolean checkbox, but those props let the
+ * model carry arbitrary values (`'yes'`/`'no'`, objects, …) compared by deep
+ * equality. Nesting the root inside a `CheckboxGroupRoot` switches it to group
+ * mode: its checked state derives from membership in the group's array model
+ * and toggling adds/removes its `value`.
+ */
+export interface CheckboxRootProps<T = boolean> extends PrimitiveProps {
+  /** Uncontrolled initial checked state. */
+  defaultChecked?: T | 'indeterminate';
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Mark associated hidden input as required. */
+  required?: boolean;
+  /** Hidden input name attribute. */
+  name?: string;
+  /**
+   * Value submitted with the form (hidden input) and used for membership when
+   * inside a `CheckboxGroupRoot`.
+   * @default 'on'
+   */
+  value?: AcceptableValue;
+  /** Id of the root element; anchors `<label for>` and aria-label derivation. */
+  id?: string;
+  /**
+   * Value the model holds when checked.
+   * @default true
+   */
+  trueValue?: T;
+  /**
+   * Value the model holds when unchecked.
+   * @default false
+   */
+  falseValue?: T;
+}
+
+export interface CheckboxRootEmits<T = boolean> {
+  checkedChange: [value: T | 'indeterminate'];
+}
+</script>
+
+<script setup lang="ts" generic="T = boolean">
+import type { Ref } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { computed, ref } from 'vue';
+import { isEqual } from '@robonen/stdlib';
+import { provideCheckboxContext, useCheckboxGroupContext } from './context';
+import { getState, isIndeterminate } from './utils';
+import { useForwardExpose } from '@robonen/vue';
+import { RovingFocusItem } from '../../utilities/roving-focus';
+import { VisuallyHiddenInputBubble } from '../../utilities/visually-hidden';
+
+defineOptions({ inheritAttrs: false });
+
+const {
+  disabled: disabledProp = false,
+  required = false,
+  value = 'on',
+  defaultChecked,
+  name,
+  id,
+  trueValue = true as unknown as T,
+  falseValue = false as unknown as T,
+  as = 'button',
+} = defineProps<CheckboxRootProps<T>>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+const emit = defineEmits<CheckboxRootEmits<T>>();
+
+// Group mode: when an ancestor `CheckboxGroupRoot` is present the checked state
+// is derived from membership in the group's array and toggling mutates it.
+const group = useCheckboxGroupContext(null);
+
+const localChecked = ref<T | 'indeterminate'>(defaultChecked ?? (falseValue as T)) as Ref<T | 'indeterminate'>;
+
+// `defineModel` handles both controlled (parent `v-model:checked`) and
+// uncontrolled modes; `localChecked` backs the uncontrolled state seeded from
+// `defaultChecked`. `checkedChange` is a separate public emit, so it stays.
+const checked = defineModel<T | 'indeterminate' | undefined>('checked', {
+  default: undefined,
+  get: v => v ?? localChecked.value,
+  set: (v) => {
+    localChecked.value = v as T | 'indeterminate';
+    return v;
+  },
+});
+
+const disabled = computed<boolean>(() => (group?.disabled.value ?? false) || disabledProp);
+
+// Canonical `CheckedState` for ARIA / `data-state` / the indicator. In group
+// mode it is pure membership; standalone it compares the model to `trueValue`.
+const checkedState = computed<CheckedState>(() => {
+  if (group) return group.isChecked(value);
+  const v = checked.value;
+  if (isIndeterminate(v)) return 'indeterminate';
+  return isEqual(v, trueValue);
+});
+
+function setChecked(v: T | 'indeterminate'): void {
+  checked.value = v;
+  emit('checkedChange', v);
+}
+
+function toggle(): void {
+  if (disabled.value) return;
+  if (group) {
+    group.toggle(value);
+    return;
+  }
+  // From indeterminate or unchecked → trueValue; from checked → falseValue.
+  const next = checkedState.value === true ? falseValue : trueValue;
+  setChecked(next);
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  // Per WAI-ARIA a checkbox does not activate on Enter; block the implicit
+  // form submit too.
+  if (event.key === 'Enter') event.preventDefault();
+  // <button> handles Space natively; synthesize toggle only for non-button hosts.
+  if (as !== 'button' && event.key === ' ') {
+    event.preventDefault();
+    toggle();
+  }
+}
+
+// Derive an accessible name from an associated `<label for=id>` when no explicit
+// `aria-label` is supplied. Guarded for SSR (no `document`).
+const ariaLabel = computed<string | undefined>(() => {
+  if (!id || !currentElement.value || globalThis.document === undefined) return undefined;
+  const label = globalThis.document.querySelector(`[for="${id}"]`) as HTMLElement | null;
+  return label?.innerText || undefined;
+});
+
+// A standalone checkbox renders a hidden form input whenever `name` is set; a
+// grouped checkbox never does (the group owns the submitted value).
+const hasHiddenInput = computed<boolean>(() => !group && !!name);
+
+provideCheckboxContext({
+  checked: checkedState,
+  disabled,
+});
+</script>
+
+<template>
+  <component
+    :is="group?.rovingFocus.value ? RovingFocusItem : Primitive"
+    :ref="forwardRef"
+    v-bind="$attrs"
+    :id="id"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    :tabindex="(as === 'button' || group?.rovingFocus.value) ? undefined : (disabled ? -1 : 0)"
+    :focusable="group?.rovingFocus.value ? !disabled : undefined"
+    role="checkbox"
+    :aria-checked="isIndeterminate(checkedState) ? 'mixed' : checkedState"
+    :aria-required="required || undefined"
+    :aria-disabled="disabled || undefined"
+    :aria-label="($attrs['aria-label'] as string) || ariaLabel"
+    :data-state="getState(checkedState)"
+    :data-disabled="disabled ? '' : undefined"
+    :disabled="disabled || undefined"
+    @click="toggle"
+    @keydown="onKeyDown"
+  >
+    <slot :checked="checkedState" :model-value="checked" :state="checkedState" />
+    <VisuallyHiddenInputBubble
+      v-if="hasHiddenInput"
+      :name="name!"
+      :value="value"
+      :checked="checkedState === true"
+      :required="required"
+      :disabled="disabled"
+    />
+  </component>
+</template>
diff --git a/vue/primitives/src/checkbox/__test__/Checkbox.test.ts b/vue/primitives/src/forms/checkbox/__test__/Checkbox.test.ts
similarity index 100%
rename from vue/primitives/src/checkbox/__test__/Checkbox.test.ts
rename to vue/primitives/src/forms/checkbox/__test__/Checkbox.test.ts
diff --git a/vue/primitives/src/forms/checkbox/__test__/CheckboxParity.test.ts b/vue/primitives/src/forms/checkbox/__test__/CheckboxParity.test.ts
new file mode 100644
index 0000000..2ed8f57
--- /dev/null
+++ b/vue/primitives/src/forms/checkbox/__test__/CheckboxParity.test.ts
@@ -0,0 +1,328 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { CheckboxGroupRoot, CheckboxIndicator, CheckboxRoot } from '../index';
+
+function press(el: Element, key: string) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+}
+
+describe('CheckboxRoot — generic value (trueValue/falseValue)', () => {
+  it('models arbitrary string values via trueValue/falseValue', async () => {
+    const model = ref<string>('no');
+    const Harness = defineComponent({
+      setup: () => () => h(CheckboxRoot, {
+        checked: model.value,
+        trueValue: 'yes',
+        falseValue: 'no',
+        'onUpdate:checked': (v: unknown) => { model.value = v as string; },
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    const el = w.element as HTMLElement;
+    expect(el.getAttribute('aria-checked')).toBe('false');
+    expect(el.getAttribute('data-state')).toBe('unchecked');
+
+    el.click();
+    await nextTick();
+    expect(model.value).toBe('yes');
+    expect(el.getAttribute('aria-checked')).toBe('true');
+
+    el.click();
+    await nextTick();
+    expect(model.value).toBe('no');
+    w.unmount();
+  });
+
+  it('compares object values by deep equality', async () => {
+    const trueVal = { id: 1 };
+    const model = ref<unknown>({ id: 0 });
+    const Harness = defineComponent({
+      setup: () => () => h(CheckboxRoot, {
+        checked: model.value,
+        trueValue: trueVal,
+        falseValue: { id: 0 },
+        'onUpdate:checked': (v: unknown) => { model.value = v; },
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    const el = w.element as HTMLElement;
+    expect(el.getAttribute('aria-checked')).toBe('false');
+    el.click();
+    await nextTick();
+    // Deeply equal to trueValue → checked.
+    expect(el.getAttribute('aria-checked')).toBe('true');
+    w.unmount();
+  });
+
+  it('uncontrolled defaultChecked seeds the generic model', () => {
+    const w = mount(CheckboxRoot, {
+      attachTo: document.body,
+      props: { defaultChecked: 'yes', trueValue: 'yes', falseValue: 'no' },
+    });
+    expect(w.element.getAttribute('aria-checked')).toBe('true');
+    w.unmount();
+  });
+});
+
+describe('CheckboxRoot — slot contract', () => {
+  it('exposes checked, modelValue and state to the default slot', async () => {
+    let captured: Record<string, unknown> = {};
+    const w = mount(CheckboxRoot, {
+      attachTo: document.body,
+      props: { defaultChecked: true },
+      slots: {
+        default: (scope: Record<string, unknown>) => {
+          captured = scope;
+          return '';
+        },
+      },
+    });
+    await nextTick();
+    expect(captured.checked).toBe(true);
+    expect(captured.state).toBe(true);
+    expect('modelValue' in captured).toBe(true);
+    w.unmount();
+  });
+});
+
+describe('CheckboxRoot — aria-label from associated label', () => {
+  it('derives aria-label from a <label for> when id is set', async () => {
+    const label = document.createElement('label');
+    label.setAttribute('for', 'cb-1');
+    label.textContent = 'Accept terms';
+    document.body.appendChild(label);
+
+    const w = mount(CheckboxRoot, {
+      attachTo: document.body,
+      props: { id: 'cb-1' },
+    });
+    await nextTick();
+    expect(w.element.getAttribute('aria-label')).toBe('Accept terms');
+    w.unmount();
+    label.remove();
+  });
+
+  it('an explicit aria-label wins over the derived one', async () => {
+    const label = document.createElement('label');
+    label.setAttribute('for', 'cb-2');
+    label.textContent = 'Derived';
+    document.body.appendChild(label);
+
+    const w = mount(CheckboxRoot, {
+      attachTo: document.body,
+      props: { id: 'cb-2' },
+      attrs: { 'aria-label': 'Explicit' },
+    });
+    await nextTick();
+    expect(w.element.getAttribute('aria-label')).toBe('Explicit');
+    w.unmount();
+    label.remove();
+  });
+});
+
+describe('CheckboxRoot — hidden form input', () => {
+  it('renders a native hidden checkbox input mirroring state', async () => {
+    const w = mount(CheckboxRoot, {
+      attachTo: document.body,
+      props: { name: 'agree', value: 'on', defaultChecked: true },
+    });
+    const input = w.element.querySelector('input[type="checkbox"]') as HTMLInputElement;
+    expect(input).toBeTruthy();
+    expect(input.name).toBe('agree');
+    expect(input.checked).toBe(true);
+    w.unmount();
+  });
+
+  it('does not render a hidden input without a name', () => {
+    const w = mount(CheckboxRoot, { attachTo: document.body });
+    expect(w.element.querySelector('input[type="checkbox"]')).toBeNull();
+    w.unmount();
+  });
+});
+
+describe('CheckboxRoot — keyboard', () => {
+  it('Enter does not toggle (WAI-ARIA) and is prevented', async () => {
+    const w = mount(CheckboxRoot, { attachTo: document.body });
+    const el = w.element as HTMLElement;
+    const ev = new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true });
+    el.dispatchEvent(ev);
+    await nextTick();
+    expect(el.getAttribute('aria-checked')).toBe('false');
+    expect(ev.defaultPrevented).toBe(true);
+    w.unmount();
+  });
+
+  it('Space toggles on a non-button host', async () => {
+    const w = mount(CheckboxRoot, { attachTo: document.body, props: { as: 'div' } });
+    const el = w.element as HTMLElement;
+    expect(el.getAttribute('tabindex')).toBe('0');
+    press(el, ' ');
+    await nextTick();
+    expect(el.getAttribute('aria-checked')).toBe('true');
+    w.unmount();
+  });
+});
+
+describe('CheckboxIndicator — Presence', () => {
+  it('forceMount keeps it mounted with data-state unchecked', () => {
+    const w = mount(CheckboxRoot, {
+      attachTo: document.body,
+      slots: {
+        default: () => h(CheckboxIndicator, { forceMount: true }, { default: () => '✓' }),
+      },
+    });
+    const span = w.element.querySelector('span') as HTMLElement;
+    expect(span).toBeTruthy();
+    expect(span.getAttribute('data-state')).toBe('unchecked');
+    w.unmount();
+  });
+
+  it('mounts on check and unmounts on uncheck (no animation)', async () => {
+    const w = mount(CheckboxRoot, {
+      attachTo: document.body,
+      slots: {
+        default: () => h(CheckboxIndicator, null, { default: () => '✓' }),
+      },
+    });
+    const el = w.element as HTMLElement;
+    expect(el.querySelector('span')).toBeNull();
+    el.click();
+    await nextTick();
+    expect(el.querySelector('span')).toBeTruthy();
+    el.click();
+    await nextTick();
+    expect(el.querySelector('span')).toBeNull();
+    w.unmount();
+  });
+});
+
+describe('CheckboxGroupRoot', () => {
+  function mountGroup(props: Record<string, unknown> = {}, values = ['a', 'b', 'c']) {
+    const Harness = defineComponent({
+      props: { groupProps: { type: Object, default: () => ({}) } },
+      setup: p => () => h('div', [
+        h(CheckboxGroupRoot, p.groupProps, {
+          default: () => values.map(v => h(CheckboxRoot, { key: v, value: v })),
+        }),
+      ]),
+    });
+    return mount(Harness, { attachTo: document.body, props: { groupProps: props } });
+  }
+
+  it('renders role="group" and checks members present in the model', async () => {
+    const w = mountGroup({ defaultValue: ['b'] });
+    const group = w.element.querySelector('[role="group"]') as HTMLElement;
+    expect(group).toBeTruthy();
+    const boxes = w.element.querySelectorAll('[role="checkbox"]');
+    expect(boxes.length).toBe(3);
+    expect(boxes[0]!.getAttribute('aria-checked')).toBe('false');
+    expect(boxes[1]!.getAttribute('aria-checked')).toBe('true');
+    w.unmount();
+  });
+
+  it('toggling a member adds/removes its value in the group model', async () => {
+    const model = ref<string[]>([]);
+    const Harness = defineComponent({
+      setup: () => () => h(CheckboxGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: string[]) => { model.value = v; },
+      }, {
+        default: () => ['a', 'b'].map(v => h(CheckboxRoot, { key: v, value: v })),
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    const boxes = w.element.querySelectorAll('[role="checkbox"]');
+
+    (boxes[0] as HTMLElement).click();
+    await nextTick();
+    expect(model.value).toEqual(['a']);
+
+    (boxes[1] as HTMLElement).click();
+    await nextTick();
+    expect(model.value).toEqual(['a', 'b']);
+
+    (boxes[0] as HTMLElement).click();
+    await nextTick();
+    expect(model.value).toEqual(['b']);
+    w.unmount();
+  });
+
+  it('emits valueChange alongside update:modelValue', async () => {
+    const Harness = defineComponent({
+      emits: ['valueChange'],
+      setup: (_, { emit }) => () => h(CheckboxGroupRoot, {
+        onValueChange: (v: string[]) => emit('valueChange', v),
+      }, {
+        default: () => [h(CheckboxRoot, { value: 'x' })],
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    (w.element.querySelector('[role="checkbox"]') as HTMLElement).click();
+    await nextTick();
+    expect(w.emitted('valueChange')).toEqual([[['x']]]);
+    w.unmount();
+  });
+
+  it('group-level disabled blocks toggling and reflects on members', async () => {
+    const w = mountGroup({ disabled: true, defaultValue: [] });
+    const box = w.element.querySelector('[role="checkbox"]') as HTMLElement;
+    expect(box.getAttribute('aria-disabled')).toBe('true');
+    box.click();
+    await nextTick();
+    expect(box.getAttribute('aria-checked')).toBe('false');
+    w.unmount();
+  });
+
+  it('renders hidden inputs for the selection inside a form', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h('form', [
+        h(CheckboxGroupRoot, { name: 'fruits', defaultValue: ['a', 'c'] }, {
+          default: () => ['a', 'b', 'c'].map(v => h(CheckboxRoot, { key: v, value: v })),
+        }),
+      ]),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const inputs = Array.from(w.element.querySelectorAll('input[name^="fruits"]')) as HTMLInputElement[];
+    expect(inputs.length).toBe(2);
+    expect(inputs.map(i => i.value)).toEqual(['a', 'c']);
+    w.unmount();
+  });
+
+  it('grouped members do not render their own hidden form input', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h('form', [
+        h(CheckboxGroupRoot, { defaultValue: ['a'] }, {
+          default: () => [h(CheckboxRoot, { value: 'a', name: 'should-be-ignored' })],
+        }),
+      ]),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    expect(w.element.querySelector('input[name="should-be-ignored"]')).toBeNull();
+    w.unmount();
+  });
+
+  it('roving focus moves focus across members with arrow keys', async () => {
+    const w = mountGroup({ rovingFocus: true, orientation: 'horizontal' });
+    const boxes = Array.from(w.element.querySelectorAll('[role="checkbox"]')) as HTMLElement[];
+    boxes[0]!.focus();
+    await nextTick();
+    press(boxes[0]!, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(boxes[1]);
+    w.unmount();
+  });
+
+  it('without rovingFocus, no RovingFocusGroup container is rendered', async () => {
+    const w = mountGroup({ rovingFocus: false });
+    // Members are still functional checkboxes.
+    const boxes = w.element.querySelectorAll('[role="checkbox"]');
+    expect(boxes.length).toBe(3);
+    (boxes[0] as HTMLElement).click();
+    await nextTick();
+    expect(boxes[0]!.getAttribute('aria-checked')).toBe('true');
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/forms/checkbox/context.ts b/vue/primitives/src/forms/checkbox/context.ts
new file mode 100644
index 0000000..dd45a96
--- /dev/null
+++ b/vue/primitives/src/forms/checkbox/context.ts
@@ -0,0 +1,39 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+export type CheckedState = boolean | 'indeterminate';
+
+/**
+ * Values a checkbox can carry through a group model or a hidden form input. A
+ * plain boolean checkbox uses `boolean`, but `trueValue`/`falseValue` and group
+ * membership accept arbitrary primitives or plain objects.
+ */
+export type AcceptableValue = string | number | boolean | Record<string, unknown> | null;
+
+export interface CheckboxContext {
+  checked: Ref<CheckedState>;
+  disabled: Ref<boolean>;
+}
+
+const ctx = useContextFactory<CheckboxContext>('CheckboxContext');
+
+export const provideCheckboxContext = ctx.provide;
+export const useCheckboxContext = ctx.inject;
+
+/**
+ * Context published by `CheckboxGroupRoot`. A `CheckboxRoot` injects it with a
+ * `null` fallback; when present it switches to group mode — its checked state
+ * comes from membership in `modelValue` and toggling pushes/splices its `value`.
+ */
+export interface CheckboxGroupContext {
+  modelValue: Ref<AcceptableValue[]>;
+  disabled: Ref<boolean>;
+  rovingFocus: Ref<boolean>;
+  toggle: (value: AcceptableValue) => void;
+  isChecked: (value: AcceptableValue) => boolean;
+}
+
+const groupCtx = useContextFactory<CheckboxGroupContext>('CheckboxGroupContext');
+
+export const provideCheckboxGroupContext = groupCtx.provide;
+export const useCheckboxGroupContext = groupCtx.inject;
diff --git a/vue/primitives/src/checkbox/demo.vue b/vue/primitives/src/forms/checkbox/demo.vue
similarity index 68%
rename from vue/primitives/src/checkbox/demo.vue
rename to vue/primitives/src/forms/checkbox/demo.vue
index 192188d..2e728db 100644
--- a/vue/primitives/src/checkbox/demo.vue
+++ b/vue/primitives/src/forms/checkbox/demo.vue
@@ -33,19 +33,19 @@ const acceptedTerms = ref(false);
 </script>
 
 <template>
-  <div class="flex flex-col gap-6 p-6 max-w-sm bg-(--bg) text-(--fg) border border-(--border) rounded-xl">
+  <div class="flex flex-col gap-6 p-6 max-w-sm bg-bg text-fg border border-border rounded-xl">
     <fieldset class="flex flex-col gap-3 m-0 p-0 border-0">
-      <legend class="text-sm font-semibold text-(--fg)">
+      <legend class="text-sm font-semibold text-fg">
         Toppings
       </legend>
 
       <label class="flex items-center gap-3 cursor-pointer select-none">
         <CheckboxRoot
           :checked="allChecked"
-          class="grid place-items-center w-5 h-5 rounded-md border border-(--border) bg-(--bg-inset) outline-none transition-colors data-[state=checked]:bg-(--accent) data-[state=indeterminate]:bg-(--accent) data-[state=checked]:border-(--accent) data-[state=indeterminate]:border-(--accent) focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="grid place-items-center w-5 h-5 rounded-md border border-border bg-bg-inset outline-none transition-colors data-[state=checked]:bg-accent data-[state=indeterminate]:bg-accent data-[state=checked]:border-accent data-[state=indeterminate]:border-accent focus-visible:ring-2 focus-visible:ring-ring"
           @checked-change="toggleAll"
         >
-          <CheckboxIndicator v-slot="{ checked }" class="text-(--accent-fg)">
+          <CheckboxIndicator v-slot="{ checked }" class="text-accent-fg">
             <svg v-if="checked === 'indeterminate'" width="12" height="12" viewBox="0 0 12 12" fill="none">
               <path d="M2.5 6h7" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
             </svg>
@@ -55,22 +55,22 @@ const acceptedTerms = ref(false);
           </CheckboxIndicator>
         </CheckboxRoot>
         <span class="text-sm font-medium">Select all</span>
-        <span class="ml-auto text-xs text-(--fg-subtle)">{{ checkedCount }}/{{ ingredients.length }}</span>
+        <span class="ml-auto text-xs text-fg-subtle">{{ checkedCount }}/{{ ingredients.length }}</span>
       </label>
 
-      <div class="flex flex-col gap-2 pl-2 border-l border-(--border)">
+      <div class="flex flex-col gap-2 pl-2 border-l border-border">
         <label v-for="item in ingredients" :key="item.id" class="flex items-center gap-3 cursor-pointer select-none">
           <CheckboxRoot
             v-model:checked="selected[item.id]"
-            class="grid place-items-center w-5 h-5 rounded-md border border-(--border) bg-(--bg-inset) outline-none transition-colors data-[state=checked]:bg-(--accent) data-[state=checked]:border-(--accent) focus-visible:ring-2 focus-visible:ring-(--ring)"
+            class="grid place-items-center w-5 h-5 rounded-md border border-border bg-bg-inset outline-none transition-colors data-[state=checked]:bg-accent data-[state=checked]:border-accent focus-visible:ring-2 focus-visible:ring-ring"
           >
-            <CheckboxIndicator class="text-(--accent-fg)">
+            <CheckboxIndicator class="text-accent-fg">
               <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
                 <path d="M2.5 6.5 5 9l4.5-5.5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
               </svg>
             </CheckboxIndicator>
           </CheckboxRoot>
-          <span class="text-sm text-(--fg)">{{ item.label }}</span>
+          <span class="text-sm text-fg">{{ item.label }}</span>
         </label>
       </div>
     </fieldset>
@@ -79,20 +79,20 @@ const acceptedTerms = ref(false);
       <CheckboxRoot
         v-model:checked="acceptedTerms"
         required
-        class="grid place-items-center w-5 h-5 mt-0.5 rounded-md border border-(--border) bg-(--bg-inset) outline-none transition-colors data-[state=checked]:bg-emerald-500 data-[state=checked]:border-emerald-500 dark:data-[state=checked]:bg-emerald-400 dark:data-[state=checked]:border-emerald-400 focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="grid place-items-center w-5 h-5 mt-0.5 rounded-md border border-border bg-bg-inset outline-none transition-colors data-[state=checked]:bg-emerald-500 data-[state=checked]:border-emerald-500 dark:data-[state=checked]:bg-emerald-400 dark:data-[state=checked]:border-emerald-400 focus-visible:ring-2 focus-visible:ring-ring"
       >
-        <CheckboxIndicator class="text-white dark:text-(--bg)">
+        <CheckboxIndicator class="text-white dark:text-bg">
           <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
             <path d="M2.5 6.5 5 9l4.5-5.5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
           </svg>
         </CheckboxIndicator>
       </CheckboxRoot>
-      <span class="text-sm text-(--fg-muted)">I accept the terms and conditions</span>
+      <span class="text-sm text-fg-muted">I accept the terms and conditions</span>
     </label>
 
     <p
       class="text-xs"
-      :class="acceptedTerms ? 'text-emerald-600 dark:text-emerald-400' : 'text-(--fg-subtle)'"
+      :class="acceptedTerms ? 'text-emerald-600 dark:text-emerald-400' : 'text-fg-subtle'"
     >
       {{ acceptedTerms ? 'Ready to submit' : 'Please accept the terms to continue' }}
     </p>
diff --git a/vue/primitives/src/forms/checkbox/index.ts b/vue/primitives/src/forms/checkbox/index.ts
new file mode 100644
index 0000000..7371693
--- /dev/null
+++ b/vue/primitives/src/forms/checkbox/index.ts
@@ -0,0 +1,15 @@
+export { default as CheckboxGroupRoot } from './CheckboxGroupRoot.vue';
+export { default as CheckboxIndicator } from './CheckboxIndicator.vue';
+export { default as CheckboxRoot } from './CheckboxRoot.vue';
+export type { AcceptableValue, CheckedState } from './context';
+export {
+  provideCheckboxContext,
+  provideCheckboxGroupContext,
+  useCheckboxContext,
+  useCheckboxGroupContext,
+} from './context';
+export type { CheckboxContext, CheckboxGroupContext } from './context';
+export type { CheckboxIndicatorProps } from './CheckboxIndicator.vue';
+export type { CheckboxGroupRootEmits, CheckboxGroupRootProps } from './CheckboxGroupRoot.vue';
+export type { CheckboxRootEmits, CheckboxRootProps } from './CheckboxRoot.vue';
+export { getState, isIndeterminate } from './utils';
diff --git a/vue/primitives/src/forms/checkbox/utils.ts b/vue/primitives/src/forms/checkbox/utils.ts
new file mode 100644
index 0000000..ecb3c0e
--- /dev/null
+++ b/vue/primitives/src/forms/checkbox/utils.ts
@@ -0,0 +1,18 @@
+import type { CheckedState } from './context';
+
+/**
+ * Shared checkbox state helpers, used by both `CheckboxRoot` and
+ * `CheckboxIndicator` so the indeterminate/`data-state` mapping cannot drift
+ * between the two parts.
+ */
+
+/** Narrows a {@link CheckedState} to the `'indeterminate'` literal. */
+export function isIndeterminate(checked?: CheckedState): checked is 'indeterminate' {
+  return checked === 'indeterminate';
+}
+
+/** Canonical `data-state` value for a {@link CheckedState}. */
+export function getState(checked: CheckedState): 'checked' | 'unchecked' | 'indeterminate' {
+  if (isIndeterminate(checked)) return 'indeterminate';
+  return checked ? 'checked' : 'unchecked';
+}
diff --git a/vue/primitives/src/editable/EditableArea.vue b/vue/primitives/src/forms/editable/EditableArea.vue
similarity index 89%
rename from vue/primitives/src/editable/EditableArea.vue
rename to vue/primitives/src/forms/editable/EditableArea.vue
index 3e4e962..f50e12e 100644
--- a/vue/primitives/src/editable/EditableArea.vue
+++ b/vue/primitives/src/forms/editable/EditableArea.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Wrapper that groups the preview and input. It mirrors edit/empty/disabled
@@ -10,7 +10,7 @@ export interface EditableAreaProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useEditableContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
diff --git a/vue/primitives/src/editable/EditableCancelTrigger.vue b/vue/primitives/src/forms/editable/EditableCancelTrigger.vue
similarity index 84%
rename from vue/primitives/src/editable/EditableCancelTrigger.vue
rename to vue/primitives/src/forms/editable/EditableCancelTrigger.vue
index 199a27a..256a536 100644
--- a/vue/primitives/src/editable/EditableCancelTrigger.vue
+++ b/vue/primitives/src/forms/editable/EditableCancelTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Button that discards the draft, restores the committed value, and leaves edit
@@ -9,7 +9,7 @@ export interface EditableCancelTriggerProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useEditableContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
@@ -26,6 +26,7 @@ const { forwardRef } = useForwardExpose();
     :type="as === 'button' ? 'button' : undefined"
     aria-label="cancel"
     :disabled="ctx.disabled.value || undefined"
+    :aria-disabled="ctx.disabled.value || undefined"
     :data-disabled="ctx.disabled.value ? '' : undefined"
     :hidden="ctx.isEditing.value ? undefined : ''"
     :style="ctx.isEditing.value ? undefined : { display: 'none' }"
diff --git a/vue/primitives/src/editable/EditableEditTrigger.vue b/vue/primitives/src/forms/editable/EditableEditTrigger.vue
similarity index 84%
rename from vue/primitives/src/editable/EditableEditTrigger.vue
rename to vue/primitives/src/forms/editable/EditableEditTrigger.vue
index e287c75..1f1f203 100644
--- a/vue/primitives/src/editable/EditableEditTrigger.vue
+++ b/vue/primitives/src/forms/editable/EditableEditTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Button that enters edit mode. It is hidden while editing and disabled when the
@@ -9,7 +9,7 @@ export interface EditableEditTriggerProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useEditableContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
@@ -26,6 +26,7 @@ const { forwardRef } = useForwardExpose();
     :type="as === 'button' ? 'button' : undefined"
     aria-label="edit"
     :disabled="ctx.disabled.value || undefined"
+    :aria-disabled="ctx.disabled.value || undefined"
     :data-disabled="ctx.disabled.value ? '' : undefined"
     :hidden="ctx.isEditing.value ? '' : undefined"
     :style="ctx.isEditing.value ? { display: 'none' } : undefined"
diff --git a/vue/primitives/src/editable/EditableInput.vue b/vue/primitives/src/forms/editable/EditableInput.vue
similarity index 94%
rename from vue/primitives/src/editable/EditableInput.vue
rename to vue/primitives/src/forms/editable/EditableInput.vue
index 6b14ae1..389112b 100644
--- a/vue/primitives/src/editable/EditableInput.vue
+++ b/vue/primitives/src/forms/editable/EditableInput.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The text input shown while editing. It binds the draft value, auto-focuses
@@ -11,7 +11,7 @@ export interface EditableInputProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import { nextTick, onMounted, watch } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useEditableContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
@@ -68,6 +68,7 @@ function onKeyDown(event: KeyboardEvent): void {
   <Primitive
     :ref="forwardRef"
     :as="as"
+    :id="ctx.id.value"
     :value="ctx.inputValue.value"
     :placeholder="ctx.placeholder.value.edit"
     :disabled="ctx.disabled.value"
diff --git a/vue/primitives/src/editable/EditablePreview.vue b/vue/primitives/src/forms/editable/EditablePreview.vue
similarity index 93%
rename from vue/primitives/src/editable/EditablePreview.vue
rename to vue/primitives/src/forms/editable/EditablePreview.vue
index 24644c9..557fff8 100644
--- a/vue/primitives/src/editable/EditablePreview.vue
+++ b/vue/primitives/src/forms/editable/EditablePreview.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Read-only display of the current value (or the preview placeholder when
@@ -10,7 +10,7 @@ export interface EditablePreviewProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { useEditableContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
diff --git a/vue/primitives/src/editable/EditableRoot.vue b/vue/primitives/src/forms/editable/EditableRoot.vue
similarity index 58%
rename from vue/primitives/src/editable/EditableRoot.vue
rename to vue/primitives/src/forms/editable/EditableRoot.vue
index d61a37c..9ba8b27 100644
--- a/vue/primitives/src/editable/EditableRoot.vue
+++ b/vue/primitives/src/forms/editable/EditableRoot.vue
@@ -1,6 +1,7 @@
 <script lang="ts">
 import type { EditableActivationMode, EditablePlaceholder, EditableSubmitMode } from './context';
-import type { PrimitiveProps } from '../primitive';
+import type { Direction } from '../../utilities/config-provider';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Inline-editable text field that toggles between a read-only preview and an
@@ -29,6 +30,20 @@ export interface EditableRootProps extends PrimitiveProps {
   disabled?: boolean;
   /** Read-only state. */
   readonly?: boolean;
+  /**
+   * Reading direction. When omitted, inherits from the active `ConfigProvider`
+   * and otherwise assumes left-to-right.
+   */
+  dir?: Direction;
+  /** Stable id, applied to the input and forwarded through context. */
+  id?: string;
+  /**
+   * Native control name. When set and the Root is inside a `<form>`, a
+   * visually-hidden `<input>` submits the value with the surrounding form.
+   */
+  name?: string;
+  /** Mark the field required so native form validation fires on empty submit. */
+  required?: boolean;
 }
 
 export interface EditableRootEmits {
@@ -38,10 +53,12 @@ export interface EditableRootEmits {
 </script>
 
 <script setup lang="ts">
-import { computed, onBeforeUnmount, ref, shallowRef, toRef, watch } from 'vue';
-import { Primitive } from '../primitive';
+import { computed, ref, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
 import { provideEditableContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
+import { useEventListener, useForwardExpose, useTimeoutFn } from '@robonen/vue';
+import { useDirection, useId } from '../../utilities/config-provider';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
 
 defineOptions({ inheritAttrs: false });
 
@@ -57,11 +74,16 @@ const {
   maxLength,
   disabled = false,
   readonly = false,
+  dir: dirProp,
+  id,
+  name,
+  required = false,
 } = defineProps<EditableRootProps>();
 
 const emit = defineEmits<EditableRootEmits>();
 
-const { forwardRef, currentElement } = useForwardExpose();
+const dir = useDirection(() => dirProp);
+const resolvedId = useId(() => id, 'editable');
 
 // Uncontrolled fallback, seeded from `defaultValue`. In controlled mode the
 // `get` reads the live prop, so local state can never go stale.
@@ -119,27 +141,63 @@ function submit(): void {
   emit('submit', inputValue.value);
 }
 
-let blurTimer: ReturnType<typeof setTimeout> | undefined;
-onBeforeUnmount(() => clearTimeout(blurTimer));
+// `defineExpose` runs before `useForwardExpose` so the imperative methods are
+// merged onto the instance's exposed object alongside the forwarded element.
+defineExpose({ edit, cancel, submit });
+const { forwardRef, currentElement } = useForwardExpose();
+
+const isFormControl = computed(() => {
+  const el = currentElement.value;
+  return !!el && !!el.closest('form');
+});
+
+// Commit or discard on an outside interaction, honoring `submitMode`.
+function handleDismiss(): void {
+  if (!isEditing.value) return;
+  if (submitMode === 'blur' || submitMode === 'both') submit();
+  else cancel();
+}
+
+// Deferred dismiss check. Hiding the focused preview/trigger on entering edit
+// mode fires a synchronous focusout with relatedTarget=null before the input's
+// autofocus lands — defer the decision and re-check where focus actually ended
+// up. Also covers the `relatedTarget === null` browser case where blur reports
+// no next target even though focus stayed within the root. Auto-cancelled on
+// scope dispose.
+const { start: deferDismissCheck, stop: cancelDismissCheck } = useTimeoutFn(() => {
+  if (!isEditing.value) return;
+  const root = currentElement.value;
+  const active = document.activeElement;
+  if (root && active && root.contains(active)) return;
+  handleDismiss();
+}, 0, { immediate: false });
 
 function onFocusOutCapture(event: FocusEvent): void {
   if (!isEditing.value) return;
   const root = currentElement.value;
   const next = event.relatedTarget as Node | null;
   if (root && next && root.contains(next)) return;
-  // Hiding the focused preview/trigger on entering edit mode fires a
-  // synchronous focusout with relatedTarget=null before the input's autofocus
-  // lands — defer the decision and re-check where focus actually ended up.
-  clearTimeout(blurTimer);
-  blurTimer = setTimeout(() => {
-    if (!isEditing.value) return;
-    const active = document.activeElement;
-    if (root && active && root.contains(active)) return;
-    if (submitMode === 'blur' || submitMode === 'both') submit();
-    else cancel();
-  }, 0);
+  cancelDismissCheck();
+  deferDismissCheck();
 }
 
+// Pointer-down outside the root also dismisses, covering clicks on
+// non-focusable regions that never move DOM focus (and thus never fire a
+// dismissing `focusout`). Document-level + capture so it sees the interaction
+// before it is swallowed; auto-disposed with the component scope.
+useEventListener(
+  () => (typeof document === 'undefined' ? undefined : document),
+  'pointerdown',
+  (event: Event) => {
+    if (!isEditing.value) return;
+    const root = currentElement.value;
+    const target = event.target as Node | null;
+    if (root && target && (root === target || root.contains(target))) return;
+    handleDismiss();
+  },
+  { capture: true },
+);
+
 provideEditableContext({
   modelValue: model,
   inputValue,
@@ -154,6 +212,8 @@ provideEditableContext({
   selectOnFocus: toRef(() => selectOnFocus),
   autoResize: toRef(() => autoResize),
   startWithEditMode: toRef(() => startWithEditMode),
+  id: resolvedId,
+  dir,
   inputRef,
   edit,
   cancel,
@@ -166,6 +226,7 @@ provideEditableContext({
     v-bind="$attrs"
     :ref="forwardRef"
     :as="as"
+    :dir="dir"
     :data-state="isEditing ? 'edit' : 'preview'"
     :data-empty="isEmpty ? '' : undefined"
     :data-disabled="disabled ? '' : undefined"
@@ -180,5 +241,14 @@ provideEditableContext({
       :cancel="cancel"
       :submit="submit"
     />
+
+    <VisuallyHiddenInput
+      v-if="isFormControl && name"
+      type="text"
+      :name="name"
+      :value="model"
+      :required="required"
+      :disabled="disabled"
+    />
   </Primitive>
 </template>
diff --git a/vue/primitives/src/editable/EditableSubmitTrigger.vue b/vue/primitives/src/forms/editable/EditableSubmitTrigger.vue
similarity index 84%
rename from vue/primitives/src/editable/EditableSubmitTrigger.vue
rename to vue/primitives/src/forms/editable/EditableSubmitTrigger.vue
index caad897..44fad93 100644
--- a/vue/primitives/src/editable/EditableSubmitTrigger.vue
+++ b/vue/primitives/src/forms/editable/EditableSubmitTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Button that commits the draft value and leaves edit mode. It is only shown
@@ -9,7 +9,7 @@ export interface EditableSubmitTriggerProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useEditableContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
@@ -26,6 +26,7 @@ const { forwardRef } = useForwardExpose();
     :type="as === 'button' ? 'button' : undefined"
     aria-label="submit"
     :disabled="ctx.disabled.value || undefined"
+    :aria-disabled="ctx.disabled.value || undefined"
     :data-disabled="ctx.disabled.value ? '' : undefined"
     :hidden="ctx.isEditing.value ? undefined : ''"
     :style="ctx.isEditing.value ? undefined : { display: 'none' }"
diff --git a/vue/primitives/src/editable/__test__/Editable.test.ts b/vue/primitives/src/forms/editable/__test__/Editable.test.ts
similarity index 63%
rename from vue/primitives/src/editable/__test__/Editable.test.ts
rename to vue/primitives/src/forms/editable/__test__/Editable.test.ts
index d14f088..e9fb69f 100644
--- a/vue/primitives/src/editable/__test__/Editable.test.ts
+++ b/vue/primitives/src/forms/editable/__test__/Editable.test.ts
@@ -271,4 +271,172 @@ describe('Editable', () => {
     expect(root.emitted('update:state')).toBeUndefined();
     w.unmount();
   });
+
+  it('threads id prop onto the input', () => {
+    const w = createEditable({ id: 'my-field', defaultValue: 'v' });
+    expect(w.find('input').attributes('id')).toBe('my-field');
+    w.unmount();
+  });
+
+  it('binds resolved dir on the root', () => {
+    const w = createEditable({ dir: 'rtl', defaultValue: 'v' });
+    expect(w.findComponent(EditableRoot).element.getAttribute('dir')).toBe('rtl');
+    w.unmount();
+  });
+
+  it('defaults dir to ltr when no override is provided', () => {
+    const w = createEditable({ defaultValue: 'v' });
+    expect(w.findComponent(EditableRoot).element.getAttribute('dir')).toBe('ltr');
+    w.unmount();
+  });
+
+  it('exposes imperative edit/cancel/submit via a template ref', async () => {
+    const exposedRef = ref<{ edit: () => void; cancel: () => void; submit: () => void } | null>(null);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            EditableRoot,
+            { ref: exposedRef as unknown as Record<string, unknown>, defaultValue: 'v' },
+            {
+              default: () => h(EditableArea, null, {
+                default: () => [h(EditablePreview), h(EditableInput)],
+              }),
+            },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(typeof exposedRef.value?.edit).toBe('function');
+    expect(typeof exposedRef.value?.cancel).toBe('function');
+    expect(typeof exposedRef.value?.submit).toBe('function');
+    exposedRef.value!.edit();
+    await nextTick();
+    expect((w.find('input').element as HTMLInputElement).hidden).toBe(false);
+    w.unmount();
+  });
+
+  it('sets aria-disabled on triggers when disabled', () => {
+    const w = createEditable({ defaultValue: 'v', disabled: true });
+    w.findAll('button').forEach((b) => {
+      expect(b.attributes('aria-disabled')).toBe('true');
+    });
+    w.unmount();
+  });
+
+  it('omits aria-disabled on triggers when enabled', () => {
+    const w = createEditable({ defaultValue: 'v' });
+    w.findAll('button').forEach((b) => {
+      expect(b.attributes('aria-disabled')).toBeUndefined();
+    });
+    w.unmount();
+  });
+
+  it('does not render a hidden form input without a surrounding form', () => {
+    const w = createEditable({ defaultValue: 'v', name: 'field' });
+    const inputs = w.findAll('input');
+    // Only the EditableInput exists; no visually-hidden form input.
+    expect(inputs.filter(i => i.attributes('name') === 'field')).toHaveLength(0);
+    w.unmount();
+  });
+
+  it('renders a hidden form input mirroring the value inside a form', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h('form', null, [
+            h(
+              EditableRoot,
+              { defaultValue: 'submitted-value', name: 'field' },
+              {
+                default: () => h(EditableArea, null, {
+                  default: () => [h(EditablePreview), h(EditableInput)],
+                }),
+              },
+            ),
+          ]);
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const hidden = w.findAll('input').find(i => i.attributes('name') === 'field');
+    expect(hidden).toBeTruthy();
+    expect((hidden!.element as HTMLInputElement).value).toBe('submitted-value');
+    w.unmount();
+  });
+
+  it('mirrors required onto the hidden form input', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h('form', null, [
+            h(
+              EditableRoot,
+              { defaultValue: '', name: 'field', required: true },
+              {
+                default: () => h(EditableArea, null, {
+                  default: () => [h(EditablePreview), h(EditableInput)],
+                }),
+              },
+            ),
+          ]);
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const hidden = w.findAll('input').find(i => i.attributes('name') === 'field');
+    expect(hidden!.attributes('required')).toBeDefined();
+    w.unmount();
+  });
+
+  it('commits on pointerdown outside the root (submitMode blur)', async () => {
+    const outside = document.createElement('div');
+    document.body.appendChild(outside);
+    const w = createEditable({ defaultValue: 'v1', startWithEditMode: true, submitMode: 'blur' });
+    await nextTick();
+    const input = w.find('input');
+    (input.element as HTMLInputElement).value = 'v2';
+    await input.trigger('input');
+    outside.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true }));
+    await waitForBlurTimers();
+    const root = w.findComponent(EditableRoot);
+    expect(root.emitted('submit')?.at(-1)).toEqual(['v2']);
+    outside.remove();
+    w.unmount();
+  });
+
+  it('cancels on pointerdown outside the root (submitMode enter)', async () => {
+    const outside = document.createElement('div');
+    document.body.appendChild(outside);
+    const w = createEditable({ defaultValue: 'v1', startWithEditMode: true, submitMode: 'enter' });
+    await nextTick();
+    const input = w.find('input');
+    (input.element as HTMLInputElement).value = 'v2';
+    await input.trigger('input');
+    outside.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true }));
+    await waitForBlurTimers();
+    const root = w.findComponent(EditableRoot);
+    expect(root.emitted('submit')).toBeUndefined();
+    expect(w.find('span').text()).toBe('v1');
+    outside.remove();
+    w.unmount();
+  });
+
+  it('does not dismiss on pointerdown inside the root', async () => {
+    const w = createEditable({ defaultValue: 'v1', startWithEditMode: true, submitMode: 'blur' });
+    await nextTick();
+    const input = w.find('input');
+    (input.element as HTMLInputElement).value = 'v2';
+    await input.trigger('input');
+    input.element.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true }));
+    await waitForBlurTimers();
+    const root = w.findComponent(EditableRoot);
+    expect(root.emitted('submit')).toBeUndefined();
+    expect((input.element as HTMLInputElement).hidden).toBe(false);
+    w.unmount();
+  });
 });
diff --git a/vue/primitives/src/forms/editable/__test__/a11y.test.ts b/vue/primitives/src/forms/editable/__test__/a11y.test.ts
new file mode 100644
index 0000000..34f4ed2
--- /dev/null
+++ b/vue/primitives/src/forms/editable/__test__/a11y.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { mount } from '@vue/test-utils';
+import axe from 'axe-core';
+import {
+  EditableArea,
+  EditableCancelTrigger,
+  EditableEditTrigger,
+  EditableInput,
+  EditablePreview,
+  EditableRoot,
+  EditableSubmitTrigger,
+} from '../index';
+
+async function checkA11y(element: Element) {
+  const results = await axe.run(element);
+  return results.violations;
+}
+
+function createEditable(rootProps: Record<string, unknown> = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () => h(
+          EditableRoot,
+          rootProps,
+          {
+            default: () => h(EditableArea, null, {
+              default: () => [
+                h(EditablePreview),
+                h(EditableInput),
+                h(EditableEditTrigger),
+                h(EditableSubmitTrigger),
+                h(EditableCancelTrigger),
+              ],
+            }),
+          },
+        );
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+describe('Editable a11y', () => {
+  it('has no axe violations in preview mode', async () => {
+    const w = createEditable({ defaultValue: 'Hello' });
+    const violations = await checkA11y(w.element);
+    expect(violations).toEqual([]);
+    w.unmount();
+  });
+
+  it('has no axe violations in edit mode', async () => {
+    const w = createEditable({ defaultValue: 'Hello', startWithEditMode: true });
+    await nextTick();
+    const violations = await checkA11y(w.element);
+    expect(violations).toEqual([]);
+    w.unmount();
+  });
+
+  it('has no axe violations when disabled', async () => {
+    const w = createEditable({ defaultValue: 'Hello', disabled: true });
+    const violations = await checkA11y(w.element);
+    expect(violations).toEqual([]);
+    w.unmount();
+  });
+
+  it('has no axe violations when readonly', async () => {
+    const w = createEditable({ defaultValue: 'Hello', readonly: true, startWithEditMode: true });
+    await nextTick();
+    const violations = await checkA11y(w.element);
+    expect(violations).toEqual([]);
+    w.unmount();
+  });
+
+  it('keeps the input labelled', () => {
+    const w = createEditable({ defaultValue: 'Hello' });
+    expect(w.find('input').attributes('aria-label')).toBe('editable input');
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/editable/context.ts b/vue/primitives/src/forms/editable/context.ts
similarity index 80%
rename from vue/primitives/src/editable/context.ts
rename to vue/primitives/src/forms/editable/context.ts
index e3ad163..2fba981 100644
--- a/vue/primitives/src/editable/context.ts
+++ b/vue/primitives/src/forms/editable/context.ts
@@ -1,4 +1,5 @@
-import type { Ref, ShallowRef } from 'vue';
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import type { Direction } from '../../utilities/config-provider';
 import { useContextFactory } from '@robonen/vue';
 
 export type EditableActivationMode = 'focus' | 'dblclick' | 'none';
@@ -30,6 +31,11 @@ export interface EditableContext {
   autoResize: Ref<boolean>;
   startWithEditMode: Ref<boolean>;
 
+  /** Stable id, threaded for aria wiring on parts. */
+  id: Ref<string>;
+  /** Resolved reading direction (per-Root prop over `ConfigProvider`). */
+  dir: ComputedRef<Direction>;
+
   /** Reactive ref to the `<EditableInput>` element, used for focus/select. */
   inputRef: ShallowRef<HTMLInputElement | undefined>;
 
diff --git a/vue/primitives/src/editable/demo.vue b/vue/primitives/src/forms/editable/demo.vue
similarity index 52%
rename from vue/primitives/src/editable/demo.vue
rename to vue/primitives/src/forms/editable/demo.vue
index 4c89074..378cef8 100644
--- a/vue/primitives/src/editable/demo.vue
+++ b/vue/primitives/src/forms/editable/demo.vue
@@ -14,8 +14,8 @@ const name = ref('Ada Lovelace');
 </script>
 
 <template>
-  <div class="w-full max-w-sm rounded-xl border border-(--border) bg-(--bg-elevated) p-4 text-(--fg)">
-    <span class="mb-2 block text-xs font-medium text-(--fg-muted)">Display name</span>
+  <div class="demo-card w-full max-w-sm p-4 text-fg">
+    <span class="mb-2 block text-xs font-medium text-fg-muted">Display name</span>
 
     <EditableRoot
       v-model="name"
@@ -27,33 +27,33 @@ const name = ref('Ada Lovelace');
     >
       <EditableArea class="flex-1">
         <EditablePreview
-          class="block w-full cursor-text rounded-md px-2 py-1.5 outline-none transition hover:bg-(--bg-inset) data-[placeholder-shown]:text-(--fg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="block w-full cursor-text rounded-md px-2 py-1.5 outline-none transition hover:bg-bg-inset data-[placeholder-shown]:text-fg-subtle focus-visible:ring-2 focus-visible:ring-ring"
         />
         <EditableInput
-          class="w-full rounded-md border border-(--border) bg-(--bg) px-2 py-1.5 text-(--fg) outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="w-full rounded-md border border-border bg-bg px-2 py-1.5 text-fg outline-none focus-visible:ring-2 focus-visible:ring-ring"
         />
       </EditableArea>
 
       <EditableEditTrigger
-        class="inline-flex h-8 items-center rounded-md border border-(--border) bg-(--bg) px-2.5 text-sm text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
+        class="inline-flex h-8 items-center rounded-md border border-border bg-bg px-2.5 text-sm text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer disabled:cursor-not-allowed disabled:opacity-40"
       >
         Edit
       </EditableEditTrigger>
 
       <EditableSubmitTrigger
-        class="inline-flex h-8 items-center rounded-md bg-(--accent) px-2.5 text-sm font-medium text-(--accent-fg) transition hover:bg-(--accent-hover) active:scale-95 cursor-pointer"
+        class="inline-flex h-8 items-center rounded-md bg-accent px-2.5 text-sm font-medium text-accent-fg transition hover:bg-accent-hover active:scale-95 cursor-pointer"
       >
         Save
       </EditableSubmitTrigger>
 
       <EditableCancelTrigger
-        class="inline-flex h-8 items-center rounded-md border border-(--border) bg-(--bg) px-2.5 text-sm text-(--fg-muted) transition hover:bg-(--bg-inset) hover:text-(--fg) active:scale-95 cursor-pointer"
+        class="inline-flex h-8 items-center rounded-md border border-border bg-bg px-2.5 text-sm text-fg-muted transition hover:bg-bg-inset hover:text-fg active:scale-95 cursor-pointer"
       >
         Cancel
       </EditableCancelTrigger>
     </EditableRoot>
 
-    <p class="mt-3 text-xs text-(--fg-subtle)">
+    <p class="mt-3 text-xs text-fg-subtle">
       Double-click the name to edit. Enter or blur saves, Escape cancels.
     </p>
   </div>
diff --git a/vue/primitives/src/editable/index.ts b/vue/primitives/src/forms/editable/index.ts
similarity index 100%
rename from vue/primitives/src/editable/index.ts
rename to vue/primitives/src/forms/editable/index.ts
diff --git a/vue/primitives/src/label/Label.vue b/vue/primitives/src/forms/label/Label.vue
similarity index 89%
rename from vue/primitives/src/label/Label.vue
rename to vue/primitives/src/forms/label/Label.vue
index ac0cecb..6bf4b8f 100644
--- a/vue/primitives/src/label/Label.vue
+++ b/vue/primitives/src/forms/label/Label.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A caption associated with a form control. Renders a native `<label>` and,
@@ -15,7 +15,7 @@ export interface LabelProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/forms/label/__test__/Label.test.ts b/vue/primitives/src/forms/label/__test__/Label.test.ts
new file mode 100644
index 0000000..e7c30bc
--- /dev/null
+++ b/vue/primitives/src/forms/label/__test__/Label.test.ts
@@ -0,0 +1,130 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { Label } from '../index';
+
+let mounted: ReturnType<typeof mount> | undefined;
+
+afterEach(() => {
+  mounted?.unmount();
+  mounted = undefined;
+});
+
+describe('Label', () => {
+  it('renders a native <label>', () => {
+    const wrapper = mount(Label, { slots: { default: 'Name' } });
+    expect(wrapper.element.tagName).toBe('LABEL');
+    expect(wrapper.text()).toBe('Name');
+  });
+
+  it('forwards `for` to the `for` attribute', () => {
+    const wrapper = mount(Label, { props: { for: 'my-input' } });
+    expect(wrapper.attributes('for')).toBe('my-input');
+  });
+
+  it('renders nothing extra with neither slot nor `for`', () => {
+    const wrapper = mount(Label);
+    expect(wrapper.html()).toBe('<label></label>');
+  });
+
+  it('renders `for` together with slot content', () => {
+    const wrapper = mount(Label, { props: { for: 'input' }, slots: { default: 'Name' } });
+    expect(wrapper.html()).toBe('<label for="input">Name</label>');
+  });
+
+  it('prevents text selection on multi-click', () => {
+    const wrapper = mount(defineComponent({
+      setup: () => () => h(Label, null, { default: () => 'x' }),
+    }));
+    const event = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 2 });
+    wrapper.element.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('does not prevent default on single click', () => {
+    const wrapper = mount(Label);
+    const event = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 1 });
+    wrapper.element.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it('does not re-prevent default when already prevented', () => {
+    const wrapper = mount(Label);
+    const event = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 3 });
+    event.preventDefault();
+    wrapper.element.dispatchEvent(event);
+    // Stays prevented but the handler short-circuits on defaultPrevented.
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  describe('polymorphism', () => {
+    it('renders as a custom element via `as`', () => {
+      const wrapper = mount(Label, { props: { as: 'span' }, slots: { default: 'Name' } });
+      expect(wrapper.element.tagName).toBe('SPAN');
+      expect(wrapper.text()).toBe('Name');
+    });
+
+    it('merges behaviour onto the slotted child via as="template"', () => {
+      // as="template" is this package's composition mechanism: the label's
+      // props (for) and listeners (mousedown) are merged onto the single
+      // slotted child instead of rendering an extra wrapper element.
+      const wrapper = mount(Label, {
+        props: { as: 'template', for: 'merged' },
+        slots: { default: () => h('button', { type: 'button' }, 'Pick') },
+      });
+      expect(wrapper.element.tagName).toBe('BUTTON');
+      expect(wrapper.attributes('for')).toBe('merged');
+    });
+
+    it('forwards mousedown handling through as="template"', () => {
+      const wrapper = mount(defineComponent({
+        setup: () => () => h(Label, { as: 'template' }, {
+          default: () => h('span', null, 'x'),
+        }),
+      }));
+      const event = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 2 });
+      wrapper.element.dispatchEvent(event);
+      expect(event.defaultPrevented).toBe(true);
+    });
+  });
+
+  describe('control association edge cases', () => {
+    it('does not move focus when clicked without a `for`', async () => {
+      const wrapper = mount(defineComponent({
+        setup: () => () => h('div', [
+          h(Label, null, { default: () => 'Name' }),
+          h('input', { id: 'input' }),
+        ]),
+      }), { attachTo: document.body });
+      mounted = wrapper;
+
+      wrapper.element.querySelector('label')!.click();
+      await nextTick();
+
+      expect(document.activeElement).not.toBe(wrapper.element.querySelector('input'));
+    });
+
+    it('does not move focus when `for` points to a missing id', async () => {
+      const wrapper = mount(defineComponent({
+        setup: () => () => h('div', [
+          h(Label, { for: 'missing' }, { default: () => 'Name' }),
+          h('input', { id: 'present' }),
+        ]),
+      }), { attachTo: document.body });
+      mounted = wrapper;
+
+      wrapper.element.querySelector('label')!.click();
+      await nextTick();
+
+      expect(document.activeElement).not.toBe(wrapper.element.querySelector('input'));
+    });
+  });
+
+  describe('ref forwarding', () => {
+    it('exposes the underlying element via forwardRef', () => {
+      const wrapper = mount(Label, { props: { for: 'x' }, slots: { default: 'Name' } });
+      const exposed = wrapper.vm.$el as HTMLElement;
+      expect(exposed.tagName).toBe('LABEL');
+    });
+  });
+});
diff --git a/vue/primitives/src/forms/label/__test__/a11y.test.ts b/vue/primitives/src/forms/label/__test__/a11y.test.ts
new file mode 100644
index 0000000..d09fa20
--- /dev/null
+++ b/vue/primitives/src/forms/label/__test__/a11y.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { mount } from '@vue/test-utils';
+import axe from 'axe-core';
+import { Label } from '../index';
+
+async function checkA11y(element: Element) {
+  const results = await axe.run(element);
+
+  return results.violations;
+}
+
+function createLabelledField(props: Record<string, unknown> = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () =>
+          h('div', [
+            h(Label, { for: 'input', ...props }, { default: () => 'Name' }),
+            h('input', { id: 'input', type: 'text' }),
+          ]);
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+describe('Label a11y', () => {
+  it('has no axe violations when associated with a native control', async () => {
+    const wrapper = createLabelledField();
+    await nextTick();
+
+    const violations = await checkA11y(wrapper.element);
+    expect(violations).toEqual([]);
+
+    wrapper.unmount();
+  });
+
+  it('has no axe violations when wrapping a control', async () => {
+    const wrapper = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h('div', [
+              h(Label, null, {
+                default: () => [
+                  'Subscribe',
+                  h('input', { id: 'checkbox', type: 'checkbox' }),
+                ],
+              }),
+            ]);
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+
+    const violations = await checkA11y(wrapper.element);
+    expect(violations).toEqual([]);
+
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/label/demo.vue b/vue/primitives/src/forms/label/demo.vue
similarity index 72%
rename from vue/primitives/src/label/demo.vue
rename to vue/primitives/src/forms/label/demo.vue
index 400dbe1..0940070 100644
--- a/vue/primitives/src/label/demo.vue
+++ b/vue/primitives/src/forms/label/demo.vue
@@ -8,7 +8,7 @@ const notify = ref(true);
 
 <template>
   <form
-    class="flex w-full max-w-sm flex-col gap-5 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 text-(--fg)"
+    class="demo-card flex w-full max-w-sm flex-col gap-5 p-5 text-fg"
     @submit.prevent
   >
     <div class="flex flex-col gap-1.5">
@@ -23,9 +23,9 @@ const notify = ref(true);
         v-model="email"
         type="email"
         placeholder="you@example.com"
-        class="rounded-md border border-(--border) bg-(--bg-inset) px-3 py-2 text-sm outline-none focus:border-(--accent) focus:ring-2 focus:ring-(--ring)"
+        class="rounded-md border border-border bg-bg-inset px-3 py-2 text-sm outline-none focus:border-accent focus:ring-2 focus:ring-ring"
       >
-      <p class="text-xs text-(--fg-subtle)">
+      <p class="text-xs text-fg-subtle">
         Click the label above to focus the field.
       </p>
     </div>
@@ -38,7 +38,7 @@ const notify = ref(true);
         id="demo-notify"
         v-model="notify"
         type="checkbox"
-        class="size-4 accent-(--accent)"
+        class="size-4 accent-accent"
       >
       Email me about product updates
     </Label>
@@ -47,7 +47,7 @@ const notify = ref(true);
       class="text-sm"
       :class="notify
         ? 'text-emerald-600 dark:text-emerald-400'
-        : 'text-(--fg-muted)'"
+        : 'text-fg-muted'"
     >
       {{ notify ? 'You will receive updates.' : 'Updates are off.' }}
     </p>
diff --git a/vue/primitives/src/label/index.ts b/vue/primitives/src/forms/label/index.ts
similarity index 100%
rename from vue/primitives/src/label/index.ts
rename to vue/primitives/src/forms/label/index.ts
diff --git a/vue/primitives/src/forms/number-field/NumberFieldDecrement.vue b/vue/primitives/src/forms/number-field/NumberFieldDecrement.vue
new file mode 100644
index 0000000..68f0b41
--- /dev/null
+++ b/vue/primitives/src/forms/number-field/NumberFieldDecrement.vue
@@ -0,0 +1,66 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A button that decreases the value by one `step`. Rendered as a `<button>` by
+ * default, kept out of the tab order (the input is the focusable spinbutton) but
+ * exposed to assistive tech with an `aria-label`. Holding the button auto-repeats
+ * the decrement, and it is disabled when the root is `disabled`/`readonly`, when
+ * its own `disabled` prop is set, or when the value is already at `min`.
+ */
+export interface NumberFieldDecrementProps extends PrimitiveProps {
+  /** Disable this button independently of the root. */
+  disabled?: boolean;
+  /**
+   * Accessible label for assistive tech. Bind via `aria-label` (Vue maps the
+   * kebab-case attribute to this prop).
+   * @default 'Decrease'
+   */
+  ariaLabel?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useNumberFieldContext } from './context';
+import { usePressedHold } from './utils';
+
+const { as = 'button', disabled = false, ariaLabel = 'Decrease' } = defineProps<NumberFieldDecrementProps>();
+const { forwardRef, currentElement } = useForwardExpose();
+const ctx = useNumberFieldContext();
+
+const isDisabled = computed(() =>
+  ctx.disabled.value || ctx.readonly.value || disabled || ctx.isDecrementDisabled.value);
+
+const { isPressed, onTrigger, consumeClick } = usePressedHold({ target: currentElement, disabled: isDisabled });
+
+onTrigger(() => ctx.decrement());
+
+function onClick(): void {
+  // Pointer presses already fired via `onTrigger`; only handle clicks with no
+  // preceding pointer press (programmatic `.click()`, keyboard activation).
+  if (consumeClick() || isDisabled.value)
+    return;
+  ctx.decrement();
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    tabindex="-1"
+    :aria-label="ariaLabel"
+    :style="{ userSelect: isPressed ? 'none' : undefined }"
+    :disabled="isDisabled || undefined"
+    :data-disabled="isDisabled ? '' : undefined"
+    :data-pressed="isPressed ? 'true' : undefined"
+    @click="onClick"
+    @contextmenu.prevent
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/forms/number-field/NumberFieldIncrement.vue b/vue/primitives/src/forms/number-field/NumberFieldIncrement.vue
new file mode 100644
index 0000000..5ae58ae
--- /dev/null
+++ b/vue/primitives/src/forms/number-field/NumberFieldIncrement.vue
@@ -0,0 +1,66 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A button that increases the value by one `step`. Rendered as a `<button>` by
+ * default, kept out of the tab order (the input is the focusable spinbutton) but
+ * exposed to assistive tech with an `aria-label`. Holding the button auto-repeats
+ * the increment, and it is disabled when the root is `disabled`/`readonly`, when
+ * its own `disabled` prop is set, or when the value is already at `max`.
+ */
+export interface NumberFieldIncrementProps extends PrimitiveProps {
+  /** Disable this button independently of the root. */
+  disabled?: boolean;
+  /**
+   * Accessible label for assistive tech. Bind via `aria-label` (Vue maps the
+   * kebab-case attribute to this prop).
+   * @default 'Increase'
+   */
+  ariaLabel?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useNumberFieldContext } from './context';
+import { usePressedHold } from './utils';
+
+const { as = 'button', disabled = false, ariaLabel = 'Increase' } = defineProps<NumberFieldIncrementProps>();
+const { forwardRef, currentElement } = useForwardExpose();
+const ctx = useNumberFieldContext();
+
+const isDisabled = computed(() =>
+  ctx.disabled.value || ctx.readonly.value || disabled || ctx.isIncrementDisabled.value);
+
+const { isPressed, onTrigger, consumeClick } = usePressedHold({ target: currentElement, disabled: isDisabled });
+
+onTrigger(() => ctx.increment());
+
+function onClick(): void {
+  // Pointer presses already fired via `onTrigger`; only handle clicks with no
+  // preceding pointer press (programmatic `.click()`, keyboard activation).
+  if (consumeClick() || isDisabled.value)
+    return;
+  ctx.increment();
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    tabindex="-1"
+    :aria-label="ariaLabel"
+    :style="{ userSelect: isPressed ? 'none' : undefined }"
+    :disabled="isDisabled || undefined"
+    :data-disabled="isDisabled ? '' : undefined"
+    :data-pressed="isPressed ? 'true' : undefined"
+    @click="onClick"
+    @contextmenu.prevent
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/forms/number-field/NumberFieldInput.vue b/vue/primitives/src/forms/number-field/NumberFieldInput.vue
new file mode 100644
index 0000000..c0bae29
--- /dev/null
+++ b/vue/primitives/src/forms/number-field/NumberFieldInput.vue
@@ -0,0 +1,154 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The text field that displays and edits the value, rendered as a native
+ * `<input role="spinbutton">` wired to the root context. It parses typed input,
+ * mirrors the current value via `aria-valuenow`/`aria-valuemin`/`aria-valuemax`,
+ * and handles Arrow/Page/Home/End keys to step, jump, or clamp to the bounds.
+ * Mouse-wheel scrolling steps the value while focused, keystrokes that would
+ * produce an invalid number are rejected, and the value is re-clamped, snapped,
+ * and reformatted on blur or Enter.
+ */
+export interface NumberFieldInputProps extends PrimitiveProps {
+  placeholder?: string;
+  name?: string;
+  required?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed, onMounted, ref, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { getActiveElement } from '@robonen/platform/browsers';
+import { useNumberFieldContext } from './context';
+
+const { as = 'input', placeholder, name, required } = defineProps<NumberFieldInputProps>();
+const ctx = useNumberFieldContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Local mirror of the displayed text so in-progress edits (e.g. a trailing
+// decimal separator) survive until the value is committed/reformatted.
+const inputValue = ref(ctx.textValue.value);
+watch(() => ctx.textValue.value, (v) => {
+  inputValue.value = v;
+});
+
+const valueNow = computed(() => ctx.value.value ?? undefined);
+
+onMounted(() => {
+  ctx.onInputElement(currentElement.value as HTMLInputElement | undefined);
+});
+
+function onInput(event: Event): void {
+  const target = event.target as HTMLInputElement;
+  inputValue.value = target.value;
+  // Live update: empty clears to null, unparseable also clears to null (the
+  // value is re-clamped/snapped/reformatted only on commit via `applyInputValue`).
+  const parsed = ctx.parseInput(target.value);
+  ctx.setValue(parsed);
+}
+
+function onBeforeInput(event: InputEvent): void {
+  const target = event.target as HTMLInputElement;
+  const next
+    = target.value.slice(0, target.selectionStart ?? undefined)
+      + (event.data ?? '')
+      + target.value.slice(target.selectionEnd ?? undefined);
+  if (!ctx.validate(next))
+    event.preventDefault();
+}
+
+function commit(event: Event): void {
+  ctx.applyInputValue((event.target as HTMLInputElement).value);
+}
+
+function onWheel(event: WheelEvent): void {
+  if (ctx.disableWheelChange.value || ctx.disabled.value || ctx.readonly.value)
+    return;
+  if (event.target !== getActiveElement())
+    return;
+  // Trackpads emit simultaneous X/Y; ignore mostly-horizontal scrolls.
+  if (Math.abs(event.deltaY) <= Math.abs(event.deltaX))
+    return;
+
+  event.preventDefault();
+  const goingDown = event.deltaY > 0;
+  const decrease = goingDown !== ctx.invertWheelChange.value;
+  if (decrease)
+    ctx.decrement();
+  else
+    ctx.increment();
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (ctx.disabled.value || ctx.readonly.value) return;
+  switch (event.key) {
+    case 'ArrowUp':
+      event.preventDefault();
+      ctx.increment();
+      break;
+    case 'ArrowDown':
+      event.preventDefault();
+      ctx.decrement();
+      break;
+    case 'PageUp':
+      event.preventDefault();
+      ctx.increment(ctx.step.value * 10);
+      break;
+    case 'PageDown':
+      event.preventDefault();
+      ctx.decrement(ctx.step.value * 10);
+      break;
+    case 'Home':
+      if (ctx.min.value !== undefined) {
+        event.preventDefault();
+        ctx.setValue(ctx.min.value);
+      }
+      break;
+    case 'End':
+      if (ctx.max.value !== undefined) {
+        event.preventDefault();
+        ctx.setValue(ctx.max.value);
+      }
+      break;
+    case 'Enter':
+      ctx.applyInputValue((event.target as HTMLInputElement).value);
+      break;
+  }
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :id="ctx.inputId"
+    role="spinbutton"
+    type="text"
+    tabindex="0"
+    :inputmode="ctx.inputMode.value"
+    autocomplete="off"
+    autocorrect="off"
+    spellcheck="false"
+    aria-roledescription="Number field"
+    :aria-valuemin="ctx.min.value"
+    :aria-valuemax="ctx.max.value"
+    :aria-valuenow="valueNow"
+    :aria-disabled="ctx.disabled.value || undefined"
+    :aria-readonly="ctx.readonly.value || undefined"
+    :disabled="ctx.disabled.value || undefined"
+    :readonly="ctx.readonly.value || undefined"
+    :placeholder="placeholder"
+    :name="name"
+    :required="required || undefined"
+    :value="inputValue"
+    @beforeinput="onBeforeInput"
+    @input="onInput"
+    @keydown="onKeyDown"
+    @wheel="onWheel"
+    @change="commit"
+    @blur="commit"
+  />
+</template>
diff --git a/vue/primitives/src/forms/number-field/NumberFieldRoot.vue b/vue/primitives/src/forms/number-field/NumberFieldRoot.vue
new file mode 100644
index 0000000..39c22ba
--- /dev/null
+++ b/vue/primitives/src/forms/number-field/NumberFieldRoot.vue
@@ -0,0 +1,245 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A numeric input with stepper controls, keyboard increment/decrement, and
+ * optional clamping. The interactive root: it owns the value (controlled via
+ * `v-model` / `update:modelValue` or uncontrolled via `defaultValue`), clamps
+ * to `min`/`max`, snaps to `step`, formats with the active locale, and provides
+ * context to `NumberFieldInput`, `NumberFieldIncrement`, and
+ * `NumberFieldDecrement`. Use it whenever you need a styled number entry with
+ * spinner buttons and arrow-key support.
+ */
+export interface NumberFieldRootProps extends PrimitiveProps {
+  defaultValue?: number | null;
+  min?: number;
+  max?: number;
+  step?: number;
+  /** When `false`, values are clamped but not snapped to the nearest step. */
+  stepSnapping?: boolean;
+  disabled?: boolean;
+  readonly?: boolean;
+  /** Native input name; submits the value with the surrounding `<form>`. */
+  name?: string;
+  /** Mark the field required so native form validation fires on empty submit. */
+  required?: boolean;
+  /** `Intl.NumberFormat` options controlling display and the allowed characters. */
+  formatOptions?: Intl.NumberFormatOptions;
+  /** Locale override for formatting/parsing; falls back to the app `ConfigProvider`. */
+  locale?: string;
+  /** When `false`, wheel scrolling over the input does not change the value. */
+  disableWheelChange?: boolean;
+  /** Invert the direction of wheel-driven stepping. */
+  invertWheelChange?: boolean;
+  /** When `true` (default), stepper buttons return focus to the input. */
+  focusOnChange?: boolean;
+}
+
+export interface NumberFieldRootEmits {
+  valueChange: [value: number | null];
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed, ref, shallowRef, toRef, watch } from 'vue';
+import { provideNumberFieldContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+import { clamp } from '@robonen/stdlib';
+import { useId, useLocale } from '../../utilities/config-provider';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
+import { createNumberFormat, handleDecimalOperation, snapValueToStep } from './utils';
+
+const {
+  step = 1,
+  stepSnapping = true,
+  disabled = false,
+  readonly = false,
+  focusOnChange = true,
+  disableWheelChange = false,
+  invertWheelChange = false,
+  min,
+  max,
+  name,
+  required,
+  formatOptions,
+  locale: localeProp,
+  defaultValue,
+  as = 'div',
+} = defineProps<NumberFieldRootProps>();
+
+const emit = defineEmits<NumberFieldRootEmits>();
+
+// `defineModel` drives both controlled (`v-model`) and uncontrolled modes; in
+// uncontrolled mode `model.value` is `undefined` until first write, so the
+// internal `localValue` below seeds from `defaultValue` and stays the live
+// source of truth (synchronous multi-step updates can't wait on a prop re-flow).
+const model = defineModel<number | null>();
+
+const localValue = ref<number | null>(
+  model.value !== undefined ? model.value : (defaultValue ?? null),
+);
+
+watch(model, (v) => {
+  if (v === undefined) return;
+  if (v === localValue.value) return;
+  localValue.value = v;
+});
+
+const locale = useLocale(() => localeProp);
+const numberFormat = createNumberFormat(locale, () => formatOptions);
+
+const inputEl = shallowRef<HTMLInputElement>();
+
+function clampInput(v: number): number {
+  if (stepSnapping && Number.isFinite(step))
+    return snapValueToStep(v, min, max, step);
+  return clamp(v, min ?? -Infinity, max ?? Infinity);
+}
+
+function setValue(v: number | null): void {
+  if (disabled || readonly) return;
+  const next = v === null ? null : clampInput(v);
+  if (next === localValue.value) return;
+  localValue.value = next;
+  // `defineModel` emits `update:modelValue` on write — no manual emit needed.
+  model.value = next;
+  emit('valueChange', next);
+}
+
+function step_(delta: number, sign: '+' | '-'): void {
+  const base = localValue.value ?? min ?? 0;
+  setValue(handleDecimalOperation(sign, base, delta));
+  if (focusOnChange)
+    inputEl.value?.focus();
+}
+
+function increment(delta = step): void {
+  step_(delta, '+');
+}
+function decrement(delta = step): void {
+  step_(delta, '-');
+}
+
+const textValue = computed(() => {
+  if (localValue.value === null)
+    return '';
+  // Only run the locale formatter when format options are present, so the
+  // plain-number contract (and existing `String(value)` display) is preserved.
+  return formatOptions ? numberFormat.format(localValue.value) : String(localValue.value);
+});
+
+const inputMode = computed<'numeric' | 'decimal'>(() => {
+  // Default `Intl.NumberFormat` reports 3 fraction digits, so only trust the
+  // formatter when the consumer actually passed `formatOptions`; otherwise the
+  // soft-keyboard hint is driven purely by whether the step is fractional.
+  const fractionDigits = formatOptions ? (numberFormat.resolved.value.maximumFractionDigits ?? 0) : 0;
+  const allowsFraction = fractionDigits > 0 || !Number.isInteger(step);
+  return allowsFraction ? 'decimal' : 'numeric';
+});
+
+function parseRaw(raw: string): number {
+  return formatOptions ? numberFormat.parse(raw) : Number(raw.trim());
+}
+
+function parseInput(raw: string): number | null {
+  const trimmed = raw.trim();
+  if (trimmed === '')
+    return null;
+  const parsed = parseRaw(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function applyInputValue(raw: string): void {
+  const trimmed = raw.trim();
+  if (trimmed === '') {
+    setValue(null);
+    return;
+  }
+  const parsed = parseRaw(trimmed);
+  if (Number.isNaN(parsed) || !Number.isFinite(parsed))
+    return;
+  setValue(parsed);
+}
+
+function validate(raw: string): boolean {
+  if (!formatOptions)
+    return true;
+  return numberFormat.isValidPartial(raw);
+}
+
+const isIncrementDisabled = computed(() => {
+  if (localValue.value === null || max === undefined)
+    return false;
+  return handleDecimalOperation('+', localValue.value, step) > max && localValue.value >= max;
+});
+const isDecrementDisabled = computed(() => {
+  if (localValue.value === null || min === undefined)
+    return false;
+  return handleDecimalOperation('-', localValue.value, step) < min && localValue.value <= min;
+});
+
+const inputId = useId(undefined, 'number-field-input').value;
+
+// `defineExpose` is consumed and merged by `useForwardExpose` — it must run
+// first so the imperative API is forwarded alongside the element ref (and so
+// `expose()` is only called once).
+defineExpose({ value: localValue, increment, decrement, setValue });
+const { forwardRef, currentElement } = useForwardExpose();
+
+const isFormControl = computed(() => {
+  const el = currentElement.value;
+  return !!el && !!el.closest('form');
+});
+
+provideNumberFieldContext({
+  value: localValue,
+  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
+  min: toRef(() => min),
+  max: toRef(() => max),
+  step: toRef(() => step),
+  disabled: toRef(() => disabled),
+  readonly: toRef(() => readonly),
+  increment,
+  decrement,
+  setValue,
+  inputId,
+  textValue,
+  inputMode,
+  parseInput,
+  applyInputValue,
+  validate,
+  isIncrementDisabled,
+  isDecrementDisabled,
+  disableWheelChange: toRef(() => disableWheelChange),
+  invertWheelChange: toRef(() => invertWheelChange),
+  focusOnChange: toRef(() => focusOnChange),
+  inputEl,
+  onInputElement: (el) => { inputEl.value = el; },
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="group"
+    :data-disabled="disabled ? '' : undefined"
+    :data-readonly="readonly ? '' : undefined"
+  >
+    <slot
+      :value="localValue"
+      :text-value="textValue"
+      :increment="increment"
+      :decrement="decrement"
+    />
+
+    <VisuallyHiddenInput
+      v-if="isFormControl && name"
+      :name="name"
+      :value="localValue"
+      :required="required"
+      :disabled="disabled"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/forms/number-field/__test__/NumberField.parity.test.ts b/vue/primitives/src/forms/number-field/__test__/NumberField.parity.test.ts
new file mode 100644
index 0000000..1c5c7ad
--- /dev/null
+++ b/vue/primitives/src/forms/number-field/__test__/NumberField.parity.test.ts
@@ -0,0 +1,381 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import type { Component } from 'vue';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  NumberFieldDecrement,
+  NumberFieldIncrement,
+  NumberFieldInput,
+  NumberFieldRoot,
+} from '../index';
+import {
+  createNumberFormat,
+  handleDecimalOperation,
+  roundToStepPrecision,
+  snapValueToStep,
+} from '../utils';
+
+let active: { unmount: () => void } | undefined;
+
+function mountField(props: Record<string, unknown> = {}, opts: { inForm?: boolean } = {}) {
+  const model = ref<number | null | undefined>(undefined);
+  const Harness = defineComponent({
+    setup: () => () => {
+      const field = h(NumberFieldRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: number | null) => { model.value = v; },
+        ...props,
+      }, {
+        default: () => [
+          h(NumberFieldInput as Component, { id: 'inp' }),
+          h(NumberFieldIncrement, { id: 'inc' }, { default: () => '+' }),
+          h(NumberFieldDecrement, { id: 'dec' }, { default: () => '−' }),
+        ],
+      });
+      return opts.inForm ? h('form', { id: 'form' }, [field]) : field;
+    },
+  });
+  const wrapper = mount(Harness, { attachTo: document.body });
+  active = wrapper;
+  return { wrapper, model };
+}
+
+function press(el: Element, key: string): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+}
+
+function pointerDown(el: Element): void {
+  el.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true, button: 0 }));
+}
+function pointerUp(): void {
+  globalThis.dispatchEvent(new PointerEvent('pointerup', { bubbles: true, cancelable: true, button: 0 }));
+}
+
+afterEach(() => {
+  active?.unmount();
+  active = undefined;
+});
+
+describe('NumberField utils', () => {
+  it('handleDecimalOperation avoids float drift', () => {
+    expect(handleDecimalOperation('+', 0.1, 0.2)).toBe(0.3);
+    expect(handleDecimalOperation('-', 0.3, 0.1)).toBe(0.2);
+    expect(handleDecimalOperation('+', 1, 2)).toBe(3);
+  });
+
+  it('roundToStepPrecision rounds to step precision', () => {
+    expect(roundToStepPrecision(0.30000000000000004, 0.1)).toBe(0.3);
+    expect(roundToStepPrecision(5, 1)).toBe(5);
+  });
+
+  it('snapValueToStep snaps to grid within bounds', () => {
+    expect(snapValueToStep(7, 0, 10, 5)).toBe(5);
+    expect(snapValueToStep(8, 0, 10, 5)).toBe(10);
+    expect(snapValueToStep(2.3, 0, 10, 0.5)).toBe(2.5);
+    expect(snapValueToStep(-1, 0, 10, 1)).toBe(0);
+  });
+
+  it('createNumberFormat formats and parses with locale separators', () => {
+    const fmt = createNumberFormat(() => 'en-US', () => ({ minimumFractionDigits: 2 }));
+    expect(fmt.format(1234.5)).toBe('1,234.50');
+    expect(fmt.parse('1,234.50')).toBe(1234.5);
+    expect(fmt.parse('abc')).toBeNaN();
+    expect(fmt.isValidPartial('1,2')).toBe(true);
+    expect(fmt.isValidPartial('xyz')).toBe(false);
+  });
+});
+
+describe('NumberField ARIA / structure', () => {
+  it('root has role=group', () => {
+    const { wrapper } = mountField({ defaultValue: 1 });
+    expect(wrapper.find('[role="group"]').exists()).toBe(true);
+  });
+
+  it('input has a11y attributes', () => {
+    mountField({ min: 0, max: 10, defaultValue: 5 });
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    expect(input.getAttribute('role')).toBe('spinbutton');
+    expect(input.getAttribute('tabindex')).toBe('0');
+    expect(input.getAttribute('autocorrect')).toBe('off');
+    expect(input.getAttribute('spellcheck')).toBe('false');
+    expect(input.getAttribute('aria-roledescription')).toBe('Number field');
+    expect(input.getAttribute('inputmode')).toBe('numeric');
+  });
+
+  it('inputmode becomes decimal with fractional step', () => {
+    mountField({ step: 0.5, defaultValue: 1 });
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    expect(input.getAttribute('inputmode')).toBe('decimal');
+  });
+
+  it('stepper buttons are exposed to AT with aria-label (not aria-hidden)', () => {
+    mountField({ defaultValue: 1 });
+    const inc = document.querySelector<HTMLButtonElement>('#inc')!;
+    const dec = document.querySelector<HTMLButtonElement>('#dec')!;
+    expect(inc.getAttribute('aria-hidden')).toBeNull();
+    expect(inc.getAttribute('aria-label')).toBe('Increase');
+    expect(dec.getAttribute('aria-label')).toBe('Decrease');
+    expect(inc.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('custom aria-label on buttons is forwarded', () => {
+    const model = ref<number | null>(1);
+    const wrapper = mount(defineComponent({
+      setup: () => () => h(NumberFieldRoot, { modelValue: model.value }, {
+        default: () => [
+          h(NumberFieldIncrement, { id: 'inc', 'aria-label': 'More' }),
+          h(NumberFieldDecrement, { id: 'dec', 'aria-label': 'Less' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    active = wrapper;
+    expect(document.querySelector('#inc')!.getAttribute('aria-label')).toBe('More');
+    expect(document.querySelector('#dec')!.getAttribute('aria-label')).toBe('Less');
+  });
+});
+
+describe('NumberField decimal-safe stepping & snapping', () => {
+  it('steps fractional values without float drift', async () => {
+    // `stepSnapping: false` isolates the decimal-safe arithmetic from grid snapping.
+    const { model } = mountField({ defaultValue: 0.1, step: 0.2, stepSnapping: false });
+    await nextTick();
+    (document.querySelector<HTMLButtonElement>('#inc')!).click();
+    await nextTick();
+    expect(model.value).toBe(0.3);
+  });
+
+  it('snaps off-grid value to step grid on commit', async () => {
+    const { model } = mountField({ min: 0, max: 10, step: 5, defaultValue: 0 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.value = '7';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    await nextTick();
+    expect(model.value).toBe(5);
+  });
+
+  it('stepSnapping=false clamps without snapping', async () => {
+    const { model } = mountField({ min: 0, max: 10, step: 5, stepSnapping: false, defaultValue: 0 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.value = '7';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    await nextTick();
+    expect(model.value).toBe(7);
+  });
+});
+
+describe('NumberField at-boundary disabled', () => {
+  it('disables increment at max and decrement at min', async () => {
+    const { model } = mountField({ min: 0, max: 5, step: 1, defaultValue: 5 });
+    await nextTick();
+    const inc = document.querySelector<HTMLButtonElement>('#inc')!;
+    expect(inc.hasAttribute('data-disabled')).toBe(true);
+    expect(inc.disabled).toBe(true);
+
+    // Move to min
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    press(input, 'Home');
+    await nextTick();
+    expect(model.value).toBe(0);
+    const dec = document.querySelector<HTMLButtonElement>('#dec')!;
+    expect(dec.hasAttribute('data-disabled')).toBe(true);
+    expect(dec.disabled).toBe(true);
+  });
+
+  it('per-button disabled prop disables independently', async () => {
+    const model = ref<number | null>(2);
+    const wrapper = mount(defineComponent({
+      setup: () => () => h(NumberFieldRoot, { modelValue: model.value }, {
+        default: () => [
+          h(NumberFieldIncrement, { id: 'inc', disabled: true }),
+          h(NumberFieldDecrement, { id: 'dec' }),
+        ],
+      }),
+    }), { attachTo: document.body });
+    active = wrapper;
+    await nextTick();
+    const inc = document.querySelector<HTMLButtonElement>('#inc')!;
+    expect(inc.disabled).toBe(true);
+    inc.click();
+    await nextTick();
+    expect(model.value).toBe(2);
+  });
+});
+
+describe('NumberField wheel', () => {
+  it('increments on wheel up while focused, decrements on wheel down', async () => {
+    const { model } = mountField({ defaultValue: 5, step: 1 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.focus();
+    input.dispatchEvent(new WheelEvent('wheel', { deltaY: -10, deltaX: 0, bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(model.value).toBe(6);
+    input.dispatchEvent(new WheelEvent('wheel', { deltaY: 10, deltaX: 0, bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(model.value).toBe(5);
+  });
+
+  it('disableWheelChange ignores wheel', async () => {
+    const { model } = mountField({ defaultValue: 5, disableWheelChange: true });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.focus();
+    input.dispatchEvent(new WheelEvent('wheel', { deltaY: -10, deltaX: 0, bubbles: true, cancelable: true }));
+    await nextTick();
+    // No value write occurred, so the uncontrolled model ref stays untouched.
+    expect(model.value).toBeUndefined();
+    expect(input.value).toBe('5');
+  });
+
+  it('invertWheelChange reverses direction', async () => {
+    const { model } = mountField({ defaultValue: 5, invertWheelChange: true });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.focus();
+    input.dispatchEvent(new WheelEvent('wheel', { deltaY: -10, deltaX: 0, bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(model.value).toBe(4);
+  });
+
+  it('ignores mostly-horizontal wheel (trackpad heuristic)', async () => {
+    const { model } = mountField({ defaultValue: 5 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.focus();
+    input.dispatchEvent(new WheelEvent('wheel', { deltaY: 2, deltaX: 20, bubbles: true, cancelable: true }));
+    await nextTick();
+    // No value write occurred, so the uncontrolled model ref stays untouched.
+    expect(model.value).toBeUndefined();
+    expect(input.value).toBe('5');
+  });
+});
+
+describe('NumberField press-and-hold', () => {
+  it('pointerdown triggers a step and sets data-pressed', async () => {
+    const { model } = mountField({ defaultValue: 0, step: 1 });
+    await nextTick();
+    const inc = document.querySelector<HTMLButtonElement>('#inc')!;
+    pointerDown(inc);
+    await nextTick();
+    expect(model.value).toBe(1);
+    expect(inc.getAttribute('data-pressed')).toBe('true');
+    pointerUp();
+    await nextTick();
+    expect(inc.getAttribute('data-pressed')).toBeNull();
+  });
+
+  it('synthetic click after a pointer press does not double-step', async () => {
+    const { model } = mountField({ defaultValue: 0, step: 1 });
+    await nextTick();
+    const inc = document.querySelector<HTMLButtonElement>('#inc')!;
+    pointerDown(inc);
+    pointerUp();
+    inc.click();
+    await nextTick();
+    expect(model.value).toBe(1);
+  });
+});
+
+describe('NumberField commit on blur / Enter', () => {
+  it('reclamps and snaps on blur', async () => {
+    const { model } = mountField({ min: 0, max: 10, step: 1, defaultValue: 5 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.value = '99';
+    input.dispatchEvent(new Event('blur', { bubbles: true }));
+    await nextTick();
+    expect(model.value).toBe(10);
+  });
+
+  it('Enter commits the value', async () => {
+    const { model } = mountField({ min: 0, max: 10, step: 1, defaultValue: 5 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    input.value = '99';
+    press(input, 'Enter');
+    await nextTick();
+    expect(model.value).toBe(10);
+  });
+});
+
+describe('NumberField beforeinput validation (formatOptions)', () => {
+  it('rejects invalid characters when formatOptions set', async () => {
+    mountField({ formatOptions: { maximumFractionDigits: 2 }, defaultValue: 1 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    const evt = new InputEvent('beforeinput', { data: 'a', bubbles: true, cancelable: true });
+    input.dispatchEvent(evt);
+    expect(evt.defaultPrevented).toBe(true);
+
+    const ok = new InputEvent('beforeinput', { data: '5', bubbles: true, cancelable: true });
+    input.dispatchEvent(ok);
+    expect(ok.defaultPrevented).toBe(false);
+  });
+});
+
+describe('NumberField formatting', () => {
+  it('displays formatted text via textValue when formatOptions set', async () => {
+    const { wrapper } = mountField({
+      formatOptions: { style: 'currency', currency: 'USD' },
+      defaultValue: 1234.5,
+    });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    expect(input.value).toContain('1,234');
+    expect(input.value).toContain('$');
+    wrapper.unmount();
+    active = undefined;
+  });
+
+  it('plain number display without formatOptions', async () => {
+    mountField({ defaultValue: 42 });
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    expect(input.value).toBe('42');
+  });
+});
+
+describe('NumberField form integration', () => {
+  it('renders a hidden input inside a form', async () => {
+    mountField({ name: 'qty', defaultValue: 3 }, { inForm: true });
+    await nextTick();
+    const hidden = document.querySelector<HTMLInputElement>('form input[name="qty"]');
+    expect(hidden).not.toBeNull();
+    expect(hidden!.value).toBe('3');
+  });
+
+  it('does not render a hidden input outside a form', async () => {
+    mountField({ name: 'qty', defaultValue: 3 });
+    await nextTick();
+    const hidden = document.querySelector<HTMLInputElement>('input[name="qty"]');
+    expect(hidden).toBeNull();
+  });
+});
+
+describe('NumberField polymorphism', () => {
+  it('Input renders the provided as element', async () => {
+    const model = ref<number | null>(1);
+    const wrapper = mount(defineComponent({
+      setup: () => () => h(NumberFieldRoot, { modelValue: model.value }, {
+        default: () => [h(NumberFieldInput as Component, { id: 'inp', as: 'input' })],
+      }),
+    }), { attachTo: document.body });
+    active = wrapper;
+    await nextTick();
+    expect(document.querySelector('#inp')!.tagName).toBe('INPUT');
+  });
+});
+
+describe('NumberField readonly', () => {
+  it('readonly blocks stepping but exposes value', async () => {
+    const { model } = mountField({ readonly: true, defaultValue: 5 });
+    await nextTick();
+    (document.querySelector<HTMLButtonElement>('#inc')!).click();
+    await nextTick();
+    expect(model.value).toBeUndefined();
+    const input = document.querySelector<HTMLInputElement>('#inp')!;
+    expect(input.getAttribute('aria-readonly')).toBe('true');
+  });
+});
diff --git a/vue/primitives/src/number-field/__test__/NumberField.test.ts b/vue/primitives/src/forms/number-field/__test__/NumberField.test.ts
similarity index 100%
rename from vue/primitives/src/number-field/__test__/NumberField.test.ts
rename to vue/primitives/src/forms/number-field/__test__/NumberField.test.ts
diff --git a/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-ArrowUp---ArrowDown-step--clamped-by-min-max-1.png b/vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-ArrowUp---ArrowDown-step--clamped-by-min-max-1.png
similarity index 100%
rename from vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-ArrowUp---ArrowDown-step--clamped-by-min-max-1.png
rename to vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-ArrowUp---ArrowDown-step--clamped-by-min-max-1.png
diff --git a/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-Home-End-jump-to-min-max-when-defined-1.png b/vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-Home-End-jump-to-min-max-when-defined-1.png
similarity index 100%
rename from vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-Home-End-jump-to-min-max-when-defined-1.png
rename to vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-Home-End-jump-to-min-max-when-defined-1.png
diff --git a/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-PageUp-PageDown-step-by-10--1.png b/vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-PageUp-PageDown-step-by-10--1.png
similarity index 100%
rename from vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-PageUp-PageDown-step-by-10--1.png
rename to vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-PageUp-PageDown-step-by-10--1.png
diff --git a/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-typing-updates-value--invalid---null-1.png b/vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-typing-updates-value--invalid---null-1.png
similarity index 100%
rename from vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-typing-updates-value--invalid---null-1.png
rename to vue/primitives/src/forms/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-typing-updates-value--invalid---null-1.png
diff --git a/vue/primitives/src/forms/number-field/context.ts b/vue/primitives/src/forms/number-field/context.ts
new file mode 100644
index 0000000..cbb9de8
--- /dev/null
+++ b/vue/primitives/src/forms/number-field/context.ts
@@ -0,0 +1,43 @@
+import type { ComputedRef, Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+export interface NumberFieldContext {
+  value: Ref<number | null>;
+  min: Ref<number | undefined>;
+  max: Ref<number | undefined>;
+  step: Ref<number>;
+  disabled: Ref<boolean>;
+  readonly: Ref<boolean>;
+  increment: (delta?: number) => void;
+  decrement: (delta?: number) => void;
+  setValue: (v: number | null) => void;
+  inputId: string;
+  /** Text shown in the field, formatted with the active locale/format options. */
+  textValue: ComputedRef<string>;
+  /** Suggested soft-keyboard mode derived from whether fractional input is allowed. */
+  inputMode: ComputedRef<'numeric' | 'decimal'>;
+  /** Live parse of a raw input string to a value (empty/unparseable → `null`). */
+  parseInput: (raw: string) => number | null;
+  /** Re-parse, snap, clamp, and reformat the raw input string. Used on commit. */
+  applyInputValue: (raw: string) => void;
+  /** `true` when a prospective raw value is a valid partial number for the locale. */
+  validate: (raw: string) => boolean;
+  /** `true` when the next increment would exceed `max`. */
+  isIncrementDisabled: ComputedRef<boolean>;
+  /** `true` when the next decrement would drop below `min`. */
+  isDecrementDisabled: ComputedRef<boolean>;
+  /** Suppress wheel-driven stepping. */
+  disableWheelChange: Ref<boolean>;
+  /** Invert the direction of wheel-driven stepping. */
+  invertWheelChange: Ref<boolean>;
+  /** Return focus to the input after a stepper button changes the value. */
+  focusOnChange: Ref<boolean>;
+  /** Track the live input element so wheel / focus-on-change can target it. */
+  inputEl: Ref<HTMLInputElement | undefined>;
+  onInputElement: (el: HTMLInputElement | undefined) => void;
+}
+
+const ctx = useContextFactory<NumberFieldContext>('NumberFieldContext');
+
+export const provideNumberFieldContext = ctx.provide;
+export const useNumberFieldContext = ctx.inject;
diff --git a/vue/primitives/src/number-field/demo.vue b/vue/primitives/src/forms/number-field/demo.vue
similarity index 63%
rename from vue/primitives/src/number-field/demo.vue
rename to vue/primitives/src/forms/number-field/demo.vue
index e407470..a2810fe 100644
--- a/vue/primitives/src/number-field/demo.vue
+++ b/vue/primitives/src/forms/number-field/demo.vue
@@ -12,24 +12,24 @@ const atMax = computed(() => quantity.value !== null && quantity.value >= MAX);
 </script>
 
 <template>
-  <div class="flex flex-col gap-5 p-6 max-w-xs bg-(--bg) text-(--fg) border border-(--border) rounded-xl">
+  <div class="flex flex-col gap-5 p-6 max-w-xs bg-bg text-fg border border-border rounded-xl">
     <div class="flex flex-col gap-1">
       <span class="text-sm font-semibold">Espresso blend</span>
-      <span class="text-xs text-(--fg-subtle)">${{ UNIT_PRICE }}.00 per bag</span>
+      <span class="text-xs text-fg-subtle">${{ UNIT_PRICE }}.00 per bag</span>
     </div>
 
     <label class="flex flex-col gap-2">
-      <span class="text-xs font-medium text-(--fg-muted)">Quantity</span>
+      <span class="text-xs font-medium text-fg-muted">Quantity</span>
 
       <NumberFieldRoot
         v-model="quantity"
         :min="1"
         :max="MAX"
         :step="1"
-        class="inline-flex items-center w-fit rounded-lg border border-(--border) bg-(--bg-inset) overflow-hidden focus-within:ring-2 focus-within:ring-(--ring) data-[disabled]:opacity-50"
+        class="inline-flex items-center w-fit rounded-lg border border-border bg-bg-inset overflow-hidden focus-within:ring-2 focus-within:ring-ring data-[disabled]:opacity-50"
       >
         <NumberFieldDecrement
-          class="grid place-items-center w-9 h-9 text-(--fg-muted) hover:bg-(--bg-subtle) hover:text-(--fg) transition-colors disabled:pointer-events-none disabled:opacity-40"
+          class="grid place-items-center w-9 h-9 text-fg-muted hover:bg-bg-subtle hover:text-fg transition-colors disabled:pointer-events-none disabled:opacity-40"
         >
           <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
             <path d="M3 7h8" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
@@ -39,11 +39,11 @@ const atMax = computed(() => quantity.value !== null && quantity.value >= MAX);
         <NumberFieldInput
           name="quantity"
           placeholder="0"
-          class="w-12 h-9 text-center text-sm font-medium bg-transparent text-(--fg) outline-none tabular-nums [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none"
+          class="w-12 h-9 text-center text-sm font-medium bg-transparent text-fg outline-none tabular-nums [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none"
         />
 
         <NumberFieldIncrement
-          class="grid place-items-center w-9 h-9 text-(--fg-muted) hover:bg-(--bg-subtle) hover:text-(--fg) transition-colors disabled:pointer-events-none disabled:opacity-40"
+          class="grid place-items-center w-9 h-9 text-fg-muted hover:bg-bg-subtle hover:text-fg transition-colors disabled:pointer-events-none disabled:opacity-40"
         >
           <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
             <path d="M7 3v8M3 7h8" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
@@ -52,14 +52,14 @@ const atMax = computed(() => quantity.value !== null && quantity.value >= MAX);
       </NumberFieldRoot>
     </label>
 
-    <div class="flex items-center justify-between pt-3 border-t border-(--border)">
-      <span class="text-sm text-(--fg-muted)">Total</span>
+    <div class="flex items-center justify-between pt-3 border-t border-border">
+      <span class="text-sm text-fg-muted">Total</span>
       <span class="text-sm font-semibold tabular-nums">${{ total }}.00</span>
     </div>
 
     <p
       class="text-xs"
-      :class="atMax ? 'text-red-600 dark:text-red-400' : 'text-(--fg-subtle)'"
+      :class="atMax ? 'text-red-600 dark:text-red-400' : 'text-fg-subtle'"
     >
       {{ atMax ? `Maximum of ${MAX} bags per order` : 'Use the arrow keys or buttons to adjust' }}
     </p>
diff --git a/vue/primitives/src/number-field/index.ts b/vue/primitives/src/forms/number-field/index.ts
similarity index 84%
rename from vue/primitives/src/number-field/index.ts
rename to vue/primitives/src/forms/number-field/index.ts
index bee87c0..14bf0b0 100644
--- a/vue/primitives/src/number-field/index.ts
+++ b/vue/primitives/src/forms/number-field/index.ts
@@ -6,3 +6,8 @@ export type { NumberFieldDecrementProps } from './NumberFieldDecrement.vue';
 export type { NumberFieldIncrementProps } from './NumberFieldIncrement.vue';
 export type { NumberFieldInputProps } from './NumberFieldInput.vue';
 export type { NumberFieldRootEmits, NumberFieldRootProps } from './NumberFieldRoot.vue';
+export {
+  provideNumberFieldContext,
+  useNumberFieldContext,
+  type NumberFieldContext,
+} from './context';
diff --git a/vue/primitives/src/forms/number-field/utils.ts b/vue/primitives/src/forms/number-field/utils.ts
new file mode 100644
index 0000000..4e947eb
--- /dev/null
+++ b/vue/primitives/src/forms/number-field/utils.ts
@@ -0,0 +1,230 @@
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import { computed, onScopeDispose, ref, toValue } from 'vue';
+import { createEventHook, useEventListener } from '@robonen/vue';
+
+/**
+ * Decimal-safe add/subtract. Floating point makes `0.1 + 0.2 === 0.30000000000000004`,
+ * which is wrong for a stepper. We scale both operands to integers by the larger
+ * of their decimal lengths, operate, then scale back.
+ */
+export function handleDecimalOperation(operator: '+' | '-', a: number, b: number): number {
+  let result = operator === '+' ? a + b : a - b;
+
+  if (a % 1 !== 0 || b % 1 !== 0) {
+    const aDecimals = a.toString().split('.')[1]?.length ?? 0;
+    const bDecimals = b.toString().split('.')[1]?.length ?? 0;
+    const multiplier = 10 ** Math.max(aDecimals, bDecimals);
+
+    const aInt = Math.round(a * multiplier);
+    const bInt = Math.round(b * multiplier);
+
+    result = (operator === '+' ? aInt + bInt : aInt - bInt) / multiplier;
+  }
+
+  return result;
+}
+
+/**
+ * Round a value to the decimal precision implied by `step` (e.g. step `0.5` →
+ * one decimal place), correcting floating-point drift after snapping.
+ */
+export function roundToStepPrecision(value: number, step: number): number {
+  const stepString = step.toString();
+  const pointIndex = stepString.indexOf('.');
+  const precision = pointIndex >= 0 ? stepString.length - pointIndex - 1 : 0;
+
+  if (precision > 0) {
+    const pow = 10 ** precision;
+    return Math.round(value * pow) / pow;
+  }
+
+  return value;
+}
+
+/**
+ * Snap `value` to the nearest multiple of `step` within `[min, max]`. Mirrors the
+ * spinbutton semantics: when the value lands beyond a bound the snapped result is
+ * pulled back to the last reachable on-grid value inside the range.
+ */
+export function snapValueToStep(value: number, min: number | undefined, max: number | undefined, step: number): number {
+  const lo = min ?? Number.NaN;
+  const hi = max ?? Number.NaN;
+
+  const remainder = (value - (Number.isNaN(lo) ? 0 : lo)) % step;
+  let snapped = roundToStepPrecision(
+    Math.abs(remainder) * 2 >= step
+      ? value + Math.sign(remainder) * (step - Math.abs(remainder))
+      : value - remainder,
+    step,
+  );
+
+  if (!Number.isNaN(lo)) {
+    if (snapped < lo)
+      snapped = lo;
+    else if (!Number.isNaN(hi) && snapped > hi)
+      snapped = lo + Math.floor(roundToStepPrecision((hi - lo) / step, step)) * step;
+  }
+  else if (!Number.isNaN(hi) && snapped > hi) {
+    snapped = Math.floor(roundToStepPrecision(hi / step, step)) * step;
+  }
+
+  return roundToStepPrecision(snapped, step);
+}
+
+export interface UsePressedHoldOptions {
+  /** Element the press starts on (pointer must go down on it). */
+  target: Ref<HTMLElement | undefined>;
+  /** When `true`, presses are ignored and any in-flight repeat stops. */
+  disabled: MaybeRefOrGetter<boolean>;
+}
+
+export interface UsePressedHoldReturn {
+  /** `true` while the pointer is held down on the target. */
+  isPressed: Ref<boolean>;
+  /** Register a callback fired once on press and then repeatedly while held. */
+  onTrigger: (fn: () => void) => void;
+  /**
+   * `true` for one `click` immediately after a real pointer press already fired
+   * the trigger. Lets a `@click` fallback (for programmatic / keyboard-activated
+   * clicks that emit no `pointerdown`) avoid double-firing.
+   */
+  consumeClick: () => boolean;
+}
+
+/**
+ * Press-and-hold auto-repeat for stepper buttons: fires immediately on
+ * pointer-down, then repeats every 60ms after an initial 400ms delay until the
+ * pointer is released, cancelled, or leaves. Built on the toolkit's
+ * `useEventListener` (auto-cleaned on scope dispose) and `createEventHook`.
+ */
+export function usePressedHold(options: UsePressedHoldOptions): UsePressedHoldReturn {
+  const { target, disabled } = options;
+  const isPressed = ref(false);
+  const triggerHook = createEventHook<void>();
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  // Set when a pointer press fired the trigger; the synthetic `click` that the
+  // browser dispatches afterwards must be swallowed by the `@click` fallback.
+  let pressDidTrigger = false;
+
+  function clearTimer(): void {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  }
+
+  function repeat(delay: number): void {
+    clearTimer();
+    if (toValue(disabled))
+      return;
+
+    triggerHook.trigger();
+    timer = setTimeout(() => repeat(60), delay);
+  }
+
+  function onPressStart(event: PointerEvent): void {
+    // Only the primary (left) button, and ignore re-entrant presses.
+    if (event.button !== 0 || isPressed.value || toValue(disabled))
+      return;
+
+    event.preventDefault();
+    isPressed.value = true;
+    pressDidTrigger = true;
+    repeat(400);
+  }
+
+  function onPressEnd(): void {
+    isPressed.value = false;
+    clearTimer();
+  }
+
+  function consumeClick(): boolean {
+    if (pressDidTrigger) {
+      pressDidTrigger = false;
+      return true;
+    }
+    return false;
+  }
+
+  useEventListener(target, 'pointerdown', onPressStart);
+  // Release/cancel are watched on `window` so lifting the pointer outside the
+  // button still ends the hold; leaving the button also ends it.
+  useEventListener(globalThis.window, 'pointerup', onPressEnd);
+  useEventListener(globalThis.window, 'pointercancel', onPressEnd);
+  useEventListener(target, 'pointerleave', onPressEnd);
+
+  // Clear any in-flight repeat when the owning component unmounts.
+  onScopeDispose(clearTimer);
+
+  return {
+    isPressed,
+    onTrigger: triggerHook.on,
+    consumeClick,
+  };
+}
+
+/**
+ * Lightweight, locale-aware number formatting/parsing on top of native
+ * `Intl.NumberFormat` (no external i18n dependency). `format` renders the value
+ * with grouping/currency/percent per `options`; `parse` strips locale-specific
+ * group and decimal separators (and currency/percent symbols) back to a plain
+ * `number`, returning `NaN` for unparseable input.
+ */
+export function createNumberFormat(locale: MaybeRefOrGetter<string>, options: MaybeRefOrGetter<Intl.NumberFormatOptions | undefined>) {
+  const formatter = computed(() => new Intl.NumberFormat(toValue(locale), toValue(options)));
+
+  const separators = computed(() => {
+    const parts = formatter.value.formatToParts(12345.6);
+    const group = parts.find(p => p.type === 'group')?.value ?? ',';
+    const decimal = parts.find(p => p.type === 'decimal')?.value ?? '.';
+    return { group, decimal };
+  });
+
+  const resolved = computed(() => formatter.value.resolvedOptions());
+
+  // The partial-validation pattern depends solely on the locale decimal
+  // separator, so rebuild it only when that separator changes rather than on
+  // every keystroke (isValidPartial runs from @beforeinput per character).
+  const partialRe = computed(
+    () => new RegExp(`^[+-]?[\\d${escapeRegExp(separators.value.decimal)}.,\\s\\u00A0%$€£¥]*$`),
+  );
+
+  function format(value: number): string {
+    return formatter.value.format(value);
+  }
+
+  function parse(raw: string): number {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+      return Number.NaN;
+
+    const { group, decimal } = separators.value;
+    // Strip everything except digits, sign, and the locale decimal separator,
+    // then normalise the decimal separator to `.` for `Number`.
+    const cleaned = trimmed
+      .split(group).join('')
+      .split(decimal).join('.')
+      .replaceAll(/[^\d.\-+e]/gi, '');
+
+    // No digits at all → not a number (`Number('')` would coerce to 0).
+    if (!/\d/.test(cleaned))
+      return Number.NaN;
+
+    const n = Number(cleaned);
+    return Number.isFinite(n) ? n : Number.NaN;
+  }
+
+  function isValidPartial(raw: string): boolean {
+    if (raw === '' || raw === '-' || raw === '+')
+      return true;
+
+    return partialRe.value.test(raw);
+  }
+
+  return { format, parse, isValidPartial, resolved };
+}
+
+function escapeRegExp(value: string): string {
+  return value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
diff --git a/vue/primitives/src/forms/pin-input/PinInputInput.vue b/vue/primitives/src/forms/pin-input/PinInputInput.vue
new file mode 100644
index 0000000..1e44b5c
--- /dev/null
+++ b/vue/primitives/src/forms/pin-input/PinInputInput.vue
@@ -0,0 +1,176 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+const DIGIT_RE = /\d/;
+const NON_DIGIT_G = /\D/g;
+
+/**
+ * A single cell of the pin input, identified by its zero-based `index`. Renders
+ * one masked-or-plain character box that reads/writes its slot of the root's
+ * value and handles typing (auto-advancing to the next cell), Backspace/Delete,
+ * arrow/Home/End navigation, and paste (spreading text across cells). Render one
+ * per character, with `index` from `0` to `length - 1`.
+ *
+ * Polymorphic via `as` (defaults to a native `<input>`); `as="template"` merges
+ * onto a single child. A per-cell `disabled` prop is honored on top of the
+ * root-level `disabled` and is skipped by arrow navigation.
+ */
+export interface PinInputInputProps extends PrimitiveProps {
+  index: number;
+  /** Disable this individual cell (merged with the root-level `disabled`). */
+  disabled?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { usePinInputContext } from './context';
+
+const { index, disabled = false, as = 'input' } = defineProps<PinInputInputProps>();
+const ctx = usePinInputContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+// `currentElement` works through `as="template"` and polymorphic tags, so the
+// cell registers whatever element it resolves to.
+watch(currentElement, (curr, prev) => {
+  if (prev)
+    ctx.unregister(prev as HTMLInputElement);
+  if (curr)
+    ctx.register(curr as HTMLInputElement);
+});
+
+const isDisabled = computed(() => disabled || ctx.disabled.value);
+
+const displayed = computed(() => {
+  const ch = ctx.value.value[index] ?? '';
+  if (!ch)
+    return '';
+  return ctx.mask.value ? '•' : ch;
+});
+
+// Hide the placeholder on the focused empty cell for a cleaner look; restore it
+// on blur (or once a value lands, since `displayed` then takes over).
+const focused = ref(false);
+const placeholderText = computed(() =>
+  focused.value && !ctx.value.value[index] ? '' : ctx.placeholder.value);
+
+function onInput(e: Event): void {
+  const target = e.target as HTMLInputElement;
+  const raw = target.value;
+  // keep only the last typed character
+  let ch = raw.length > 0 ? raw[raw.length - 1]! : '';
+  if (ctx.type.value === 'number' && ch && !DIGIT_RE.test(ch))
+    ch = '';
+  ctx.setAt(index, ch);
+  // re-sync DOM input since we overwrite with displayed
+  target.value = ch ? (ctx.mask.value ? '•' : ch) : '';
+  if (ch && index < ctx.length.value - 1)
+    ctx.focusRelative(index, 1);
+}
+
+function onKeyDown(e: KeyboardEvent): void {
+  const i = index;
+  switch (e.key) {
+    case 'Backspace': {
+      const current = ctx.value.value[i] ?? '';
+      if (current) {
+        ctx.clearAt(i);
+      }
+      else if (i > 0) {
+        ctx.focusIndex(i - 1);
+        ctx.clearAt(i - 1);
+      }
+      e.preventDefault();
+      return;
+    }
+    case 'Delete': {
+      ctx.clearAt(i);
+      e.preventDefault();
+      return;
+    }
+  }
+
+  // Arrow/Home/End navigation is direction-aware (RTL flips left/right) and
+  // skips disabled cells. Vertical keys are ignored for this horizontal field.
+  const action = rovingKeyToAction(e, { orientation: 'horizontal', dir: ctx.dir.value, loop: false });
+  if (!action)
+    return;
+  e.preventDefault();
+  ctx.focusRelative(i, action.delta, action.absolute);
+}
+
+function onFocus(e: FocusEvent): void {
+  // OTP sequential-fill guard: never let the user start in the middle, redirect
+  // to the first empty cell so the code is entered left-to-right without gaps.
+  if (ctx.otp.value) {
+    const firstEmpty = ctx.firstEmptyIndex();
+    if (firstEmpty !== -1 && firstEmpty < index) {
+      ctx.focusIndex(firstEmpty);
+      return;
+    }
+  }
+  focused.value = true;
+  const target = e.target as HTMLInputElement;
+  // Place the caret after the (single) character so typing overwrites predictably.
+  try {
+    target.setSelectionRange(1, 1);
+  }
+  catch {
+    /* noop — non-text inputs */
+  }
+}
+
+function onBlur(): void {
+  focused.value = false;
+}
+
+function onPaste(e: ClipboardEvent): void {
+  const data = e.clipboardData?.getData('text') ?? '';
+  if (!data)
+    return;
+  e.preventDefault();
+  const chars = ctx.type.value === 'number'
+    ? data.replaceAll(NON_DIGIT_G, '').split('')
+    : data.split('');
+  let idx = index;
+  for (const ch of chars) {
+    if (idx >= ctx.length.value)
+      break;
+    ctx.setAt(idx, ch);
+    idx++;
+  }
+  ctx.focusIndex(Math.min(idx, ctx.length.value - 1));
+}
+
+const inputType = computed(() => (ctx.mask.value ? 'password' : 'text'));
+const inputMode = computed(() => (ctx.type.value === 'number' ? 'numeric' : 'text'));
+const ariaLabel = computed(() => `pin input ${index + 1} of ${ctx.length.value}`);
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="inputType"
+    autocapitalize="none"
+    :inputmode="inputMode"
+    :pattern="ctx.type.value === 'number' ? '[0-9]*' : undefined"
+    :value="displayed"
+    :placeholder="placeholderText"
+    :disabled="isDisabled || undefined"
+    :autocomplete="ctx.otp.value ? 'one-time-code' : 'off'"
+    :aria-label="ariaLabel"
+    :data-index="index"
+    :data-disabled="isDisabled ? '' : undefined"
+    :data-complete="ctx.isComplete.value ? '' : undefined"
+    maxlength="1"
+    @input="onInput"
+    @keydown="onKeyDown"
+    @focus="onFocus"
+    @blur="onBlur"
+    @paste="onPaste"
+  />
+</template>
diff --git a/vue/primitives/src/pin-input/PinInputRoot.vue b/vue/primitives/src/forms/pin-input/PinInputRoot.vue
similarity index 54%
rename from vue/primitives/src/pin-input/PinInputRoot.vue
rename to vue/primitives/src/forms/pin-input/PinInputRoot.vue
index bcbebe8..7fe29dd 100644
--- a/vue/primitives/src/pin-input/PinInputRoot.vue
+++ b/vue/primitives/src/forms/pin-input/PinInputRoot.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Direction } from '../../utilities/config-provider';
 
 /**
  * A segmented input for short codes — OTP / one-time passwords, 2FA tokens, or
@@ -10,6 +11,10 @@ import type { PrimitiveProps } from '../primitive';
  * `PinInputInput`. Emits `complete` once every cell is filled. Use it for
  * verification codes where each character gets its own cell with auto-advance,
  * arrow-key navigation, and clipboard paste spreading across cells.
+ *
+ * Native form support: pass `name` (and optionally `required` / `id`) to render
+ * a visually-hidden form control holding the joined value, so the field submits
+ * with its owning `<form>` and participates in native `required` validation.
  */
 export interface PinInputRootProps extends PrimitiveProps {
   defaultValue?: string[];
@@ -19,15 +24,31 @@ export interface PinInputRootProps extends PrimitiveProps {
   type?: 'text' | 'number';
   disabled?: boolean;
   placeholder?: string;
-
+  /**
+   * Reading direction. Affects arrow-key navigation (in `rtl`, `ArrowRight`
+   * moves to the previous cell). Falls back to the active `ConfigProvider`
+   * `dir`, then `ltr`.
+   */
+  dir?: Direction;
+  /** Name submitted with the owning form (enables the hidden form control). */
+  name?: string;
+  /** Mirror the `required` constraint so native form validation fires. */
+  required?: boolean;
+  /** Id forwarded to the hidden form control for label association. */
+  id?: string;
 }
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed, ref, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { computed, ref, shallowRef, toRef, triggerRef, watch } from 'vue';
 import { providePinInputContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
+import { useDirection } from '../../utilities/config-provider';
+import { resolveNextIndex } from '../../internal/utils/roving-focus';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
+
+defineOptions({ inheritAttrs: false });
 
 const {
   defaultValue,
@@ -37,11 +58,17 @@ const {
   type = 'text',
   disabled = false,
   placeholder = '',
+  dir,
+  name,
+  required = false,
+  id,
   as = 'div',
 } = defineProps<PinInputRootProps>();
 
 const { forwardRef } = useForwardExpose();
 
+const direction = useDirection(() => dir);
+
 const emit = defineEmits<{
   complete: [value: string];
 }>();
@@ -84,16 +111,23 @@ watch(lengthRef, (n) => {
   value.value = next;
 });
 
-const inputs = ref<HTMLInputElement[]>([]);
+// `shallowRef` so the registered `<input>` elements are stored raw (a deep
+// `ref` would proxy each element — breaking `includes(el)` identity checks and
+// `.focus()`). The array is mutated in place, so `triggerRef` after each change.
+const inputs = shallowRef<HTMLInputElement[]>([]);
 
 function register(el: HTMLInputElement): void {
-  if (!inputs.value.includes(el))
+  if (!inputs.value.includes(el)) {
     inputs.value.push(el);
+    triggerRef(inputs);
+  }
 }
 function unregister(el: HTMLInputElement): void {
   const i = inputs.value.indexOf(el);
-  if (i !== -1)
+  if (i !== -1) {
     inputs.value.splice(i, 1);
+    triggerRef(inputs);
+  }
 }
 
 function commit(v: string[]): void {
@@ -124,6 +158,10 @@ function clearAt(index: number): void {
   commit(next);
 }
 
+function isCellDisabled(el: HTMLInputElement | undefined): boolean {
+  return !el || el.hasAttribute('data-disabled');
+}
+
 function focusIndex(index: number): void {
   const el = inputs.value[index];
   if (el) {
@@ -137,6 +175,41 @@ function focusIndex(index: number): void {
   }
 }
 
+// Move focus by `delta` (±1) or to an absolute edge, skipping disabled cells.
+// `delta` is already resolved by the caller for reading direction; navigation
+// never loops (a pin field has hard edges).
+function focusRelative(index: number, delta: number, absolute?: 'home' | 'end'): void {
+  const count = inputs.value.length;
+  if (count === 0)
+    return;
+
+  if (absolute) {
+    let i = absolute === 'home' ? 0 : count - 1;
+    const step = absolute === 'home' ? 1 : -1;
+    while (i >= 0 && i < count && isCellDisabled(inputs.value[i]))
+      i += step;
+    if (i >= 0 && i < count)
+      focusIndex(i);
+    return;
+  }
+
+  let i = resolveNextIndex(index, delta, count, false);
+  while (i !== index && isCellDisabled(inputs.value[i])) {
+    const next = resolveNextIndex(i, delta, count, false);
+    if (next === i)
+      return;
+    i = next;
+  }
+  if (i !== index && !isCellDisabled(inputs.value[i]))
+    focusIndex(i);
+}
+
+function firstEmptyIndex(): number {
+  return value.value.findIndex(ch => ch.length === 0);
+}
+
+const isComplete = computed(() => value.value.every(ch => ch.length === 1));
+
 providePinInputContext({
   value,
   length: lengthRef,
@@ -145,23 +218,51 @@ providePinInputContext({
   type: toRef(() => type),
   disabled: toRef(() => disabled),
   placeholder: toRef(() => placeholder),
+  dir: direction,
+  isComplete,
   inputs,
   register,
   unregister,
   setAt,
   clearAt,
   focusIndex,
+  focusRelative,
+  firstEmptyIndex,
 });
 
 defineSlots<{
   default: (props: { value: string[]; isComplete: boolean }) => unknown;
 }>();
 
-const isComplete = computed(() => value.value.every(ch => ch.length === 1));
+const serialized = computed(() => value.value.join(''));
+
+function onHiddenFocus(): void {
+  inputs.value[0]?.focus();
+}
 </script>
 
 <template>
-  <Primitive :ref="forwardRef" :as="as" role="group" :data-disabled="disabled ? '' : undefined">
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="group"
+    v-bind="$attrs"
+    :dir="direction"
+    :data-complete="isComplete ? '' : undefined"
+    :data-disabled="disabled ? '' : undefined"
+  >
     <slot :value="value" :is-complete="isComplete" />
+
+    <VisuallyHiddenInput
+      v-if="name !== undefined"
+      :id="id"
+      feature="focusable"
+      :tabindex="-1"
+      :name="name"
+      :value="serialized"
+      :required="required"
+      :disabled="disabled"
+      @focus="onHiddenFocus"
+    />
   </Primitive>
 </template>
diff --git a/vue/primitives/src/forms/pin-input/__test__/PinInput.test.ts b/vue/primitives/src/forms/pin-input/__test__/PinInput.test.ts
new file mode 100644
index 0000000..b220d20
--- /dev/null
+++ b/vue/primitives/src/forms/pin-input/__test__/PinInput.test.ts
@@ -0,0 +1,301 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import type { Component } from 'vue';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { PinInputInput, PinInputRoot } from '../index';
+
+function mountPin(props: Record<string, unknown> = {}) {
+  const model = ref<string[] | undefined>(undefined);
+  const completed = ref<string | null>(null);
+  const Harness = defineComponent({
+    setup: () => () => h(PinInputRoot, {
+      modelValue: model.value,
+      length: 4,
+      'onUpdate:modelValue': (v: string[]) => { model.value = v; },
+      onComplete: (v: string) => { completed.value = v; },
+      ...props,
+    }, {
+      default: () => [0, 1, 2, 3].map(i => h(PinInputInput as Component, { key: i, index: i })),
+    }),
+  });
+  const wrapper = mount(Harness, { attachTo: document.body });
+  return { wrapper, model, completed };
+}
+
+function inputs(): HTMLInputElement[] {
+  return Array.from(document.querySelectorAll<HTMLInputElement>('input[data-index]'));
+}
+
+function type(el: HTMLInputElement, ch: string): void {
+  el.value = ch;
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+function key(el: Element, k: string): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key: k, bubbles: true, cancelable: true }));
+}
+
+describe('PinInput', () => {
+  it('renders N inputs based on length', () => {
+    const { wrapper } = mountPin();
+    expect(inputs().length).toBe(4);
+    wrapper.unmount();
+  });
+
+  it('typing auto-advances focus and fires complete', async () => {
+    const { wrapper, model, completed } = mountPin();
+    await nextTick();
+    const [a, b, c, d] = inputs();
+    type(a!, '1');
+    await nextTick();
+    expect(document.activeElement).toBe(b);
+    type(b!, '2');
+    type(c!, '3');
+    type(d!, '4');
+    await nextTick();
+    expect(model.value).toEqual(['1', '2', '3', '4']);
+    expect(completed.value).toBe('1234');
+    wrapper.unmount();
+  });
+
+  it('Backspace on empty moves to previous and clears', async () => {
+    const { wrapper, model } = mountPin();
+    await nextTick();
+    const [a, b] = inputs();
+    type(a!, '1');
+    await nextTick();
+    b!.focus();
+    key(b!, 'Backspace');
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+    expect(model.value![0]).toBe('');
+    wrapper.unmount();
+  });
+
+  it('ArrowLeft/ArrowRight navigate', async () => {
+    const { wrapper } = mountPin();
+    await nextTick();
+    const [a, b, c] = inputs();
+    b!.focus();
+    key(b!, 'ArrowLeft');
+    expect(document.activeElement).toBe(a);
+    key(a!, 'ArrowRight');
+    expect(document.activeElement).toBe(b);
+    key(b!, 'ArrowRight');
+    expect(document.activeElement).toBe(c);
+    wrapper.unmount();
+  });
+
+  it('type=number rejects non-digit input', async () => {
+    const { wrapper, model } = mountPin({ type: 'number' });
+    await nextTick();
+    const [a] = inputs();
+    type(a!, 'x');
+    await nextTick();
+    expect(model.value?.[0] ?? '').toBe('');
+    type(a!, '7');
+    await nextTick();
+    expect(model.value![0]).toBe('7');
+    wrapper.unmount();
+  });
+
+  it('paste fills across inputs', async () => {
+    const { wrapper, model, completed } = mountPin();
+    await nextTick();
+    const [a] = inputs();
+    a!.focus();
+    const event = new Event('paste', { bubbles: true, cancelable: true }) as unknown as ClipboardEvent;
+    Object.defineProperty(event, 'clipboardData', {
+      value: { getData: (_type: string) => '9876' },
+    });
+    a!.dispatchEvent(event);
+    await nextTick();
+    expect(model.value).toEqual(['9', '8', '7', '6']);
+    expect(completed.value).toBe('9876');
+    wrapper.unmount();
+  });
+
+  it('mask renders password type for each input', async () => {
+    const { wrapper } = mountPin({ mask: true });
+    await nextTick();
+    for (const el of inputs())
+      expect(el.getAttribute('type')).toBe('password');
+    wrapper.unmount();
+  });
+
+  it('sets per-input aria-label and group role', async () => {
+    const { wrapper } = mountPin();
+    await nextTick();
+    const group = document.querySelector('[role="group"]');
+    expect(group).toBeTruthy();
+    const all = inputs();
+    expect(all[0]!.getAttribute('aria-label')).toBe('pin input 1 of 4');
+    expect(all[3]!.getAttribute('aria-label')).toBe('pin input 4 of 4');
+    wrapper.unmount();
+  });
+
+  it('exposes data-complete on root and inputs once filled', async () => {
+    const { wrapper } = mountPin();
+    await nextTick();
+    const group = document.querySelector('[role="group"]')!;
+    expect(group.hasAttribute('data-complete')).toBe(false);
+    const [a, b, c, d] = inputs();
+    type(a!, '1');
+    type(b!, '2');
+    type(c!, '3');
+    type(d!, '4');
+    await nextTick();
+    expect(group.hasAttribute('data-complete')).toBe(true);
+    expect(inputs()[0]!.hasAttribute('data-complete')).toBe(true);
+    wrapper.unmount();
+  });
+
+  it('sets numeric hardening attributes when type=number', async () => {
+    const { wrapper } = mountPin({ type: 'number' });
+    await nextTick();
+    const a = inputs()[0]!;
+    expect(a.getAttribute('inputmode')).toBe('numeric');
+    expect(a.getAttribute('pattern')).toBe('[0-9]*');
+    expect(a.getAttribute('autocapitalize')).toBe('none');
+    wrapper.unmount();
+  });
+
+  it('renders a hidden form input when name is provided', async () => {
+    const { wrapper } = mountPin({ name: 'otp', required: true, id: 'otp-field' });
+    await nextTick();
+    const hidden = document.querySelector<HTMLInputElement>('input[name="otp"]');
+    expect(hidden).toBeTruthy();
+    expect(hidden!.required).toBe(true);
+    const [a, b] = inputs();
+    type(a!, '1');
+    type(b!, '2');
+    await nextTick();
+    expect(hidden!.value).toBe('12');
+    wrapper.unmount();
+  });
+
+  it('does not render a hidden form input without name', async () => {
+    const { wrapper } = mountPin();
+    await nextTick();
+    expect(document.querySelector('input[name]')).toBeNull();
+    wrapper.unmount();
+  });
+
+  it('hidden input focus forwards to the first cell', async () => {
+    const { wrapper } = mountPin({ name: 'otp' });
+    await nextTick();
+    const hidden = document.querySelector<HTMLInputElement>('input[name="otp"]')!;
+    hidden.dispatchEvent(new FocusEvent('focus', { bubbles: true }));
+    await nextTick();
+    expect(document.activeElement).toBe(inputs()[0]);
+    wrapper.unmount();
+  });
+
+  it('RTL flips arrow-key navigation', async () => {
+    const { wrapper } = mountPin({ dir: 'rtl' });
+    await nextTick();
+    const [a, b, c] = inputs();
+    b!.focus();
+    key(b!, 'ArrowRight');
+    expect(document.activeElement).toBe(a);
+    key(a!, 'ArrowLeft');
+    expect(document.activeElement).toBe(b);
+    key(b!, 'ArrowLeft');
+    expect(document.activeElement).toBe(c);
+    wrapper.unmount();
+  });
+
+  it('Home/End jump to edges', async () => {
+    const { wrapper } = mountPin();
+    await nextTick();
+    const all = inputs();
+    all[1]!.focus();
+    key(all[1]!, 'End');
+    expect(document.activeElement).toBe(all[3]);
+    key(all[3]!, 'Home');
+    expect(document.activeElement).toBe(all[0]);
+    wrapper.unmount();
+  });
+
+  it('per-input disabled blocks navigation onto the cell and skips it', async () => {
+    const model = ref<string[] | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(PinInputRoot, {
+        modelValue: model.value,
+        length: 3,
+        'onUpdate:modelValue': (v: string[]) => { model.value = v; },
+      }, {
+        default: () => [
+          h(PinInputInput as Component, { key: 0, index: 0 }),
+          h(PinInputInput as Component, { key: 1, index: 1, disabled: true }),
+          h(PinInputInput as Component, { key: 2, index: 2 }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const all = inputs();
+    expect(all[1]!.disabled).toBe(true);
+    expect(all[1]!.hasAttribute('data-disabled')).toBe(true);
+    all[0]!.focus();
+    key(all[0]!, 'ArrowRight');
+    // skips the disabled middle cell, lands on index 2
+    expect(document.activeElement).toBe(all[2]);
+    wrapper.unmount();
+  });
+
+  it('OTP mode redirects focus to the first empty cell', async () => {
+    const { wrapper, model } = mountPin({ otp: true });
+    await nextTick();
+    const all = inputs();
+    type(all[0]!, '1');
+    await nextTick();
+    expect(model.value?.[0]).toBe('1');
+    // attempt to focus the last (empty, out-of-order) cell -> redirected to index 1
+    all[3]!.dispatchEvent(new FocusEvent('focus', { bubbles: true }));
+    await nextTick();
+    expect(document.activeElement).toBe(all[1]);
+    wrapper.unmount();
+  });
+
+  it('renders inputs polymorphically via as', async () => {
+    const model = ref<string[] | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(PinInputRoot, {
+        modelValue: model.value,
+        length: 2,
+      }, {
+        default: () => [0, 1].map(i => h(PinInputInput as Component, { key: i, index: i, as: 'input' })),
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    expect(inputs().length).toBe(2);
+    wrapper.unmount();
+  });
+
+  it('disabled root blocks mutation', async () => {
+    const { wrapper, model } = mountPin({ disabled: true });
+    await nextTick();
+    const a = inputs()[0]!;
+    expect(a.disabled).toBe(true);
+    type(a, '5');
+    await nextTick();
+    expect(model.value?.[0] ?? '').toBe('');
+    wrapper.unmount();
+  });
+
+  it('hides placeholder on the focused empty cell', async () => {
+    const { wrapper } = mountPin({ placeholder: '○' });
+    await nextTick();
+    const a = inputs()[0]!;
+    expect(a.getAttribute('placeholder')).toBe('○');
+    a.dispatchEvent(new FocusEvent('focus', { bubbles: true }));
+    await nextTick();
+    expect(a.getAttribute('placeholder')).toBe('');
+    a.dispatchEvent(new FocusEvent('blur', { bubbles: true }));
+    await nextTick();
+    expect(a.getAttribute('placeholder')).toBe('○');
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-Backspace-on-empty-moves-to-previous-and-clears-1.png b/vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-Backspace-on-empty-moves-to-previous-and-clears-1.png
similarity index 100%
rename from vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-Backspace-on-empty-moves-to-previous-and-clears-1.png
rename to vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-Backspace-on-empty-moves-to-previous-and-clears-1.png
diff --git a/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-mask-renders-password-type-for-each-input-1.png b/vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-mask-renders-password-type-for-each-input-1.png
similarity index 100%
rename from vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-mask-renders-password-type-for-each-input-1.png
rename to vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-mask-renders-password-type-for-each-input-1.png
diff --git a/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-paste-fills-across-inputs-1.png b/vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-paste-fills-across-inputs-1.png
similarity index 100%
rename from vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-paste-fills-across-inputs-1.png
rename to vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-paste-fills-across-inputs-1.png
diff --git a/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-type-number-rejects-non-digit-input-1.png b/vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-type-number-rejects-non-digit-input-1.png
similarity index 100%
rename from vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-type-number-rejects-non-digit-input-1.png
rename to vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-type-number-rejects-non-digit-input-1.png
diff --git a/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-typing-auto-advances-focus-and-fires-complete-1.png b/vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-typing-auto-advances-focus-and-fires-complete-1.png
similarity index 100%
rename from vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-typing-auto-advances-focus-and-fires-complete-1.png
rename to vue/primitives/src/forms/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-typing-auto-advances-focus-and-fires-complete-1.png
diff --git a/vue/primitives/src/pin-input/context.ts b/vue/primitives/src/forms/pin-input/context.ts
similarity index 60%
rename from vue/primitives/src/pin-input/context.ts
rename to vue/primitives/src/forms/pin-input/context.ts
index c1bb67b..0925c21 100644
--- a/vue/primitives/src/pin-input/context.ts
+++ b/vue/primitives/src/forms/pin-input/context.ts
@@ -1,4 +1,5 @@
 import type { ComputedRef, Ref } from 'vue';
+import type { Direction } from '../../utilities/config-provider';
 import { useContextFactory } from '@robonen/vue';
 
 export interface PinInputContext {
@@ -9,12 +10,21 @@ export interface PinInputContext {
   type: ComputedRef<'text' | 'number'>;
   disabled: ComputedRef<boolean>;
   placeholder: ComputedRef<string>;
+  dir: ComputedRef<Direction>;
+  isComplete: ComputedRef<boolean>;
   inputs: Ref<HTMLInputElement[]>;
   register: (el: HTMLInputElement) => void;
   unregister: (el: HTMLInputElement) => void;
   setAt: (index: number, char: string) => void;
   clearAt: (index: number) => void;
   focusIndex: (index: number) => void;
+  /**
+   * Move focus relative to `index` by `delta` (`±1`) or to an absolute edge,
+   * skipping disabled cells. RTL-aware navigation is resolved by the caller.
+   */
+  focusRelative: (index: number, delta: number, absolute?: 'home' | 'end') => void;
+  /** Index of the first cell whose value is still empty, or `-1` if all filled. */
+  firstEmptyIndex: () => number;
 }
 
 const ctx = useContextFactory<PinInputContext>('PinInputContext');
diff --git a/vue/primitives/src/pin-input/demo.vue b/vue/primitives/src/forms/pin-input/demo.vue
similarity index 76%
rename from vue/primitives/src/pin-input/demo.vue
rename to vue/primitives/src/forms/pin-input/demo.vue
index b6c905b..68081a3 100644
--- a/vue/primitives/src/pin-input/demo.vue
+++ b/vue/primitives/src/forms/pin-input/demo.vue
@@ -22,11 +22,11 @@ function reset() {
 </script>
 
 <template>
-  <div class="w-full max-w-sm rounded-xl border border-(--border) bg-(--bg-elevated) p-6 text-(--fg)">
+  <div class="demo-card w-full max-w-sm p-6 text-fg">
     <h3 class="text-base font-semibold">
       Verify your email
     </h3>
-    <p class="mt-1 text-sm text-(--fg-muted)">
+    <p class="mt-1 text-sm text-fg-muted">
       Enter the 6-digit code we sent to your inbox.
     </p>
 
@@ -44,12 +44,12 @@ function reset() {
         v-for="i in LENGTH"
         :key="i"
         :index="i - 1"
-        class="h-12 w-10 rounded-lg border bg-(--bg) text-center text-lg font-medium text-(--fg) outline-none transition-colors placeholder:text-(--fg-subtle) focus:border-(--accent) focus:ring-2 focus:ring-(--ring) disabled:cursor-not-allowed"
+        class="h-12 w-10 rounded-lg border bg-bg text-center text-lg font-medium text-fg outline-none transition-colors placeholder:text-fg-subtle focus:border-accent focus:ring-2 focus:ring-ring disabled:cursor-not-allowed"
         :class="status === 'error'
           ? 'border-red-500 dark:border-red-400'
           : isComplete && status === 'ok'
             ? 'border-emerald-500 dark:border-emerald-400'
-            : 'border-(--border)'"
+            : 'border-border'"
       />
     </PinInputRoot>
 
@@ -57,7 +57,7 @@ function reset() {
       <p
         class="font-medium"
         :class="{
-          'text-(--fg-subtle)': status === 'idle' || status === 'verifying',
+          'text-fg-subtle': status === 'idle' || status === 'verifying',
           'text-emerald-600 dark:text-emerald-400': status === 'ok',
           'text-red-600 dark:text-red-400': status === 'error',
         }"
@@ -70,7 +70,7 @@ function reset() {
 
       <button
         type="button"
-        class="rounded-md px-2 py-1 text-sm text-(--accent) transition-colors hover:bg-(--bg-inset)"
+        class="rounded-md px-2 py-1 text-sm text-accent transition-colors hover:bg-bg-inset"
         @click="reset"
       >
         Reset
diff --git a/vue/primitives/src/pin-input/index.ts b/vue/primitives/src/forms/pin-input/index.ts
similarity index 100%
rename from vue/primitives/src/pin-input/index.ts
rename to vue/primitives/src/forms/pin-input/index.ts
diff --git a/vue/primitives/src/forms/radio-group/Radio.vue b/vue/primitives/src/forms/radio-group/Radio.vue
new file mode 100644
index 0000000..542c0f2
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/Radio.vue
@@ -0,0 +1,106 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { AcceptableValue } from './utils';
+
+/**
+ * A standalone radio, usable on its own outside a `RadioGroupRoot`. It owns its
+ * own `checked` state (controlled via `v-model:checked` or uncontrolled), and
+ * — when given a `name` inside a `<form>` — renders a hidden native input so its
+ * value participates in form submission and native validation.
+ *
+ * Like `RadioGroupItem` it emits a cancelable `select` event before toggling;
+ * call `event.preventDefault()` to veto.
+ */
+export interface RadioProps extends PrimitiveProps {
+  /** Element `id`, also used to derive an `aria-label` from an associated `<label for=id>`. */
+  id?: string;
+  /** The value submitted with the owning form when `name` is set. */
+  value?: AcceptableValue;
+  /** When `true`, the radio cannot be interacted with. */
+  disabled?: boolean;
+  /** Marks the radio as required for assistive tech and native validation. */
+  required?: boolean;
+  /** Name of the hidden form field submitted with the owning `<form>`. */
+  name?: string;
+}
+
+export interface RadioEmits {
+  /** Fired before `checked` flips. Call `event.preventDefault()` to cancel. */
+  select: [event: CustomEvent<{ originalEvent: Event; value: AcceptableValue | undefined }>];
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+
+const { value, disabled = false, required = false, name, id, as = 'button' } = defineProps<RadioProps>();
+const emit = defineEmits<RadioEmits>();
+
+const checked = defineModel<boolean>('checked', { default: false });
+
+defineSlots<{
+  default?: (props: { checked: boolean }) => unknown;
+}>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+const dataState = computed(() => checked.value ? 'checked' : 'unchecked');
+
+const isFormControl = computed(() => {
+  const el = currentElement.value;
+  return !!el && !!el.closest('form');
+});
+
+const ariaLabel = computed(() => {
+  if (!id || !currentElement.value || globalThis.document === undefined) return undefined;
+  const label = globalThis.document.querySelector<HTMLLabelElement>(`[for="${id}"]`);
+  return label?.textContent?.trim() || (value !== undefined && value !== null && typeof value !== 'object' ? String(value) : undefined);
+});
+
+function onClick(event: MouseEvent): void {
+  if (disabled) return;
+  const select = new CustomEvent('radio.select', { bubbles: true, cancelable: true, detail: { originalEvent: event, value } });
+  emit('select', select);
+  if (select.defaultPrevented) return;
+  checked.value = true;
+}
+function onKeyDown(event: KeyboardEvent): void {
+  if (event.key === 'Enter') event.preventDefault();
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :id="id"
+    :type="as === 'button' ? 'button' : undefined"
+    role="radio"
+    :aria-checked="checked"
+    :aria-label="ariaLabel"
+    :aria-required="required || undefined"
+    :aria-disabled="disabled || undefined"
+    :data-state="dataState"
+    :data-disabled="disabled ? '' : undefined"
+    :disabled="disabled || undefined"
+    @click="onClick"
+    @keydown="onKeyDown"
+  >
+    <slot :checked="checked" />
+
+    <input
+      v-if="isFormControl && name"
+      type="radio"
+      tabindex="-1"
+      aria-hidden="true"
+      :name="name"
+      :value="value === undefined || value === null ? '' : (typeof value === 'object' ? JSON.stringify(value) : String(value))"
+      :checked="checked"
+      :required="required"
+      :disabled="disabled"
+      style="position: absolute; pointer-events: none; opacity: 0; margin: 0; transform: translateX(-100%);"
+    >
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/forms/radio-group/RadioGroupIndicator.vue b/vue/primitives/src/forms/radio-group/RadioGroupIndicator.vue
new file mode 100644
index 0000000..ae220d5
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/RadioGroupIndicator.vue
@@ -0,0 +1,39 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Renders its content only when the parent `RadioGroupItem` is selected,
+ * mirroring that state via `data-state`. Place the filled dot or check mark
+ * inside it. Wrapped in `Presence`, so it can animate out via CSS leave
+ * animations; use `forceMount` to keep it mounted for animation control.
+ */
+export interface RadioGroupIndicatorProps extends PrimitiveProps {
+  /** Keep the indicator mounted regardless of checked state (for exit animations / measuring). */
+  forceMount?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useRadioGroupItemContext } from './context';
+
+const { as = 'span', forceMount = false } = defineProps<RadioGroupIndicatorProps>();
+const { forwardRef } = useForwardExpose();
+const item = useRadioGroupItemContext();
+</script>
+
+<template>
+  <Presence :present="forceMount || item.checked.value">
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :data-state="item.checked.value ? 'checked' : 'unchecked'"
+      :data-disabled="item.disabled.value ? '' : undefined"
+      style="pointer-events: none;"
+    >
+      <slot />
+    </Primitive>
+  </Presence>
+</template>
diff --git a/vue/primitives/src/forms/radio-group/RadioGroupItem.vue b/vue/primitives/src/forms/radio-group/RadioGroupItem.vue
new file mode 100644
index 0000000..0072a91
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/RadioGroupItem.vue
@@ -0,0 +1,131 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { AcceptableValue } from './utils';
+
+/**
+ * A single selectable option within a `RadioGroupRoot`, rendered by default as
+ * a native `<button role="radio">`. Clicking, pressing Space, or arrow-keying
+ * onto it selects its `value`; it reflects selection via `data-state` and
+ * participates in the group's roving tab order. Provides context to a nested
+ * `RadioGroupIndicator`.
+ *
+ * Emits a cancelable `select` event before the value commits — call
+ * `event.preventDefault()` to veto the selection.
+ */
+export interface RadioGroupItemProps<T extends AcceptableValue = AcceptableValue> extends PrimitiveProps {
+  /** The value this item represents — any structural value, not just strings. */
+  value: T;
+  /** When `true`, the item cannot be selected or focused. */
+  disabled?: boolean;
+  /** Marks the item as required (merged with the group-level `required`). */
+  required?: boolean;
+  /** Associates a `<label for=id>`; its text becomes the radio's `aria-label`. */
+  id?: string;
+}
+
+export interface RadioGroupItemEmits<T extends AcceptableValue = AcceptableValue> {
+  /** Fired before the value commits. Call `event.preventDefault()` to cancel. */
+  select: [event: CustomEvent<{ originalEvent: Event; value: T }>];
+}
+</script>
+
+<script setup lang="ts" generic="T extends AcceptableValue = AcceptableValue">
+import { computed } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { useCollectionInjector } from '../../utilities/collection';
+import { useForwardExpose } from '@robonen/vue';
+import { provideRadioGroupItemContext, useRadioGroupContext } from './context';
+
+const { value, disabled = false, required = false, id, as = 'button' } = defineProps<RadioGroupItemProps<T>>();
+const emit = defineEmits<RadioGroupItemEmits<T>>();
+
+defineSlots<{
+  default?: (props: {
+    /** Whether this item is the selected one. */
+    checked: boolean;
+    /** Whether this item is required (group-level or item-level). */
+    required: boolean;
+    /** Whether this item is disabled (group-level or item-level). */
+    disabled: boolean;
+  }) => unknown;
+}>();
+
+const ctx = useRadioGroupContext();
+const { CollectionItem } = useCollectionInjector<AcceptableValue>();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const isChecked = computed(() => ctx.isChecked(value));
+const isDisabled = computed(() => ctx.disabled.value || disabled);
+const isRequired = computed(() => ctx.required.value || required);
+const dataState = computed(() => isChecked.value ? 'checked' : 'unchecked');
+
+// Derive an accessible name from an associated `<label for=id>` for icon-only
+// radios that have no visible text content of their own.
+const ariaLabel = computed(() => {
+  if (!id || !currentElement.value || globalThis.document === undefined) return undefined;
+  const label = globalThis.document.querySelector<HTMLLabelElement>(`[for="${id}"]`);
+  return label?.textContent?.trim() || undefined;
+});
+
+provideRadioGroupItemContext({
+  value,
+  checked: isChecked,
+  disabled: isDisabled,
+});
+
+// Only one item should be in the tab order:
+// - the checked one, or
+// - the first enabled one if nothing is checked.
+const isTabStop = computed(() => {
+  if (isDisabled.value) return false;
+  const el = currentElement.value;
+  return !!el && ctx.tabStopElement.value === el;
+});
+
+function commit(originalEvent: Event): void {
+  if (isDisabled.value) return;
+  const select = new CustomEvent('radio.select', { bubbles: true, cancelable: true, detail: { originalEvent, value } });
+  emit('select', select);
+  if (select.defaultPrevented) return;
+  ctx.setValue(value);
+}
+
+function onClick(event: MouseEvent): void {
+  commit(event);
+  currentElement.value?.focus();
+}
+function onKeyDown(event: KeyboardEvent): void {
+  // Radios must not activate on Enter (WAI-ARIA): suppress the native button
+  // activation so Enter does not commit a selection or submit a form.
+  if (event.key === 'Enter') {
+    event.preventDefault();
+    return;
+  }
+  if (!currentElement.value) return;
+  ctx.onItemKeyDown(event, currentElement.value);
+}
+</script>
+
+<template>
+  <CollectionItem :value="value">
+    <Primitive
+      :as="as"
+      :ref="forwardRef"
+      :id="id"
+      :type="as === 'button' ? 'button' : undefined"
+      role="radio"
+      :aria-checked="isChecked"
+      :aria-label="ariaLabel"
+      :aria-required="isRequired || undefined"
+      :aria-disabled="isDisabled || undefined"
+      :data-state="dataState"
+      :data-disabled="isDisabled ? '' : undefined"
+      :tabindex="isTabStop ? 0 : -1"
+      :disabled="isDisabled || undefined"
+      @click="onClick"
+      @keydown="onKeyDown"
+    >
+      <slot :checked="isChecked" :required="isRequired" :disabled="isDisabled" />
+    </Primitive>
+  </CollectionItem>
+</template>
diff --git a/vue/primitives/src/forms/radio-group/RadioGroupRoot.vue b/vue/primitives/src/forms/radio-group/RadioGroupRoot.vue
new file mode 100644
index 0000000..4630c19
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/RadioGroupRoot.vue
@@ -0,0 +1,250 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { RovingDirection } from '../../internal/utils/roving-focus';
+import type { AcceptableValue, RadioCompareBy } from './utils';
+
+/**
+ * A set of mutually exclusive options where only one may be selected at a time,
+ * built on `role="radiogroup"` with full keyboard roving focus (arrow keys move
+ * and select, Space selects, Home/End and PageUp/PageDown jump to ends). The
+ * container and state owner: it tracks the selected value (controlled via
+ * `v-model` or uncontrolled via `defaultValue`), provides context to
+ * `RadioGroupItem`, and renders a hidden form input when `name` is set and the
+ * group lives inside a `<form>`.
+ *
+ * Values are not limited to strings — numbers, booleans, `null`, and plain
+ * objects are supported and compared structurally (override with `by`). Reach
+ * for it whenever a user must pick exactly one choice from a small, visible
+ * list.
+ */
+export interface RadioGroupRootProps<T extends AcceptableValue = AcceptableValue> extends PrimitiveProps {
+  /** The value of the radio item that should be checked when initially rendered (uncontrolled). */
+  defaultValue?: T;
+  /** When `true`, prevents the user from interacting with radio items. */
+  disabled?: boolean;
+  /** Marks the group, and every item, as required for assistive tech and native validation. */
+  required?: boolean;
+  /** Name of the hidden form field submitted with the owning `<form>`. */
+  name?: string;
+  /** The orientation arrow navigation follows. */
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * Reading direction. When omitted, inherits from the active `ConfigProvider`
+   * (falling back to `'ltr'`), so an app-wide RTL setting flips arrow navigation.
+   */
+  dir?: RovingDirection;
+  /** When `true`, arrow navigation wraps from the last item to the first and vice versa. */
+  loop?: boolean;
+  /**
+   * How an item `value` is compared against the selected value. Omitted →
+   * structural deep equality; a function → custom comparator; a string →
+   * compare that property key.
+   */
+  by?: RadioCompareBy;
+}
+
+export interface RadioGroupRootEmits<T extends AcceptableValue = AcceptableValue> {
+  /** Emitted whenever the selected value changes (alias of `update:modelValue`). */
+  valueChange: [value: T];
+}
+</script>
+
+<script setup lang="ts" generic="T extends AcceptableValue = AcceptableValue">
+import type { Ref } from 'vue';
+import { computed, ref, toRef, useTemplateRef, watch } from 'vue';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useDirection } from '../../utilities/config-provider';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { provideRadioGroupContext } from './context';
+import { compareValues } from './utils';
+
+const {
+  disabled = false,
+  required = false,
+  orientation = 'vertical',
+  dir,
+  loop = true,
+  defaultValue,
+  name,
+  by,
+  as = 'div',
+} = defineProps<RadioGroupRootProps<T>>();
+
+const emit = defineEmits<RadioGroupRootEmits<T>>();
+const model = defineModel<T | undefined>({ default: undefined });
+
+defineSlots<{
+  default?: (props: {
+    /** The currently selected value (or `undefined` when nothing is selected). */
+    value: AcceptableValue | undefined;
+  }) => unknown;
+}>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Resolve `dir` against the global ConfigProvider so an app-wide RTL setting is
+// honoured; a per-group `dir` prop still wins.
+const direction = useDirection(() => dir);
+
+const localValue = ref<AcceptableValue | undefined>(model.value ?? defaultValue) as Ref<AcceptableValue | undefined>;
+
+watch(model, (v) => {
+  if (v === undefined) return;
+  if (v !== localValue.value) localValue.value = v;
+});
+
+function isChecked(v: AcceptableValue): boolean {
+  return compareValues(localValue.value, v, by);
+}
+
+function setValue(v: AcceptableValue): boolean {
+  if (disabled) return false;
+  localValue.value = v;
+  model.value = v as T;
+  emit('valueChange', v as T);
+  return true;
+}
+
+// DOM-order items via Collection primitive — survives `v-for` reorders. The
+// Collection carries each item's `value`, so non-string values round-trip
+// without serialising through a DOM attribute.
+const { getItems, CollectionSlot } = useCollectionProvider<AcceptableValue>();
+const items = computed(() => getItems(true).map(i => i.ref));
+
+// The single roving tab-stop element, derived ONCE here instead of having every
+// item independently scan `items`: the checked item when a value is selected,
+// otherwise the first enabled item. Reuses the Collection's `value`-carrying
+// records so checked-ness is tested without per-item DOM reads.
+const tabStopElement = computed<HTMLElement | undefined>(() => {
+  const records = getItems(true);
+  if (localValue.value !== undefined) {
+    for (const record of records) {
+      if (record.value !== undefined && isChecked(record.value)) return record.ref;
+    }
+    return undefined;
+  }
+  for (const record of records) {
+    if (!record.ref.hasAttribute('data-disabled')) return record.ref;
+  }
+  return undefined;
+});
+
+// Only render the hidden field when the group is genuinely inside a form, so a
+// stray named input is not added to the document otherwise.
+const isFormControl = computed(() => {
+  const el = currentElement.value;
+  return !!el && !!el.closest('form');
+});
+
+// Serialise the selected value for the native input. Objects/arrays go through
+// JSON so non-primitive values still round-trip through native form submission.
+const submittedValue = computed(() => {
+  const v = localValue.value;
+  if (v === undefined || v === null) return '';
+  if (typeof v === 'object') return JSON.stringify(v);
+  return String(v);
+});
+
+const hiddenInput = useTemplateRef<HTMLInputElement>('hiddenInput');
+
+// Mirror programmatic value changes onto the native input by driving its value
+// through the native setter and dispatching the events a real edit would
+// produce, so native validation and third-party form listeners observe them.
+watch(submittedValue, (next) => {
+  const input = hiddenInput.value;
+  if (!input || globalThis.window === undefined) return;
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis.HTMLInputElement.prototype, 'value');
+  descriptor?.set?.call(input, next);
+  input.dispatchEvent(new Event('input', { bubbles: true }));
+  input.dispatchEvent(new Event('change', { bubbles: true }));
+}, { flush: 'post' });
+
+function focusIndex(i: number): void {
+  const el = items.value[i];
+  if (!el || el.hasAttribute('data-disabled')) return;
+  el.focus();
+  // Route selection through the element's native click so the item's cancelable
+  // `select` event fires and a native `click`/`change` is dispatched for
+  // downstream listeners — instead of mutating state behind their back.
+  el.click();
+}
+
+function onItemKeyDown(event: KeyboardEvent, el: HTMLElement): void {
+  // Space selects the focused item (via its native click) without moving focus.
+  if (event.key === ' ') {
+    event.preventDefault();
+    if (!el.hasAttribute('data-disabled')) el.click();
+    return;
+  }
+
+  const enabled = items.value.filter(x => !x.hasAttribute('data-disabled'));
+
+  // PageUp/PageDown jump to the first/last enabled item (WAI-ARIA optional).
+  if (event.key === 'PageUp' || event.key === 'PageDown') {
+    event.preventDefault();
+    if (enabled.length === 0) return;
+    const target = event.key === 'PageUp' ? enabled[0]! : enabled[enabled.length - 1]!;
+    return focusIndex(items.value.indexOf(target));
+  }
+
+  const action = rovingKeyToAction(event, { orientation, dir: direction.value, loop });
+  if (!action) return;
+  event.preventDefault();
+  if (enabled.length === 0) return;
+  const current = enabled.indexOf(el);
+  if (action.absolute === 'home') return focusIndex(items.value.indexOf(enabled[0]!));
+  if (action.absolute === 'end') return focusIndex(items.value.indexOf(enabled[enabled.length - 1]!));
+  const nextIdx = resolveNextIndex(current === -1 ? 0 : current, action.delta, enabled.length, loop);
+  focusIndex(items.value.indexOf(enabled[nextIdx]!));
+}
+
+provideRadioGroupContext({
+  value: localValue,
+  setValue,
+  isChecked,
+  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
+  orientation: toRef(() => orientation),
+  direction,
+  loop: toRef(() => loop),
+  disabled: toRef(() => disabled),
+  required: toRef(() => required),
+  name: toRef(() => name),
+  items,
+  tabStopElement,
+  onItemKeyDown,
+});
+</script>
+
+<template>
+  <CollectionSlot>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      role="radiogroup"
+      :aria-orientation="orientation"
+      :aria-required="required || undefined"
+      :aria-disabled="disabled || undefined"
+      :dir="direction"
+      :data-orientation="orientation"
+      :data-disabled="disabled ? '' : undefined"
+    >
+      <slot :value="localValue" />
+
+      <input
+        v-if="isFormControl && name"
+        ref="hiddenInput"
+        type="radio"
+        tabindex="-1"
+        aria-hidden="true"
+        :name="name"
+        :value="submittedValue"
+        :checked="localValue !== undefined && localValue !== null"
+        :required="required"
+        :disabled="disabled"
+        style="position: absolute; pointer-events: none; opacity: 0; margin: 0; transform: translateX(-100%);"
+      >
+    </Primitive>
+  </CollectionSlot>
+</template>
diff --git a/vue/primitives/src/forms/radio-group/__test__/RadioGroup.features.test.ts b/vue/primitives/src/forms/radio-group/__test__/RadioGroup.features.test.ts
new file mode 100644
index 0000000..5245ee2
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/__test__/RadioGroup.features.test.ts
@@ -0,0 +1,430 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { provideConfig } from '../../../utilities/config-provider';
+import {
+  Radio,
+  RadioGroupIndicator,
+  RadioGroupItem,
+  RadioGroupRoot,
+  useRadioGroupContext,
+  useRadioGroupItemContext,
+} from '../index';
+
+function press(el: Element, key: string): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+}
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('RadioGroup — non-string values', () => {
+  it('supports number values (controlled selection + check state)', async () => {
+    const model = ref<number | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: number | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: 1, id: 'one' }),
+          h(RadioGroupItem, { value: 2, id: 'two' }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    document.querySelector<HTMLButtonElement>('#two')!.click();
+    await nextTick();
+    expect(model.value).toBe(2);
+    expect(document.querySelector('#two')!.getAttribute('aria-checked')).toBe('true');
+    expect(document.querySelector('#one')!.getAttribute('aria-checked')).toBe('false');
+    wrapper.unmount();
+  });
+
+  it('supports boolean values', async () => {
+    const model = ref<boolean | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: boolean | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: true, id: 'yes' }),
+          h(RadioGroupItem, { value: false, id: 'no' }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    document.querySelector<HTMLButtonElement>('#no')!.click();
+    await nextTick();
+    expect(model.value).toBe(false);
+    expect(document.querySelector('#no')!.getAttribute('aria-checked')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('compares object values structurally (deep equality)', async () => {
+    const optA = { id: 'a' };
+    const model = ref<Record<string, unknown> | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: Record<string, unknown> | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: optA, id: 'oa' }),
+          h(RadioGroupItem, { value: { id: 'b' }, id: 'ob' }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    // Select via a structurally-equal (not identical) object.
+    model.value = { id: 'a' };
+    await nextTick();
+    expect(document.querySelector('#oa')!.getAttribute('aria-checked')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('honours a `by` property-key comparator', async () => {
+    const model = ref<Record<string, unknown> | undefined>({ id: 1, label: 'stale' });
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        by: 'id',
+        'onUpdate:modelValue': (v: Record<string, unknown> | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: { id: 1, label: 'fresh' }, id: 'i1' }),
+          h(RadioGroupItem, { value: { id: 2, label: 'other' }, id: 'i2' }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    // Different object identity + different label, same `id` → checked.
+    expect(document.querySelector('#i1')!.getAttribute('aria-checked')).toBe('true');
+    expect(document.querySelector('#i2')!.getAttribute('aria-checked')).toBe('false');
+    wrapper.unmount();
+  });
+});
+
+function mountGroup(opts: Record<string, unknown> = {}, itemOpts: Array<Record<string, unknown>> = []) {
+  const model = ref<string | undefined>(undefined);
+  const defaults = itemOpts.length
+    ? itemOpts
+    : [
+        { value: 'a', id: 'a' },
+        { value: 'b', id: 'b' },
+        { value: 'c', id: 'c', disabled: true },
+      ];
+  const Harness = defineComponent({
+    setup: () => () => h(RadioGroupRoot, {
+      modelValue: model.value,
+      'onUpdate:modelValue': (v: string | undefined) => { model.value = v; },
+      ...opts,
+    }, {
+      default: () => defaults.map(d => h(RadioGroupItem, d)),
+    }),
+  });
+  return { wrapper: mount(Harness, { attachTo: document.body }), model };
+}
+
+describe('RadioGroup — PageUp/PageDown', () => {
+  it('PageDown jumps to last enabled item, PageUp to first', async () => {
+    const { wrapper, model } = mountGroup({ defaultValue: 'a' });
+    await nextTick();
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    const b = document.querySelector<HTMLButtonElement>('#b')!;
+    a.focus();
+    press(a, 'PageDown');
+    await nextTick();
+    // 'c' is disabled in the default set, so last enabled is 'b'.
+    expect(document.activeElement).toBe(b);
+    expect(model.value).toBe('b');
+    press(b, 'PageUp');
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+    expect(model.value).toBe('a');
+    wrapper.unmount();
+  });
+});
+
+describe('RadioGroup — cancelable select event', () => {
+  it('emits select and applies value when not prevented', async () => {
+    const model = ref<string | undefined>(undefined);
+    const onSelect = vi.fn();
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: string | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: 'a', id: 'a', onSelect }),
+          h(RadioGroupItem, { value: 'b', id: 'b' }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    document.querySelector<HTMLButtonElement>('#a')!.click();
+    await nextTick();
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(model.value).toBe('a');
+    wrapper.unmount();
+  });
+
+  it('vetoes selection when preventDefault is called', async () => {
+    const model = ref<string | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: string | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: 'a', id: 'a', onSelect: (e: CustomEvent) => e.preventDefault() }),
+          h(RadioGroupItem, { value: 'b', id: 'b' }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    document.querySelector<HTMLButtonElement>('#a')!.click();
+    await nextTick();
+    expect(model.value).toBeUndefined();
+    expect(document.querySelector('#a')!.getAttribute('aria-checked')).toBe('false');
+    wrapper.unmount();
+  });
+});
+
+describe('RadioGroup — accessibility', () => {
+  it('group-level required propagates aria-required to each item', async () => {
+    const { wrapper } = mountGroup({ required: true });
+    await nextTick();
+    expect(document.querySelector('#a')!.getAttribute('aria-required')).toBe('true');
+    expect(document.querySelector('#b')!.getAttribute('aria-required')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('derives aria-label from an associated <label for=id>', async () => {
+    const label = document.createElement('label');
+    label.setAttribute('for', 'labelled');
+    label.textContent = 'Pick me';
+    document.body.appendChild(label);
+
+    const { wrapper } = mountGroup({}, [
+      { value: 'x', id: 'labelled' },
+      { value: 'y', id: 'plain' },
+    ]);
+    await nextTick();
+    await nextTick();
+    expect(document.querySelector('#labelled')!.getAttribute('aria-label')).toBe('Pick me');
+    expect(document.querySelector('#plain')!.getAttribute('aria-label')).toBeNull();
+    wrapper.unmount();
+    label.remove();
+  });
+
+  it('Enter does not select a radio (WAI-ARIA)', async () => {
+    const { wrapper, model } = mountGroup();
+    await nextTick();
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    a.focus();
+    press(a, 'Enter');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+    wrapper.unmount();
+  });
+});
+
+describe('RadioGroup — RTL via ConfigProvider', () => {
+  it('inherits dir=rtl from ConfigProvider and flips horizontal arrows', async () => {
+    const model = ref<string | undefined>('b');
+    const RtlProvider = defineComponent({
+      setup(_, { slots }) {
+        provideConfig({ dir: 'rtl' });
+        return () => slots.default?.();
+      },
+    });
+    const Harness = defineComponent({
+      setup: () => () => h(RtlProvider, null, {
+        default: () => h(RadioGroupRoot, {
+          modelValue: model.value,
+          orientation: 'horizontal',
+          'onUpdate:modelValue': (v: string | undefined) => { model.value = v; },
+        }, {
+          default: () => [
+            h(RadioGroupItem, { value: 'a', id: 'a' }),
+            h(RadioGroupItem, { value: 'b', id: 'b' }),
+          ],
+        }),
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const b = document.querySelector<HTMLButtonElement>('#b')!;
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    b.focus();
+    // In RTL, ArrowLeft moves to the *next* item (a is after b visually).
+    press(b, 'ArrowLeft');
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+    expect(model.value).toBe('a');
+    expect((wrapper.element.querySelector('[role="radiogroup"]') as HTMLElement).getAttribute('dir')).toBe('rtl');
+    wrapper.unmount();
+  });
+});
+
+describe('RadioGroup — form gating', () => {
+  it('does NOT render a hidden input outside a form even when name is set', async () => {
+    const { wrapper } = mountGroup({ name: 'fruit' });
+    await nextTick();
+    await nextTick();
+    expect(document.querySelector('input[type="radio"][name="fruit"]')).toBeNull();
+    wrapper.unmount();
+  });
+});
+
+describe('RadioGroup — Indicator presence', () => {
+  it('renders the indicator for the checked item and removes it when unchecked', async () => {
+    const model = ref<string | undefined>('a');
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: string | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: 'a', id: 'a' }, { default: () => h(RadioGroupIndicator) }),
+          h(RadioGroupItem, { value: 'b', id: 'b' }, { default: () => h(RadioGroupIndicator) }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    expect(document.querySelector('#a')!.querySelector('span')).toBeTruthy();
+    expect(document.querySelector('#b')!.querySelector('span')).toBeNull();
+    model.value = 'b';
+    await nextTick();
+    await nextTick();
+    expect(document.querySelector('#b')!.querySelector('span')).toBeTruthy();
+    wrapper.unmount();
+  });
+
+  it('forceMount keeps the indicator mounted while unchecked', async () => {
+    const model = ref<string | undefined>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: string | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: 'a', id: 'fa' }, { default: () => h(RadioGroupIndicator, { forceMount: true }) }),
+        ],
+      }),
+    });
+    const w2 = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    expect(document.querySelector('#fa')!.querySelector('span')).toBeTruthy();
+    w2.unmount();
+  });
+});
+
+describe('RadioGroup — context exports', () => {
+  it('exposes useRadioGroupContext and useRadioGroupItemContext to custom parts', async () => {
+    const seen: { group?: boolean; item?: boolean } = {};
+    const CustomPart = defineComponent({
+      setup() {
+        const group = useRadioGroupContext();
+        const item = useRadioGroupItemContext();
+        seen.group = typeof group.setValue === 'function';
+        seen.item = item.value !== undefined;
+        return () => h('i', { 'data-checked': item.checked.value });
+      },
+    });
+    const model = ref<string | undefined>('a');
+    const Harness = defineComponent({
+      setup: () => () => h(RadioGroupRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: string | undefined) => { model.value = v; },
+      }, {
+        default: () => [
+          h(RadioGroupItem, { value: 'a', id: 'a' }, { default: () => h(CustomPart) }),
+        ],
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    expect(seen.group).toBe(true);
+    expect(seen.item).toBe(true);
+    expect(document.querySelector('i')!.getAttribute('data-checked')).toBe('true');
+    wrapper.unmount();
+  });
+});
+
+describe('Radio — standalone', () => {
+  it('toggles its own checked state on click', async () => {
+    const checked = ref(false);
+    const Harness = defineComponent({
+      setup: () => () => h(Radio, {
+        checked: checked.value,
+        value: 'solo',
+        id: 'solo',
+        'onUpdate:checked': (v: boolean) => { checked.value = v; },
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const el = document.querySelector<HTMLButtonElement>('#solo')!;
+    expect(el.getAttribute('role')).toBe('radio');
+    expect(el.getAttribute('aria-checked')).toBe('false');
+    el.click();
+    await nextTick();
+    expect(checked.value).toBe(true);
+    expect(el.getAttribute('aria-checked')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('honours a vetoing select handler', async () => {
+    const checked = ref(false);
+    const Harness = defineComponent({
+      setup: () => () => h(Radio, {
+        checked: checked.value,
+        value: 'solo',
+        id: 'solo',
+        'onUpdate:checked': (v: boolean) => { checked.value = v; },
+        onSelect: (e: CustomEvent) => e.preventDefault(),
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    document.querySelector<HTMLButtonElement>('#solo')!.click();
+    await nextTick();
+    expect(checked.value).toBe(false);
+    wrapper.unmount();
+  });
+
+  it('renders a hidden form input inside a <form> and submits its value', async () => {
+    const submitted = ref<FormData | null>(null);
+    const Harness = defineComponent({
+      setup: () => () => h('form', {
+        onSubmit: (e: SubmitEvent) => {
+          e.preventDefault();
+          submitted.value = new FormData(e.target as HTMLFormElement);
+        },
+      }, [
+        h(Radio, { value: 'solo', name: 'choice', id: 'solo', checked: true }),
+        h('button', { type: 'submit', id: 'submit' }, 'go'),
+      ]),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    await nextTick();
+    const input = wrapper.element.querySelector('input[type="radio"][name="choice"]') as HTMLInputElement;
+    expect(input).toBeTruthy();
+    (wrapper.element as HTMLFormElement).requestSubmit();
+    await nextTick();
+    expect(submitted.value!.get('choice')).toBe('solo');
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/radio-group/__test__/RadioGroup.form.test.ts b/vue/primitives/src/forms/radio-group/__test__/RadioGroup.form.test.ts
similarity index 100%
rename from vue/primitives/src/radio-group/__test__/RadioGroup.form.test.ts
rename to vue/primitives/src/forms/radio-group/__test__/RadioGroup.form.test.ts
diff --git a/vue/primitives/src/radio-group/__test__/RadioGroup.test.ts b/vue/primitives/src/forms/radio-group/__test__/RadioGroup.test.ts
similarity index 100%
rename from vue/primitives/src/radio-group/__test__/RadioGroup.test.ts
rename to vue/primitives/src/forms/radio-group/__test__/RadioGroup.test.ts
diff --git a/vue/primitives/src/radio-group/__test__/__screenshots__/RadioGroup.form.test.ts/RadioGroup---form-submission-hidden-input-forwards-the-selected-value-into-FormData-on-submit-1.png b/vue/primitives/src/forms/radio-group/__test__/__screenshots__/RadioGroup.form.test.ts/RadioGroup---form-submission-hidden-input-forwards-the-selected-value-into-FormData-on-submit-1.png
similarity index 100%
rename from vue/primitives/src/radio-group/__test__/__screenshots__/RadioGroup.form.test.ts/RadioGroup---form-submission-hidden-input-forwards-the-selected-value-into-FormData-on-submit-1.png
rename to vue/primitives/src/forms/radio-group/__test__/__screenshots__/RadioGroup.form.test.ts/RadioGroup---form-submission-hidden-input-forwards-the-selected-value-into-FormData-on-submit-1.png
diff --git a/vue/primitives/src/forms/radio-group/context.ts b/vue/primitives/src/forms/radio-group/context.ts
new file mode 100644
index 0000000..b23624b
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/context.ts
@@ -0,0 +1,49 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { RovingDirection, RovingOrientation } from '../../internal/utils/roving-focus';
+import type { AcceptableValue } from './utils';
+import { useContextFactory } from '@robonen/vue';
+
+export interface RadioGroupContext {
+  value: Ref<AcceptableValue | undefined>;
+  /**
+   * Commits a selection. Returns `true` when the value was applied, `false`
+   * when it was blocked (disabled group/item or a vetoed `select` event), so
+   * callers can decide whether to follow up (e.g. move focus).
+   */
+  setValue: (v: AcceptableValue) => boolean;
+  /** Structural equality test against the selected value, honouring `by`. */
+  isChecked: (v: AcceptableValue) => boolean;
+  orientation: Ref<RovingOrientation>;
+  direction: Ref<RovingDirection>;
+  loop: Ref<boolean>;
+  disabled: Ref<boolean>;
+  required: Ref<boolean>;
+  name: Ref<string | undefined>;
+  /** DOM-ordered item elements, sourced from the internal Collection. */
+  items: ComputedRef<HTMLElement[]>;
+  /**
+   * The single element that holds the roving tab stop (the checked item, or the
+   * first enabled item when nothing is selected). Computed once in the Root so
+   * each item does an O(1) identity check instead of scanning `items`.
+   */
+  tabStopElement: ComputedRef<HTMLElement | undefined>;
+  onItemKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
+}
+
+const rootCtx = useContextFactory<RadioGroupContext>('RadioGroupContext');
+
+export const provideRadioGroupContext = rootCtx.provide;
+export const useRadioGroupContext = rootCtx.inject;
+
+export interface RadioGroupItemContext {
+  value: AcceptableValue;
+  checked: ComputedRef<boolean>;
+  disabled: ComputedRef<boolean>;
+}
+
+const itemCtx = useContextFactory<RadioGroupItemContext>('RadioGroupItemContext');
+
+export const provideRadioGroupItemContext = itemCtx.provide;
+export const useRadioGroupItemContext = itemCtx.inject;
+
+export type { AcceptableValue, RadioCompareBy } from './utils';
diff --git a/vue/primitives/src/radio-group/demo.vue b/vue/primitives/src/forms/radio-group/demo.vue
similarity index 100%
rename from vue/primitives/src/radio-group/demo.vue
rename to vue/primitives/src/forms/radio-group/demo.vue
diff --git a/vue/primitives/src/forms/radio-group/index.ts b/vue/primitives/src/forms/radio-group/index.ts
new file mode 100644
index 0000000..a0b573b
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/index.ts
@@ -0,0 +1,16 @@
+export { default as Radio } from './Radio.vue';
+export { default as RadioGroupIndicator } from './RadioGroupIndicator.vue';
+export { default as RadioGroupItem } from './RadioGroupItem.vue';
+export { default as RadioGroupRoot } from './RadioGroupRoot.vue';
+export type { RadioEmits, RadioProps } from './Radio.vue';
+export type { RadioGroupIndicatorProps } from './RadioGroupIndicator.vue';
+export type { RadioGroupItemEmits, RadioGroupItemProps } from './RadioGroupItem.vue';
+export type { RadioGroupRootEmits, RadioGroupRootProps } from './RadioGroupRoot.vue';
+export {
+  provideRadioGroupContext,
+  provideRadioGroupItemContext,
+  useRadioGroupContext,
+  useRadioGroupItemContext,
+} from './context';
+export type { RadioGroupContext, RadioGroupItemContext } from './context';
+export type { AcceptableValue as RadioGroupAcceptableValue, RadioCompareBy as RadioGroupCompareBy } from './utils';
diff --git a/vue/primitives/src/forms/radio-group/utils.ts b/vue/primitives/src/forms/radio-group/utils.ts
new file mode 100644
index 0000000..846a82f
--- /dev/null
+++ b/vue/primitives/src/forms/radio-group/utils.ts
@@ -0,0 +1,34 @@
+import { isEqual } from '@robonen/stdlib';
+
+/**
+ * Any value a radio item can carry — not just strings. Mirrors the
+ * select/listbox value model so a radio group can hold numbers, booleans, or
+ * plain objects (compared structurally or via `by`).
+ */
+export type AcceptableValue = string | number | boolean | Record<string, unknown> | null;
+
+/**
+ * Strategy for comparing a radio item's `value` against the group's selected
+ * value. Omitted → structural deep equality (`@robonen/stdlib` `isEqual`), so
+ * object/array values toggle correctly; a function → custom comparator; a
+ * string → compare that property key.
+ */
+export type RadioCompareBy = string | ((a: AcceptableValue, b: AcceptableValue) => boolean);
+
+/**
+ * Compare two radio values. `undefined` on the selected side never matches, so
+ * an unselected group reports every item as unchecked.
+ */
+export function compareValues(
+  selected: AcceptableValue | undefined,
+  candidate: AcceptableValue,
+  by?: RadioCompareBy,
+): boolean {
+  if (selected === undefined) return false;
+  if (typeof by === 'function') return by(selected, candidate);
+  if (typeof by === 'string') {
+    return (selected as Record<string, unknown> | null)?.[by]
+      === (candidate as Record<string, unknown> | null)?.[by];
+  }
+  return isEqual(selected, candidate);
+}
diff --git a/vue/primitives/src/slider/SliderRange.vue b/vue/primitives/src/forms/slider/SliderRange.vue
similarity index 95%
rename from vue/primitives/src/slider/SliderRange.vue
rename to vue/primitives/src/forms/slider/SliderRange.vue
index 882af08..b8ed4b1 100644
--- a/vue/primitives/src/slider/SliderRange.vue
+++ b/vue/primitives/src/forms/slider/SliderRange.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The filled portion of the track representing the selected span, rendered
@@ -11,7 +11,7 @@ export interface SliderRangeProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
 import { useSliderContext } from './context';
diff --git a/vue/primitives/src/slider/SliderRoot.vue b/vue/primitives/src/forms/slider/SliderRoot.vue
similarity index 68%
rename from vue/primitives/src/slider/SliderRoot.vue
rename to vue/primitives/src/forms/slider/SliderRoot.vue
index b041c30..1c20d75 100644
--- a/vue/primitives/src/slider/SliderRoot.vue
+++ b/vue/primitives/src/forms/slider/SliderRoot.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
-import type { SliderDirection, SliderOrientation } from './context';
-import type { PrimitiveProps } from '../primitive';
+import type { SliderDirection, SliderOrientation, SliderThumbAlignment, SliderValueText } from './context';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * An accessible slider for picking one or more numeric values from a range by
@@ -26,7 +26,10 @@ export interface SliderRootProps extends PrimitiveProps {
   minStepsBetweenThumbs?: number;
   /** Orientation. @default 'horizontal' */
   orientation?: SliderOrientation;
-  /** Writing direction. @default 'ltr' */
+  /**
+   * Writing direction. When omitted it is inherited from the nearest
+   * `ConfigProvider` (falling back to `'ltr'`); an explicit value wins.
+   */
   dir?: SliderDirection;
   /** Invert the direction of interaction. @default false */
   inverted?: boolean;
@@ -38,6 +41,24 @@ export interface SliderRootProps extends PrimitiveProps {
   name?: string;
   /** Mark hidden inputs as required. */
   required?: boolean;
+  /**
+   * Thumb positioning strategy.
+   * - `'overflow'` (default): thumbs are positioned purely by percentage and
+   *   may overflow the track at the extremes (offset via CSS if needed).
+   * - `'contain'`: thumbs are inset so they stay fully within the track.
+   * @default 'overflow'
+   */
+  thumbAlignment?: SliderThumbAlignment;
+  /**
+   * Multiplier applied to `step` for large jumps (Page Up/Down and
+   * Shift+Arrow). @default 10
+   */
+  largeStep?: number;
+  /**
+   * Optional formatter producing a human-friendly `aria-valuetext` for each
+   * thumb. Receives the raw value and its thumb index.
+   */
+  valueText?: SliderValueText;
 }
 
 export interface SliderRootEmits {
@@ -53,9 +74,10 @@ import {
   roundToStep,
   scaleLinear,
 } from './utils';
-import { computed, nextTick, shallowRef, toRef, watch } from 'vue';
-import { Primitive } from '../primitive';
+import { computed, nextTick, onScopeDispose, shallowRef, toRef, watch } from 'vue';
+import { Primitive } from '../../internal/primitive';
 import { provideSliderContext } from './context';
+import { useDirection } from '../../utilities/config-provider';
 import { useForwardExpose } from '@robonen/vue';
 import { clamp } from '@robonen/stdlib';
 
@@ -65,31 +87,38 @@ const {
   step = 1,
   minStepsBetweenThumbs = 0,
   orientation = 'horizontal',
-  dir = 'ltr',
+  dir,
   inverted = false,
   disabled = false,
   defaultValue,
   name,
   required,
+  thumbAlignment = 'overflow',
+  largeStep = 10,
+  valueText,
   as = 'span',
 } = defineProps<SliderRootProps>();
 
-const { forwardRef } = useForwardExpose();
+// Resolve direction: explicit `dir` prop wins, otherwise inherit from the
+// nearest `ConfigProvider` (falls back to `'ltr'`).
+const direction = useDirection(() => dir);
 
 const emit = defineEmits<SliderRootEmits>();
 
 // `defineModel` drives both controlled (`v-model`) and uncontrolled modes; in
 // uncontrolled mode `model.value` is `undefined` until first write, so the
-// internal `localValues` below seeds from `defaultValue`/`min`.
-const model = defineModel<number[]>();
+// internal `localValues` below seeds from `defaultValue`/`min`. `null` is
+// accepted (and treated like "no value") for parity with controllers that
+// reset by binding `null`.
+const model = defineModel<number[] | null>();
 
-function toArray(v: number | number[] | undefined): number[] {
+function toArray(v: number | number[] | null | undefined): number[] {
   if (Array.isArray(v)) return v.slice();
   if (typeof v === 'number') return [v];
   return [];
 }
 
-const seed = model.value !== undefined ? model.value.slice() : toArray(defaultValue);
+const seed = Array.isArray(model.value) ? model.value.slice() : toArray(defaultValue);
 // `shallowRef` — the array is always replaced wholesale; no need to proxy items.
 const localValues = shallowRef<number[]>(seed.length > 0 ? seed : [min]);
 
@@ -100,7 +129,7 @@ watch(() => step, (s) => {
 });
 
 watch(model, (v) => {
-  if (v === undefined) return;
+  if (v === null || v === undefined) return;
   // Ref-level check is enough; the setter below guards on deep equality again.
   if (v === localValues.value) return;
   localValues.value = v.slice();
@@ -181,7 +210,7 @@ function getValueFromPointer(event: PointerEvent): number {
   let offset = horizontal ? event.clientX - rect.left : event.clientY - rect.top;
   // ltr horizontal: left = min. rtl or inverted flip.
   // For vertical we invert by default (top = max visually); `inverted` flips back.
-  const flip = (horizontal ? dir === 'rtl' : true) !== inverted;
+  const flip = (horizontal ? direction.value === 'rtl' : true) !== inverted;
   if (flip) offset = size - offset;
   return scaleLinear(offset, 0, size, min, max);
 }
@@ -193,14 +222,30 @@ function handlePointerMove(event: PointerEvent): void {
   updateValue(activeIndex, getValueFromPointer(event));
 }
 
-function handlePointerUp(): void {
-  if (activeIndex === -1) return;
+// Single teardown for the gesture-scoped window listeners, shared by pointerup,
+// pointercancel and scope-dispose so none of them can strand the others.
+function stopDrag(): void {
   activeIndex = -1;
   globalThis.removeEventListener('pointermove', handlePointerMove);
   globalThis.removeEventListener('pointerup', handlePointerUp);
+  globalThis.removeEventListener('pointercancel', handlePointerCancel);
+}
+
+function handlePointerUp(): void {
+  if (activeIndex === -1) return;
+  stopDrag();
   commit();
 }
 
+// Without this, an OS-interrupted gesture (touch cancelled, lost pointer capture,
+// context menu, scroll takeover) never fires pointerup: the window listeners stay
+// attached and `activeIndex` stays pinned to a stale thumb. Abort with no commit
+// (the live value already reflects the last committed move).
+function handlePointerCancel(): void {
+  if (activeIndex === -1) return;
+  stopDrag();
+}
+
 function startDragFromTrack(event: PointerEvent): void {
   if (disabled) return;
   const raw = getValueFromPointer(event);
@@ -211,6 +256,22 @@ function startDragFromTrack(event: PointerEvent): void {
   nextTick(() => thumbEls[index]?.focus());
   globalThis.addEventListener('pointermove', handlePointerMove);
   globalThis.addEventListener('pointerup', handlePointerUp);
+  globalThis.addEventListener('pointercancel', handlePointerCancel);
+}
+
+// A mid-drag unmount (slider removed while a thumb is held) would otherwise leak
+// the window listeners, which retain this instance via their closures.
+onScopeDispose(stopDrag);
+
+// Drag is initiated on the ROOT, not the track: thumbs are siblings of the
+// track (the standard anatomy), so a press on a thumb does NOT bubble to the
+// track — it bubbles here. Handling it on the root drags whether the press
+// lands on the track, the range, or a thumb.
+function onRootPointerDown(event: PointerEvent): void {
+  if (disabled || event.button !== 0) return;
+  event.preventDefault();
+  (event.target as HTMLElement).setPointerCapture?.(event.pointerId);
+  startDragFromTrack(event);
 }
 
 // Keep values clamped if bounds change.
@@ -241,9 +302,13 @@ provideSliderContext({
   max: toRef(() => max),
   step: toRef(() => step),
   orientation: toRef(() => orientation),
-  direction: toRef(() => dir),
+  // `direction` is already a `ComputedRef<SliderDirection>` from `useDirection`.
+  direction,
   disabled: toRef(() => disabled),
   inverted: toRef(() => inverted),
+  thumbAlignment: toRef(() => thumbAlignment),
+  valueText: toRef(() => valueText),
+  largeStepMultiplier: toRef(() => largeStep),
   trackRef,
   registerThumb,
   unregisterThumb,
@@ -253,6 +318,11 @@ provideSliderContext({
 });
 
 defineExpose({ values });
+
+// `useForwardExpose` runs AFTER `defineExpose` so the composable merges the
+// prior expose bindings (plus props + `$el`) instead of `defineExpose`'s
+// `expose()` clobbering them and warning "expose() should be called only once".
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
@@ -262,7 +332,8 @@ defineExpose({ values });
     :aria-disabled="disabled || undefined"
     :data-disabled="disabled ? '' : undefined"
     :data-orientation="orientation"
-    :dir="dir"
+    :dir="direction"
+    @pointerdown="onRootPointerDown"
   >
     <slot :values="values" />
     <template v-if="name">
diff --git a/vue/primitives/src/slider/SliderThumb.vue b/vue/primitives/src/forms/slider/SliderThumb.vue
similarity index 53%
rename from vue/primitives/src/slider/SliderThumb.vue
rename to vue/primitives/src/forms/slider/SliderThumb.vue
index f1cc8e3..30f3390 100644
--- a/vue/primitives/src/slider/SliderThumb.vue
+++ b/vue/primitives/src/forms/slider/SliderThumb.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A draggable handle rendered as `role="slider"`, one per value, placed inside
@@ -18,13 +18,15 @@ export interface SliderThumbProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed, onBeforeUnmount, ref, watch } from 'vue';
-import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { computed, onBeforeUnmount, ref, useAttrs, watch } from 'vue';
+import { useElementSize, useForwardExpose } from '@robonen/vue';
 import { useSliderContext } from './context';
+import { getDefaultThumbLabel, getThumbInBoundsOffset } from './utils';
 
 const { as = 'span' } = defineProps<SliderThumbProps>();
 const ctx = useSliderContext();
+const attrs = useAttrs();
 
 const { forwardRef, currentElement } = useForwardExpose();
 const index = ref(-1);
@@ -47,6 +49,33 @@ const percentage = computed(() => {
   return ((value.value - min) / range) * 100;
 });
 
+// Measure the thumb only matters for `thumbAlignment: 'contain'`; for the
+// default `'overflow'` path the size is never read, so it adds no reactivity.
+const { width, height } = useElementSize(currentElement);
+
+// In-bounds inset (px) so the thumb stays fully within the track at the
+// extremes. `0` for `'overflow'` (the default) — same positioning as before.
+const inBoundsOffset = computed(() => {
+  if (ctx.thumbAlignment.value !== 'contain') return 0;
+  const horizontal = ctx.orientation.value === 'horizontal';
+  const size = horizontal ? width.value : height.value;
+  if (size === 0) return 0;
+  const rtl = ctx.direction.value === 'rtl';
+  const inverted = ctx.inverted.value;
+  // `direction` mirrors the positioning edge: +1 when the start edge sits at
+  // the low end, -1 when flipped (rtl/inverted in horizontal, inverted in
+  // vertical).
+  const flip = horizontal ? rtl !== inverted : inverted;
+  const direction = flip ? -1 : 1;
+  return getThumbInBoundsOffset(size, percentage.value, direction);
+});
+
+// `left: calc(P% + Opx)` keeps the monomorphic style shape while folding in
+// the contain offset (which is `0px` for overflow).
+function edge(pct: number, offset: number): string {
+  return offset === 0 ? `${pct}%` : `calc(${pct}% + ${offset}px)`;
+}
+
 // Stable shape: always return the same keys in the same order so V8 keeps
 // one hidden class for this object and the style patcher sees a monomorphic
 // input. Unused sides are explicit `undefined`.
@@ -56,15 +85,16 @@ const positionStyle = computed<{
   top: string | undefined;
   bottom: string | undefined;
 }>(() => {
-  const pct = `${percentage.value}%`;
+  const pct = percentage.value;
+  const offset = inBoundsOffset.value;
   const horizontal = ctx.orientation.value === 'horizontal';
   const rtl = ctx.direction.value === 'rtl';
   const inverted = ctx.inverted.value;
   if (horizontal) {
     const flip = rtl !== inverted;
     return {
-      left: flip ? undefined : pct,
-      right: flip ? pct : undefined,
+      left: flip ? undefined : edge(pct, offset),
+      right: flip ? edge(pct, offset) : undefined,
       top: undefined,
       bottom: undefined,
     };
@@ -72,36 +102,50 @@ const positionStyle = computed<{
   return {
     left: undefined,
     right: undefined,
-    top: inverted ? pct : undefined,
-    bottom: inverted ? undefined : pct,
+    top: inverted ? edge(pct, offset) : undefined,
+    bottom: inverted ? undefined : edge(pct, offset),
   };
 });
 
-function largeStep(): number {
-  const step = ctx.step.value;
-  return Math.max(step * 10, step);
-}
+// Fall back to a generated label (`Minimum`/`Maximum`/`Value N of M`) only when
+// the consumer has not supplied an explicit `aria-label`/`aria-labelledby`.
+const accessibleLabel = computed<string | undefined>(() => {
+  const hasLabel = attrs['aria-label'] !== undefined && attrs['aria-label'] !== null;
+  const hasLabelledBy = attrs['aria-labelledby'] !== undefined && attrs['aria-labelledby'] !== null;
+  if (hasLabel || hasLabelledBy) return undefined;
+  return getDefaultThumbLabel(index.value, ctx.values.value.length);
+});
+
+// Humanised `aria-valuetext` from the optional formatter; the consumer can
+// still override by passing their own `aria-valuetext` (it wins via `$attrs`).
+const valueText = computed<string | undefined>(() => {
+  if (attrs['aria-valuetext'] !== undefined && attrs['aria-valuetext'] !== null) return undefined;
+  const fmt = ctx.valueText.value;
+  return fmt ? fmt(value.value, index.value) : undefined;
+});
 
 function onKeyDown(event: KeyboardEvent): void {
   if (ctx.disabled.value || index.value === -1) return;
   const horizontal = ctx.orientation.value === 'horizontal';
   const rtl = ctx.direction.value === 'rtl';
   const step = ctx.step.value;
-  const big = largeStep();
+  // Shift+Arrow jumps by the same large step as Page Up/Down.
+  const big = step * ctx.largeStepMultiplier.value;
   const current = ctx.values.value[index.value] ?? ctx.min.value;
+  const unit = event.shiftKey ? big : step;
   let delta: number;
   switch (event.key) {
     case 'ArrowRight':
-      delta = horizontal ? (rtl ? -step : step) : 0;
+      delta = horizontal ? (rtl ? -unit : unit) : 0;
       break;
     case 'ArrowLeft':
-      delta = horizontal ? (rtl ? step : -step) : 0;
+      delta = horizontal ? (rtl ? unit : -unit) : 0;
       break;
     case 'ArrowUp':
-      delta = horizontal ? 0 : step;
+      delta = horizontal ? 0 : unit;
       break;
     case 'ArrowDown':
-      delta = horizontal ? 0 : -step;
+      delta = horizontal ? 0 : -unit;
       break;
     case 'PageUp':
       delta = big;
@@ -132,9 +176,11 @@ function onKeyDown(event: KeyboardEvent): void {
     :ref="forwardRef"
     role="slider"
     :tabindex="ctx.disabled.value ? -1 : 0"
+    :aria-label="accessibleLabel"
     :aria-valuemin="ctx.min.value"
     :aria-valuemax="ctx.max.value"
     :aria-valuenow="value"
+    :aria-valuetext="valueText"
     :aria-orientation="ctx.orientation.value"
     :aria-disabled="ctx.disabled.value || undefined"
     :data-disabled="ctx.disabled.value ? '' : undefined"
diff --git a/vue/primitives/src/slider/SliderTrack.vue b/vue/primitives/src/forms/slider/SliderTrack.vue
similarity index 75%
rename from vue/primitives/src/slider/SliderTrack.vue
rename to vue/primitives/src/forms/slider/SliderTrack.vue
index 87dd5ff..260e543 100644
--- a/vue/primitives/src/slider/SliderTrack.vue
+++ b/vue/primitives/src/forms/slider/SliderTrack.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The full-length rail the thumbs travel along, rendered inside `SliderRoot`.
@@ -11,7 +11,7 @@ export interface SliderTrackProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { onBeforeUnmount, watch } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
 import { useSliderContext } from './context';
@@ -27,12 +27,9 @@ onBeforeUnmount(() => {
   ctx.trackRef.value = null;
 });
 
-function onPointerDown(event: PointerEvent): void {
-  if (ctx.disabled.value) return;
-  event.preventDefault();
-  (event.target as HTMLElement).setPointerCapture?.(event.pointerId);
-  ctx.startDragFromTrack(event);
-}
+// NOTE: the drag-initiating `pointerdown` lives on `SliderRoot`, not here —
+// thumbs are siblings of the track, so a press on a thumb would never reach a
+// track-level handler. The track only registers itself as the geometry ref.
 </script>
 
 <template>
@@ -41,7 +38,6 @@ function onPointerDown(event: PointerEvent): void {
     :ref="forwardRef"
     :data-disabled="ctx.disabled.value ? '' : undefined"
     :data-orientation="ctx.orientation.value"
-    @pointerdown="onPointerDown"
   >
     <slot />
   </Primitive>
diff --git a/vue/primitives/src/forms/slider/__test__/Slider.test.ts b/vue/primitives/src/forms/slider/__test__/Slider.test.ts
new file mode 100644
index 0000000..6ab106d
--- /dev/null
+++ b/vue/primitives/src/forms/slider/__test__/Slider.test.ts
@@ -0,0 +1,571 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { provideConfig } from '../../../utilities/config-provider';
+import { SliderRange, SliderRoot, SliderThumb, SliderTrack } from '../index';
+
+// Minimal declarative config wrapper (the package ships no ConfigProvider
+// component; config is provided via `provideConfig` inside a setup).
+const ConfigProvider = defineComponent({
+  props: { dir: { type: String, default: undefined } },
+  setup(props, { slots }) {
+    provideConfig({ dir: () => props.dir as 'ltr' | 'rtl' | undefined });
+    return () => slots.default?.();
+  },
+});
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function mountSingle(opts: Partial<{ min: number; max: number; step: number; defaultValue: number; disabled: boolean; orientation: 'horizontal' | 'vertical'; dir: 'ltr' | 'rtl' }> = {}) {
+  const model = ref<number[] | undefined>(undefined);
+  const Harness = defineComponent({
+    setup() {
+      return () => h(SliderRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: number[]) => { model.value = v; },
+        ...opts,
+      }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb, { 'aria-label': 'Volume' }),
+        ],
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+function mountRange(opts: Partial<{ min: number; max: number; step: number; defaultValue: number[]; minStepsBetweenThumbs: number }> = {}) {
+  const model = ref<number[] | undefined>(undefined);
+  const Harness = defineComponent({
+    setup() {
+      return () => h(SliderRoot, {
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: number[]) => { model.value = v; },
+        ...opts,
+      }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb, { id: 'thumb-0' }),
+          h(SliderThumb, { id: 'thumb-1' }),
+        ],
+      });
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, model };
+}
+
+function keydown(el: Element, key: string, opts: { shiftKey?: boolean } = {}): void {
+  const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, shiftKey: opts.shiftKey ?? false });
+  el.dispatchEvent(event);
+}
+
+describe('Slider — single thumb', () => {
+  it('renders with role="slider" and ARIA attrs', async () => {
+    mountSingle({ defaultValue: 40, min: 0, max: 100 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb).toBeTruthy();
+    expect(thumb.getAttribute('aria-valuemin')).toBe('0');
+    expect(thumb.getAttribute('aria-valuemax')).toBe('100');
+    expect(thumb.getAttribute('aria-valuenow')).toBe('40');
+    expect(thumb.getAttribute('aria-orientation')).toBe('horizontal');
+    expect(thumb.tabIndex).toBe(0);
+  });
+
+  it('ArrowRight/ArrowLeft adjust by step', async () => {
+    const { model } = mountSingle({ defaultValue: 50, step: 5 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toEqual([55]);
+    keydown(thumb, 'ArrowLeft');
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toEqual([45]);
+  });
+
+  it('ArrowLeft is reversed in RTL', async () => {
+    const { model } = mountSingle({ defaultValue: 50, step: 5, dir: 'rtl' });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toEqual([55]);
+  });
+
+  it('Home/End clamp to min/max', async () => {
+    const { model } = mountSingle({ defaultValue: 50, min: 0, max: 100 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value).toEqual([0]);
+    keydown(thumb, 'End');
+    await nextTick();
+    expect(model.value).toEqual([100]);
+  });
+
+  it('PageUp / PageDown step by 10×', async () => {
+    const { model } = mountSingle({ defaultValue: 50, step: 1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'PageUp');
+    await nextTick();
+    expect(model.value).toEqual([60]);
+    keydown(thumb, 'PageDown');
+    keydown(thumb, 'PageDown');
+    await nextTick();
+    expect(model.value).toEqual([40]);
+  });
+
+  it('clamps at min / max', async () => {
+    const { model } = mountSingle({ defaultValue: 95, min: 0, max: 100, step: 10 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toEqual([100]);
+    keydown(thumb, 'End');
+    await nextTick();
+    expect(model.value).toEqual([100]);
+    keydown(thumb, 'Home');
+    await nextTick();
+    expect(model.value).toEqual([0]);
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(model.value).toEqual([0]);
+  });
+
+  it('disabled: tabindex=-1 and keys do nothing', async () => {
+    const { model } = mountSingle({ defaultValue: 50, disabled: true });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.tabIndex).toBe(-1);
+    expect(thumb.getAttribute('aria-disabled')).toBe('true');
+    keydown(thumb, 'ArrowRight');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+
+  it('vertical orientation reports aria-orientation', async () => {
+    mountSingle({ defaultValue: 50, orientation: 'vertical' });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.getAttribute('aria-orientation')).toBe('vertical');
+  });
+
+  it('writes hidden input when name is set', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, { defaultValue: 30, name: 'volume' }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const input = document.querySelector<HTMLInputElement>('input[type="hidden"][name="volume"]')!;
+    expect(input).toBeTruthy();
+    expect(input.value).toBe('30');
+  });
+});
+
+describe('Slider — range (two thumbs)', () => {
+  it('renders two thumbs with independent aria-valuenow', async () => {
+    mountRange({ defaultValue: [20, 80] });
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(thumbs).toHaveLength(2);
+    expect(thumbs[0]!.getAttribute('aria-valuenow')).toBe('20');
+    expect(thumbs[1]!.getAttribute('aria-valuenow')).toBe('80');
+  });
+
+  it('preserves order by clamping against neighbour', async () => {
+    const { model } = mountRange({ defaultValue: [40, 50], step: 1 });
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    // Push first thumb right past second
+    for (let i = 0; i < 20; i++) keydown(thumbs[0]!, 'ArrowRight');
+    await nextTick();
+    expect(model.value![0]).toBeLessThanOrEqual(model.value![1]!);
+    expect(model.value![0]).toBe(50);
+  });
+
+  it('respects minStepsBetweenThumbs', async () => {
+    const { model } = mountRange({ defaultValue: [30, 50], step: 1, minStepsBetweenThumbs: 10 });
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    // Try to move first thumb up; should stop 10 below second.
+    for (let i = 0; i < 30; i++) keydown(thumbs[0]!, 'ArrowRight');
+    await nextTick();
+    expect(model.value![0]).toBe(40);
+    expect(model.value![1]).toBe(50);
+  });
+
+  it('writes hidden inputs with [] suffix for range', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, { defaultValue: [10, 90], name: 'range' }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const inputs = document.querySelectorAll<HTMLInputElement>('input[type="hidden"][name="range[]"]');
+    expect(inputs).toHaveLength(2);
+    expect(inputs[0]!.value).toBe('10');
+    expect(inputs[1]!.value).toBe('90');
+  });
+});
+
+describe('Slider — Shift+Arrow large step', () => {
+  it('Shift+ArrowRight/Left jumps by step × largeStep multiplier (default 10×)', async () => {
+    const { model } = mountSingle({ defaultValue: 50, step: 1 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowRight', { shiftKey: true });
+    await nextTick();
+    expect(model.value).toEqual([60]);
+    keydown(thumb, 'ArrowLeft', { shiftKey: true });
+    keydown(thumb, 'ArrowLeft', { shiftKey: true });
+    await nextTick();
+    expect(model.value).toEqual([40]);
+  });
+
+  it('Shift+ArrowUp/Down jumps by large step in vertical orientation', async () => {
+    const { model } = mountSingle({ defaultValue: 50, step: 1, orientation: 'vertical' });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'ArrowUp', { shiftKey: true });
+    await nextTick();
+    expect(model.value).toEqual([60]);
+  });
+
+  it('honours a custom largeStep prop for both Page and Shift+Arrow', async () => {
+    const Harness = defineComponent({
+      setup() {
+        const model = ref<number[]>([50]);
+        return () => h(SliderRoot, {
+          modelValue: model.value,
+          step: 1,
+          largeStep: 25,
+          'onUpdate:modelValue': (v: number[]) => { model.value = v; },
+        }, {
+          default: () => [
+            h(SliderTrack, null, { default: () => h(SliderRange) }),
+            h(SliderThumb, { 'aria-label': 'V' }),
+          ],
+        });
+      },
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'PageUp');
+    await nextTick();
+    expect(thumb.getAttribute('aria-valuenow')).toBe('75');
+    keydown(thumb, 'ArrowLeft', { shiftKey: true });
+    await nextTick();
+    expect(thumb.getAttribute('aria-valuenow')).toBe('50');
+    w.unmount();
+  });
+
+  it('Shift has no effect on Home/End (still clamps to bounds)', async () => {
+    const { model } = mountSingle({ defaultValue: 50, min: 0, max: 100 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    keydown(thumb, 'Home', { shiftKey: true });
+    await nextTick();
+    expect(model.value).toEqual([0]);
+  });
+});
+
+describe('Slider — default accessible thumb labels', () => {
+  it('single thumb has no auto label (value is self-describing)', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, { defaultValue: 40 }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.getAttribute('aria-label')).toBeNull();
+  });
+
+  it('two thumbs default to Minimum / Maximum', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, { defaultValue: [20, 80] }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(thumbs[0]!.getAttribute('aria-label')).toBe('Minimum');
+    expect(thumbs[1]!.getAttribute('aria-label')).toBe('Maximum');
+  });
+
+  it('three or more thumbs default to "Value N of M"', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, { defaultValue: [10, 50, 90] }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb),
+          h(SliderThumb),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(thumbs[0]!.getAttribute('aria-label')).toBe('Value 1 of 3');
+    expect(thumbs[1]!.getAttribute('aria-label')).toBe('Value 2 of 3');
+    expect(thumbs[2]!.getAttribute('aria-label')).toBe('Value 3 of 3');
+  });
+
+  it('an explicit aria-label wins over the default', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, { defaultValue: [20, 80] }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb, { 'aria-label': 'Lower bound' }),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(thumbs[0]!.getAttribute('aria-label')).toBe('Lower bound');
+    expect(thumbs[1]!.getAttribute('aria-label')).toBe('Maximum');
+  });
+
+  it('aria-labelledby suppresses the default label', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, { defaultValue: [20, 80] }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb, { 'aria-labelledby': 'lbl-0' }),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(thumbs[0]!.getAttribute('aria-label')).toBeNull();
+    expect(thumbs[0]!.getAttribute('aria-labelledby')).toBe('lbl-0');
+  });
+});
+
+describe('Slider — aria-valuetext formatter', () => {
+  it('applies the valueText formatter to each thumb', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, {
+        defaultValue: [20, 80],
+        valueText: (v: number) => `${v}%`,
+      }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(thumbs[0]!.getAttribute('aria-valuetext')).toBe('20%');
+    expect(thumbs[1]!.getAttribute('aria-valuetext')).toBe('80%');
+  });
+
+  it('passes the thumb index to the formatter', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, {
+        defaultValue: [20, 80],
+        valueText: (v: number, i: number) => `idx${i}:${v}`,
+      }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb),
+          h(SliderThumb),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
+    expect(thumbs[0]!.getAttribute('aria-valuetext')).toBe('idx0:20');
+    expect(thumbs[1]!.getAttribute('aria-valuetext')).toBe('idx1:80');
+  });
+
+  it('no aria-valuetext when no formatter is provided', async () => {
+    mountSingle({ defaultValue: 40 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.getAttribute('aria-valuetext')).toBeNull();
+  });
+
+  it('an explicit aria-valuetext attr wins over the formatter', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, {
+        defaultValue: [50],
+        valueText: (v: number) => `${v}%`,
+      }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb, { 'aria-valuetext': 'fifty' }),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.getAttribute('aria-valuetext')).toBe('fifty');
+  });
+});
+
+describe('Slider — global direction inheritance', () => {
+  it('inherits dir="rtl" from a ConfigProvider when no dir prop is set', async () => {
+    const Harness = defineComponent({
+      setup() {
+        const model = ref<number[]>([50]);
+        return () => h(ConfigProvider, { dir: 'rtl' }, {
+          default: () => h(SliderRoot, {
+            modelValue: model.value,
+            step: 5,
+            'onUpdate:modelValue': (v: number[]) => { model.value = v; },
+          }, {
+            default: () => [
+              h(SliderTrack, null, { default: () => h(SliderRange) }),
+              h(SliderThumb, { 'aria-label': 'V', id: 't' }),
+            ],
+          }),
+        });
+      },
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumb = document.getElementById('t')!;
+    // In RTL, ArrowLeft increases the value (reversed) — proving the inherited dir reached the thumb.
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(thumb.getAttribute('aria-valuenow')).toBe('55');
+    w.unmount();
+  });
+
+  it('an explicit dir prop overrides the ConfigProvider dir', async () => {
+    const Harness = defineComponent({
+      setup() {
+        const model = ref<number[]>([50]);
+        return () => h(ConfigProvider, { dir: 'rtl' }, {
+          default: () => h(SliderRoot, {
+            modelValue: model.value,
+            step: 5,
+            dir: 'ltr',
+            'onUpdate:modelValue': (v: number[]) => { model.value = v; },
+          }, {
+            default: () => [
+              h(SliderTrack, null, { default: () => h(SliderRange) }),
+              h(SliderThumb, { 'aria-label': 'V', id: 't2' }),
+            ],
+          }),
+        });
+      },
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumb = document.getElementById('t2')!;
+    // Explicit ltr: ArrowLeft decreases.
+    keydown(thumb, 'ArrowLeft');
+    await nextTick();
+    expect(thumb.getAttribute('aria-valuenow')).toBe('45');
+    w.unmount();
+  });
+});
+
+describe('Slider — null modelValue tolerance', () => {
+  it('seeds from defaultValue when modelValue is null', async () => {
+    const Harness = defineComponent({
+      setup() {
+        const model = ref<number[] | null>(null);
+        return () => h(SliderRoot, {
+          modelValue: model.value,
+          defaultValue: 30,
+          'onUpdate:modelValue': (v: number[]) => { model.value = v; },
+        }, {
+          default: () => [
+            h(SliderTrack, null, { default: () => h(SliderRange) }),
+            h(SliderThumb, { 'aria-label': 'V' }),
+          ],
+        });
+      },
+    });
+    const w = track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    expect(thumb.getAttribute('aria-valuenow')).toBe('30');
+    w.unmount();
+  });
+});
+
+describe('Slider — thumbAlignment', () => {
+  it('overflow (default) positions thumbs purely by percentage', async () => {
+    mountSingle({ defaultValue: 50, min: 0, max: 100 });
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    // 50% with no in-bounds offset.
+    expect(thumb.style.left).toBe('50%');
+  });
+
+  it('contain produces a calc() with an in-bounds offset', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(SliderRoot, {
+        defaultValue: 0,
+        min: 0,
+        max: 100,
+        thumbAlignment: 'contain',
+      }, {
+        default: () => [
+          h(SliderTrack, null, { default: () => h(SliderRange) }),
+          h(SliderThumb, { 'aria-label': 'V' }),
+        ],
+      }),
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
+    // jsdom reports element size as 0, so the offset collapses to 0px and the
+    // contain path still yields a percentage (no crash, monomorphic shape).
+    expect(thumb.style.left).toBe('0%');
+    expect(thumb.getAttribute('data-orientation')).toBe('horizontal');
+  });
+});
diff --git a/vue/primitives/src/slider/context.ts b/vue/primitives/src/forms/slider/context.ts
similarity index 54%
rename from vue/primitives/src/slider/context.ts
rename to vue/primitives/src/forms/slider/context.ts
index d11be03..053aeeb 100644
--- a/vue/primitives/src/slider/context.ts
+++ b/vue/primitives/src/forms/slider/context.ts
@@ -4,6 +4,23 @@ import { useContextFactory } from '@robonen/vue';
 export type SliderOrientation = 'horizontal' | 'vertical';
 export type SliderDirection = 'ltr' | 'rtl';
 
+/**
+ * Thumb positioning strategy.
+ * - `'overflow'` — thumbs are positioned purely by percentage; at the
+ *   extremes half the thumb sits outside the track (default — preserves the
+ *   original behaviour and lets the consumer offset via CSS `transform`).
+ * - `'contain'` — thumbs are inset so they stay fully within the track bounds
+ *   at `0 %` / `100 %`.
+ */
+export type SliderThumbAlignment = 'overflow' | 'contain';
+
+/**
+ * Formatter turning a raw thumb value into a human-friendly string for
+ * `aria-valuetext`. Receives the value and its thumb index; return `undefined`
+ * to omit `aria-valuetext` for that thumb.
+ */
+export type SliderValueText = (value: number, index: number) => string | undefined;
+
 /**
  * Context shared between `SliderRoot` and its descendants.
  *
@@ -22,10 +39,16 @@ export interface SliderContext {
   direction: Ref<SliderDirection>;
   disabled: Ref<boolean>;
   inverted: Ref<boolean>;
+  /** Thumb positioning strategy — `'overflow'` (default) or `'contain'`. */
+  thumbAlignment: Ref<SliderThumbAlignment>;
+  /** Optional formatter for per-thumb `aria-valuetext`; `undefined` when unset. */
+  valueText: Ref<SliderValueText | undefined>;
   trackRef: Ref<HTMLElement | null>;
   registerThumb: (el: HTMLElement) => number;
   unregisterThumb: (el: HTMLElement) => void;
   getThumbIndex: (el: HTMLElement) => number;
+  /** Large-step multiplier (Page keys / Shift+Arrow) applied to `step`. */
+  largeStepMultiplier: Ref<number>;
   updateValue: (index: number, next: number) => void;
   startDragFromTrack: (event: PointerEvent) => void;
 }
diff --git a/vue/primitives/src/slider/demo.vue b/vue/primitives/src/forms/slider/demo.vue
similarity index 65%
rename from vue/primitives/src/slider/demo.vue
rename to vue/primitives/src/forms/slider/demo.vue
index 464b265..d25f94a 100644
--- a/vue/primitives/src/slider/demo.vue
+++ b/vue/primitives/src/forms/slider/demo.vue
@@ -7,12 +7,12 @@ const price = ref([20, 80]);
 </script>
 
 <template>
-  <div class="w-full max-w-sm space-y-8 rounded-xl border border-(--border) bg-(--bg-elevated) p-6 text-(--fg)">
+  <div class="demo-card w-full max-w-sm space-y-8 p-6 text-fg">
     <!-- Single value -->
     <div class="space-y-3">
       <div class="flex items-baseline justify-between text-sm">
         <span class="font-medium">Volume</span>
-        <span class="font-mono text-(--fg-muted)">{{ volume[0] }}%</span>
+        <span class="font-mono text-fg-muted">{{ volume[0] }}%</span>
       </div>
 
       <SliderRoot
@@ -22,12 +22,12 @@ const price = ref([20, 80]);
         :step="1"
         class="relative flex h-5 w-full touch-none select-none items-center"
       >
-        <SliderTrack class="relative h-1.5 w-full grow rounded-full bg-(--bg-inset)">
-          <SliderRange class="absolute h-full rounded-full bg-(--accent)" />
+        <SliderTrack class="relative h-1.5 w-full grow rounded-full bg-bg-inset">
+          <SliderRange class="absolute h-full rounded-full bg-accent" />
         </SliderTrack>
         <SliderThumb
           aria-label="Volume"
-          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-(--accent) bg-(--bg) shadow-sm outline-none transition focus-visible:ring-2 focus-visible:ring-(--ring) hover:scale-110"
+          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-accent bg-bg shadow-sm outline-none transition focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
         />
       </SliderRoot>
     </div>
@@ -36,7 +36,7 @@ const price = ref([20, 80]);
     <div class="space-y-3">
       <div class="flex items-baseline justify-between text-sm">
         <span class="font-medium">Price range</span>
-        <span class="font-mono text-(--fg-muted)">${{ price[0] }} – ${{ price[1] }}</span>
+        <span class="font-mono text-fg-muted">${{ price[0] }} – ${{ price[1] }}</span>
       </div>
 
       <SliderRoot
@@ -47,35 +47,35 @@ const price = ref([20, 80]);
         :min-steps-between-thumbs="1"
         class="relative flex h-5 w-full touch-none select-none items-center"
       >
-        <SliderTrack class="relative h-1.5 w-full grow rounded-full bg-(--bg-inset)">
-          <SliderRange class="absolute h-full rounded-full bg-(--accent)" />
+        <SliderTrack class="relative h-1.5 w-full grow rounded-full bg-bg-inset">
+          <SliderRange class="absolute h-full rounded-full bg-accent" />
         </SliderTrack>
         <SliderThumb
           aria-label="Minimum price"
-          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-(--accent) bg-(--bg) shadow-sm outline-none transition focus-visible:ring-2 focus-visible:ring-(--ring) hover:scale-110"
+          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-accent bg-bg shadow-sm outline-none transition focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
         />
         <SliderThumb
           aria-label="Maximum price"
-          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-(--accent) bg-(--bg) shadow-sm outline-none transition focus-visible:ring-2 focus-visible:ring-(--ring) hover:scale-110"
+          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-accent bg-bg shadow-sm outline-none transition focus-visible:ring-2 focus-visible:ring-ring hover:scale-110"
         />
       </SliderRoot>
     </div>
 
     <!-- Disabled -->
     <div class="space-y-3">
-      <span class="text-sm font-medium text-(--fg-muted)">Disabled</span>
+      <span class="text-sm font-medium text-fg-muted">Disabled</span>
 
       <SliderRoot
         :default-value="40"
         disabled
         class="relative flex h-5 w-full touch-none select-none items-center opacity-50"
       >
-        <SliderTrack class="relative h-1.5 w-full grow rounded-full bg-(--bg-inset)">
-          <SliderRange class="absolute h-full rounded-full bg-(--fg-subtle)" />
+        <SliderTrack class="relative h-1.5 w-full grow rounded-full bg-bg-inset">
+          <SliderRange class="absolute h-full rounded-full bg-fg-subtle" />
         </SliderTrack>
         <SliderThumb
           aria-label="Disabled value"
-          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-(--fg-subtle) bg-(--bg)"
+          class="absolute block h-4 w-4 -translate-x-1/2 rounded-full border-2 border-fg-subtle bg-bg"
         />
       </SliderRoot>
     </div>
diff --git a/vue/primitives/src/slider/index.ts b/vue/primitives/src/forms/slider/index.ts
similarity index 81%
rename from vue/primitives/src/slider/index.ts
rename to vue/primitives/src/forms/slider/index.ts
index ecc31b2..2662bb1 100644
--- a/vue/primitives/src/slider/index.ts
+++ b/vue/primitives/src/forms/slider/index.ts
@@ -2,7 +2,7 @@ export { default as SliderRange } from './SliderRange.vue';
 export { default as SliderRoot } from './SliderRoot.vue';
 export { default as SliderThumb } from './SliderThumb.vue';
 export { default as SliderTrack } from './SliderTrack.vue';
-export type { SliderDirection, SliderOrientation } from './context';
+export type { SliderDirection, SliderOrientation, SliderThumbAlignment, SliderValueText } from './context';
 export type { SliderRangeProps } from './SliderRange.vue';
 export type { SliderRootEmits, SliderRootProps } from './SliderRoot.vue';
 export type { SliderThumbProps } from './SliderThumb.vue';
diff --git a/vue/primitives/src/forms/slider/utils.ts b/vue/primitives/src/forms/slider/utils.ts
new file mode 100644
index 0000000..c1712a1
--- /dev/null
+++ b/vue/primitives/src/forms/slider/utils.ts
@@ -0,0 +1,98 @@
+/**
+ * Returns the number of decimal digits in a numeric `step`.
+ *
+ * Used by {@link roundToStep} to compensate floating-point drift without
+ * allocating strings on every invocation (the cost is paid once per `step`
+ * change and cached by the caller).
+ */
+export function getStepDecimals(step: number): number {
+  if (!Number.isFinite(step)) return 0;
+  const str = String(step);
+  const dot = str.indexOf('.');
+  if (dot === -1) return 0;
+  return str.length - dot - 1;
+}
+
+/**
+ * Snap `value` to the nearest multiple of `step` anchored at `min`.
+ *
+ * `decimals` must be pre-computed by the caller via {@link getStepDecimals}
+ * and cached per-`step` — this function is on the pointermove hot path.
+ */
+export function roundToStep(value: number, step: number, min: number, decimals: number): number {
+  const nearest = Math.round((value - min) / step) * step + min;
+  return decimals > 0 ? Number(nearest.toFixed(decimals)) : nearest;
+}
+
+/**
+ * Linear projection of `value` from the input domain onto the output range.
+ *
+ * Plain (non-curried) form — no per-call closure allocation.
+ */
+export function scaleLinear(value: number, d0: number, d1: number, r0: number, r1: number): number {
+  if (d0 === d1 || r0 === r1) return r0;
+  return r0 + ((r1 - r0) / (d1 - d0)) * (value - d0);
+}
+
+/**
+ * Verify that adjacent values in an already-sorted `values` array differ by
+ * at least `minStepsBetween * step`.
+ *
+ * The caller is expected to maintain the invariant that `values` is sorted
+ * ascending (the slider Root guarantees this by construction).
+ */
+export function hasMinStepsBetweenSortedValues(values: number[], minStepsBetween: number, step: number): boolean {
+  if (minStepsBetween <= 0 || values.length < 2) return true;
+  const minGap = minStepsBetween * step;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i]! - values[i - 1]! < minGap) return false;
+  }
+  return true;
+}
+
+/**
+ * Index of the value in `values` closest to `nextValue`.
+ *
+ * Single-pass — no intermediate distance array.
+ */
+export function getClosestValueIndex(values: number[], nextValue: number): number {
+  if (values.length <= 1) return 0;
+  let bestIdx = 0;
+  let bestDist = Math.abs(values[0]! - nextValue);
+  for (let i = 1; i < values.length; i++) {
+    const d = Math.abs(values[i]! - nextValue);
+    if (d < bestDist) {
+      bestDist = d;
+      bestIdx = i;
+    }
+  }
+  return bestIdx;
+}
+
+/**
+ * Offset (in pixels) that keeps a thumb of `size` px centred on its track
+ * position fully inside the track at the extremes. At 0 % the thumb is nudged
+ * inward by half its size, at 100 % outward by the same amount, scaling
+ * linearly in between. `direction` is `1` when the start edge grows from the
+ * low end and `-1` when inverted, so the sign matches the positioning edge.
+ *
+ * Returns `0` for the `'overflow'` alignment (caller short-circuits) — used only
+ * for `'contain'`.
+ */
+export function getThumbInBoundsOffset(size: number, percent: number, direction: number): number {
+  const halfSize = size / 2;
+  const offset = scaleLinear(percent, 0, 50, 0, halfSize);
+  return (halfSize - offset * direction) * direction;
+}
+
+/**
+ * Default accessible label for a thumb when the consumer does not supply an
+ * explicit `aria-label`. Single-thumb sliders return `undefined` (the value is
+ * self-describing via `aria-valuenow`); two thumbs become `Minimum` / `Maximum`;
+ * three or more become `Value N of M`.
+ */
+export function getDefaultThumbLabel(index: number, total: number): string | undefined {
+  if (total > 2) return `Value ${index + 1} of ${total}`;
+  if (total === 2) return index === 0 ? 'Minimum' : 'Maximum';
+  return undefined;
+}
diff --git a/vue/primitives/src/stepper/StepperDescription.vue b/vue/primitives/src/forms/stepper/StepperDescription.vue
similarity index 84%
rename from vue/primitives/src/stepper/StepperDescription.vue
rename to vue/primitives/src/forms/stepper/StepperDescription.vue
index f74d113..52e7cc0 100644
--- a/vue/primitives/src/stepper/StepperDescription.vue
+++ b/vue/primitives/src/forms/stepper/StepperDescription.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Optional supporting text for a step. Its `id` is wired to the trigger's
@@ -9,7 +9,7 @@ export interface StepperDescriptionProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useStepperItemContext } from './context';
 
diff --git a/vue/primitives/src/stepper/StepperIndicator.vue b/vue/primitives/src/forms/stepper/StepperIndicator.vue
similarity index 76%
rename from vue/primitives/src/stepper/StepperIndicator.vue
rename to vue/primitives/src/forms/stepper/StepperIndicator.vue
index d848c00..00b4625 100644
--- a/vue/primitives/src/stepper/StepperIndicator.vue
+++ b/vue/primitives/src/forms/stepper/StepperIndicator.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { StepperState } from './context';
 
 /**
  * The visual marker for a step — typically a numbered circle or check. Defaults
@@ -10,12 +11,16 @@ export interface StepperIndicatorProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useStepperItemContext } from './context';
 
 const { as = 'div' } = defineProps<StepperIndicatorProps>();
 
+defineSlots<{
+  default?: (props: { step: number; state: StepperState }) => unknown;
+}>();
+
 const item = useStepperItemContext();
 const { forwardRef } = useForwardExpose();
 </script>
diff --git a/vue/primitives/src/stepper/StepperItem.vue b/vue/primitives/src/forms/stepper/StepperItem.vue
similarity index 86%
rename from vue/primitives/src/stepper/StepperItem.vue
rename to vue/primitives/src/forms/stepper/StepperItem.vue
index 6304371..cefa6d4 100644
--- a/vue/primitives/src/stepper/StepperItem.vue
+++ b/vue/primitives/src/forms/stepper/StepperItem.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { StepperState } from './context';
 
 /**
  * A single step within the stepper. Associates its child trigger, indicator,
@@ -19,12 +20,16 @@ export interface StepperItemProps extends PrimitiveProps {
 <script setup lang="ts">
 import { computed, toRef } from 'vue';
 import { provideStepperItemContext, useStepperRootContext } from './context';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
 const { as = 'div', step, disabled = false, completed = false } = defineProps<StepperItemProps>();
 
+defineSlots<{
+  default?: (props: { state: StepperState; step: number }) => unknown;
+}>();
+
 const root = useStepperRootContext();
 const { forwardRef } = useForwardExpose();
 
diff --git a/vue/primitives/src/stepper/StepperRoot.vue b/vue/primitives/src/forms/stepper/StepperRoot.vue
similarity index 51%
rename from vue/primitives/src/stepper/StepperRoot.vue
rename to vue/primitives/src/forms/stepper/StepperRoot.vue
index 7ff541f..4df9c22 100644
--- a/vue/primitives/src/stepper/StepperRoot.vue
+++ b/vue/primitives/src/forms/stepper/StepperRoot.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
 import type { StepperDirection, StepperOrientation } from './context';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A multi-step progress control that guides users through a sequence of steps —
@@ -23,20 +23,52 @@ export interface StepperRootProps extends PrimitiveProps {
   linear?: boolean;
   /** Disable the entire stepper. */
   disabled?: boolean;
+  /**
+   * Builds the message announced to screen readers via the visually-hidden
+   * live region whenever the active step changes. Override for i18n.
+   * @default ({ value, total }) => `Step ${value} of ${total}`
+   */
+  announceLabel?: (state: { value: number; total: number }) => string;
 }
 
 export interface StepperRootEmits {
   'update:modelValue': [value: number];
 }
+
+export interface StepperRootSlotProps {
+  /** Current active step (1-based). */
+  value: number;
+  /** Total number of registered steps. */
+  total: number;
+  /** `true` when the active step is the first step. */
+  isFirstStep: boolean;
+  /** `true` when the active step is the last step. */
+  isLastStep: boolean;
+  /** `true` when the next step's trigger is disabled (or absent). */
+  isNextDisabled: boolean;
+  /** `true` when the previous step's trigger is disabled (or absent). */
+  isPrevDisabled: boolean;
+  /** Navigate to an absolute step (1-based). */
+  goToStep: (step: number) => void;
+  /** Navigate to the next step. */
+  goToNextStep: () => void;
+  /** Navigate to the previous step. */
+  goToPrevStep: () => void;
+  /** `true` when there is a step after the active one. */
+  hasNext: () => boolean;
+  /** `true` when there is a step before the active one. */
+  hasPrev: () => boolean;
+}
 </script>
 
 <script setup lang="ts">
 import { computed, toRef } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { Primitive } from '../primitive';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { Primitive } from '../../internal/primitive';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
 import { provideStepperRootContext } from './context';
-import { useCollectionProvider } from '../collection';
-import { useConfig } from '../config-provider';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useConfig } from '../../utilities/config-provider';
 import { useForwardExpose } from '@robonen/vue';
 
 const {
@@ -46,15 +78,19 @@ const {
   linear = true,
   disabled = false,
   dir,
+  announceLabel,
 } = defineProps<StepperRootProps>();
 
+defineSlots<{
+  default?: (props: StepperRootSlotProps) => unknown;
+}>();
+
 const model = defineModel<number>();
 
 // Uncontrolled mode: seed the active step from `defaultValue` (parent passed no `v-model`).
 if (model.value === undefined)
   model.value = defaultValue;
 
-const { forwardRef } = useForwardExpose();
 const config = useConfig();
 
 const direction = computed(() => dir ?? config.dir.value);
@@ -83,6 +119,38 @@ function goToStep(step: number): void {
   commit(step);
 }
 
+function goToNextStep(): void {
+  goToStep(value.value + 1);
+}
+
+function goToPrevStep(): void {
+  goToStep(value.value - 1);
+}
+
+function hasNext(): boolean {
+  return value.value < total.value;
+}
+
+function hasPrev(): boolean {
+  return value.value > 1;
+}
+
+const isFirstStep = computed(() => value.value <= 1);
+const isLastStep = computed(() => total.value > 0 && value.value >= total.value);
+
+// Boundary or DOM-disabled state of the adjacent triggers — lets consumers wire
+// Next/Prev buttons without re-deriving step math themselves.
+const isNextDisabled = computed(() => {
+  if (disabled || !hasNext()) return true;
+  const next = getItems(true)[value.value]?.ref;
+  return next ? next.hasAttribute('data-disabled') : true;
+});
+const isPrevDisabled = computed(() => {
+  if (disabled || !hasPrev()) return true;
+  const prev = getItems(true)[value.value - 2]?.ref;
+  return prev ? prev.hasAttribute('data-disabled') : true;
+});
+
 function onTriggerKeyDown(event: KeyboardEvent, el: HTMLElement): void {
   const action = rovingKeyToAction(event, {
     orientation,
@@ -119,9 +187,42 @@ provideStepperRootContext({
   direction,
   linear: toRef(() => linear),
   disabled: toRef(() => disabled),
+  isFirstStep,
+  isLastStep,
+  isNextDisabled,
+  isPrevDisabled,
   goToStep,
+  goToNextStep,
+  goToPrevStep,
+  hasNext,
+  hasPrev,
   onTriggerKeyDown,
 });
+
+const announcement = computed(() => announceLabel
+  ? announceLabel({ value: value.value, total: total.value })
+  : `Step ${value.value} of ${total.value}`);
+
+defineExpose({
+  /** Current active step (1-based). */
+  value,
+  /** Total number of registered steps. */
+  total,
+  isFirstStep,
+  isLastStep,
+  isNextDisabled,
+  isPrevDisabled,
+  goToStep,
+  goToNextStep,
+  goToPrevStep,
+  hasNext,
+  hasPrev,
+});
+
+// `useForwardExpose` runs AFTER `defineExpose` so the composable merges the
+// prior expose bindings (plus props + `$el`) instead of `defineExpose`'s
+// `expose()` clobbering them and warning "expose() should be called only once".
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
@@ -139,8 +240,25 @@ provideStepperRootContext({
       <slot
         :value="value"
         :total="total"
+        :is-first-step="isFirstStep"
+        :is-last-step="isLastStep"
+        :is-next-disabled="isNextDisabled"
+        :is-prev-disabled="isPrevDisabled"
         :go-to-step="goToStep"
+        :go-to-next-step="goToNextStep"
+        :go-to-prev-step="goToPrevStep"
+        :has-next="hasNext"
+        :has-prev="hasPrev"
       />
+
+      <VisuallyHidden
+        v-if="as !== 'template'"
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+      >
+        {{ announcement }}
+      </VisuallyHidden>
     </Primitive>
   </CollectionSlot>
 </template>
diff --git a/vue/primitives/src/stepper/StepperSeparator.vue b/vue/primitives/src/forms/stepper/StepperSeparator.vue
similarity index 52%
rename from vue/primitives/src/stepper/StepperSeparator.vue
rename to vue/primitives/src/forms/stepper/StepperSeparator.vue
index c8f9d81..360d7fd 100644
--- a/vue/primitives/src/stepper/StepperSeparator.vue
+++ b/vue/primitives/src/forms/stepper/StepperSeparator.vue
@@ -1,24 +1,34 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { StepperOrientation } from './context';
 
 /**
  * The decorative connector drawn between adjacent steps. It is `aria-hidden`
  * and exposes the owning item's `state` and the stepper `orientation` as data
  * attributes so the line can be styled to reflect progress.
  */
-export interface StepperSeparatorProps extends PrimitiveProps {}
+export interface StepperSeparatorProps extends PrimitiveProps {
+  /**
+   * Override the connector orientation. Defaults to the stepper's own
+   * orientation, so you usually do not need to set it.
+   */
+  orientation?: StepperOrientation;
+}
 </script>
 
 <script setup lang="ts">
+import { computed } from 'vue';
 import { useStepperItemContext, useStepperRootContext } from './context';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 
-const { as = 'div' } = defineProps<StepperSeparatorProps>();
+const { as = 'div', orientation } = defineProps<StepperSeparatorProps>();
 
 const root = useStepperRootContext();
 const item = useStepperItemContext();
 const { forwardRef } = useForwardExpose();
+
+const resolvedOrientation = computed(() => orientation ?? root.orientation.value);
 </script>
 
 <template>
@@ -27,7 +37,7 @@ const { forwardRef } = useForwardExpose();
     :as="as"
     role="separator"
     aria-hidden="true"
-    :data-orientation="root.orientation.value"
+    :data-orientation="resolvedOrientation"
     :data-state="item.state.value"
   >
     <slot />
diff --git a/vue/primitives/src/stepper/StepperTitle.vue b/vue/primitives/src/forms/stepper/StepperTitle.vue
similarity index 84%
rename from vue/primitives/src/stepper/StepperTitle.vue
rename to vue/primitives/src/forms/stepper/StepperTitle.vue
index 69a52fd..be3cc6e 100644
--- a/vue/primitives/src/stepper/StepperTitle.vue
+++ b/vue/primitives/src/forms/stepper/StepperTitle.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The accessible label for a step. Its `id` is wired to the trigger's
@@ -9,7 +9,7 @@ export interface StepperTitleProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useStepperItemContext } from './context';
 
diff --git a/vue/primitives/src/stepper/StepperTrigger.vue b/vue/primitives/src/forms/stepper/StepperTrigger.vue
similarity index 91%
rename from vue/primitives/src/stepper/StepperTrigger.vue
rename to vue/primitives/src/forms/stepper/StepperTrigger.vue
index 41cfa43..3ddd3f6 100644
--- a/vue/primitives/src/stepper/StepperTrigger.vue
+++ b/vue/primitives/src/forms/stepper/StepperTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The interactive control for a step. Clicking or pressing it navigates to the
@@ -11,8 +11,8 @@ export interface StepperTriggerProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import { useStepperItemContext, useStepperRootContext } from './context';
-import { Primitive } from '../primitive';
-import { useCollectionInjector } from '../collection';
+import { Primitive } from '../../internal/primitive';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
 
 const { as = 'button' } = defineProps<StepperTriggerProps>();
diff --git a/vue/primitives/src/forms/stepper/__test__/Stepper.test.ts b/vue/primitives/src/forms/stepper/__test__/Stepper.test.ts
new file mode 100644
index 0000000..1ab3a38
--- /dev/null
+++ b/vue/primitives/src/forms/stepper/__test__/Stepper.test.ts
@@ -0,0 +1,409 @@
+import {
+  StepperDescription,
+  StepperIndicator,
+  StepperItem,
+  StepperRoot,
+  StepperSeparator,
+  StepperTitle,
+  StepperTrigger,
+} from '../index';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+
+function createStepper(rootProps: Record<string, unknown> = {}, stepCount = 3, itemProps: Record<number, Record<string, unknown>> = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () => h(
+          StepperRoot,
+          rootProps,
+          {
+            default: () => Array.from({ length: stepCount }, (_, i) => {
+              const step = i + 1;
+              return h(
+                StepperItem,
+                { key: step, step, ...itemProps[step] },
+                {
+                  default: () => [
+                    h(StepperTrigger, null, { default: () => [
+                      h(StepperIndicator),
+                      h(StepperTitle, null, { default: () => `Step ${step}` }),
+                      h(StepperDescription, null, { default: () => `Description ${step}` }),
+                    ] }),
+                    i < stepCount - 1 ? h(StepperSeparator) : null,
+                  ],
+                },
+              );
+            }),
+          },
+        );
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+function press(el: Element, key: string) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+}
+
+describe('Stepper', () => {
+  it('renders with role=group', () => {
+    const w = createStepper();
+    const root = w.find('[role="group"]');
+    expect(root.exists()).toBe(true);
+    expect(root.attributes('aria-label')).toBe('progress');
+    w.unmount();
+  });
+
+  it('first item is active by default (step=1)', () => {
+    const w = createStepper();
+    const items = w.findAllComponents(StepperItem);
+    expect(items[0]!.attributes('data-state')).toBe('active');
+    expect(items[0]!.attributes('aria-current')).toBe('step');
+    expect(items[1]!.attributes('data-state')).toBe('inactive');
+    w.unmount();
+  });
+
+  it('honors defaultValue', () => {
+    const w = createStepper({ defaultValue: 2 });
+    const items = w.findAllComponents(StepperItem);
+    expect(items[0]!.attributes('data-state')).toBe('completed');
+    expect(items[1]!.attributes('data-state')).toBe('active');
+    expect(items[2]!.attributes('data-state')).toBe('inactive');
+    w.unmount();
+  });
+
+  it('v-model moves the active step', async () => {
+    const value = ref(1);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { modelValue: value.value, 'onUpdate:modelValue': (v: number) => (value.value = v) },
+            {
+              default: () => [1, 2, 3].map(step =>
+                h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger, null, { default: () => `S${step}` }) }),
+              ),
+            },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    const triggers = w.findAll('button');
+    await triggers[1]!.trigger('mousedown');
+    await nextTick();
+    expect(value.value).toBe(2);
+    w.unmount();
+  });
+
+  it('linear mode blocks skipping ahead', async () => {
+    const w = createStepper();
+    const triggers = w.findAll('button');
+    await triggers[2]!.trigger('mousedown'); // try to skip to 3
+    await nextTick();
+    const items = w.findAllComponents(StepperItem);
+    expect(items[0]!.attributes('data-state')).toBe('active'); // unchanged
+    w.unmount();
+  });
+
+  it('non-linear mode allows arbitrary step', async () => {
+    const w = createStepper({ linear: false });
+    const triggers = w.findAll('button');
+    await triggers[2]!.trigger('mousedown');
+    await nextTick();
+    const items = w.findAllComponents(StepperItem);
+    expect(items[2]!.attributes('data-state')).toBe('active');
+    w.unmount();
+  });
+
+  it('disabled item is not focusable and cannot be activated', async () => {
+    const w = createStepper({ linear: false }, 3, { 2: { disabled: true } });
+    const items = w.findAllComponents(StepperItem);
+    expect(items[1]!.attributes('data-disabled')).toBe('');
+    const triggers = w.findAll('button');
+    expect(triggers[1]!.attributes('tabindex')).toBe('-1');
+    await triggers[1]!.trigger('mousedown');
+    await nextTick();
+    expect(items[0]!.attributes('data-state')).toBe('active'); // unchanged
+    w.unmount();
+  });
+
+  it('Enter/Space on trigger activates step', async () => {
+    const w = createStepper({ linear: false });
+    const triggers = w.findAll('button');
+    (triggers[1]!.element as HTMLElement).focus();
+    press(triggers[1]!.element, 'Enter');
+    await nextTick();
+    const items = w.findAllComponents(StepperItem);
+    expect(items[1]!.attributes('data-state')).toBe('active');
+    w.unmount();
+  });
+
+  it('ArrowRight / ArrowLeft move focus between triggers', () => {
+    const w = createStepper({ linear: false });
+    const triggers = w.findAll('button').map(t => t.element as HTMLElement);
+    triggers[0]!.focus();
+    press(triggers[0]!, 'ArrowRight');
+    expect(document.activeElement).toBe(triggers[1]);
+    press(triggers[1]!, 'ArrowRight');
+    expect(document.activeElement).toBe(triggers[2]);
+    press(triggers[2]!, 'ArrowLeft');
+    expect(document.activeElement).toBe(triggers[1]);
+    w.unmount();
+  });
+
+  it('Home / End jump to first / last trigger', () => {
+    const w = createStepper({ linear: false });
+    const triggers = w.findAll('button').map(t => t.element as HTMLElement);
+    triggers[1]!.focus();
+    press(triggers[1]!, 'End');
+    expect(document.activeElement).toBe(triggers[2]);
+    press(triggers[2]!, 'Home');
+    expect(document.activeElement).toBe(triggers[0]);
+    w.unmount();
+  });
+
+  it('completed prop forces completed state', () => {
+    const w = createStepper({}, 3, { 1: { completed: true } });
+    const items = w.findAllComponents(StepperItem);
+    expect(items[0]!.attributes('data-state')).toBe('completed');
+    w.unmount();
+  });
+
+  it('renders a visually-hidden status live region announcing the active step', async () => {
+    const w = createStepper({ defaultValue: 2 });
+    await nextTick();
+    const status = w.find('[role="status"]');
+    expect(status.exists()).toBe(true);
+    expect(status.attributes('aria-live')).toBe('polite');
+    expect(status.attributes('aria-atomic')).toBe('true');
+    expect(status.attributes('aria-hidden')).toBeUndefined();
+    expect(status.text()).toBe('Step 2 of 3');
+    w.unmount();
+  });
+
+  it('live region updates its message when the step changes', async () => {
+    const value = ref(1);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { modelValue: value.value, 'onUpdate:modelValue': (v: number) => (value.value = v), linear: false },
+            { default: () => [1, 2, 3].map(step => h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger, null, { default: () => `S${step}` }) })) },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(w.find('[role="status"]').text()).toBe('Step 1 of 3');
+    const triggers = w.findAll('button');
+    await triggers[2]!.trigger('mousedown');
+    await nextTick();
+    expect(w.find('[role="status"]').text()).toBe('Step 3 of 3');
+    w.unmount();
+  });
+
+  it('announceLabel customizes the live-region message', async () => {
+    const w = createStepper({
+      defaultValue: 2,
+      announceLabel: ({ value, total }: { value: number; total: number }) => `${value}/${total} done`,
+    });
+    await nextTick();
+    expect(w.find('[role="status"]').text()).toBe('2/3 done');
+    w.unmount();
+  });
+
+  it('does not render the live region when as="template"', () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { as: 'template' },
+            { default: () => h('div', { class: 'root-shell' }, [1, 2].map(step => h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger) }))) },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    expect(w.find('[role="status"]').exists()).toBe(false);
+    expect(w.find('.root-shell').exists()).toBe(true);
+    w.unmount();
+  });
+
+  it('exposes imperative navigation API via template ref', async () => {
+    const value = ref(1);
+    const rootRef = ref<any>(null);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { ref: rootRef, modelValue: value.value, 'onUpdate:modelValue': (v: number) => (value.value = v) },
+            { default: () => [1, 2, 3].map(step => h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger) })) },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(rootRef.value.value).toBe(1);
+    expect(rootRef.value.total).toBe(3);
+    expect(rootRef.value.isFirstStep).toBe(true);
+    expect(rootRef.value.isLastStep).toBe(false);
+    expect(rootRef.value.hasNext()).toBe(true);
+    expect(rootRef.value.hasPrev()).toBe(false);
+
+    rootRef.value.goToNextStep();
+    await nextTick();
+    expect(value.value).toBe(2);
+    expect(rootRef.value.isFirstStep).toBe(false);
+
+    rootRef.value.goToPrevStep();
+    await nextTick();
+    expect(value.value).toBe(1);
+
+    rootRef.value.goToStep(2);
+    await nextTick();
+    expect(value.value).toBe(2);
+    w.unmount();
+  });
+
+  it('prevStep at first step and nextStep at last step are no-ops', async () => {
+    const value = ref(1);
+    const rootRef = ref<any>(null);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { ref: rootRef, modelValue: value.value, 'onUpdate:modelValue': (v: number) => (value.value = v), linear: false },
+            { default: () => [1, 2, 3].map(step => h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger) })) },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    rootRef.value.goToPrevStep();
+    await nextTick();
+    expect(value.value).toBe(1); // clamped at first
+
+    rootRef.value.goToStep(3);
+    await nextTick();
+    expect(value.value).toBe(3);
+    rootRef.value.goToNextStep();
+    await nextTick();
+    expect(value.value).toBe(3); // clamped at last
+    w.unmount();
+  });
+
+  it('disabled root blocks imperative navigation', async () => {
+    const value = ref(1);
+    const rootRef = ref<any>(null);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { ref: rootRef, modelValue: value.value, 'onUpdate:modelValue': (v: number) => (value.value = v), disabled: true, linear: false },
+            { default: () => [1, 2, 3].map(step => h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger) })) },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(rootRef.value.isNextDisabled).toBe(true);
+    expect(rootRef.value.isPrevDisabled).toBe(true);
+    rootRef.value.goToNextStep();
+    await nextTick();
+    expect(value.value).toBe(1); // unchanged
+    w.unmount();
+  });
+
+  it('isNextDisabled reflects the next step being DOM-disabled', async () => {
+    const rootRef = ref<any>(null);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { ref: rootRef, defaultValue: 1, linear: false },
+            { default: () => [1, 2, 3].map(step => h(StepperItem, { key: step, step, disabled: step === 2 }, { default: () => h(StepperTrigger) })) },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(rootRef.value.isNextDisabled).toBe(true); // step 2 is disabled
+    expect(rootRef.value.isPrevDisabled).toBe(true); // no prev at step 1
+    w.unmount();
+  });
+
+  it('exposes expanded slot props on the root default slot', async () => {
+    const captured: Record<string, unknown> = {};
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { defaultValue: 1 },
+            {
+              default: (slotProps: Record<string, unknown>) => {
+                Object.assign(captured, slotProps);
+                return [1, 2, 3].map(step => h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger) }));
+              },
+            },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(captured.value).toBe(1);
+    expect(captured.total).toBe(3);
+    expect(captured.isFirstStep).toBe(true);
+    expect(captured.isLastStep).toBe(false);
+    expect(typeof captured.goToStep).toBe('function');
+    expect(typeof captured.goToNextStep).toBe('function');
+    expect(typeof captured.goToPrevStep).toBe('function');
+    expect(typeof captured.hasNext).toBe('function');
+    expect(typeof captured.hasPrev).toBe('function');
+    w.unmount();
+  });
+
+  it('StepperSeparator inherits orientation and can override it', () => {
+    const w = createStepper({ orientation: 'vertical' });
+    const sep = w.find('[role="separator"]');
+    expect(sep.exists()).toBe(true);
+    expect(sep.attributes('aria-hidden')).toBe('true');
+    expect(sep.attributes('data-orientation')).toBe('vertical');
+    w.unmount();
+  });
+
+  it('StepperSeparator orientation prop overrides the root orientation', () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            StepperRoot,
+            { orientation: 'horizontal' },
+            { default: () => h(StepperItem, { step: 1 }, { default: () => [h(StepperTrigger), h(StepperSeparator, { orientation: 'vertical' })] }) },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    const sep = w.find('[role="separator"]');
+    expect(sep.attributes('data-orientation')).toBe('vertical');
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/stepper/context.ts b/vue/primitives/src/forms/stepper/context.ts
similarity index 61%
rename from vue/primitives/src/stepper/context.ts
rename to vue/primitives/src/forms/stepper/context.ts
index 44f04b8..1461a69 100644
--- a/vue/primitives/src/stepper/context.ts
+++ b/vue/primitives/src/forms/stepper/context.ts
@@ -18,8 +18,25 @@ export interface StepperRootContext {
   linear: Ref<boolean>;
   /** Whether the whole stepper is disabled. */
   disabled: Ref<boolean>;
+  /** `true` when the active step is the first step. */
+  isFirstStep: ComputedRef<boolean>;
+  /** `true` when the active step is the last registered step. */
+  isLastStep: ComputedRef<boolean>;
+  /** `true` when the next step's trigger is disabled (or there is no next step). */
+  isNextDisabled: ComputedRef<boolean>;
+  /** `true` when the previous step's trigger is disabled (or there is no previous step). */
+  isPrevDisabled: ComputedRef<boolean>;
 
+  /** Navigate to an absolute step (1-based), respecting `linear`/`disabled`. */
   goToStep: (step: number) => void;
+  /** Navigate to the step after the active one. */
+  goToNextStep: () => void;
+  /** Navigate to the step before the active one. */
+  goToPrevStep: () => void;
+  /** `true` when there is a step after the active one. */
+  hasNext: () => boolean;
+  /** `true` when there is a step before the active one. */
+  hasPrev: () => boolean;
   onTriggerKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
 }
 
diff --git a/vue/primitives/src/stepper/demo.vue b/vue/primitives/src/forms/stepper/demo.vue
similarity index 63%
rename from vue/primitives/src/stepper/demo.vue
rename to vue/primitives/src/forms/stepper/demo.vue
index 83daccd..9b70333 100644
--- a/vue/primitives/src/stepper/demo.vue
+++ b/vue/primitives/src/forms/stepper/demo.vue
@@ -30,7 +30,7 @@ function prev() {
 </script>
 
 <template>
-  <div class="w-full max-w-xl text-(--fg)">
+  <div class="w-full max-w-xl text-fg">
     <StepperRoot
       v-model="current"
       class="flex items-start"
@@ -43,11 +43,11 @@ function prev() {
       >
         <div class="flex w-full items-center">
           <StepperTrigger
-            class="flex flex-col items-center gap-2 rounded-md p-1 transition-opacity focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) disabled:cursor-not-allowed disabled:opacity-50"
+            class="flex flex-col items-center gap-2 rounded-md p-1 transition-opacity focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
           >
             <StepperIndicator
               v-slot="{ state, step }"
-              class="grid size-9 place-items-center rounded-full border text-sm font-semibold transition-colors data-[state=inactive]:border-(--border) data-[state=inactive]:bg-(--bg) data-[state=inactive]:text-(--fg-muted) data-[state=active]:border-(--accent) data-[state=active]:bg-(--accent) data-[state=active]:text-(--accent-fg) data-[state=completed]:border-emerald-500 data-[state=completed]:bg-emerald-500 data-[state=completed]:text-white dark:data-[state=completed]:border-emerald-400 dark:data-[state=completed]:bg-emerald-400 dark:data-[state=completed]:text-emerald-950"
+              class="grid size-9 place-items-center rounded-full border text-sm font-semibold transition-colors data-[state=inactive]:border-border data-[state=inactive]:bg-bg data-[state=inactive]:text-fg-muted data-[state=active]:border-accent data-[state=active]:bg-accent data-[state=active]:text-accent-fg data-[state=completed]:border-emerald-500 data-[state=completed]:bg-emerald-500 data-[state=completed]:text-white dark:data-[state=completed]:border-emerald-400 dark:data-[state=completed]:bg-emerald-400 dark:data-[state=completed]:text-emerald-950"
             >
               <svg
                 v-if="state === 'completed'"
@@ -69,32 +69,32 @@ function prev() {
 
           <StepperSeparator
             v-if="i < steps.length - 1"
-            class="mx-1 h-0.5 flex-1 rounded-full bg-(--border) data-[state=completed]:bg-emerald-500 dark:data-[state=completed]:bg-emerald-400"
+            class="mx-1 h-0.5 flex-1 rounded-full bg-border data-[state=completed]:bg-emerald-500 dark:data-[state=completed]:bg-emerald-400"
           />
         </div>
 
         <div class="flex flex-col items-center text-center">
-          <StepperTitle class="text-sm font-medium text-(--fg)">
+          <StepperTitle class="text-sm font-medium text-fg">
             {{ s.title }}
           </StepperTitle>
-          <StepperDescription class="text-xs text-(--fg-subtle)">
+          <StepperDescription class="text-xs text-fg-subtle">
             {{ s.description }}
           </StepperDescription>
         </div>
       </StepperItem>
     </StepperRoot>
 
-    <div class="mt-6 rounded-lg border border-(--border) bg-(--bg-subtle) p-6 text-center">
-      <p class="text-sm text-(--fg-muted)">
+    <div class="mt-6 rounded-lg border border-border bg-bg-subtle p-6 text-center">
+      <p class="text-sm text-fg-muted">
         Step {{ current }} of {{ steps.length }} —
-        <span class="font-medium text-(--fg)">{{ steps[current - 1].title }}</span>
+        <span class="font-medium text-fg">{{ steps[current - 1].title }}</span>
       </p>
     </div>
 
     <div class="mt-4 flex items-center justify-between">
       <button
         type="button"
-        class="rounded-md border border-(--border) bg-(--bg) px-4 py-2 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) disabled:cursor-not-allowed disabled:opacity-40"
+        class="rounded-md border border-border bg-bg px-4 py-2 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40"
         :disabled="current === 1"
         @click="prev"
       >
@@ -102,7 +102,7 @@ function prev() {
       </button>
       <button
         type="button"
-        class="rounded-md bg-(--accent) px-4 py-2 text-sm font-medium text-(--accent-fg) transition-colors hover:bg-(--accent-hover) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) disabled:cursor-not-allowed disabled:opacity-40"
+        class="rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-fg transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40"
         :disabled="isLast"
         @click="next"
       >
diff --git a/vue/primitives/src/stepper/index.ts b/vue/primitives/src/forms/stepper/index.ts
similarity index 91%
rename from vue/primitives/src/stepper/index.ts
rename to vue/primitives/src/forms/stepper/index.ts
index 97c6ce6..ea1a1af 100644
--- a/vue/primitives/src/stepper/index.ts
+++ b/vue/primitives/src/forms/stepper/index.ts
@@ -18,7 +18,7 @@ export {
   type StepperDirection,
 } from './context';
 
-export type { StepperRootProps, StepperRootEmits } from './StepperRoot.vue';
+export type { StepperRootProps, StepperRootEmits, StepperRootSlotProps } from './StepperRoot.vue';
 export type { StepperItemProps } from './StepperItem.vue';
 export type { StepperTriggerProps } from './StepperTrigger.vue';
 export type { StepperIndicatorProps } from './StepperIndicator.vue';
diff --git a/vue/primitives/src/switch/Switch.vue b/vue/primitives/src/forms/switch/Switch.vue
similarity index 60%
rename from vue/primitives/src/switch/Switch.vue
rename to vue/primitives/src/forms/switch/Switch.vue
index 88d2b53..1d10965 100644
--- a/vue/primitives/src/switch/Switch.vue
+++ b/vue/primitives/src/forms/switch/Switch.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A control that toggles between an on and off state, mirroring a physical
@@ -10,6 +10,10 @@ import type { PrimitiveProps } from '../primitive';
  * works uncontrolled (`defaultValue`) or controlled with `v-model`. Use it for
  * instant settings toggles where the change applies immediately, as opposed to
  * a checkbox that is typically submitted with a form.
+ *
+ * Pair it with `SwitchThumb` for the moving part: the thumb reads the switch
+ * context and mirrors `data-state`/`data-disabled`, enabling
+ * `data-[state=checked]` thumb animations.
  */
 export interface SwitchProps<T = boolean> extends PrimitiveProps {
 
@@ -25,14 +29,35 @@ export interface SwitchProps<T = boolean> extends PrimitiveProps {
   required?: boolean;
   /** Name for the hidden form input. If provided, a hidden input mirrors state. */
   name?: string;
+  /**
+   * Id of the root element. Anchors an associated `<label for>` and lets the
+   * switch derive an accessible name from that label when no explicit
+   * `aria-label` is supplied.
+   */
+  id?: string;
+  /**
+   * Explicit string submitted with the form when the switch is on. When omitted
+   * the current `truthy`/`falsy` value is serialized automatically, so number,
+   * boolean and object pairs round-trip without extra wiring.
+   */
+  value?: string;
+}
+
+export interface SwitchEmits<T = boolean> {
+  /** Emitted whenever the value changes (also drives `v-model`). */
+  'update:modelValue': [value: T];
 }
 </script>
 
 <script setup lang="ts" generic="T = boolean">
 import type { Ref } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed, ref, toRaw } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
+import { VisuallyHiddenInputBubble } from '../../utilities/visually-hidden';
+import { provideSwitchContext } from './context';
+
+defineOptions({ inheritAttrs: false });
 
 const {
   truthy = true as unknown as T,
@@ -41,10 +66,14 @@ const {
   disabled = false,
   required = false,
   name,
+  id,
+  value: valueProp,
   as = 'button',
 } = defineProps<SwitchProps<T>>();
 
-const { forwardRef } = useForwardExpose();
+defineEmits<SwitchEmits<T>>();
+
+const { forwardRef, currentElement } = useForwardExpose();
 
 const local = ref<T>((defaultValue ?? falsy) as T) as Ref<T>;
 
@@ -58,6 +87,25 @@ const value = defineModel<T>({
 
 const checked = computed<boolean>(() => Object.is(toRaw(value.value), toRaw(truthy)));
 
+const disabledState = computed<boolean>(() => disabled);
+
+// Derive an accessible name from an associated `<label for=id>` when no explicit
+// `aria-label` is supplied. Guarded for SSR (no `document`).
+const ariaLabel = computed<string | undefined>(() => {
+  if (!id || !currentElement.value || globalThis.document === undefined) return undefined;
+  const label = globalThis.document.querySelector(`[for="${id}"]`) as HTMLElement | null;
+  return label?.innerText || undefined;
+});
+
+// The form value: an explicit `value` prop wins, otherwise the active
+// truthy/falsy value is serialized so number/boolean/object pairs round-trip.
+const formValue = computed<string>(() => valueProp ?? serialize(checked.value ? truthy : falsy));
+
+provideSwitchContext({
+  checked,
+  disabled: disabledState,
+});
+
 function toggle() {
   if (disabled) return;
   value.value = checked.value ? falsy : truthy;
@@ -91,10 +139,13 @@ function serialize(v: T): string {
 <template>
   <Primitive
     :ref="forwardRef"
+    v-bind="$attrs"
+    :id="id"
     :as="as"
     :type="as === 'button' ? 'button' : undefined"
     role="switch"
     :tabindex="as === 'button' ? undefined : (disabled ? -1 : 0)"
+    :aria-label="($attrs['aria-label'] as string) || ariaLabel"
     :aria-checked="checked"
     :aria-required="required ? true : undefined"
     :aria-disabled="as === 'button' ? undefined : (disabled ? true : undefined)"
@@ -105,22 +156,13 @@ function serialize(v: T): string {
     @keydown="onKeydown"
   >
     <slot :checked="checked" :value="value" />
-    <input
+    <VisuallyHiddenInputBubble
       v-if="name"
-      type="checkbox"
-      tabindex="-1"
-      aria-hidden="true"
       :name="name"
-      :value="serialize(checked ? truthy : falsy)"
+      :value="formValue"
       :checked="checked"
       :disabled="disabled"
       :required="required"
-      :style="{
-        position: 'absolute',
-        pointerEvents: 'none',
-        opacity: 0,
-        margin: 0,
-      }"
-    >
+    />
   </Primitive>
 </template>
diff --git a/vue/primitives/src/forms/switch/SwitchThumb.vue b/vue/primitives/src/forms/switch/SwitchThumb.vue
new file mode 100644
index 0000000..30931d7
--- /dev/null
+++ b/vue/primitives/src/forms/switch/SwitchThumb.vue
@@ -0,0 +1,38 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The moving part of a switch. Renders alongside the root and mirrors the
+ * root's state through its own `data-state` (`checked`/`unchecked`) and
+ * `data-disabled` attributes, so the thumb can be animated with
+ * `data-[state=checked]` selectors — the most common switch UI pattern. It
+ * holds no state of its own; it reads the switch context provided by the root.
+ */
+export interface SwitchThumbProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { useSwitchContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'span' } = defineProps<SwitchThumbProps>();
+
+const ctx = useSwitchContext();
+
+defineOptions({ inheritAttrs: false });
+
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    v-bind="$attrs"
+    :data-state="ctx.checked.value ? 'checked' : 'unchecked'"
+    :data-disabled="ctx.disabled.value ? '' : undefined"
+  >
+    <slot :checked="ctx.checked.value" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/switch/__test__/Switch.test.ts b/vue/primitives/src/forms/switch/__test__/Switch.test.ts
similarity index 100%
rename from vue/primitives/src/switch/__test__/Switch.test.ts
rename to vue/primitives/src/forms/switch/__test__/Switch.test.ts
diff --git a/vue/primitives/src/forms/switch/__test__/SwitchParity.test.ts b/vue/primitives/src/forms/switch/__test__/SwitchParity.test.ts
new file mode 100644
index 0000000..31e41bd
--- /dev/null
+++ b/vue/primitives/src/forms/switch/__test__/SwitchParity.test.ts
@@ -0,0 +1,221 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { Switch, SwitchThumb, useSwitchContext } from '../index';
+
+describe('switchThumb — context-driven part', () => {
+  it('mirrors the root data-state and toggles with it', async () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      slots: { default: () => h(SwitchThumb) },
+    });
+    const thumb = w.element.querySelector('span') as HTMLElement;
+    expect(thumb).toBeTruthy();
+    expect(thumb.getAttribute('data-state')).toBe('unchecked');
+
+    (w.element as HTMLElement).click();
+    await nextTick();
+    expect(thumb.getAttribute('data-state')).toBe('checked');
+
+    (w.element as HTMLElement).click();
+    await nextTick();
+    expect(thumb.getAttribute('data-state')).toBe('unchecked');
+    w.unmount();
+  });
+
+  it('reflects data-disabled from the root', () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { disabled: true },
+      slots: { default: () => h(SwitchThumb) },
+    });
+    const thumb = w.element.querySelector('span') as HTMLElement;
+    expect(thumb.getAttribute('data-disabled')).toBe('');
+    w.unmount();
+  });
+
+  it('has no data-disabled when enabled', () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      slots: { default: () => h(SwitchThumb) },
+    });
+    const thumb = w.element.querySelector('span') as HTMLElement;
+    expect(thumb.getAttribute('data-disabled')).toBeNull();
+    w.unmount();
+  });
+
+  it('honours a polymorphic `as` host', () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      slots: { default: () => h(SwitchThumb, { as: 'div' }) },
+    });
+    expect(w.element.querySelector('div')).toBeTruthy();
+    w.unmount();
+  });
+
+  it('exposes checked to its default slot', async () => {
+    let captured: unknown;
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { defaultValue: true },
+      slots: {
+        default: () => h(SwitchThumb, null, {
+          default: (scope: { checked: boolean }) => {
+            captured = scope.checked;
+            return '';
+          },
+        }),
+      },
+    });
+    await nextTick();
+    expect(captured).toBe(true);
+    w.unmount();
+  });
+
+  it('throws when used without a switch ancestor', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(() => mount(SwitchThumb, { attachTo: document.body })).toThrow();
+    spy.mockRestore();
+  });
+});
+
+describe('switchContext — public hook', () => {
+  it('provides checked + disabled to descendants', async () => {
+    let ctxChecked: boolean | undefined;
+    const Consumer = defineComponent({
+      setup() {
+        const ctx = useSwitchContext();
+        return () => {
+          ctxChecked = ctx.checked.value;
+          return h('i');
+        };
+      },
+    });
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { defaultValue: true },
+      slots: { default: () => h(Consumer) },
+    });
+    await nextTick();
+    expect(ctxChecked).toBe(true);
+    w.unmount();
+  });
+});
+
+describe('switch — accessible name from <label for>', () => {
+  let label: HTMLLabelElement | undefined;
+  afterEach(() => {
+    label?.remove();
+    label = undefined;
+  });
+
+  it('derives aria-label from an associated label when id is set', async () => {
+    label = document.createElement('label');
+    label.setAttribute('for', 'sw-1');
+    label.textContent = 'Airplane mode';
+    document.body.appendChild(label);
+
+    const w = mount(Switch, { attachTo: document.body, props: { id: 'sw-1' } });
+    await nextTick();
+    expect(w.element.getAttribute('aria-label')).toBe('Airplane mode');
+    expect(w.element.getAttribute('id')).toBe('sw-1');
+    w.unmount();
+  });
+
+  it('an explicit aria-label wins over the derived one', async () => {
+    label = document.createElement('label');
+    label.setAttribute('for', 'sw-2');
+    label.textContent = 'Derived';
+    document.body.appendChild(label);
+
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { id: 'sw-2' },
+      attrs: { 'aria-label': 'Explicit' },
+    });
+    await nextTick();
+    expect(w.element.getAttribute('aria-label')).toBe('Explicit');
+    w.unmount();
+  });
+
+  it('has no aria-label when neither id-label nor explicit label exist', () => {
+    const w = mount(Switch, { attachTo: document.body });
+    expect(w.element.getAttribute('aria-label')).toBeNull();
+    w.unmount();
+  });
+});
+
+describe('switch — hidden form input', () => {
+  it('renders a hidden checkbox input mirroring state', () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { name: 'agree', defaultValue: true },
+    });
+    const input = w.element.querySelector('input[type="checkbox"]') as HTMLInputElement;
+    expect(input).toBeTruthy();
+    expect(input.name).toBe('agree');
+    expect(input.checked).toBe(true);
+    expect(input.value).toBe('true');
+    w.unmount();
+  });
+
+  it('an explicit value prop overrides the serialized form value', () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { name: 'agree', value: 'yes-please', defaultValue: true },
+    });
+    const input = w.element.querySelector('input[type="checkbox"]') as HTMLInputElement;
+    expect(input.value).toBe('yes-please');
+    w.unmount();
+  });
+
+  it('serializes custom string truthy/falsy pairs', async () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { name: 'mode', truthy: 'on', falsy: 'off', defaultValue: 'on' },
+    });
+    expect((w.element.querySelector('input') as HTMLInputElement).value).toBe('on');
+    (w.element as HTMLElement).click();
+    await nextTick();
+    expect((w.element.querySelector('input') as HTMLInputElement).value).toBe('off');
+    w.unmount();
+  });
+
+  it('mirrors disabled and required onto the hidden input', () => {
+    const w = mount(Switch, {
+      attachTo: document.body,
+      props: { name: 'agree', disabled: true, required: true },
+    });
+    const input = w.element.querySelector('input[type="checkbox"]') as HTMLInputElement;
+    expect(input.disabled).toBe(true);
+    expect(input.required).toBe(true);
+    w.unmount();
+  });
+
+  it('dispatches native change events on the hidden input when toggled programmatically', async () => {
+    const model = ref(false);
+    const Harness = defineComponent({
+      setup: () => () => h(Switch, {
+        name: 'agree',
+        modelValue: model.value,
+        'onUpdate:modelValue': (v: unknown) => { model.value = v as boolean; },
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    const input = w.element.querySelector('input[type="checkbox"]') as HTMLInputElement;
+    const onChange = vi.fn();
+    input.addEventListener('change', onChange);
+
+    model.value = true;
+    await nextTick();
+    await nextTick();
+    expect(onChange).toHaveBeenCalled();
+    w.unmount();
+  });
+
+  it('does not render a hidden input without a name', () => {
+    const w = mount(Switch, { attachTo: document.body });
+    expect(w.element.querySelector('input[type="checkbox"]')).toBeNull();
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/forms/switch/context.ts b/vue/primitives/src/forms/switch/context.ts
new file mode 100644
index 0000000..87a43fa
--- /dev/null
+++ b/vue/primitives/src/forms/switch/context.ts
@@ -0,0 +1,19 @@
+import type { ComputedRef } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+/**
+ * Context published by the switch root for descendant parts (e.g. the thumb).
+ * Both fields are derived state, so parts can mirror them into `data-state` /
+ * `data-disabled` without reaching back into the DOM.
+ */
+export interface SwitchContext {
+  /** Whether the switch is currently in its "on" state. */
+  checked: ComputedRef<boolean>;
+  /** Whether interaction is disabled. */
+  disabled: ComputedRef<boolean>;
+}
+
+const ctx = useContextFactory<SwitchContext>('switch');
+
+export const provideSwitchContext = ctx.provide;
+export const useSwitchContext = ctx.inject;
diff --git a/vue/primitives/src/switch/demo.vue b/vue/primitives/src/forms/switch/demo.vue
similarity index 70%
rename from vue/primitives/src/switch/demo.vue
rename to vue/primitives/src/forms/switch/demo.vue
index 17b32dd..7b8b777 100644
--- a/vue/primitives/src/switch/demo.vue
+++ b/vue/primitives/src/forms/switch/demo.vue
@@ -10,8 +10,8 @@ const theme = ref<'dark' | 'light'>('light');
 </script>
 
 <template>
-  <div class="flex w-full max-w-sm flex-col gap-1 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 text-(--fg)">
-    <h3 class="mb-2 text-sm font-semibold text-(--fg)">
+  <div class="demo-card flex w-full max-w-sm flex-col gap-1 p-5 text-fg">
+    <h3 class="mb-2 text-sm font-semibold text-fg">
       Settings
     </h3>
 
@@ -21,12 +21,12 @@ const theme = ref<'dark' | 'light'>('light');
     >
       <span class="flex flex-col">
         <span class="text-sm font-medium">Wi-Fi</span>
-        <span class="text-xs text-(--fg-subtle)">Connect to available networks</span>
+        <span class="text-xs text-fg-subtle">Connect to available networks</span>
       </span>
       <Switch
         id="demo-wifi"
         v-model="wifi"
-        class="relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-0 bg-(--bg-inset) p-0.5 outline-none transition-colors data-[state=checked]:bg-(--accent) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-0 bg-bg-inset p-0.5 outline-none transition-colors data-[state=checked]:bg-accent focus-visible:ring-2 focus-visible:ring-ring"
       >
         <span
           class="pointer-events-none block size-5 rounded-full bg-white shadow-sm transition-transform duration-200 ease-out"
@@ -41,12 +41,12 @@ const theme = ref<'dark' | 'light'>('light');
     >
       <span class="flex flex-col">
         <span class="text-sm font-medium">Notifications</span>
-        <span class="text-xs text-(--fg-subtle)">Push alerts to this device</span>
+        <span class="text-xs text-fg-subtle">Push alerts to this device</span>
       </span>
       <Switch
         id="demo-notify"
         v-model="notifications"
-        class="relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-0 bg-(--bg-inset) p-0.5 outline-none transition-colors data-[state=checked]:bg-(--accent) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-0 bg-bg-inset p-0.5 outline-none transition-colors data-[state=checked]:bg-accent focus-visible:ring-2 focus-visible:ring-ring"
       >
         <span
           class="pointer-events-none block size-5 rounded-full bg-white shadow-sm transition-transform duration-200 ease-out"
@@ -55,17 +55,17 @@ const theme = ref<'dark' | 'light'>('light');
       </Switch>
     </label>
 
-    <div class="flex items-center justify-between gap-4 border-t border-(--border) px-1 pt-3 mt-1">
+    <div class="flex items-center justify-between gap-4 border-t border-border px-1 pt-3 mt-1">
       <span class="flex flex-col">
         <span class="text-sm font-medium">Appearance</span>
-        <span class="text-xs text-(--fg-subtle)">Toggles between two string values</span>
+        <span class="text-xs text-fg-subtle">Toggles between two string values</span>
       </span>
       <Switch
         v-model="theme"
         truthy="dark"
         falsy="light"
         aria-label="Theme"
-        class="relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-0 bg-(--bg-inset) p-0.5 outline-none transition-colors data-[state=checked]:bg-(--fg) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-0 bg-bg-inset p-0.5 outline-none transition-colors data-[state=checked]:bg-fg focus-visible:ring-2 focus-visible:ring-ring"
       >
         <template #default="{ value }">
           <span
@@ -78,12 +78,12 @@ const theme = ref<'dark' | 'light'>('light');
       </Switch>
     </div>
 
-    <p class="mt-3 rounded-lg bg-(--bg-subtle) px-3 py-2 text-xs text-(--fg-muted)">
+    <p class="mt-3 rounded-lg bg-bg-subtle px-3 py-2 text-xs text-fg-muted">
       Wi-Fi is
       <span :class="wifi ? 'text-emerald-600 dark:text-emerald-400' : 'text-red-600 dark:text-red-400'">{{ wifi ? 'on' : 'off' }}</span>,
       notifications are
       <span :class="notifications ? 'text-emerald-600 dark:text-emerald-400' : 'text-red-600 dark:text-red-400'">{{ notifications ? 'on' : 'off' }}</span>,
-      theme is <span class="text-(--fg)">{{ theme }}</span>.
+      theme is <span class="text-fg">{{ theme }}</span>.
     </p>
   </div>
 </template>
diff --git a/vue/primitives/src/forms/switch/index.ts b/vue/primitives/src/forms/switch/index.ts
new file mode 100644
index 0000000..d85a250
--- /dev/null
+++ b/vue/primitives/src/forms/switch/index.ts
@@ -0,0 +1,6 @@
+export { default as Switch } from './Switch.vue';
+export type { SwitchEmits, SwitchProps } from './Switch.vue';
+export { default as SwitchThumb } from './SwitchThumb.vue';
+export type { SwitchThumbProps } from './SwitchThumb.vue';
+export { provideSwitchContext, useSwitchContext } from './context';
+export type { SwitchContext } from './context';
diff --git a/vue/primitives/src/tags-input/TagsInputClear.vue b/vue/primitives/src/forms/tags-input/TagsInputClear.vue
similarity index 90%
rename from vue/primitives/src/tags-input/TagsInputClear.vue
rename to vue/primitives/src/forms/tags-input/TagsInputClear.vue
index 843471e..fc0e495 100644
--- a/vue/primitives/src/tags-input/TagsInputClear.vue
+++ b/vue/primitives/src/forms/tags-input/TagsInputClear.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that removes every tag at once. No-op when the list is already
@@ -9,7 +9,7 @@ export interface TagsInputClearProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useTagsInputContext } from './context';
 
diff --git a/vue/primitives/src/tags-input/TagsInputInput.vue b/vue/primitives/src/forms/tags-input/TagsInputInput.vue
similarity index 86%
rename from vue/primitives/src/tags-input/TagsInputInput.vue
rename to vue/primitives/src/forms/tags-input/TagsInputInput.vue
index f2480ed..b2f2608 100644
--- a/vue/primitives/src/tags-input/TagsInputInput.vue
+++ b/vue/primitives/src/forms/tags-input/TagsInputInput.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The text field where new tags are typed. Commits the current value on Enter,
@@ -18,7 +18,7 @@ export interface TagsInputInputProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { nextTick, onMounted, ref } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useTagsInputContext } from './context';
 
@@ -72,6 +72,16 @@ function onBlur(event: FocusEvent): void {
   ctx.selectedElement.value = undefined;
   if (!ctx.addOnBlur.value) return;
   const target = event.target as HTMLInputElement;
+
+  // When composed with a popup (combobox/listbox), the input owns the popup via
+  // `aria-controls`. A blur whose focus lands inside that popup must NOT commit
+  // the typed text — the clicked option should be added instead.
+  const controlledId = target.getAttribute('aria-controls');
+  if (controlledId) {
+    const relatedTarget = event.relatedTarget as Element | null;
+    if (relatedTarget?.closest(`#${CSS.escape(controlledId)}`)) return;
+  }
+
   if (!target.value) return;
   commitCurrent(target);
 }
@@ -118,6 +128,7 @@ onMounted(() => {
 
 <template>
   <Primitive
+    :id="ctx.id.value"
     :ref="forwardRef"
     :as="as"
     type="text"
diff --git a/vue/primitives/src/tags-input/TagsInputItem.vue b/vue/primitives/src/forms/tags-input/TagsInputItem.vue
similarity index 87%
rename from vue/primitives/src/tags-input/TagsInputItem.vue
rename to vue/primitives/src/forms/tags-input/TagsInputItem.vue
index 61ea167..6deb837 100644
--- a/vue/primitives/src/tags-input/TagsInputItem.vue
+++ b/vue/primitives/src/forms/tags-input/TagsInputItem.vue
@@ -1,5 +1,5 @@
 <script lang="ts" generic="T extends TagValue = string">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { TagValue } from './context';
 
 /**
@@ -15,10 +15,11 @@ export interface TagsInputItemProps<U extends TagValue = string> extends Primiti
 </script>
 
 <script setup lang="ts" generic="T extends TagValue = string">
+import type { Ref } from 'vue';
 import { computed, ref, toRef } from 'vue';
 import { provideTagsInputItemContext, useTagsInputContext } from './context';
-import { Primitive } from '../primitive';
-import { useCollectionInjector } from '../collection';
+import { Primitive } from '../../internal/primitive';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
 
 const { as = 'div', value, disabled = false } = defineProps<TagsInputItemProps<T>>();
@@ -34,7 +35,7 @@ const display = computed(() => ctx.displayValue(value));
 const textId = ref<string>('');
 
 provideTagsInputItemContext({
-  value: toRef(() => value) as any,
+  value: toRef(() => value) as Ref<T>,
   displayValue: display,
   isSelected,
   disabled: isDisabled,
diff --git a/vue/primitives/src/tags-input/TagsInputItemDelete.vue b/vue/primitives/src/forms/tags-input/TagsInputItemDelete.vue
similarity index 75%
rename from vue/primitives/src/tags-input/TagsInputItemDelete.vue
rename to vue/primitives/src/forms/tags-input/TagsInputItemDelete.vue
index 0bec701..63349d3 100644
--- a/vue/primitives/src/tags-input/TagsInputItemDelete.vue
+++ b/vue/primitives/src/forms/tags-input/TagsInputItemDelete.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that removes its parent tag from the list when clicked. Render it
@@ -10,8 +10,9 @@ export interface TagsInputItemDeleteProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import { useTagsInputContext, useTagsInputItemContext } from './context';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
+import { isEqual } from '@robonen/stdlib';
 
 const { as = 'button' } = defineProps<TagsInputItemDeleteProps>();
 
@@ -21,7 +22,9 @@ const { forwardRef } = useForwardExpose();
 
 function onClick(): void {
   if (item.disabled.value) return;
-  const idx = ctx.modelValue.value.indexOf(item.value.value);
+  // Deep equality so object tags (whose stored reference may differ from the
+  // prop's reference) still resolve to the correct index.
+  const idx = ctx.modelValue.value.findIndex(v => isEqual(v, item.value.value));
   if (idx !== -1) ctx.onRemoveValue(idx);
 }
 </script>
diff --git a/vue/primitives/src/tags-input/TagsInputItemText.vue b/vue/primitives/src/forms/tags-input/TagsInputItemText.vue
similarity index 85%
rename from vue/primitives/src/tags-input/TagsInputItemText.vue
rename to vue/primitives/src/forms/tags-input/TagsInputItemText.vue
index 17c6a41..0ca4478 100644
--- a/vue/primitives/src/tags-input/TagsInputItemText.vue
+++ b/vue/primitives/src/forms/tags-input/TagsInputItemText.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The visible label for a tag. Renders the item's display value and exposes an
@@ -9,9 +9,9 @@ export interface TagsInputItemTextProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 import { useTagsInputItemContext } from './context';
 
 const { as = 'span' } = defineProps<TagsInputItemTextProps>();
diff --git a/vue/primitives/src/tags-input/TagsInputRoot.vue b/vue/primitives/src/forms/tags-input/TagsInputRoot.vue
similarity index 72%
rename from vue/primitives/src/tags-input/TagsInputRoot.vue
rename to vue/primitives/src/forms/tags-input/TagsInputRoot.vue
index ff98c9d..9bf749a 100644
--- a/vue/primitives/src/tags-input/TagsInputRoot.vue
+++ b/vue/primitives/src/forms/tags-input/TagsInputRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts" generic="T extends TagValue = string">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { TagValue } from './context';
 
 /**
@@ -33,6 +33,15 @@ export interface TagsInputRootProps<U extends TagValue = string> extends Primiti
   convertValue?: (raw: string) => U;
   /** Render a tag value as text. @default `String(v)` */
   displayValue?: (value: U) => string;
+  /**
+   * Native input name. When set, a visually-hidden mirror input bubbles the tag
+   * list into the owning `<form>` for native submission and validation.
+   */
+  name?: string;
+  /** Mark the field as required for native form validation. */
+  required?: boolean;
+  /** Id forwarded onto the inner `<TagsInputInput>` for `label[for]`/aria wiring. */
+  id?: string;
 }
 
 export interface TagsInputRootEmits<U extends TagValue = string> {
@@ -44,12 +53,14 @@ export interface TagsInputRootEmits<U extends TagValue = string> {
 
 <script setup lang="ts" generic="T extends TagValue = string">
 import { computed, ref, shallowRef, toRef, watch } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import type { Ref } from 'vue';
 import { provideTagsInputContext } from './context';
-import { useCollectionProvider } from '../collection';
-import { useConfig } from '../config-provider';
-import { useForwardExpose } from '@robonen/vue';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useConfig } from '../../utilities/config-provider';
+import { useFocusWithin, useForwardExpose } from '@robonen/vue';
+import { isEqual } from '@robonen/stdlib';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
 
 const {
   as = 'div',
@@ -64,33 +75,44 @@ const {
   max = 0,
   convertValue,
   displayValue,
+  name,
+  required = false,
+  id,
 } = defineProps<TagsInputRootProps<T>>();
 
 const emit = defineEmits<TagsInputRootEmits<T>>();
 
-const model = defineModel<T[]>();
+// Widened controlled contract: a `null`/`undefined` controlled value resolves
+// to `[]` instead of risking a throw on `.length`/iteration downstream.
+const model = defineModel<T[] | null | undefined>();
 
-const { forwardRef } = useForwardExpose();
+function normalize(v: T[] | null | undefined): T[] {
+  return Array.isArray(v) ? v : [];
+}
+
+const { forwardRef, currentElement } = useForwardExpose();
 const config = useConfig();
 const direction = computed(() => dir ?? config.dir.value);
+const { focused } = useFocusWithin(currentElement);
 
 // shallowRef: array is always replaced via commit(), never mutated in place.
-const localValue = shallowRef<T[]>((model.value ?? defaultValue ?? []).slice()) as Ref<T[]>;
+const localValue = shallowRef<T[]>(normalize(model.value ?? defaultValue).slice()) as Ref<T[]>;
 
 watch(model, (v) => {
   if (v === undefined) return;
+  const next = normalize(v);
   const cur = localValue.value;
-  if (v.length === cur.length) {
+  if (next.length === cur.length) {
     let equal = true;
-    for (let i = 0; i < v.length; i++) {
-      if (v[i] !== cur[i]) {
+    for (let i = 0; i < next.length; i++) {
+      if (next[i] !== cur[i]) {
         equal = false;
         break;
       }
     }
     if (equal) return;
   }
-  localValue.value = v.slice();
+  localValue.value = next.slice();
 });
 
 const selectedElement = shallowRef<HTMLElement>();
@@ -106,9 +128,19 @@ function commit(next: T[]): void {
 const convert: (raw: string) => T = convertValue ?? ((raw: string) => raw as unknown as T);
 const display: (value: T) => string = displayValue ?? ((value: T) => String(value));
 
+// An object tag can only be produced through `convertValue`; without it the
+// raw string is cast verbatim, which silently breaks equality and submission.
+function assertConvertibleValues(cur: T[]): void {
+  if (convertValue) return;
+  const sample = cur.length > 0 ? cur[0] : (defaultValue && defaultValue.length > 0 ? defaultValue[0] : undefined);
+  if (sample !== undefined && typeof sample === 'object')
+    throw new Error('TagsInput: provide a `convertValue` function when using object tag values.');
+}
+
 function onAddValue(raw: string): boolean {
   if (disabled) return false;
   const cur = localValue.value;
+  assertConvertibleValues(cur);
   if (max > 0 && cur.length >= max) {
     const payload = convert(raw);
     isInvalidInput.value = true;
@@ -117,7 +149,10 @@ function onAddValue(raw: string): boolean {
   }
   const payload = convert(raw);
   if (!duplicate) {
-    const exists = cur.some(v => v === payload || display(v) === display(payload));
+    // Deep structural equality catches object tags whose reference differs but
+    // whose shape matches; the display-aware check additionally rejects two
+    // distinct values that render to the same label.
+    const exists = cur.some(v => isEqual(v, payload) || display(v) === display(payload));
     if (exists) {
       isInvalidInput.value = true;
       emit('invalid', payload);
@@ -232,6 +267,7 @@ provideTagsInputContext({
   direction,
   max: toRef(() => max),
   duplicate: toRef(() => duplicate),
+  id: toRef(() => id),
   convertValue: convert,
   displayValue: display,
   onAddValue,
@@ -248,8 +284,17 @@ provideTagsInputContext({
       :dir="direction"
       :data-disabled="disabled ? '' : undefined"
       :data-invalid="isInvalidInput ? '' : undefined"
+      :data-focused="focused ? '' : undefined"
     >
       <slot :model-value="localValue" />
+
+      <VisuallyHiddenInput
+        v-if="name"
+        :name="name"
+        :value="localValue"
+        :required="required"
+        :disabled="disabled"
+      />
     </Primitive>
   </CollectionSlot>
 </template>
diff --git a/vue/primitives/src/tags-input/__test__/TagsInput.test.ts b/vue/primitives/src/forms/tags-input/__test__/TagsInput.test.ts
similarity index 53%
rename from vue/primitives/src/tags-input/__test__/TagsInput.test.ts
rename to vue/primitives/src/forms/tags-input/__test__/TagsInput.test.ts
index 7c65316..835d9c4 100644
--- a/vue/primitives/src/tags-input/__test__/TagsInput.test.ts
+++ b/vue/primitives/src/forms/tags-input/__test__/TagsInput.test.ts
@@ -48,6 +48,40 @@ function createTagsInput(rootProps: Record<string, unknown> = {}) {
   );
 }
 
+interface ObjTag { id: string; label: string }
+
+function createObjectTagsInput(rootProps: Record<string, unknown> = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        const tags = ref<ObjTag[]>((rootProps.defaultValue as ObjTag[] | undefined) ?? []);
+        return () => h(
+          TagsInputRoot,
+          {
+            modelValue: tags.value,
+            'onUpdate:modelValue': (v: TagValue[]) => (tags.value = v as ObjTag[]),
+            ...rootProps,
+          },
+          {
+            default: ({ modelValue }: { modelValue: ObjTag[] }) => [
+              ...modelValue.map(tag =>
+                h(TagsInputItem, { key: tag.id, value: tag }, {
+                  default: () => [
+                    h(TagsInputItemText, null, { default: () => tag.label }),
+                    h(TagsInputItemDelete, null, { default: () => '×' }),
+                  ],
+                }),
+              ),
+              h(TagsInputInput),
+            ],
+          },
+        );
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
 function press(el: Element, key: string) {
   el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
 }
@@ -200,6 +234,173 @@ describe('TagsInput', () => {
     w.unmount();
   });
 
+  it('renders a hidden form-bubbling input per tag when name is set', async () => {
+    const w = createTagsInput({ defaultValue: ['a', 'b'], name: 'tags' });
+    await nextTick();
+    const hidden = w.findAll('input').filter(i => i.attributes('name')?.startsWith('tags'));
+    expect(hidden).toHaveLength(2);
+    expect(hidden.map(i => (i.element as HTMLInputElement).name).sort()).toEqual(['tags[0]', 'tags[1]']);
+    w.unmount();
+  });
+
+  it('renders no hidden input when name is omitted', () => {
+    const w = createTagsInput({ defaultValue: ['a'] });
+    const named = w.findAll('input').filter(i => i.attributes('name'));
+    expect(named).toHaveLength(0);
+    w.unmount();
+  });
+
+  it('keeps one hidden input for a required empty list (native required validation)', async () => {
+    const w = createTagsInput({ defaultValue: [], name: 'tags', required: true });
+    await nextTick();
+    const hidden = w.findAll('input').filter(i => i.attributes('name') === 'tags');
+    expect(hidden).toHaveLength(1);
+    expect((hidden[0]!.element as HTMLInputElement).required).toBe(true);
+    w.unmount();
+  });
+
+  it('forwards Root id onto the inner input', () => {
+    const w = createTagsInput({ id: 'my-tags' });
+    expect((w.find('input[type="text"]').element as HTMLInputElement).id).toBe('my-tags');
+    w.unmount();
+  });
+
+  it('reflects focus-within via data-focused on Root', async () => {
+    const w = createTagsInput();
+    const root = w.findComponent(TagsInputRoot as Component).element as HTMLElement;
+    const input = w.find('input').element as HTMLInputElement;
+    expect(root.hasAttribute('data-focused')).toBe(false);
+    input.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+    await nextTick();
+    expect(root.hasAttribute('data-focused')).toBe(true);
+    w.unmount();
+  });
+
+  it('normalizes a null controlled value to an empty list', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          const tags = ref<string[] | null>(null);
+          return () => h(
+            TagsInputRoot,
+            {
+              modelValue: tags.value,
+              'onUpdate:modelValue': (v: TagValue[]) => (tags.value = v as string[]),
+            },
+            {
+              default: ({ modelValue }: { modelValue: string[] }) => [
+                ...modelValue.map(tag => h(TagsInputItem, { key: tag, value: tag }, {
+                  default: () => [h(TagsInputItemText, null, { default: () => tag })],
+                })),
+                h(TagsInputInput),
+              ],
+            },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    expect(w.findAllComponents(TagsInputItem as Component)).toHaveLength(0);
+    const input = w.find('input');
+    (input.element as HTMLInputElement).value = 'x';
+    await input.trigger('keydown', { key: 'Enter' });
+    await nextTick();
+    await nextTick();
+    expect(w.findAllComponents(TagsInputItem as Component)).toHaveLength(1);
+    w.unmount();
+  });
+
+  it('addOnBlur does NOT commit when focus moves into the aria-controls popup', async () => {
+    const popup = document.createElement('div');
+    popup.id = 'tags-popup';
+    const option = document.createElement('button');
+    popup.appendChild(option);
+    document.body.appendChild(popup);
+
+    const w = createTagsInput({ addOnBlur: true });
+    const input = w.find('input').element as HTMLInputElement;
+    input.setAttribute('aria-controls', 'tags-popup');
+    input.value = 'pending';
+    input.dispatchEvent(new FocusEvent('blur', { bubbles: true, relatedTarget: option }));
+    await nextTick();
+    expect(w.findAllComponents(TagsInputItem as Component)).toHaveLength(0);
+
+    document.body.removeChild(popup);
+    w.unmount();
+  });
+
+  it('addOnBlur commits when focus moves outside the aria-controls popup', async () => {
+    const w = createTagsInput({ addOnBlur: true });
+    const input = w.find('input').element as HTMLInputElement;
+    input.setAttribute('aria-controls', 'tags-popup');
+    input.value = 'pending';
+    input.dispatchEvent(new FocusEvent('blur', { bubbles: true, relatedTarget: null }));
+    await nextTick();
+    expect(w.findAllComponents(TagsInputItem as Component)).toHaveLength(1);
+    w.unmount();
+  });
+
+  it('throws on add when object tags are used without convertValue', async () => {
+    const captured: unknown[] = [];
+    const w = mount(
+      defineComponent({
+        setup() {
+          const tags = ref<ObjTag[]>([{ id: 'a', label: 'A' }]);
+          return () => h(
+            TagsInputRoot,
+            {
+              modelValue: tags.value,
+              'onUpdate:modelValue': (v: TagValue[]) => (tags.value = v as ObjTag[]),
+            },
+            { default: () => [h(TagsInputInput)] },
+          );
+        },
+      }),
+      { attachTo: document.body, global: { config: { errorHandler: (err: unknown) => captured.push(err) } } },
+    );
+    const input = w.find('input');
+    (input.element as HTMLInputElement).value = 'b';
+    press(input.element, 'Enter');
+    await nextTick();
+    expect(captured).toHaveLength(1);
+    expect((captured[0] as Error).message).toMatch(/convertValue/);
+    w.unmount();
+  });
+
+  it('deletes an object tag via its delete button using deep equality', async () => {
+    const w = createObjectTagsInput({
+      defaultValue: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }],
+      convertValue: (raw: string) => ({ id: raw, label: raw.toUpperCase() }),
+      displayValue: (v: { label: string }) => v.label,
+    });
+    await nextTick();
+    // Click the first tag's delete button; deep equality resolves its index even
+    // though the stored object is a fresh reference per render.
+    const firstDelete = w.findAll('button').find(b => b.text() === '×')!;
+    await firstDelete.trigger('click');
+    await nextTick();
+    const remaining = w.findAllComponents(TagsInputItem as Component);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0]!.text()).toContain('B');
+    w.unmount();
+  });
+
+  it('rejects structurally-equal object tags as duplicates', async () => {
+    const w = createObjectTagsInput({
+      defaultValue: [{ id: 'a', label: 'A' }],
+      convertValue: (raw: string) => ({ id: raw, label: raw.toUpperCase() }),
+      displayValue: (v: { label: string }) => v.label,
+    });
+    const input = w.find('input');
+    (input.element as HTMLInputElement).value = 'a';
+    await input.trigger('keydown', { key: 'Enter' });
+    await nextTick();
+    await nextTick();
+    expect(w.findAllComponents(TagsInputItem as Component)).toHaveLength(1);
+    expect(w.findComponent(TagsInputRoot as Component).emitted('invalid')).toBeTruthy();
+    w.unmount();
+  });
+
   // Mirrors demo.vue: Clear lives in a footer wrapper that is a deep
   // descendant of Root, not a direct slot child.
   it('Clear injects context when nested deeper inside Root (demo layout)', async () => {
diff --git a/vue/primitives/src/tags-input/context.ts b/vue/primitives/src/forms/tags-input/context.ts
similarity index 86%
rename from vue/primitives/src/tags-input/context.ts
rename to vue/primitives/src/forms/tags-input/context.ts
index 38a477a..33d1d3f 100644
--- a/vue/primitives/src/tags-input/context.ts
+++ b/vue/primitives/src/forms/tags-input/context.ts
@@ -20,6 +20,8 @@ export interface TagsInputContext<T extends TagValue = TagValue> {
   max: Ref<number>;
   /** Allow duplicate tags. */
   duplicate: Ref<boolean>;
+  /** Optional id forwarded onto the `<TagsInputInput>` for label/aria wiring. */
+  id: Ref<string | undefined>;
 
   /** Normalize a raw string into a tag value. */
   convertValue: (raw: string) => T;
@@ -45,9 +47,9 @@ export interface TagsInputItemContext<T extends TagValue = TagValue> {
 export const {
   inject: useTagsInputContext,
   provide: provideTagsInputContext,
-} = useContextFactory<TagsInputContext<any>>('tags-input');
+} = useContextFactory<TagsInputContext<TagValue>>('tags-input');
 
 export const {
   inject: useTagsInputItemContext,
   provide: provideTagsInputItemContext,
-} = useContextFactory<TagsInputItemContext<any>>('tags-input-item');
+} = useContextFactory<TagsInputItemContext<TagValue>>('tags-input-item');
diff --git a/vue/primitives/src/tags-input/demo.vue b/vue/primitives/src/forms/tags-input/demo.vue
similarity index 71%
rename from vue/primitives/src/tags-input/demo.vue
rename to vue/primitives/src/forms/tags-input/demo.vue
index 5fabf5e..c88b9aa 100644
--- a/vue/primitives/src/tags-input/demo.vue
+++ b/vue/primitives/src/forms/tags-input/demo.vue
@@ -21,11 +21,11 @@ function onInvalid() {
 </script>
 
 <template>
-  <div class="w-full max-w-md rounded-xl border border-(--border) bg-(--bg-elevated) p-6 text-(--fg)">
+  <div class="demo-card w-full max-w-md p-6 text-fg">
     <h3 class="text-base font-semibold">
       Invite teammates
     </h3>
-    <p class="mt-1 text-sm text-(--fg-muted)">
+    <p class="mt-1 text-sm text-fg-muted">
       Type an address and press Enter, comma, or paste a list.
     </p>
 
@@ -39,16 +39,16 @@ function onInvalid() {
       class="group"
       @invalid="onInvalid"
     >
-      <div class="mt-4 flex flex-wrap items-center gap-1.5 rounded-lg border border-(--border) bg-(--bg) p-2 transition-colors focus-within:border-(--accent) focus-within:ring-2 focus-within:ring-(--ring) group-data-[invalid]:border-red-500 dark:group-data-[invalid]:border-red-400">
+      <div class="mt-4 flex flex-wrap items-center gap-1.5 rounded-lg border border-border bg-bg p-2 transition-colors focus-within:border-accent focus-within:ring-2 focus-within:ring-ring group-data-[invalid]:border-red-500 dark:group-data-[invalid]:border-red-400">
         <TagsInputItem
           v-for="tag in recipients"
           :key="tag"
           :value="tag"
-          class="flex items-center gap-1 rounded-md bg-(--bg-subtle) py-0.5 pl-2 pr-1 text-sm text-(--fg) data-[state=active]:bg-(--accent) data-[state=active]:text-(--accent-fg)"
+          class="flex items-center gap-1 rounded-md bg-bg-subtle py-0.5 pl-2 pr-1 text-sm text-fg data-[state=active]:bg-accent data-[state=active]:text-accent-fg"
         >
           <TagsInputItemText class="leading-none" />
           <TagsInputItemDelete
-            class="grid h-4 w-4 place-items-center rounded text-(--fg-subtle) transition-colors hover:bg-(--bg-inset) hover:text-(--fg)"
+            class="grid h-4 w-4 place-items-center rounded text-fg-subtle transition-colors hover:bg-bg-inset hover:text-fg"
             aria-label="Remove"
           >
             <svg width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden="true">
@@ -59,21 +59,21 @@ function onInvalid() {
 
         <TagsInputInput
           placeholder="name@company.com"
-          class="min-w-32 flex-1 bg-transparent px-1 py-0.5 text-sm text-(--fg) outline-none placeholder:text-(--fg-subtle)"
+          class="min-w-32 flex-1 bg-transparent px-1 py-0.5 text-sm text-fg outline-none placeholder:text-fg-subtle"
         />
       </div>
 
       <div class="mt-3 flex items-center justify-between text-sm">
         <p
           class="font-medium transition-colors"
-          :class="wasInvalid ? 'text-red-600 dark:text-red-400' : 'text-(--fg-subtle)'"
+          :class="wasInvalid ? 'text-red-600 dark:text-red-400' : 'text-fg-subtle'"
         >
           <span v-if="wasInvalid">Duplicate or limit reached</span>
           <span v-else>{{ recipients.length }} / 5 recipients</span>
         </p>
 
         <TagsInputClear
-          class="rounded-md px-2 py-1 text-(--accent) transition-colors hover:bg-(--bg-inset) disabled:cursor-not-allowed disabled:opacity-50"
+          class="rounded-md px-2 py-1 text-accent transition-colors hover:bg-bg-inset disabled:cursor-not-allowed disabled:opacity-50"
         >
           Clear all
         </TagsInputClear>
diff --git a/vue/primitives/src/tags-input/index.ts b/vue/primitives/src/forms/tags-input/index.ts
similarity index 100%
rename from vue/primitives/src/tags-input/index.ts
rename to vue/primitives/src/forms/tags-input/index.ts
diff --git a/vue/primitives/src/toggle-group/ToggleGroupItem.vue b/vue/primitives/src/forms/toggle-group/ToggleGroupItem.vue
similarity index 62%
rename from vue/primitives/src/toggle-group/ToggleGroupItem.vue
rename to vue/primitives/src/forms/toggle-group/ToggleGroupItem.vue
index 608f37f..9aad36c 100644
--- a/vue/primitives/src/toggle-group/ToggleGroupItem.vue
+++ b/vue/primitives/src/forms/toggle-group/ToggleGroupItem.vue
@@ -1,14 +1,17 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { ToggleGroupValue } from './context';
 /**
  * A single toggle button within a `ToggleGroupRoot`, rendered as a native
  * `<button>`. Clicking or pressing Space toggles its `value` on or off; it
  * reflects its pressed state via `data-state` (`on`/`off`) and participates in
  * the group's roving tab order. Must be used inside a `ToggleGroupRoot`, whose
- * `type` determines whether selecting it deselects its siblings.
+ * `type` determines whether selecting it deselects its siblings. The `value`
+ * may be any structural value (string, number, bigint, `null`, or a plain
+ * object), compared with deep equality.
  */
 export interface ToggleGroupItemProps extends PrimitiveProps {
-  value: string;
+  value: ToggleGroupValue;
   disabled?: boolean;
 
 }
@@ -16,8 +19,8 @@ export interface ToggleGroupItemProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { Primitive } from '../primitive';
-import { useCollectionInjector } from '../collection';
+import { Primitive } from '../../internal/primitive';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
 import { useToggleGroupContext } from './context';
 
@@ -30,14 +33,13 @@ const { forwardRef, currentElement } = useForwardExpose();
 const isDisabled = computed(() => ctx.disabled.value || disabled);
 const isPressed = computed(() => ctx.isPressed(value));
 
-// Roving focus: only one enabled item is the tabstop (first pressed, else first enabled).
+// Roving focus: only one enabled item is the tabstop (first pressed, else first
+// enabled). The tab-stop element is computed once in the Root from reactive
+// pressed state and shared via context, so each item only does an O(1) identity
+// check here instead of re-scanning the whole list and reading DOM attributes.
 const isTabStop = computed(() => {
   if (!ctx.rovingFocus.value || isDisabled.value) return !ctx.rovingFocus.value && !isDisabled.value;
-  const enabled = ctx.items.value.filter(x => !x.hasAttribute('data-disabled'));
-  if (enabled.length === 0) return false;
-  const firstPressed = enabled.find(n => n.getAttribute('aria-pressed') === 'true' || n.getAttribute('aria-checked') === 'true');
-  const target = firstPressed ?? enabled[0];
-  return currentElement.value === target;
+  return currentElement.value === ctx.tabStopElement.value;
 });
 
 function onClick(): void {
@@ -46,12 +48,28 @@ function onClick(): void {
 }
 function onKeyDown(event: KeyboardEvent): void {
   if (!currentElement.value) return;
+  // A native <button> activates on Space/Enter itself; synthesize activation
+  // for non-button hosts so they still toggle from the keyboard.
+  if (as !== 'button' && (event.key === ' ' || event.key === 'Enter')) {
+    event.preventDefault();
+    onClick();
+    return;
+  }
   ctx.onItemKeyDown(event, currentElement.value);
 }
+// Safari does not focus buttons on click; focus on mousedown so the roving
+// tab-stop and :focus-visible styling stay consistent across browsers.
+function onMouseDown(event: MouseEvent): void {
+  if (isDisabled.value) {
+    event.preventDefault();
+    return;
+  }
+  currentElement.value?.focus();
+}
 </script>
 
 <template>
-  <CollectionItem>
+  <CollectionItem :value="value">
     <Primitive
       :as="as"
       :ref="forwardRef"
@@ -66,6 +84,7 @@ function onKeyDown(event: KeyboardEvent): void {
       :disabled="isDisabled || undefined"
       @click="onClick"
       @keydown="onKeyDown"
+      @mousedown="onMouseDown"
     >
       <slot :pressed="isPressed" />
     </Primitive>
diff --git a/vue/primitives/src/forms/toggle-group/ToggleGroupRoot.vue b/vue/primitives/src/forms/toggle-group/ToggleGroupRoot.vue
new file mode 100644
index 0000000..dd6fe23
--- /dev/null
+++ b/vue/primitives/src/forms/toggle-group/ToggleGroupRoot.vue
@@ -0,0 +1,260 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { RovingDirection } from '../../internal/utils/roving-focus';
+import type { ToggleGroupType, ToggleGroupValue } from './context';
+
+/**
+ * A set of two-state toggle buttons that behave as one control, with full
+ * keyboard roving focus (arrow keys move, Home/End jump to ends, PageUp/PageDown
+ * jump to first/last). Set `type` to `'single'` for mutually exclusive options
+ * (like a segmented control) or `'multiple'` to let several be pressed at once
+ * (like a text-formatting bar). When `type` is omitted it is inferred from the
+ * value shape: an array value implies `'multiple'`, otherwise `'single'`.
+ * This is the container and state owner: it tracks the pressed value(s)
+ * (controlled via `v-model` or uncontrolled via `defaultValue`) and provides
+ * context to each `ToggleGroupItem`. With a `name`, the selected value(s) are
+ * also bridged into native form submission. Reach for it to group related
+ * toggles such as text alignment, view modes, or formatting options.
+ */
+export interface ToggleGroupRootProps extends PrimitiveProps {
+  /**
+   * Whether one (`'single'`) or several (`'multiple'`) items can be pressed.
+   * When omitted, inferred from the value shape (array → `'multiple'`).
+   */
+  type?: ToggleGroupType;
+  defaultValue?: ToggleGroupValue | ToggleGroupValue[];
+  disabled?: boolean;
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * Reading direction. When omitted, inherits from a `ConfigProvider` (or LTR).
+   */
+  dir?: RovingDirection;
+  loop?: boolean;
+  rovingFocus?: boolean;
+  /** Native input name for form submission. When set, a hidden input mirrors the value. */
+  name?: string;
+  /** Mark the field as required for native form validation. */
+  required?: boolean;
+}
+
+export interface ToggleGroupRootEmits {
+  valueChange: [value: ToggleGroupValue | ToggleGroupValue[]];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, toRef, watchEffect } from 'vue';
+import { isEqual } from '@robonen/stdlib';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useForwardExpose } from '@robonen/vue';
+import { useDirection } from '../../utilities/config-provider';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
+import { Primitive } from '../../internal/primitive';
+import { provideToggleGroupContext } from './context';
+
+const {
+  type: explicitType,
+  disabled = false,
+  orientation = 'horizontal',
+  dir,
+  loop = true,
+  rovingFocus = true,
+  defaultValue,
+  name,
+  required = false,
+  as = 'div',
+} = defineProps<ToggleGroupRootProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+const emit = defineEmits<ToggleGroupRootEmits>();
+
+const model = defineModel<ToggleGroupValue | ToggleGroupValue[] | undefined>({ default: undefined });
+
+// Resolve the reading direction, inheriting from a ConfigProvider when `dir` is
+// omitted (per-component prop always wins).
+const direction = useDirection(() => dir);
+
+// Infer single/multiple from the value shape when `type` is not explicit:
+// an array value (model or default) implies `'multiple'`, otherwise `'single'`.
+// An explicit `type` always wins.
+const resolvedType = computed<ToggleGroupType>(() => {
+  if (explicitType) return explicitType;
+  const sample = model.value !== undefined ? model.value : defaultValue;
+  return Array.isArray(sample) ? 'multiple' : 'single';
+});
+
+// Dev-only coherence check: an explicit `type` that disagrees with the value
+// shape is surfaced as a warning (the explicit `type` is still honored).
+if (__DEV__) {
+  watchEffect(() => {
+    const sample = model.value !== undefined ? model.value : defaultValue;
+    if (explicitType === undefined || sample === undefined)
+      return;
+
+    const inferred: ToggleGroupType = Array.isArray(sample) ? 'multiple' : 'single';
+    if (explicitType !== inferred) {
+      console.warn(
+        `[ToggleGroup] "type" is "${explicitType}" but the provided value is ${
+          Array.isArray(sample) ? 'an array' : 'not an array'
+        }. Following the explicit "type"; pass a ${
+          explicitType === 'single' ? 'scalar' : 'array'
+        } value to silence this warning.`,
+      );
+    }
+  });
+}
+
+function normalize(v: ToggleGroupValue | ToggleGroupValue[] | undefined): ToggleGroupValue[] {
+  if (v === undefined) return [];
+  if (Array.isArray(v)) return v.slice();
+  return [v];
+}
+
+// Seed the uncontrolled default once; defineModel owns state thereafter.
+if (model.value === undefined && defaultValue !== undefined)
+  model.value = defaultValue;
+
+// Normalized array view of the public model (value | value[] | undefined).
+const localValue = computed<ToggleGroupValue[]>(() => normalize(model.value));
+
+function emitValue(next: ToggleGroupValue[]): void {
+  if (resolvedType.value === 'single') {
+    const v = next.length > 0 ? next[0]! : undefined;
+    model.value = v;
+    emit('valueChange', v ?? '');
+  }
+  else {
+    model.value = next;
+    emit('valueChange', next);
+  }
+}
+
+function toggle(v: ToggleGroupValue): void {
+  if (disabled) return;
+  if (resolvedType.value === 'single') {
+    if (localValue.value.some(x => isEqual(x, v))) emitValue([]);
+    else emitValue([v]);
+  }
+  else if (localValue.value.some(x => isEqual(x, v))) {
+    emitValue(localValue.value.filter(x => !isEqual(x, v)));
+  }
+  else {
+    emitValue([...localValue.value, v]);
+  }
+}
+
+function isPressed(v: ToggleGroupValue): boolean {
+  return localValue.value.some(x => isEqual(x, v));
+}
+
+// DOM-order items via Collection primitive — survives v-for reorders.
+const { getItems, CollectionSlot } = useCollectionProvider<ToggleGroupValue>();
+const items = computed(() => getItems(true).map(i => i.ref));
+
+// The single roving tab stop, computed once per items/value change in the Root
+// (first pressed enabled item, else first enabled item) so each item derives
+// `isTabStop` via an O(1) identity check instead of independently scanning and
+// reading DOM attributes across the whole list (O(N²) on every settle).
+const tabStopElement = computed<HTMLElement | undefined>(() => {
+  const enabled = getItems(false);
+  if (enabled.length === 0) return undefined;
+  for (const item of enabled) {
+    if (item.value !== undefined && isPressed(item.value)) return item.ref;
+  }
+  return enabled[0]!.ref;
+});
+
+function onItemKeyDown(event: KeyboardEvent, el: HTMLElement): void {
+  if (!rovingFocus) return;
+  // Don't hijack focus for modifier-key chords (Ctrl/Meta/Alt navigation, etc.).
+  if (event.ctrlKey || event.metaKey || event.altKey) return;
+
+  const enabled = items.value.filter(x => !x.hasAttribute('data-disabled'));
+  if (enabled.length === 0) return;
+  const current = enabled.indexOf(el);
+
+  // PageUp/PageDown jump to first/last (handled inline; the shared util covers
+  // arrows + Home/End only).
+  if (event.key === 'PageUp') {
+    event.preventDefault();
+    enabled[0]!.focus();
+    return;
+  }
+  if (event.key === 'PageDown') {
+    event.preventDefault();
+    enabled[enabled.length - 1]!.focus();
+    return;
+  }
+
+  const action = rovingKeyToAction(event, { orientation, dir: direction.value, loop });
+  if (!action) return;
+  event.preventDefault();
+  if (action.absolute === 'home') {
+    enabled[0]!.focus();
+    return;
+  }
+  if (action.absolute === 'end') {
+    enabled[enabled.length - 1]!.focus();
+    return;
+  }
+  const nextIdx = resolveNextIndex(current === -1 ? 0 : current, action.delta, enabled.length, loop);
+  enabled[nextIdx]!.focus();
+}
+
+// Whether the group lives inside a real <form>; SSR defaults to bridging so the
+// value still submits server-side. Mirrors the package-wide form-control check.
+const isFormControl = computed(() => {
+  const el = currentElement.value;
+  return typeof document === 'undefined' ? true : (!!el && !!el.closest('form'));
+});
+
+// The value submitted with the form: a scalar in single mode, an array in
+// multiple mode (so VisuallyHiddenInput encodes name[0], name[1], …).
+const submittedValue = computed<ToggleGroupValue | ToggleGroupValue[]>(() =>
+  resolvedType.value === 'single'
+    ? (localValue.value.length > 0 ? localValue.value[0]! : '')
+    : localValue.value,
+);
+
+provideToggleGroupContext({
+  type: resolvedType,
+  value: localValue,
+  toggle,
+  isPressed,
+  orientation: toRef(() => orientation),
+  direction,
+  loop: toRef(() => loop),
+  disabled: toRef(() => disabled),
+  rovingFocus: toRef(() => rovingFocus),
+  items,
+  tabStopElement,
+  onItemKeyDown,
+});
+</script>
+
+<template>
+  <CollectionSlot>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :role="resolvedType === 'single' ? 'radiogroup' : 'group'"
+      :aria-orientation="orientation"
+      :aria-disabled="disabled || undefined"
+      :dir="direction"
+      :data-orientation="orientation"
+      :data-disabled="disabled ? '' : undefined"
+    >
+      <slot :value="localValue" :model-value="model" />
+
+      <VisuallyHiddenInput
+        v-if="isFormControl && name"
+        :name="name"
+        :value="submittedValue"
+        :required="required"
+        :disabled="disabled"
+      />
+    </Primitive>
+  </CollectionSlot>
+</template>
diff --git a/vue/primitives/src/toggle-group/__test__/ToggleGroup.test.ts b/vue/primitives/src/forms/toggle-group/__test__/ToggleGroup.test.ts
similarity index 100%
rename from vue/primitives/src/toggle-group/__test__/ToggleGroup.test.ts
rename to vue/primitives/src/forms/toggle-group/__test__/ToggleGroup.test.ts
diff --git a/vue/primitives/src/forms/toggle-group/__test__/ToggleGroupExtensions.test.ts b/vue/primitives/src/forms/toggle-group/__test__/ToggleGroupExtensions.test.ts
new file mode 100644
index 0000000..bbf028d
--- /dev/null
+++ b/vue/primitives/src/forms/toggle-group/__test__/ToggleGroupExtensions.test.ts
@@ -0,0 +1,327 @@
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { provideConfig } from '../../../utilities/config-provider';
+import { ToggleGroupItem, ToggleGroupRoot } from '../index';
+
+// Minimal declarative config wrapper (the package ships no ConfigProvider
+// component; config is provided via `provideConfig` inside a setup).
+const ConfigProvider = defineComponent({
+  props: { dir: { type: String, default: undefined } },
+  setup(props, { slots }) {
+    provideConfig({ dir: () => props.dir as 'ltr' | 'rtl' | undefined });
+    return () => slots.default?.();
+  },
+});
+
+type AnyVal = unknown;
+
+function press(el: Element, key: string, init: KeyboardEventInit = {}): void {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+}
+
+const mounted: Array<{ unmount: () => void }> = [];
+afterEach(() => {
+  while (mounted.length) mounted.pop()!.unmount();
+});
+
+function mountGroup(opts: Record<string, unknown> = {}, items?: Array<Record<string, unknown>>) {
+  const { modelValue: initial, ...rootProps } = opts;
+  const model = ref<AnyVal>(initial);
+  const list = items ?? [
+    { value: 'a', id: 'a' },
+    { value: 'b', id: 'b' },
+    { value: 'c', id: 'c', disabled: true },
+    { value: 'd', id: 'd' },
+  ];
+  const Harness = defineComponent({
+    setup: () => () => h(ToggleGroupRoot, {
+      modelValue: model.value,
+      'onUpdate:modelValue': (v: AnyVal) => { model.value = v; },
+      ...rootProps,
+    }, {
+      default: () => list.map(p => h(ToggleGroupItem, p, { default: () => String(p.value) })),
+    }),
+  });
+  const wrapper = mount(Harness, { attachTo: document.body });
+  mounted.push(wrapper);
+  return { wrapper, model };
+}
+
+describe('ToggleGroup — type inference', () => {
+  it('infers multiple when defaultValue is an array', async () => {
+    const { wrapper } = mountGroup({ defaultValue: ['a'] });
+    await nextTick();
+    expect(wrapper.element.getAttribute('role')).toBe('group');
+    expect(document.querySelector('#a')!.getAttribute('aria-pressed')).toBe('true');
+    expect(document.querySelector('#a')!.getAttribute('role')).toBeNull();
+  });
+
+  it('infers single when defaultValue is a scalar', async () => {
+    const { wrapper } = mountGroup({ defaultValue: 'a' });
+    await nextTick();
+    expect(wrapper.element.getAttribute('role')).toBe('radiogroup');
+    expect(document.querySelector('#a')!.getAttribute('role')).toBe('radio');
+  });
+
+  it('infers multiple from an array modelValue', async () => {
+    const { wrapper } = mountGroup({ modelValue: ['a', 'b'] });
+    await nextTick();
+    expect(wrapper.element.getAttribute('role')).toBe('group');
+  });
+
+  it('explicit type wins and warns on conflict (dev)', async () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { wrapper } = mountGroup({ type: 'single', defaultValue: ['a'] });
+    await nextTick();
+    // Explicit type honored despite array value.
+    expect(wrapper.element.getAttribute('role')).toBe('radiogroup');
+    expect(spy).toHaveBeenCalled();
+    expect(spy.mock.calls[0]![0]).toContain('ToggleGroup');
+    spy.mockRestore();
+  });
+});
+
+describe('ToggleGroup — deep equality values', () => {
+  it('toggles number values via deep equality', async () => {
+    const { model } = mountGroup({ type: 'single' }, [
+      { value: 1, id: 'n1' },
+      { value: 2, id: 'n2' },
+    ]);
+    await nextTick();
+    const n1 = document.querySelector<HTMLButtonElement>('#n1')!;
+    n1.click();
+    await nextTick();
+    expect(model.value).toBe(1);
+    expect(n1.getAttribute('aria-checked')).toBe('true');
+    n1.click();
+    await nextTick();
+    expect(model.value).toBeUndefined();
+  });
+
+  it('toggles object values structurally (multiple)', async () => {
+    const v1 = { k: 1 };
+    const v2 = { k: 2 };
+    const { model } = mountGroup({ type: 'multiple', modelValue: [] }, [
+      { value: v1, id: 'o1' },
+      { value: v2, id: 'o2' },
+    ]);
+    await nextTick();
+    const o1 = document.querySelector<HTMLButtonElement>('#o1')!;
+    o1.click();
+    await nextTick();
+    expect(model.value).toEqual([{ k: 1 }]);
+    expect(o1.getAttribute('aria-pressed')).toBe('true');
+    // Toggling off the same structural value removes it.
+    o1.click();
+    await nextTick();
+    expect(model.value).toEqual([]);
+  });
+});
+
+describe('ToggleGroup — controlled reset', () => {
+  it('external reset to undefined clears the pressed value', async () => {
+    const { wrapper, model } = mountGroup({ type: 'single', modelValue: 'a' });
+    await nextTick();
+    expect(document.querySelector('#a')!.getAttribute('aria-checked')).toBe('true');
+    model.value = undefined;
+    await wrapper.vm.$nextTick();
+    await nextTick();
+    expect(document.querySelector('#a')!.getAttribute('aria-checked')).toBe('false');
+  });
+});
+
+describe('ToggleGroup — keyboard extensions', () => {
+  it('PageUp jumps to first enabled, PageDown to last enabled', async () => {
+    mountGroup();
+    await nextTick();
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    const b = document.querySelector<HTMLButtonElement>('#b')!;
+    const d = document.querySelector<HTMLButtonElement>('#d')!;
+    b.focus();
+    press(b, 'PageUp');
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+    press(a, 'PageDown');
+    await nextTick();
+    expect(document.activeElement).toBe(d);
+  });
+
+  it('modifier-key chords do not move focus', async () => {
+    mountGroup();
+    await nextTick();
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    a.focus();
+    press(a, 'ArrowRight', { ctrlKey: true });
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+    press(a, 'ArrowRight', { metaKey: true });
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+    press(a, 'ArrowRight', { altKey: true });
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+  });
+
+  it('rovingFocus=false disables arrow navigation', async () => {
+    mountGroup({ rovingFocus: false });
+    await nextTick();
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    a.focus();
+    press(a, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+  });
+});
+
+describe('ToggleGroup — non-button host activation', () => {
+  it('Space/Enter toggle a non-button item', async () => {
+    const { model } = mountGroup({ type: 'single' }, [
+      { value: 'a', id: 'a', as: 'div' },
+      { value: 'b', id: 'b', as: 'div' },
+    ]);
+    await nextTick();
+    const a = document.querySelector<HTMLElement>('#a')!;
+    a.focus();
+    press(a, ' ');
+    await nextTick();
+    expect(model.value).toBe('a');
+    const b = document.querySelector<HTMLElement>('#b')!;
+    b.focus();
+    press(b, 'Enter');
+    await nextTick();
+    expect(model.value).toBe('b');
+  });
+});
+
+describe('ToggleGroup — mousedown focus', () => {
+  it('focuses the item on mousedown', async () => {
+    mountGroup();
+    await nextTick();
+    const b = document.querySelector<HTMLButtonElement>('#b')!;
+    b.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(document.activeElement).toBe(b);
+  });
+
+  it('does not focus a disabled item on mousedown', async () => {
+    mountGroup();
+    await nextTick();
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    a.focus();
+    const c = document.querySelector<HTMLButtonElement>('#c')!;
+    const event = new MouseEvent('mousedown', { bubbles: true, cancelable: true });
+    c.dispatchEvent(event);
+    await nextTick();
+    expect(document.activeElement).not.toBe(c);
+    expect(event.defaultPrevented).toBe(true);
+  });
+});
+
+describe('ToggleGroup — direction inheritance', () => {
+  it('inherits rtl from ConfigProvider (ArrowRight goes backwards)', async () => {
+    const model = ref<AnyVal>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(ConfigProvider, { dir: 'rtl' }, {
+        default: () => h(ToggleGroupRoot, {
+          modelValue: model.value,
+          'onUpdate:modelValue': (v: AnyVal) => { model.value = v; },
+        }, {
+          default: () => [
+            h(ToggleGroupItem, { value: 'a', id: 'a' }, { default: () => 'A' }),
+            h(ToggleGroupItem, { value: 'b', id: 'b' }, { default: () => 'B' }),
+          ],
+        }),
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    mounted.push(wrapper);
+    await nextTick();
+    const a = document.querySelector<HTMLButtonElement>('#a')!;
+    const b = document.querySelector<HTMLButtonElement>('#b')!;
+    expect(wrapper.find('[role="radiogroup"]').attributes('dir')).toBe('rtl');
+    b.focus();
+    // In rtl, ArrowRight moves toward the start (b -> a).
+    press(b, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(a);
+  });
+
+  it('per-component dir prop overrides ConfigProvider', async () => {
+    const model = ref<AnyVal>(undefined);
+    const Harness = defineComponent({
+      setup: () => () => h(ConfigProvider, { dir: 'rtl' }, {
+        default: () => h(ToggleGroupRoot, {
+          dir: 'ltr',
+          modelValue: model.value,
+          'onUpdate:modelValue': (v: AnyVal) => { model.value = v; },
+        }, {
+          default: () => [h(ToggleGroupItem, { value: 'a', id: 'a' }, { default: () => 'A' })],
+        }),
+      }),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    mounted.push(wrapper);
+    await nextTick();
+    expect(wrapper.find('[role="radiogroup"]').attributes('dir')).toBe('ltr');
+  });
+});
+
+describe('ToggleGroup — form integration', () => {
+  it('renders a hidden input inside a form (single)', async () => {
+    const model = ref<AnyVal>('a');
+    const Harness = defineComponent({
+      setup: () => () => h('form', {}, [
+        h(ToggleGroupRoot, {
+          type: 'single',
+          name: 'align',
+          modelValue: model.value,
+          'onUpdate:modelValue': (v: AnyVal) => { model.value = v; },
+        }, {
+          default: () => [
+            h(ToggleGroupItem, { value: 'a', id: 'a' }, { default: () => 'A' }),
+            h(ToggleGroupItem, { value: 'b', id: 'b' }, { default: () => 'B' }),
+          ],
+        }),
+      ]),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    mounted.push(wrapper);
+    await nextTick();
+    const hidden = document.querySelector<HTMLInputElement>('form input[name="align"]');
+    expect(hidden).not.toBeNull();
+    expect(hidden!.value).toBe('a');
+  });
+
+  it('encodes array names for multiple', async () => {
+    const model = ref<AnyVal>(['a', 'b']);
+    const Harness = defineComponent({
+      setup: () => () => h('form', {}, [
+        h(ToggleGroupRoot, {
+          type: 'multiple',
+          name: 'marks',
+          modelValue: model.value,
+          'onUpdate:modelValue': (v: AnyVal) => { model.value = v; },
+        }, {
+          default: () => [
+            h(ToggleGroupItem, { value: 'a', id: 'a' }, { default: () => 'A' }),
+            h(ToggleGroupItem, { value: 'b', id: 'b' }, { default: () => 'B' }),
+          ],
+        }),
+      ]),
+    });
+    const wrapper = mount(Harness, { attachTo: document.body });
+    mounted.push(wrapper);
+    await nextTick();
+    const inputs = Array.from(document.querySelectorAll<HTMLInputElement>('form input[name^="marks"]'));
+    const names = inputs.map(i => i.getAttribute('name')).sort();
+    expect(names).toEqual(['marks[0]', 'marks[1]']);
+    expect(inputs.map(i => i.value).sort()).toEqual(['a', 'b']);
+  });
+
+  it('does not render a hidden input without a name', async () => {
+    mountGroup({ type: 'single', defaultValue: 'a' });
+    await nextTick();
+    expect(document.querySelector('input[type="hidden"]')).toBeNull();
+  });
+});
diff --git a/vue/primitives/src/forms/toggle-group/context.ts b/vue/primitives/src/forms/toggle-group/context.ts
new file mode 100644
index 0000000..d6bb335
--- /dev/null
+++ b/vue/primitives/src/forms/toggle-group/context.ts
@@ -0,0 +1,39 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { RovingDirection, RovingOrientation } from '../../internal/utils/roving-focus';
+import { useContextFactory } from '@robonen/vue';
+
+export type ToggleGroupType = 'single' | 'multiple';
+
+/**
+ * An individual item value. Beyond plain strings, the group accepts numbers,
+ * bigints, `null`, and plain objects, comparing them with structural deep
+ * equality so object/number values toggle correctly. `boolean` is intentionally
+ * excluded so the `modelValue` prop is not coerced by Vue's boolean-prop casting.
+ */
+export type ToggleGroupValue = string | number | bigint | null | Record<string, unknown>;
+
+export interface ToggleGroupContext {
+  type: Ref<ToggleGroupType>;
+  value: Ref<ToggleGroupValue[]>;
+  toggle: (v: ToggleGroupValue) => void;
+  isPressed: (v: ToggleGroupValue) => boolean;
+  orientation: Ref<RovingOrientation>;
+  direction: Ref<RovingDirection>;
+  loop: Ref<boolean>;
+  disabled: Ref<boolean>;
+  rovingFocus: Ref<boolean>;
+  /** DOM-ordered items, sourced from the internal Collection. */
+  items: ComputedRef<HTMLElement[]>;
+  /**
+   * The single enabled item that holds the roving tab stop (first pressed, else
+   * first enabled), computed once in the Root from reactive pressed state. Each
+   * item compares its own element against this to derive `isTabStop` in O(1).
+   */
+  tabStopElement: ComputedRef<HTMLElement | undefined>;
+  onItemKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
+}
+
+const ctx = useContextFactory<ToggleGroupContext>('ToggleGroupContext');
+
+export const provideToggleGroupContext = ctx.provide;
+export const useToggleGroupContext = ctx.inject;
diff --git a/vue/primitives/src/toggle-group/demo.vue b/vue/primitives/src/forms/toggle-group/demo.vue
similarity index 69%
rename from vue/primitives/src/toggle-group/demo.vue
rename to vue/primitives/src/forms/toggle-group/demo.vue
index 18cb933..2552bf2 100644
--- a/vue/primitives/src/toggle-group/demo.vue
+++ b/vue/primitives/src/forms/toggle-group/demo.vue
@@ -22,20 +22,20 @@ const alignments = [
 </script>
 
 <template>
-  <div class="flex flex-col gap-5 p-6 max-w-md bg-(--bg) text-(--fg) border border-(--border) rounded-xl">
+  <div class="flex flex-col gap-5 p-6 max-w-md bg-bg text-fg border border-border rounded-xl">
     <div class="flex flex-col gap-2">
-      <span class="text-xs font-medium text-(--fg-muted)">Text formatting (multiple)</span>
+      <span class="text-xs font-medium text-fg-muted">Text formatting (multiple)</span>
       <ToggleGroupRoot
         v-model="formatting"
         type="multiple"
-        class="inline-flex w-fit gap-1 p-1 rounded-lg bg-(--bg-inset) border border-(--border)"
+        class="inline-flex w-fit gap-1 p-1 rounded-lg bg-bg-inset border border-border"
       >
         <ToggleGroupItem
           v-for="m in marks"
           :key="m.value"
           :value="m.value"
           :title="m.title"
-          class="grid place-items-center w-8 h-8 rounded-md text-sm select-none outline-none transition-colors text-(--fg-muted) hover:bg-(--bg-subtle) data-[state=on]:bg-(--accent) data-[state=on]:text-(--accent-fg) focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="grid place-items-center w-8 h-8 rounded-md text-sm select-none outline-none transition-colors text-fg-muted hover:bg-bg-subtle data-[state=on]:bg-accent data-[state=on]:text-accent-fg focus-visible:ring-2 focus-visible:ring-ring"
           :class="m.class"
         >
           {{ m.label }}
@@ -44,18 +44,18 @@ const alignments = [
     </div>
 
     <div class="flex flex-col gap-2">
-      <span class="text-xs font-medium text-(--fg-muted)">Alignment (single)</span>
+      <span class="text-xs font-medium text-fg-muted">Alignment (single)</span>
       <ToggleGroupRoot
         v-model="align"
         type="single"
-        class="inline-flex w-fit gap-1 p-1 rounded-lg bg-(--bg-inset) border border-(--border)"
+        class="inline-flex w-fit gap-1 p-1 rounded-lg bg-bg-inset border border-border"
       >
         <ToggleGroupItem
           v-for="a in alignments"
           :key="a.value"
           :value="a.value"
           :title="a.title"
-          class="grid place-items-center w-8 h-8 rounded-md text-sm font-medium select-none outline-none transition-colors text-(--fg-muted) hover:bg-(--bg-subtle) data-[state=on]:bg-(--accent) data-[state=on]:text-(--accent-fg) focus-visible:ring-2 focus-visible:ring-(--ring)"
+          class="grid place-items-center w-8 h-8 rounded-md text-sm font-medium select-none outline-none transition-colors text-fg-muted hover:bg-bg-subtle data-[state=on]:bg-accent data-[state=on]:text-accent-fg focus-visible:ring-2 focus-visible:ring-ring"
         >
           {{ a.label }}
         </ToggleGroupItem>
@@ -63,7 +63,7 @@ const alignments = [
     </div>
 
     <p
-      class="px-3 py-6 rounded-lg bg-(--bg-subtle) border border-(--border) text-sm"
+      class="px-3 py-6 rounded-lg bg-bg-subtle border border-border text-sm"
       :class="[
         { 'font-bold': formatting.includes('bold') },
         { 'italic': formatting.includes('italic') },
diff --git a/vue/primitives/src/toggle-group/index.ts b/vue/primitives/src/forms/toggle-group/index.ts
similarity index 81%
rename from vue/primitives/src/toggle-group/index.ts
rename to vue/primitives/src/forms/toggle-group/index.ts
index b553bdc..df3b10e 100644
--- a/vue/primitives/src/toggle-group/index.ts
+++ b/vue/primitives/src/forms/toggle-group/index.ts
@@ -1,5 +1,5 @@
 export { default as ToggleGroupItem } from './ToggleGroupItem.vue';
 export { default as ToggleGroupRoot } from './ToggleGroupRoot.vue';
-export type { ToggleGroupType } from './context';
+export type { ToggleGroupType, ToggleGroupValue } from './context';
 export type { ToggleGroupItemProps } from './ToggleGroupItem.vue';
 export type { ToggleGroupRootEmits, ToggleGroupRootProps } from './ToggleGroupRoot.vue';
diff --git a/vue/primitives/src/forms/toggle/Toggle.vue b/vue/primitives/src/forms/toggle/Toggle.vue
new file mode 100644
index 0000000..6775a93
--- /dev/null
+++ b/vue/primitives/src/forms/toggle/Toggle.vue
@@ -0,0 +1,135 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/** Canonical `data-state` value reflected on the host element. */
+export type ToggleState = 'on' | 'off';
+
+/** Events emitted by `Toggle`. */
+export interface ToggleEmits {
+  /** Fired when the pressed state changes. Backs `v-model:pressed`. */
+  'update:pressed': [pressed: boolean];
+}
+
+/**
+ * A two-state button that can be pressed on or off, like a bold or italic
+ * control in a text editor toolbar. Renders a native `<button>` by default
+ * (handling Space/Enter and the `disabled` attribute for you), exposes
+ * `aria-pressed`, `data-state` (`on`/`off`), and `data-disabled` for styling,
+ * and works uncontrolled (`defaultPressed`) or controlled via `v-model:pressed`.
+ * When rendered as a non-button element it synthesizes keyboard activation and
+ * the appropriate `tabindex`/`aria-disabled`. Provide `name` to mirror the
+ * pressed state into a hidden checkbox so it participates in native form
+ * submission (suppressed automatically when nested in a `ToggleGroup`, which
+ * owns the submitted value). Use it for a single standalone toggle; for a set
+ * of mutually related toggles use `ToggleGroup` instead.
+ */
+export interface ToggleProps extends PrimitiveProps {
+
+  /** Uncontrolled initial pressed state. */
+  defaultPressed?: boolean;
+  /** Disables the toggle. */
+  disabled?: boolean;
+  /**
+   * Name for the hidden form input. When provided (and the toggle lives inside
+   * a `<form>` and is not nested in a `ToggleGroup`), a hidden checkbox mirrors
+   * the pressed state so it is submitted with the owning form.
+   */
+  name?: string;
+  /** Marks the control as required for form submission (native validation). */
+  required?: boolean;
+  /** Value submitted by the hidden form input when pressed. Defaults to `'on'`. */
+  value?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed, ref } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
+import { useToggleGroupContext } from '../toggle-group/context';
+
+const {
+  defaultPressed = false,
+  disabled = false,
+  as = 'button',
+  name,
+  required = false,
+  value = 'on',
+} = defineProps<ToggleProps>();
+
+defineEmits<ToggleEmits>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// A standalone Toggle nested inside a ToggleGroup must not also submit its own
+// value — the group owns the form value. `null` fallback keeps this optional.
+const toggleGroupContext = useToggleGroupContext(null);
+
+const localPressed = ref<boolean>(defaultPressed);
+
+const pressed = defineModel<boolean>('pressed', {
+  default: undefined,
+  get: v => v ?? localPressed.value,
+  set: (v) => {
+    localPressed.value = v;
+    return v;
+  },
+});
+
+const dataState = computed<ToggleState>(() => (pressed.value ? 'on' : 'off'));
+
+// Whether the toggle lives inside a real <form>; SSR defaults to bridging so
+// the value still submits server-side. Mirrors the package-wide check.
+const isFormControl = computed(() => {
+  const el = currentElement.value;
+  return typeof document === 'undefined' ? true : (!!el && !!el.closest('form'));
+});
+
+const renderHiddenInput = computed(() =>
+  !!name && !toggleGroupContext && isFormControl.value);
+
+function toggle() {
+  if (disabled) return;
+  pressed.value = !pressed.value;
+}
+
+function onClick() {
+  toggle();
+}
+
+function onKeydown(event: KeyboardEvent) {
+  // <button> handles Space/Enter natively; synthesize only for non-button hosts.
+  if (as === 'button') return;
+  if (event.key !== ' ' && event.key !== 'Enter') return;
+  event.preventDefault();
+  toggle();
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    :tabindex="as === 'button' ? undefined : (disabled ? -1 : 0)"
+    :aria-pressed="pressed"
+    :aria-disabled="as === 'button' ? undefined : (disabled ? true : undefined)"
+    :data-state="dataState"
+    :data-disabled="disabled ? '' : undefined"
+    :disabled="as === 'button' ? disabled : undefined"
+    @click="onClick"
+    @keydown="onKeydown"
+  >
+    <slot :pressed="pressed" :disabled="disabled" :state="dataState" />
+
+    <VisuallyHiddenInput
+      v-if="renderHiddenInput"
+      :name="name!"
+      :value="pressed ? value : ''"
+      :checked="pressed"
+      :required="required"
+      :disabled="disabled"
+    />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/forms/toggle/__test__/Toggle.test.ts b/vue/primitives/src/forms/toggle/__test__/Toggle.test.ts
new file mode 100644
index 0000000..21208f5
--- /dev/null
+++ b/vue/primitives/src/forms/toggle/__test__/Toggle.test.ts
@@ -0,0 +1,237 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { computed, defineComponent, h, nextTick, ref, shallowRef } from 'vue';
+import { Toggle } from '../index';
+import { provideToggleGroupContext } from '../../toggle-group/context';
+
+describe('Toggle', () => {
+  it('defaults to unpressed and toggles on click', async () => {
+    const wrapper = mount(Toggle);
+    expect(wrapper.attributes('aria-pressed')).toBe('false');
+    expect(wrapper.attributes('data-state')).toBe('off');
+    await wrapper.trigger('click');
+    expect(wrapper.attributes('aria-pressed')).toBe('true');
+    expect(wrapper.attributes('data-state')).toBe('on');
+  });
+
+  it('respects defaultPressed', () => {
+    const wrapper = mount(Toggle, { props: { defaultPressed: true } });
+    expect(wrapper.attributes('aria-pressed')).toBe('true');
+  });
+
+  it('syncs with v-model', async () => {
+    const pressed = ref(false);
+    const wrapper = mount(Toggle, {
+      props: { pressed: pressed.value, 'onUpdate:pressed': (v: boolean) => { pressed.value = v; } },
+    });
+    await wrapper.trigger('click');
+    expect(pressed.value).toBe(true);
+  });
+
+  it('does not toggle when disabled', async () => {
+    const wrapper = mount(Toggle, { props: { disabled: true } });
+    await wrapper.trigger('click');
+    expect(wrapper.attributes('aria-pressed')).toBe('false');
+    expect(wrapper.attributes('data-disabled')).toBe('');
+  });
+
+  it('sets type="button" on button element', () => {
+    const wrapper = mount(Toggle);
+    expect(wrapper.attributes('type')).toBe('button');
+  });
+
+  describe('keyboard activation', () => {
+    it('toggles on Space when as is not a button', async () => {
+      const wrapper = mount(Toggle, { props: { as: 'div' } });
+      await wrapper.trigger('keydown', { key: ' ' });
+      expect(wrapper.attributes('aria-pressed')).toBe('true');
+      await wrapper.trigger('keydown', { key: ' ' });
+      expect(wrapper.attributes('aria-pressed')).toBe('false');
+    });
+
+    it('toggles on Enter when as is not a button', async () => {
+      const wrapper = mount(Toggle, { props: { as: 'div' } });
+      await wrapper.trigger('keydown', { key: 'Enter' });
+      expect(wrapper.attributes('aria-pressed')).toBe('true');
+    });
+
+    it('ignores other keys', async () => {
+      const wrapper = mount(Toggle, { props: { as: 'div' } });
+      await wrapper.trigger('keydown', { key: 'a' });
+      await wrapper.trigger('keydown', { key: 'Tab' });
+      expect(wrapper.attributes('aria-pressed')).toBe('false');
+    });
+
+    it('does not synthesize keyboard toggle on native button', async () => {
+      const wrapper = mount(Toggle);
+      await wrapper.trigger('keydown', { key: ' ' });
+      expect(wrapper.attributes('aria-pressed')).toBe('false');
+    });
+
+    it('does not toggle on keyboard when disabled (as=div)', async () => {
+      const wrapper = mount(Toggle, { props: { as: 'div', disabled: true } });
+      await wrapper.trigger('keydown', { key: ' ' });
+      await wrapper.trigger('keydown', { key: 'Enter' });
+      expect(wrapper.attributes('aria-pressed')).toBe('false');
+    });
+  });
+
+  describe('non-button host (as="div")', () => {
+    it('sets aria-disabled when disabled', () => {
+      const wrapper = mount(Toggle, { props: { as: 'div', disabled: true } });
+      expect(wrapper.attributes('aria-disabled')).toBe('true');
+    });
+
+    it('does not set aria-disabled when enabled', () => {
+      const wrapper = mount(Toggle, { props: { as: 'div' } });
+      expect(wrapper.attributes('aria-disabled')).toBeUndefined();
+    });
+
+    it('has tabindex=0 when enabled, -1 when disabled', () => {
+      const enabled = mount(Toggle, { props: { as: 'div' } });
+      expect(enabled.attributes('tabindex')).toBe('0');
+      const disabled = mount(Toggle, { props: { as: 'div', disabled: true } });
+      expect(disabled.attributes('tabindex')).toBe('-1');
+    });
+
+    it('button host has no synthesized tabindex', () => {
+      const wrapper = mount(Toggle);
+      expect(wrapper.attributes('tabindex')).toBeUndefined();
+    });
+  });
+
+  describe('slot scope', () => {
+    it('exposes pressed, disabled and state', async () => {
+      const seen: Array<{ pressed: boolean; disabled: boolean; state: string }> = [];
+      const wrapper = mount(Toggle, {
+        props: { disabled: false },
+        slots: {
+          default: (scope: { pressed: boolean; disabled: boolean; state: string }) => {
+            seen.push({ pressed: scope.pressed, disabled: scope.disabled, state: scope.state });
+            return scope.state;
+          },
+        },
+      });
+      expect(seen.at(-1)).toEqual({ pressed: false, disabled: false, state: 'off' });
+      await wrapper.trigger('click');
+      expect(seen.at(-1)).toEqual({ pressed: true, disabled: false, state: 'on' });
+      wrapper.unmount();
+    });
+
+    it('exposes disabled=true in scope when disabled', () => {
+      let scopeDisabled: boolean | undefined;
+      const wrapper = mount(Toggle, {
+        props: { disabled: true },
+        slots: {
+          default: (scope: { disabled: boolean }) => {
+            scopeDisabled = scope.disabled;
+            return '';
+          },
+        },
+      });
+      expect(scopeDisabled).toBe(true);
+      wrapper.unmount();
+    });
+  });
+
+  describe('form integration', () => {
+    function mountInForm(props: Record<string, unknown>) {
+      const Host = defineComponent({
+        props: ['toggleProps'],
+        setup(p) {
+          return () => h('form', {}, [h(Toggle, p.toggleProps as Record<string, unknown>)]);
+        },
+      });
+      return mount(Host, { props: { toggleProps: props }, attachTo: document.body });
+    }
+
+    it('renders a hidden checkbox input inside a form when name is set', async () => {
+      const wrapper = mountInForm({ name: 'bold', defaultPressed: true });
+      await nextTick();
+      const input = wrapper.find('input[type="checkbox"]');
+      expect(input.exists()).toBe(true);
+      expect(input.attributes('name')).toBe('bold');
+      expect((input.element as HTMLInputElement).checked).toBe(true);
+      wrapper.unmount();
+    });
+
+    it('does not render a hidden input without a name', () => {
+      const wrapper = mountInForm({ defaultPressed: true });
+      expect(wrapper.find('input').exists()).toBe(false);
+      wrapper.unmount();
+    });
+
+    it('does not render a hidden input outside a form', () => {
+      const wrapper = mount(Toggle, { props: { name: 'bold' }, attachTo: document.body });
+      expect(wrapper.find('input').exists()).toBe(false);
+      wrapper.unmount();
+    });
+
+    it('hidden input reflects unchecked state and required flag', async () => {
+      const wrapper = mountInForm({ name: 'bold', required: true });
+      await nextTick();
+      const input = wrapper.find('input[type="checkbox"]');
+      expect(input.exists()).toBe(true);
+      expect((input.element as HTMLInputElement).checked).toBe(false);
+      expect(input.attributes('required')).toBeDefined();
+      wrapper.unmount();
+    });
+
+    it('submits a custom value when pressed', async () => {
+      const wrapper = mountInForm({ name: 'bold', value: 'enabled' });
+      await nextTick();
+      const toggle = wrapper.findComponent(Toggle);
+      await toggle.trigger('click');
+      const input = wrapper.find('input[type="checkbox"]');
+      expect(input.attributes('value')).toBe('enabled');
+      wrapper.unmount();
+    });
+  });
+
+  describe('toggle-group awareness', () => {
+    it('suppresses its own hidden input when a ToggleGroup context is present', async () => {
+      // A minimal provider stands in for ToggleGroupRoot: Toggle only checks for
+      // the presence of the context to decide whether to suppress its own input.
+      const GroupProvider = defineComponent({
+        setup(_, { slots }) {
+          provideToggleGroupContext({
+            type: ref('single'),
+            value: shallowRef([]),
+            toggle: () => {},
+            isPressed: () => false,
+            orientation: ref('horizontal'),
+            direction: ref('ltr'),
+            loop: ref(true),
+            disabled: ref(false),
+            rovingFocus: ref(true),
+            items: computed(() => []),
+            onItemKeyDown: () => {},
+          });
+          return () => slots.default?.();
+        },
+      });
+      const Host = defineComponent({
+        setup() {
+          return () => h('form', {}, [
+            h(GroupProvider, {}, {
+              default: () => h(Toggle, { name: 'bold', defaultPressed: true }),
+            }),
+          ]);
+        },
+      });
+      const wrapper = mount(Host, { attachTo: document.body });
+      await nextTick();
+      // The nested Toggle must not render its own form input — the group owns it.
+      const namedBold = wrapper.findAll('input').filter(i => i.attributes('name') === 'bold');
+      expect(namedBold.length).toBe(0);
+      wrapper.unmount();
+    });
+  });
+
+  it('exports an emits-typed update:pressed event', async () => {
+    const wrapper = mount(Toggle);
+    await wrapper.trigger('click');
+    expect(wrapper.emitted('update:pressed')).toEqual([[true]]);
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/toggle/demo.vue b/vue/primitives/src/forms/toggle/demo.vue
similarity index 51%
rename from vue/primitives/src/toggle/demo.vue
rename to vue/primitives/src/forms/toggle/demo.vue
index edc6bf6..25302ec 100644
--- a/vue/primitives/src/toggle/demo.vue
+++ b/vue/primitives/src/forms/toggle/demo.vue
@@ -14,43 +14,43 @@ const sampleClass = computed(() => [
 </script>
 
 <template>
-  <div class="flex w-full max-w-sm flex-col gap-3 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 text-(--fg)">
-    <div class="flex items-center gap-1 rounded-lg border border-(--border) bg-(--bg-subtle) p-1">
+  <div class="demo-card flex w-full max-w-sm flex-col gap-3 p-5 text-fg">
+    <div class="flex items-center gap-1 rounded-lg border border-border bg-bg-subtle p-1">
       <Toggle
         v-model:pressed="bold"
         aria-label="Bold"
-        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent font-bold text-(--fg-muted) outline-none transition-colors hover:bg-(--bg-inset) data-[state=on]:bg-(--accent) data-[state=on]:text-(--accent-fg) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent font-bold text-fg-muted outline-none transition-colors hover:bg-bg-inset data-[state=on]:bg-accent data-[state=on]:text-accent-fg focus-visible:ring-2 focus-visible:ring-ring"
       >
         B
       </Toggle>
       <Toggle
         v-model:pressed="italic"
         aria-label="Italic"
-        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent italic text-(--fg-muted) outline-none transition-colors hover:bg-(--bg-inset) data-[state=on]:bg-(--accent) data-[state=on]:text-(--accent-fg) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent italic text-fg-muted outline-none transition-colors hover:bg-bg-inset data-[state=on]:bg-accent data-[state=on]:text-accent-fg focus-visible:ring-2 focus-visible:ring-ring"
       >
         i
       </Toggle>
       <Toggle
         v-model:pressed="underline"
         aria-label="Underline"
-        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent underline text-(--fg-muted) outline-none transition-colors hover:bg-(--bg-inset) data-[state=on]:bg-(--accent) data-[state=on]:text-(--accent-fg) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent underline text-fg-muted outline-none transition-colors hover:bg-bg-inset data-[state=on]:bg-accent data-[state=on]:text-accent-fg focus-visible:ring-2 focus-visible:ring-ring"
       >
         U
       </Toggle>
 
-      <div class="mx-1 h-5 w-px bg-(--border)" />
+      <div class="mx-1 h-5 w-px bg-border" />
 
       <Toggle
         disabled
         aria-label="Strikethrough (unavailable)"
-        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent text-(--fg-muted) line-through outline-none transition-colors hover:bg-(--bg-inset) data-[disabled]:cursor-not-allowed data-[disabled]:opacity-40"
+        class="inline-flex size-8 items-center justify-center rounded-md border-0 bg-transparent text-fg-muted line-through outline-none transition-colors hover:bg-bg-inset data-[disabled]:cursor-not-allowed data-[disabled]:opacity-40"
       >
         S
       </Toggle>
     </div>
 
     <p
-      class="min-h-16 rounded-lg bg-(--bg-subtle) px-3 py-2 text-sm text-(--fg)"
+      class="min-h-16 rounded-lg bg-bg-subtle px-3 py-2 text-sm text-fg"
       :class="sampleClass"
     >
       The quick brown fox jumps over the lazy dog.
diff --git a/vue/primitives/src/forms/toggle/index.ts b/vue/primitives/src/forms/toggle/index.ts
new file mode 100644
index 0000000..3cb12a8
--- /dev/null
+++ b/vue/primitives/src/forms/toggle/index.ts
@@ -0,0 +1,2 @@
+export { default as Toggle } from './Toggle.vue';
+export type { ToggleEmits, ToggleProps, ToggleState } from './Toggle.vue';
diff --git a/vue/primitives/src/index.ts b/vue/primitives/src/index.ts
index 4b002a0..490fe96 100644
--- a/vue/primitives/src/index.ts
+++ b/vue/primitives/src/index.ts
@@ -1,58 +1,124 @@
-export * from './config-provider';
-export * from './primitive';
-export * from './presence';
-export * from './collection';
-export * from './roving-focus';
-export * from './pagination';
-export * from './focus-scope';
-export * from './visually-hidden';
-export * from './teleport';
-export * from './dismissable-layer';
-export * from './dialog';
-export * from './alert-dialog';
-export * from './drawer';
-export * from './scroll-area';
-export * from './separator';
-export * from './label';
-export * from './aspect-ratio';
-export * from './toggle';
-export * from './switch';
-export * from './progress';
-export * from './collapsible';
-export * from './avatar';
-export * from './slider';
-export * from './checkbox';
-export * from './toolbar';
-export * from './radio-group';
-export * from './toggle-group';
-export * from './number-field';
-export * from './pin-input';
-export * from './tabs';
-export * from './accordion';
-export * from './popper';
-export * from './hover-card';
-export * from './popover';
-export * from './tooltip';
-export * from './tree';
-export * from './stepper';
-export * from './editable';
-export * from './tags-input';
-export * from './listbox';
+export * from './utilities/config-provider';
+export * from './internal/primitive';
+export * from './utilities/presence';
+export * from './utilities/collection';
+export * from './utilities/roving-focus';
+export * from './navigation/pagination';
+export * from './utilities/focus-scope';
+export * from './utilities/visually-hidden';
+export * from './utilities/teleport';
+export * from './utilities/dismissable-layer';
+export * from './overlays/dialog';
+export * from './overlays/alert-dialog';
+export * from './overlays/drawer';
+export * from './display/scroll-area';
+export * from './display/separator';
+export * from './forms/label';
+export * from './display/aspect-ratio';
+export * from './forms/toggle';
+export * from './forms/switch';
+export * from './display/progress';
+export * from './disclosure/collapsible';
+export * from './display/avatar';
+export * from './forms/slider';
+export * from './forms/checkbox';
+export * from './menus/toolbar';
+export * from './forms/radio-group';
+export * from './forms/toggle-group';
+export * from './forms/number-field';
+export * from './forms/pin-input';
+export * from './disclosure/tabs';
+export * from './disclosure/accordion';
+export * from './overlays/popper';
+export * from './overlays/hover-card';
+export * from './overlays/popover';
+export * from './overlays/tooltip';
+export * from './navigation/tree';
+export * from './forms/stepper';
+export * from './forms/editable';
+export * from './forms/tags-input';
+export * from './selection/listbox';
 
-export * from './menu';
-export * from './dropdown-menu';
-export * from './context-menu';
-export * from './menubar';
+export * from './menus/menu';
+export * from './menus/dropdown-menu';
+export * from './menus/context-menu';
+export * from './menus/menubar';
 
-export * from './select';
-export * from './toast';
+export * from './selection/select';
+export * from './feedback/toast';
 
-export * from './combobox';
-export * from './navigation-menu';
+export * from './selection/combobox';
+export * from './menus/navigation-menu';
 
-export * from './command';
+export * from './menus/command';
 
-export * from './calendar';
-export * from './date-picker';
+export * from './display/calendar';
+export * from './display/date-picker';
 
-export * from './qr-code';
+export * from './display/qr-code';
+
+export * from './canvas/flow';
+
+// ── Media-editor infrastructure (composable-only leaves) ──────────────────────
+export * from './internal/scale';
+export * from './internal/spline';
+export * from './internal/color';
+export * from './internal/pointer-drag';
+export * from './internal/snapping';
+
+// zoom-pan shares several generic names with `flow` (clampZoom, zoomAtPointer,
+// wheelToZoomFactor, fitViewTransform, useViewportApi) and re-exports the
+// flow-origin geometry types (Viewport/Rect/XYPosition/Dimensions). Those stay
+// available on the `@robonen/primitives/zoom-pan` subpath; the root barrel
+// re-exports only zoom-pan's own unambiguous surface (flow claimed those names
+// first). See zoom-pan/index.ts for the full module surface.
+export {
+  ViewportRoot,
+  ViewportSurface,
+  ViewportContent,
+  provideViewportContext,
+  useViewportContext,
+  useZoomPan,
+  useInteractionState,
+  clampViewport,
+  screenToContent,
+  contentToScreen,
+  measureContentRect,
+} from './canvas/zoom-pan';
+export type {
+  UseZoomPanReturn,
+  FitParams,
+  FitViewportOptions,
+  SurfaceOrigin,
+  SurfaceRect,
+  TranslateExtent,
+  ViewportApi,
+  ViewportConstraints,
+  ViewportContext,
+  ViewportRootProps,
+  ZoomPanAxis,
+  ZoomPanOptions,
+} from './canvas/zoom-pan';
+
+// ── Media-editor components (Phase 2: standalone surfaces) ────────────────────
+export * from './canvas/compare-slider';
+export * from './canvas/time-ruler';
+export * from './canvas/canvas-stage';
+export * from './canvas/angle-dial';
+export * from './color/color-area';
+export * from './color/hue-slider';
+export * from './color/alpha-slider';
+export * from './color/color-field';
+
+// ── Media-editor components (Phase 3: overlays + plots) ───────────────────────
+export * from './canvas/curve-editor';
+export * from './canvas/waveform';
+export * from './canvas/transform-box';
+export * from './canvas/crop';
+export * from './canvas/gradient-editor';
+export * from './canvas/histogram';
+export * from './canvas/levels';
+
+// ── Media-editor composites (Phase 4) ─────────────────────────────────────────
+export * from './canvas/timeline';
+export * from './canvas/keyframe-track';
diff --git a/vue/primitives/src/internal/color/__test__/color.test.ts b/vue/primitives/src/internal/color/__test__/color.test.ts
new file mode 100644
index 0000000..85018b7
--- /dev/null
+++ b/vue/primitives/src/internal/color/__test__/color.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest';
+import {
+  contrastRatio,
+  formatHsva,
+  hexToRgba,
+  hslToHsv,
+  hsvToHsl,
+  hsvToRgb,
+  isLight,
+  parseColor,
+  rgbToHex,
+  rgbToHsv,
+} from '../index';
+import type { RGB } from '../index';
+
+const BLACK: RGB = { r: 0, g: 0, b: 0 };
+const WHITE: RGB = { r: 255, g: 255, b: 255 };
+
+describe('hsvToRgb known conversions', () => {
+  it('maps primary hues to pure channels', () => {
+    expect(hsvToRgb({ h: 0, s: 1, v: 1 })).toEqual({ r: 255, g: 0, b: 0 });
+    expect(hsvToRgb({ h: 120, s: 1, v: 1 })).toEqual({ r: 0, g: 255, b: 0 });
+    expect(hsvToRgb({ h: 240, s: 1, v: 1 })).toEqual({ r: 0, g: 0, b: 255 });
+  });
+
+  it('maps achromatic extremes to white and black', () => {
+    expect(hsvToRgb({ h: 0, s: 0, v: 1 })).toEqual({ r: 255, g: 255, b: 255 });
+    expect(hsvToRgb({ h: 0, s: 0, v: 0 })).toEqual({ r: 0, g: 0, b: 0 });
+    expect(hsvToRgb({ h: 200, s: 1, v: 0 })).toEqual({ r: 0, g: 0, b: 0 });
+  });
+});
+
+describe('rgb/hsv round-trip stability', () => {
+  const samples: RGB[] = [
+    { r: 255, g: 0, b: 128 },
+    { r: 12, g: 200, b: 87 },
+    { r: 64, g: 64, b: 64 },
+    { r: 255, g: 255, b: 255 },
+    { r: 0, g: 0, b: 0 },
+    { r: 33, g: 150, b: 243 },
+  ];
+
+  it('survives rgbToHsv -> hsvToRgb within +/-1 per channel', () => {
+    for (const rgb of samples) {
+      const back = hsvToRgb(rgbToHsv(rgb));
+      expect(Math.abs(back.r - rgb.r)).toBeLessThanOrEqual(1);
+      expect(Math.abs(back.g - rgb.g)).toBeLessThanOrEqual(1);
+      expect(Math.abs(back.b - rgb.b)).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('survives hsvToHsl -> hslToHsv within tolerance', () => {
+    const hsv = { h: 210, s: 0.6, v: 0.8 };
+    const back = hslToHsv(hsvToHsl(hsv));
+    expect(back.h).toBeCloseTo(hsv.h, 5);
+    expect(back.s).toBeCloseTo(hsv.s, 5);
+    expect(back.v).toBeCloseTo(hsv.v, 5);
+  });
+});
+
+describe('hex conversions', () => {
+  it('serializes rgb to lowercase hex', () => {
+    expect(rgbToHex({ r: 255, g: 0, b: 128 })).toBe('#ff0080');
+    expect(rgbToHex({ r: 255, g: 0, b: 128 }, 0.5)).toBe('#ff008080');
+  });
+
+  it('parses 6 and 8 digit hex', () => {
+    expect(hexToRgba('#ff0080')).toEqual({ r: 255, g: 0, b: 128, a: 1 });
+    const withAlpha = hexToRgba('#ff008080');
+    expect(withAlpha).not.toBeNull();
+    expect(withAlpha!.a).toBeCloseTo(0.5, 2);
+  });
+
+  it('parses shorthand hex', () => {
+    expect(hexToRgba('#f00')).toEqual({ r: 255, g: 0, b: 0, a: 1 });
+  });
+
+  it('returns null on invalid hex', () => {
+    expect(hexToRgba('bad')).toBeNull();
+    expect(hexToRgba('#12')).toBeNull();
+  });
+});
+
+describe('parseColor', () => {
+  it('parses shorthand hex to canonical HSVA', () => {
+    const hsva = parseColor('#f00');
+    expect(hsva).not.toBeNull();
+    expect(hsva!.h).toBeCloseTo(0, 5);
+    expect(hsva!.s).toBeCloseTo(1, 5);
+    expect(hsva!.v).toBeCloseTo(1, 5);
+    expect(hsva!.a).toBe(1);
+  });
+
+  it('parses rgb() to canonical hue', () => {
+    const hsva = parseColor('rgb(0,255,0)');
+    expect(hsva).not.toBeNull();
+    expect(hsva!.h).toBeCloseTo(120, 5);
+  });
+
+  it('parses rgba() with alpha', () => {
+    const hsva = parseColor('rgba(0, 0, 255, 0.5)');
+    expect(hsva).not.toBeNull();
+    expect(hsva!.h).toBeCloseTo(240, 5);
+    expect(hsva!.a).toBe(0.5);
+  });
+
+  it('parses hsl()/hsla()', () => {
+    const hsva = parseColor('hsl(120, 100%, 50%)');
+    expect(hsva).not.toBeNull();
+    expect(hsva!.h).toBeCloseTo(120, 5);
+    expect(hsva!.s).toBeCloseTo(1, 5);
+    expect(hsva!.v).toBeCloseTo(1, 5);
+  });
+
+  it('returns null on nonsense', () => {
+    expect(parseColor('nonsense')).toBeNull();
+    expect(parseColor('rgb(a, b, c)')).toBeNull();
+  });
+});
+
+describe('formatHsva', () => {
+  const red = parseColor('#ff0000')!;
+
+  it('formats across CSS formats', () => {
+    expect(formatHsva(red, 'hex')).toBe('#ff0000');
+    expect(formatHsva({ ...red, a: 0.5 }, 'hex8')).toBe('#ff000080');
+    expect(formatHsva(red, 'rgb')).toBe('rgb(255, 0, 0)');
+    expect(formatHsva({ ...red, a: 0.5 }, 'rgba')).toBe('rgba(255, 0, 0, 0.5)');
+    expect(formatHsva(red, 'hsl')).toBe('hsl(0, 100%, 50%)');
+    expect(formatHsva({ ...red, a: 0.5 }, 'hsla')).toBe('hsla(0, 100%, 50%, 0.5)');
+  });
+});
+
+describe('wcag helpers', () => {
+  it('computes max contrast for black/white', () => {
+    expect(contrastRatio(WHITE, BLACK)).toBeCloseTo(21, 1);
+  });
+
+  it('detects light vs dark colors', () => {
+    expect(isLight(WHITE)).toBe(true);
+    expect(isLight(BLACK)).toBe(false);
+  });
+});
diff --git a/vue/primitives/src/internal/color/convert.ts b/vue/primitives/src/internal/color/convert.ts
new file mode 100644
index 0000000..a8e682f
--- /dev/null
+++ b/vue/primitives/src/internal/color/convert.ts
@@ -0,0 +1,235 @@
+import type { HSL, HSV, RGB, RGBA } from './types';
+
+/**
+ * Convert an {@link HSV} color to {@link RGB} (channels rounded to integers).
+ */
+export function hsvToRgb(hsv: HSV): RGB {
+  const h = ((hsv.h % 360) + 360) % 360;
+  const s = hsv.s;
+  const v = hsv.v;
+
+  const c = v * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = v - c;
+
+  // Map the hue sector to chroma-relative r/g/b locals inline (no tuple alloc).
+  let r: number;
+  let g: number;
+  let b: number;
+  if (h < 60) {
+    r = c;
+    g = x;
+    b = 0;
+  }
+  else if (h < 120) {
+    r = x;
+    g = c;
+    b = 0;
+  }
+  else if (h < 180) {
+    r = 0;
+    g = c;
+    b = x;
+  }
+  else if (h < 240) {
+    r = 0;
+    g = x;
+    b = c;
+  }
+  else if (h < 300) {
+    r = x;
+    g = 0;
+    b = c;
+  }
+  else {
+    r = c;
+    g = 0;
+    b = x;
+  }
+
+  return {
+    r: Math.round((r + m) * 255),
+    g: Math.round((g + m) * 255),
+    b: Math.round((b + m) * 255),
+  };
+}
+
+/**
+ * Convert an {@link RGB} color to {@link HSV} (`h`/`s`/`v` kept as floats).
+ */
+export function rgbToHsv(rgb: RGB): HSV {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+
+  let h = 0;
+  if (delta !== 0) {
+    if (max === r) {
+      h = 60 * (((g - b) / delta) % 6);
+    }
+    else if (max === g) {
+      h = 60 * ((b - r) / delta + 2);
+    }
+    else {
+      h = 60 * ((r - g) / delta + 4);
+    }
+  }
+  if (h < 0) h += 360;
+
+  const s = max === 0 ? 0 : delta / max;
+  const v = max;
+
+  return { h, s, v };
+}
+
+/**
+ * Convert an {@link RGB} color to {@link HSL} (`h`/`s`/`l` kept as floats).
+ */
+export function rgbToHsl(rgb: RGB): HSL {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+
+  const l = (max + min) / 2;
+
+  let h = 0;
+  let s = 0;
+  if (delta !== 0) {
+    s = delta / (1 - Math.abs(2 * l - 1));
+    if (max === r) {
+      h = 60 * (((g - b) / delta) % 6);
+    }
+    else if (max === g) {
+      h = 60 * ((b - r) / delta + 2);
+    }
+    else {
+      h = 60 * ((r - g) / delta + 4);
+    }
+  }
+  if (h < 0) h += 360;
+
+  return { h, s, l };
+}
+
+/**
+ * Convert an {@link HSL} color to {@link RGB} (channels rounded to integers).
+ */
+export function hslToRgb(hsl: HSL): RGB {
+  const h = ((hsl.h % 360) + 360) % 360;
+  const s = hsl.s;
+  const l = hsl.l;
+
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+
+  // Map the hue sector to chroma-relative r/g/b locals inline (no tuple alloc).
+  let r: number;
+  let g: number;
+  let b: number;
+  if (h < 60) {
+    r = c;
+    g = x;
+    b = 0;
+  }
+  else if (h < 120) {
+    r = x;
+    g = c;
+    b = 0;
+  }
+  else if (h < 180) {
+    r = 0;
+    g = c;
+    b = x;
+  }
+  else if (h < 240) {
+    r = 0;
+    g = x;
+    b = c;
+  }
+  else if (h < 300) {
+    r = x;
+    g = 0;
+    b = c;
+  }
+  else {
+    r = c;
+    g = 0;
+    b = x;
+  }
+
+  return {
+    r: Math.round((r + m) * 255),
+    g: Math.round((g + m) * 255),
+    b: Math.round((b + m) * 255),
+  };
+}
+
+/**
+ * Convert an {@link HSV} color directly to {@link HSL} without an RGB round-trip.
+ */
+export function hsvToHsl(hsv: HSV): HSL {
+  const l = hsv.v * (1 - hsv.s / 2);
+  let s = 0;
+  if (l !== 0 && l !== 1) {
+    s = (hsv.v - l) / Math.min(l, 1 - l);
+  }
+  return { h: hsv.h, s, l };
+}
+
+/**
+ * Convert an {@link HSL} color directly to {@link HSV} without an RGB round-trip.
+ */
+export function hslToHsv(hsl: HSL): HSV {
+  const v = hsl.l + hsl.s * Math.min(hsl.l, 1 - hsl.l);
+  let s = 0;
+  if (v !== 0) {
+    s = 2 * (1 - hsl.l / v);
+  }
+  return { h: hsl.h, s, v };
+}
+
+/** Convert a single `0–255` channel to a two-character lowercase hex pair. */
+function channelToHex(value: number): string {
+  return Math.round(value).toString(16).padStart(2, '0');
+}
+
+/**
+ * Convert an {@link RGB} color to a `#rrggbb` hex string, or `#rrggbbaa` when an
+ * alpha (`0–1`) is provided via `withAlpha`.
+ */
+export function rgbToHex(rgb: RGB, withAlpha?: number): string {
+  const base = `#${channelToHex(rgb.r)}${channelToHex(rgb.g)}${channelToHex(rgb.b)}`;
+  if (withAlpha === undefined) return base;
+  return base + channelToHex(Math.round(withAlpha * 255));
+}
+
+/**
+ * Parse a `#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa` hex string into {@link RGBA},
+ * returning `null` when the input is not a valid hex color.
+ */
+export function hexToRgba(hex: string): RGBA | null {
+  const match = /^#([0-9a-f]{3,8})$/i.exec(hex.trim());
+  if (!match) return null;
+
+  let value = match[1]!;
+  if (value.length === 3 || value.length === 4) {
+    value = value.split('').map(c => c + c).join('');
+  }
+  if (value.length !== 6 && value.length !== 8) return null;
+
+  const r = Number.parseInt(value.slice(0, 2), 16);
+  const g = Number.parseInt(value.slice(2, 4), 16);
+  const b = Number.parseInt(value.slice(4, 6), 16);
+  const a = value.length === 8 ? Number.parseInt(value.slice(6, 8), 16) / 255 : 1;
+
+  return { r, g, b, a };
+}
diff --git a/vue/primitives/src/internal/color/index.ts b/vue/primitives/src/internal/color/index.ts
new file mode 100644
index 0000000..f29f30e
--- /dev/null
+++ b/vue/primitives/src/internal/color/index.ts
@@ -0,0 +1,13 @@
+export {
+  hexToRgba,
+  hslToHsv,
+  hslToRgb,
+  hsvToHsl,
+  hsvToRgb,
+  rgbToHex,
+  rgbToHsl,
+  rgbToHsv,
+} from './convert';
+export { formatHsva, parseColor } from './parse';
+export type { HSL, HSLA, HSV, HSVA, RGB, RGBA } from './types';
+export { clampChannel, contrastRatio, hsvaToCss, isLight, relativeLuminance } from './utils';
diff --git a/vue/primitives/src/internal/color/parse.ts b/vue/primitives/src/internal/color/parse.ts
new file mode 100644
index 0000000..dcd1889
--- /dev/null
+++ b/vue/primitives/src/internal/color/parse.ts
@@ -0,0 +1,68 @@
+import { hexToRgba, hslToHsv, hsvToHsl, hsvToRgb, rgbToHex, rgbToHsv } from './convert';
+import type { HSVA } from './types';
+
+const RGB_RE = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/i;
+const HSL_RE = /^hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*(?:,\s*([\d.]+)\s*)?\)$/i;
+
+/**
+ * Parse a hex (`#rgb`/`#rrggbb`/`#rrggbbaa`), `rgb()`/`rgba()` or
+ * `hsl()`/`hsla()` color string into canonical {@link HSVA}, or `null` when the
+ * input cannot be parsed.
+ */
+export function parseColor(input: string): HSVA | null {
+  const value = input.trim();
+
+  const hexMatch = hexToRgba(value);
+  if (hexMatch) {
+    return { ...rgbToHsv(hexMatch), a: hexMatch.a };
+  }
+
+  const rgbMatch = RGB_RE.exec(value);
+  if (rgbMatch) {
+    const r = Number(rgbMatch[1]);
+    const g = Number(rgbMatch[2]);
+    const b = Number(rgbMatch[3]);
+    const a = rgbMatch[4] === undefined ? 1 : Number(rgbMatch[4]);
+    if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) || Number.isNaN(a)) return null;
+    return { ...rgbToHsv({ r, g, b }), a };
+  }
+
+  const hslMatch = HSL_RE.exec(value);
+  if (hslMatch) {
+    const h = Number(hslMatch[1]);
+    const s = Number(hslMatch[2]) / 100;
+    const l = Number(hslMatch[3]) / 100;
+    const a = hslMatch[4] === undefined ? 1 : Number(hslMatch[4]);
+    if (Number.isNaN(h) || Number.isNaN(s) || Number.isNaN(l) || Number.isNaN(a)) return null;
+    return { ...hslToHsv({ h, s, l }), a };
+  }
+
+  return null;
+}
+
+/**
+ * Format a canonical {@link HSVA} color as a string in the requested CSS
+ * `format`.
+ */
+export function formatHsva(hsva: HSVA, format: 'hex' | 'hex8' | 'rgb' | 'rgba' | 'hsl' | 'hsla'): string {
+  const rgb = hsvToRgb(hsva);
+
+  switch (format) {
+    case 'hex':
+      return rgbToHex(rgb);
+    case 'hex8':
+      return rgbToHex(rgb, hsva.a);
+    case 'rgb':
+      return `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`;
+    case 'rgba':
+      return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${hsva.a})`;
+    case 'hsl': {
+      const hsl = hsvToHsl(hsva);
+      return `hsl(${Math.round(hsl.h)}, ${Math.round(hsl.s * 100)}%, ${Math.round(hsl.l * 100)}%)`;
+    }
+    case 'hsla': {
+      const hsl = hsvToHsl(hsva);
+      return `hsla(${Math.round(hsl.h)}, ${Math.round(hsl.s * 100)}%, ${Math.round(hsl.l * 100)}%, ${hsva.a})`;
+    }
+  }
+}
diff --git a/vue/primitives/src/internal/color/types.ts b/vue/primitives/src/internal/color/types.ts
new file mode 100644
index 0000000..65395b1
--- /dev/null
+++ b/vue/primitives/src/internal/color/types.ts
@@ -0,0 +1,35 @@
+/** Red/green/blue color with channels in the `0–255` range. */
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/** {@link RGB} extended with an alpha channel in the `0–1` range. */
+export interface RGBA extends RGB {
+  a: number;
+}
+
+/** Hue/saturation/value color (`h` `0–360`, `s`/`v` `0–1`). */
+export interface HSV {
+  h: number;
+  s: number;
+  v: number;
+}
+
+/** {@link HSV} extended with an alpha channel in the `0–1` range. */
+export interface HSVA extends HSV {
+  a: number;
+}
+
+/** Hue/saturation/lightness color (`h` `0–360`, `s`/`l` `0–1`). */
+export interface HSL {
+  h: number;
+  s: number;
+  l: number;
+}
+
+/** {@link HSL} extended with an alpha channel in the `0–1` range. */
+export interface HSLA extends HSL {
+  a: number;
+}
diff --git a/vue/primitives/src/internal/color/utils.ts b/vue/primitives/src/internal/color/utils.ts
new file mode 100644
index 0000000..b3fb3b9
--- /dev/null
+++ b/vue/primitives/src/internal/color/utils.ts
@@ -0,0 +1,43 @@
+import { clamp } from '@robonen/stdlib';
+import { hsvToRgb } from './convert';
+import type { HSVA, RGB } from './types';
+
+/** Clamp `value` to the inclusive `[0, max]` range. */
+export function clampChannel(value: number, max: number): number {
+  return clamp(value, 0, max);
+}
+
+/** Linearize a single sRGB `0–1` channel for WCAG luminance math. */
+function linearize(channel: number): number {
+  return channel <= 0.03928
+    ? channel / 12.92
+    : ((channel + 0.055) / 1.055) ** 2.4;
+}
+
+/** Compute the WCAG relative luminance (`0–1`) of an {@link RGB} color. */
+export function relativeLuminance(rgb: RGB): number {
+  const r = linearize(rgb.r / 255);
+  const g = linearize(rgb.g / 255);
+  const b = linearize(rgb.b / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** Compute the WCAG contrast ratio (`1–21`) between two {@link RGB} colors. */
+export function contrastRatio(a: RGB, b: RGB): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const lighter = Math.max(la, lb);
+  const darker = Math.min(la, lb);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/** Whether `rgb` is light enough that a dark contrasting element reads best. */
+export function isLight(rgb: RGB): boolean {
+  return relativeLuminance(rgb) > 0.179;
+}
+
+/** Render an {@link HSVA} color as a CSS `rgba(r, g, b, a)` string. */
+export function hsvaToCss(hsva: HSVA): string {
+  const { r, g, b } = hsvToRgb(hsva);
+  return `rgba(${r}, ${g}, ${b}, ${hsva.a})`;
+}
diff --git a/vue/primitives/src/internal/pointer-drag/__test__/computeFrame.test.ts b/vue/primitives/src/internal/pointer-drag/__test__/computeFrame.test.ts
new file mode 100644
index 0000000..cb2c72f
--- /dev/null
+++ b/vue/primitives/src/internal/pointer-drag/__test__/computeFrame.test.ts
@@ -0,0 +1,203 @@
+import { describe, expect, it } from 'vitest';
+import { computeFrame, resolveAxisLock } from '../computeFrame';
+import type { DragModifiers, Point } from '../types';
+
+const NO_MOD: DragModifiers = { shift: false, alt: false, ctrl: false, meta: false };
+const SHIFT: DragModifiers = { shift: true, alt: false, ctrl: false, meta: false };
+
+const ORIGIN: Point = { x: 0, y: 0 };
+
+describe('resolveAxisLock', () => {
+  it('returns the static axis verbatim when not "both"', () => {
+    expect(resolveAxisLock('x', true, SHIFT, { x: 5, y: 50 })).toBe('x');
+    expect(resolveAxisLock('y', true, SHIFT, { x: 50, y: 5 })).toBe('y');
+  });
+
+  it('is "none" for "both" without shift-lock', () => {
+    expect(resolveAxisLock('both', false, SHIFT, { x: 5, y: 50 })).toBe('none');
+    expect(resolveAxisLock('both', true, NO_MOD, { x: 5, y: 50 })).toBe('none');
+  });
+
+  it('picks the dominant axis under shift-lock', () => {
+    expect(resolveAxisLock('both', true, SHIFT, { x: 50, y: 5 })).toBe('x');
+    expect(resolveAxisLock('both', true, SHIFT, { x: 5, y: 50 })).toBe('y');
+  });
+
+  it('resolves an exact tie to "x"', () => {
+    expect(resolveAxisLock('both', true, SHIFT, { x: 10, y: 10 })).toBe('x');
+    expect(resolveAxisLock('both', true, SHIFT, { x: -10, y: 10 })).toBe('x');
+  });
+});
+
+describe('computeFrame — axis lock zeroing', () => {
+  it('zeros the y component when locked to x', () => {
+    const { total } = computeFrame({
+      start: ORIGIN,
+      last: { x: 30, y: 40 },
+      rect: undefined,
+      axis: 'x',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: ORIGIN,
+    });
+    expect(total).toEqual({ x: 30, y: 0 });
+  });
+
+  it('zeros the x component when locked to y', () => {
+    const { total } = computeFrame({
+      start: ORIGIN,
+      last: { x: 30, y: 40 },
+      rect: undefined,
+      axis: 'y',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: ORIGIN,
+    });
+    expect(total).toEqual({ x: 0, y: 40 });
+  });
+
+  it('leaves both components free when axis is "none"', () => {
+    const { total } = computeFrame({
+      start: ORIGIN,
+      last: { x: 30, y: 40 },
+      rect: undefined,
+      axis: 'none',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: ORIGIN,
+    });
+    expect(total).toEqual({ x: 30, y: 40 });
+  });
+});
+
+describe('computeFrame — snap then clamp ordering', () => {
+  it('snaps the total to a scalar grid (both axes)', () => {
+    const { total } = computeFrame({
+      start: ORIGIN,
+      last: { x: 23, y: 38 },
+      rect: undefined,
+      axis: 'none',
+      snapGrid: 10,
+      bounds: undefined,
+      prevTotal: ORIGIN,
+    });
+    expect(total).toEqual({ x: 20, y: 40 });
+  });
+
+  it('snaps each axis independently with a tuple grid', () => {
+    const { total } = computeFrame({
+      start: ORIGIN,
+      last: { x: 23, y: 38 },
+      rect: undefined,
+      axis: 'none',
+      snapGrid: [10, 25],
+      bounds: undefined,
+      prevTotal: ORIGIN,
+    });
+    expect(total).toEqual({ x: 20, y: 50 });
+  });
+
+  it('a snapped value never lands outside the bounds (clamp runs after snap)', () => {
+    // Raw 47 snaps to 50, which exceeds maxX 45 → clamp wins → 45.
+    const { total } = computeFrame({
+      start: ORIGIN,
+      last: { x: 47, y: 0 },
+      rect: undefined,
+      axis: 'none',
+      snapGrid: 10,
+      bounds: { maxX: 45 },
+      prevTotal: ORIGIN,
+    });
+    expect(total.x).toBe(45);
+    expect(total.x).toBeLessThanOrEqual(45);
+  });
+
+  it('clamps the lower bound too', () => {
+    const { total } = computeFrame({
+      start: ORIGIN,
+      last: { x: -100, y: -100 },
+      rect: undefined,
+      axis: 'none',
+      snapGrid: undefined,
+      bounds: { minX: -20, minY: -30 },
+      prevTotal: ORIGIN,
+    });
+    expect(total).toEqual({ x: -20, y: -30 });
+  });
+});
+
+describe('computeFrame — total recomputed from start (no double-count on axis flip)', () => {
+  it('an axis-lock flip mid-gesture does not accumulate frame deltas', () => {
+    const start: Point = { x: 0, y: 0 };
+    const last: Point = { x: 30, y: 40 };
+
+    // Frame 1: locked to x. total = (30, 0).
+    const f1 = computeFrame({
+      start,
+      last,
+      rect: undefined,
+      axis: 'x',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: { x: 0, y: 0 },
+    });
+    expect(f1.total).toEqual({ x: 30, y: 0 });
+
+    // Frame 2: SAME pointer position, but the lock flipped to y. Because the
+    // total is recomputed from `start` (not accumulated), it is (0, 40) — NOT
+    // (30, 40). The delta reflects the jump off the previous total.
+    const f2 = computeFrame({
+      start,
+      last,
+      rect: undefined,
+      axis: 'y',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: f1.total,
+    });
+    expect(f2.total).toEqual({ x: 0, y: 40 });
+    expect(f2.delta).toEqual({ x: -30, y: 40 });
+  });
+
+  it('delta is the difference between this total and prevTotal', () => {
+    const { delta } = computeFrame({
+      start: ORIGIN,
+      last: { x: 15, y: 25 },
+      rect: undefined,
+      axis: 'none',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: { x: 10, y: 10 },
+    });
+    expect(delta).toEqual({ x: 5, y: 15 });
+  });
+});
+
+describe('computeFrame — elementPoint', () => {
+  it('is pointer minus rect top-left when a rect is supplied', () => {
+    const rect = { left: 100, top: 200 } as DOMRect;
+    const { elementPoint } = computeFrame({
+      start: ORIGIN,
+      last: { x: 130, y: 240 },
+      rect,
+      axis: 'none',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: ORIGIN,
+    });
+    expect(elementPoint).toEqual({ x: 30, y: 40 });
+  });
+
+  it('is the origin when no rect is supplied', () => {
+    const { elementPoint } = computeFrame({
+      start: ORIGIN,
+      last: { x: 130, y: 240 },
+      rect: undefined,
+      axis: 'none',
+      snapGrid: undefined,
+      bounds: undefined,
+      prevTotal: ORIGIN,
+    });
+    expect(elementPoint).toEqual({ x: 0, y: 0 });
+  });
+});
diff --git a/vue/primitives/src/internal/pointer-drag/__test__/usePointerDrag.test.ts b/vue/primitives/src/internal/pointer-drag/__test__/usePointerDrag.test.ts
new file mode 100644
index 0000000..3237229
--- /dev/null
+++ b/vue/primitives/src/internal/pointer-drag/__test__/usePointerDrag.test.ts
@@ -0,0 +1,228 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, shallowRef } from 'vue';
+import { usePointerDrag } from '../usePointerDrag';
+import type { UsePointerDragOptions } from '../usePointerDrag';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+/** One animation-frame tick, so the rAF-batched flush has run. */
+function raf(): Promise<void> {
+  return new Promise(resolve => requestAnimationFrame(() => resolve()));
+}
+
+function down(el: Element, clientX: number, clientY: number, pointerId = 1): void {
+  el.dispatchEvent(new PointerEvent('pointerdown', { pointerId, button: 0, clientX, clientY, bubbles: true, cancelable: true }));
+}
+function move(el: Element, clientX: number, clientY: number, pointerId = 1): void {
+  el.dispatchEvent(new PointerEvent('pointermove', { pointerId, clientX, clientY, bubbles: true }));
+}
+function up(el: Element, clientX: number, clientY: number, pointerId = 1): void {
+  el.dispatchEvent(new PointerEvent('pointerup', { pointerId, clientX, clientY, bubbles: true }));
+}
+function cancelPointer(el: Element, pointerId = 1): void {
+  el.dispatchEvent(new PointerEvent('pointercancel', { pointerId, bubbles: true }));
+}
+
+function mountDrag(options: UsePointerDragOptions = {}) {
+  const api = shallowRef<ReturnType<typeof usePointerDrag>>();
+  const Harness = defineComponent({
+    setup() {
+      const el = shallowRef<HTMLElement | null>(null);
+      api.value = usePointerDrag(el, options);
+      return () => h('div', { ref: el, style: 'width:200px;height:200px;' });
+    },
+  });
+  const wrapper = track(mount(Harness, { attachTo: document.body }));
+  const el = wrapper.element as HTMLElement;
+  return { wrapper, el, api };
+}
+
+describe('usePointerDrag', () => {
+  it('a sub-threshold press is a click: onStart/onMove/onCommit never fire', async () => {
+    const onStart = vi.fn();
+    const onCommit = vi.fn();
+    const onEnd = vi.fn();
+    const { el, api } = mountDrag({ threshold: 5, onStart, onCommit, onEnd });
+    await nextTick();
+
+    down(el, 50, 50);
+    move(el, 52, 51); // < 5px in both axes
+    await raf();
+    up(el, 52, 51);
+    await raf();
+
+    expect(onStart).not.toHaveBeenCalled();
+    expect(onCommit).not.toHaveBeenCalled();
+    expect(api.value!.isDragging.value).toBe(false);
+    // onEnd does not fire when the drag never started.
+    expect(onEnd).not.toHaveBeenCalled();
+  });
+
+  it('a real drag toggles isDragging and commits once with the terminal total', async () => {
+    const onCommit = vi.fn();
+    const onStart = vi.fn();
+    const { el, api } = mountDrag({ threshold: 3, onStart, onCommit });
+    await nextTick();
+
+    down(el, 100, 100);
+    move(el, 140, 130);
+    await raf();
+
+    expect(onStart).toHaveBeenCalledTimes(1);
+    expect(api.value!.isDragging.value).toBe(true);
+    expect(api.value!.total.value).toEqual({ x: 40, y: 30 });
+
+    up(el, 140, 130);
+    await raf();
+
+    expect(api.value!.isDragging.value).toBe(false);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+    const committed = onCommit.mock.calls[0]![0];
+    expect(committed.total).toEqual({ x: 40, y: 30 });
+  });
+
+  it('the final pointerup flush captures a move that had no rAF tick yet', async () => {
+    const onCommit = vi.fn();
+    const { el } = mountDrag({ threshold: 3, onCommit });
+    await nextTick();
+
+    down(el, 0, 0);
+    move(el, 50, 0);
+    await raf(); // establish the drag
+
+    // A trailing move with NO rAF tick before the up — endDrag must flush it.
+    move(el, 80, 0);
+    up(el, 80, 0);
+    await raf();
+
+    expect(onCommit).toHaveBeenCalledTimes(1);
+    expect(onCommit.mock.calls[0]![0].total).toEqual({ x: 80, y: 0 });
+  });
+
+  it('pointercancel fires onEnd but NOT onCommit', async () => {
+    const onEnd = vi.fn();
+    const onCommit = vi.fn();
+    const { el, api } = mountDrag({ threshold: 3, onEnd, onCommit });
+    await nextTick();
+
+    down(el, 0, 0);
+    move(el, 40, 40);
+    await raf();
+    cancelPointer(el);
+    await raf();
+
+    expect(onEnd).toHaveBeenCalledTimes(1);
+    expect(onEnd.mock.calls[0]![1].type).toBe('pointercancel');
+    expect(onCommit).not.toHaveBeenCalled();
+    expect(api.value!.isDragging.value).toBe(false);
+  });
+
+  it('a second pointerId during a drag is ignored (multi-touch guard)', async () => {
+    const { el, api } = mountDrag({ threshold: 3 });
+    await nextTick();
+
+    down(el, 0, 0, 1);
+    move(el, 40, 0, 1);
+    await raf();
+    expect(api.value!.total.value).toEqual({ x: 40, y: 0 });
+
+    // Foreign pointer 2 must not move the gesture.
+    move(el, 999, 999, 2);
+    await raf();
+    expect(api.value!.total.value).toEqual({ x: 40, y: 0 });
+
+    // A foreign pointerup must not end the gesture either.
+    up(el, 999, 999, 2);
+    await raf();
+    expect(api.value!.isDragging.value).toBe(true);
+
+    up(el, 40, 0, 1);
+    await raf();
+    expect(api.value!.isDragging.value).toBe(false);
+  });
+
+  it('onStart returning false unwinds the gesture (clean re-press)', async () => {
+    const onMove = vi.fn();
+    const onCommit = vi.fn();
+    const { el, api } = mountDrag({ threshold: 3, onStart: () => false, onMove, onCommit });
+    await nextTick();
+
+    down(el, 0, 0);
+    move(el, 40, 0);
+    await raf();
+
+    expect(api.value!.isDragging.value).toBe(false);
+    expect(onMove).not.toHaveBeenCalled();
+
+    up(el, 40, 0);
+    await raf();
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it('a pointerup on window (not the target) still ends the gesture', async () => {
+    const onCommit = vi.fn();
+    const { el, api } = mountDrag({ threshold: 3, onCommit });
+    await nextTick();
+
+    down(el, 0, 0);
+    move(el, 40, 0);
+    await raf();
+    expect(api.value!.isDragging.value).toBe(true);
+
+    // The release is seen on window, not the target (capture lost / pointer left
+    // the element). The gesture must still end.
+    globalThis.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX: 40, clientY: 0 }));
+    await raf();
+
+    expect(api.value!.isDragging.value).toBe(false);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it('a target detached mid-drag does NOT strand the gesture (the stuck-handler bug)', async () => {
+    const onCommit = vi.fn();
+    const { el, api } = mountDrag({ threshold: 0, onCommit });
+    await nextTick();
+
+    down(el, 10, 0);
+    move(el, 50, 0);
+    await raf();
+    expect(api.value!.isDragging.value).toBe(true);
+
+    // Simulate the target being replaced/removed by a re-render during the drag.
+    el.remove();
+    // The release now happens with the original element gone; window must catch it.
+    globalThis.dispatchEvent(new PointerEvent('pointerup', { pointerId: 1, clientX: 50, clientY: 0 }));
+    await raf();
+
+    expect(api.value!.isDragging.value).toBe(false);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it('cancel() aborts imperatively: onEnd fires, onCommit does not', async () => {
+    const onEnd = vi.fn();
+    const onCommit = vi.fn();
+    const { el, api } = mountDrag({ threshold: 3, onEnd, onCommit });
+    await nextTick();
+
+    down(el, 0, 0);
+    move(el, 40, 40);
+    await raf();
+
+    api.value!.cancel();
+    expect(onEnd).toHaveBeenCalledTimes(1);
+    expect(onCommit).not.toHaveBeenCalled();
+    expect(api.value!.isDragging.value).toBe(false);
+  });
+});
diff --git a/vue/primitives/src/internal/pointer-drag/computeFrame.ts b/vue/primitives/src/internal/pointer-drag/computeFrame.ts
new file mode 100644
index 0000000..ff4a60b
--- /dev/null
+++ b/vue/primitives/src/internal/pointer-drag/computeFrame.ts
@@ -0,0 +1,99 @@
+import { clamp } from '@robonen/stdlib';
+import type { DragAxis, DragBounds, DragModifiers, EffectiveAxis, Point } from './types';
+
+/**
+ * Resolve which axis a frame is constrained to.
+ *
+ * A statically configured axis (`'x'` / `'y'`) always wins. With `'both'` and
+ * `lockOnShift` enabled, holding shift locks to the *dominant* axis of the raw
+ * total so far (the larger absolute component); ties resolve to `'x'`. Otherwise
+ * the frame is unconstrained (`'none'`).
+ *
+ * @param staticAxis The configured axis from options.
+ * @param lockOnShift Whether shift engages dominant-axis locking.
+ * @param modifiers Live modifier flags from the current pointer event.
+ * @param rawTotal The unconstrained `last - start` total, used to pick the dominant axis.
+ */
+export function resolveAxisLock(
+  staticAxis: DragAxis,
+  lockOnShift: boolean,
+  modifiers: DragModifiers,
+  rawTotal: Point,
+): EffectiveAxis {
+  if (staticAxis !== 'both') return staticAxis;
+  if (lockOnShift && modifiers.shift)
+    return Math.abs(rawTotal.x) >= Math.abs(rawTotal.y) ? 'x' : 'y';
+  return 'none';
+}
+
+/** Round a value to the nearest multiple of `grid` (a `0`/falsy grid is a no-op). */
+function snapAxis(value: number, grid: number): number {
+  return grid ? Math.round(value / grid) * grid : value;
+}
+
+/** Inputs for a single drag frame computation. */
+interface ComputeFrameParams {
+  /** Client point where the gesture began. */
+  start: Point;
+  /** Latest client point of the pointer. */
+  last: Point;
+  /** Tracked element rect, or `undefined` when rect tracking is off. */
+  rect: DOMRect | undefined;
+  /** Resolved axis constraint for this frame. */
+  axis: EffectiveAxis;
+  /** Snap grid: a scalar (both axes) or `[gx, gy]` tuple; `undefined` disables snapping. */
+  snapGrid: number | [number, number] | undefined;
+  /** Optional per-axis clamp on the cumulative total. */
+  bounds: DragBounds | undefined;
+  /** The previously committed total, used to derive this frame's `delta`. */
+  prevTotal: Point;
+}
+
+/**
+ * Compute one drag frame as a pure function of its inputs — no DOM access, no
+ * reactivity, fully unit-testable.
+ *
+ * Order of operations is load-bearing:
+ * 1. `rawTotal = last - start`.
+ * 2. Apply the axis lock by zeroing the constrained-out component.
+ * 3. Snap the *total* (not the delta) to `snapGrid` when set.
+ * 4. Clamp the total to `bounds` per axis.
+ *
+ * `delta = clampedTotal - prevTotal`. The total is always recomputed from
+ * `start` every frame (frame deltas are never accumulated) so a mid-gesture
+ * axis-lock flip can never double-count.
+ */
+export function computeFrame(params: ComputeFrameParams): { total: Point; delta: Point; elementPoint: Point } {
+  const { start, last, rect, axis, snapGrid, bounds, prevTotal } = params;
+
+  // 1. Raw cumulative movement from the gesture origin.
+  let tx = last.x - start.x;
+  let ty = last.y - start.y;
+
+  // 2. Axis lock: zero the locked-out component.
+  if (axis === 'x') ty = 0;
+  else if (axis === 'y') tx = 0;
+
+  // 3. Snap the TOTAL to the grid (scalar grid applies to both axes).
+  if (snapGrid !== undefined) {
+    const gx = typeof snapGrid === 'number' ? snapGrid : snapGrid[0];
+    const gy = typeof snapGrid === 'number' ? snapGrid : snapGrid[1];
+    tx = snapAxis(tx, gx);
+    ty = snapAxis(ty, gy);
+  }
+
+  // 4. Clamp the (snapped) total to bounds, per axis. Done after snap so a
+  //    snapped value can never land outside the bounds.
+  if (bounds) {
+    tx = clamp(tx, bounds.minX ?? -Infinity, bounds.maxX ?? Infinity);
+    ty = clamp(ty, bounds.minY ?? -Infinity, bounds.maxY ?? Infinity);
+  }
+
+  const total: Point = { x: tx, y: ty };
+  const delta: Point = { x: tx - prevTotal.x, y: ty - prevTotal.y };
+  const elementPoint: Point = rect
+    ? { x: last.x - rect.left, y: last.y - rect.top }
+    : { x: 0, y: 0 };
+
+  return { total, delta, elementPoint };
+}
diff --git a/vue/primitives/src/internal/pointer-drag/dom.ts b/vue/primitives/src/internal/pointer-drag/dom.ts
new file mode 100644
index 0000000..e26b25a
--- /dev/null
+++ b/vue/primitives/src/internal/pointer-drag/dom.ts
@@ -0,0 +1,22 @@
+/**
+ * `setPointerCapture` / `releasePointerCapture` throw when there is no live
+ * pointer for the id — which happens for synthetic events in tests and for
+ * pointers that were already released. These guards swallow only that case.
+ */
+export function capturePointer(el: HTMLElement | undefined, id: number): void {
+  try {
+    el?.setPointerCapture?.(id);
+  }
+  catch {
+    /* no active pointer (synthetic event) */
+  }
+}
+
+export function releasePointer(el: HTMLElement | undefined, id: number): void {
+  try {
+    el?.releasePointerCapture?.(id);
+  }
+  catch {
+    /* pointer already released */
+  }
+}
diff --git a/vue/primitives/src/internal/pointer-drag/index.ts b/vue/primitives/src/internal/pointer-drag/index.ts
new file mode 100644
index 0000000..2c82324
--- /dev/null
+++ b/vue/primitives/src/internal/pointer-drag/index.ts
@@ -0,0 +1,11 @@
+export { computeFrame, resolveAxisLock } from './computeFrame';
+export type {
+  DragAxis,
+  DragBounds,
+  DragModifiers,
+  DragState,
+  EffectiveAxis,
+  Point,
+} from './types';
+export { usePointerDrag } from './usePointerDrag';
+export type { UsePointerDragOptions, UsePointerDragReturn } from './usePointerDrag';
diff --git a/vue/primitives/src/internal/pointer-drag/types.ts b/vue/primitives/src/internal/pointer-drag/types.ts
new file mode 100644
index 0000000..b64ff0b
--- /dev/null
+++ b/vue/primitives/src/internal/pointer-drag/types.ts
@@ -0,0 +1,74 @@
+// Re-export the package-canonical 2D point (from internal `utils/geometry`,
+// which is not in the root barrel) so `spline` and `pointer-drag` share one
+// identical `Point` symbol and the root barrel stays free of a TS2308 clash.
+// Imported locally as well so the interfaces below can reference it.
+import type { Point } from '../utils/geometry';
+
+/** A 2D point in client (screen) pixels unless stated otherwise. */
+export type { Point };
+
+/**
+ * The axis a drag is allowed to move along.
+ * - `'x'` / `'y'`: constrain to that single axis.
+ * - `'both'`: free movement (the default).
+ */
+export type DragAxis = 'x' | 'y' | 'both';
+
+/**
+ * The axis actually in effect for a given frame, after axis-lock resolution.
+ * `'none'` means free 2D movement (no constraint), as opposed to a hard `'x'`
+ * or `'y'` lock.
+ */
+export type EffectiveAxis = 'x' | 'y' | 'none';
+
+/** Optional per-axis min/max clamp applied to the cumulative drag total. */
+export interface DragBounds {
+  /** Lower bound for the x total. */
+  minX?: number;
+  /** Upper bound for the x total. */
+  maxX?: number;
+  /** Lower bound for the y total. */
+  minY?: number;
+  /** Upper bound for the y total. */
+  maxY?: number;
+}
+
+/** Snapshot of the keyboard modifier flags read off a pointer event. */
+export interface DragModifiers {
+  /** `event.shiftKey` at the moment the frame was produced. */
+  shift: boolean;
+  /** `event.altKey` at the moment the frame was produced. */
+  alt: boolean;
+  /** `event.ctrlKey` at the moment the frame was produced. */
+  ctrl: boolean;
+  /** `event.metaKey` at the moment the frame was produced. */
+  meta: boolean;
+}
+
+/** The full, reactive state of an in-flight (or just-ended) drag gesture. */
+export interface DragState {
+  /** Client point where the gesture started (pointerdown). */
+  startPoint: Point;
+  /** Current client point of the pointer. */
+  point: Point;
+  /**
+   * Pointer position relative to the tracked element's top-left, in client
+   * pixels. `{ x: 0, y: 0 }` when no rect is tracked.
+   */
+  elementPoint: Point;
+  /** Movement since the previous committed frame. */
+  delta: Point;
+  /**
+   * Cumulative movement since `startPoint`, after axis lock, snap, and bounds.
+   * Always recomputed from `startPoint` each frame (never accumulated).
+   */
+  total: Point;
+  /** The axis constraint in effect for the current frame. */
+  axis: EffectiveAxis;
+  /** Modifier flags read live off the latest pointer event. */
+  modifiers: DragModifiers;
+  /** The captured `pointerId` for this gesture. */
+  pointerId: number;
+  /** The captured `pointerType` (`'mouse'` | `'touch'` | `'pen'`). */
+  pointerType: string;
+}
diff --git a/vue/primitives/src/internal/pointer-drag/usePointerDrag.ts b/vue/primitives/src/internal/pointer-drag/usePointerDrag.ts
new file mode 100644
index 0000000..ac982c5
--- /dev/null
+++ b/vue/primitives/src/internal/pointer-drag/usePointerDrag.ts
@@ -0,0 +1,419 @@
+import type { ComputedRef, DeepReadonly, MaybeRefOrGetter, Ref } from 'vue';
+import { onScopeDispose, readonly, shallowReadonly, shallowRef, toValue } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import { computeFrame, resolveAxisLock } from './computeFrame';
+import { capturePointer, releasePointer } from './dom';
+import type { DragAxis, DragBounds, DragModifiers, DragState, Point } from './types';
+
+/** Options for {@link usePointerDrag}. */
+export interface UsePointerDragOptions {
+  /** Axis the drag is constrained to. @default 'both' */
+  axis?: DragAxis;
+  /** When `axis` is `'both'`, holding shift locks to the dominant axis. @default false */
+  lockAxisOnShift?: boolean;
+  /** Pixels the pointer must travel before a press becomes a drag. @default 3 */
+  threshold?: number;
+  /**
+   * Snap the cumulative total to a grid. A scalar applies to both axes; a
+   * `[gx, gy]` tuple snaps each axis independently. `undefined` disables snapping.
+   */
+  snapGrid?: MaybeRefOrGetter<number | [number, number] | undefined>;
+  /** Optional per-axis clamp applied to the cumulative total. */
+  bounds?: MaybeRefOrGetter<DragBounds | undefined>;
+  /** Cache the tracked element's rect on pointerdown so `elementPoint` is populated. @default false */
+  trackElementRect?: boolean;
+  /** Supply the rect explicitly (falls back to `target.getBoundingClientRect()`). */
+  getRect?: () => DOMRect | undefined;
+  /** Restrict which pointer types start a drag. When omitted, all types are accepted. */
+  pointerTypes?: Array<'mouse' | 'touch' | 'pen'>;
+  /** Mouse buttons that start a drag (matched against `event.button`). @default [0] */
+  buttons?: MaybeRefOrGetter<number[]>;
+  /** Reject new pointerdowns while truthy (does not abort an active gesture). @default false */
+  disabled?: MaybeRefOrGetter<boolean>;
+  /** Call `preventDefault()` on the initiating pointerdown. @default true */
+  preventDefault?: MaybeRefOrGetter<boolean>;
+  /** Call `stopPropagation()` on the initiating pointerdown. @default false */
+  stopPropagation?: MaybeRefOrGetter<boolean>;
+  /**
+   * Fired once when the threshold is first crossed. Return `false` to abort the
+   * gesture (the capture is released and state reset for a clean re-press).
+   */
+  onStart?: (state: DragState, event: PointerEvent) => void | false;
+  /** Fired every committed frame while dragging. */
+  onMove?: (state: DragState, event: PointerEvent) => void;
+  /** Fired on pointerup or pointercancel. Inspect `event.type` to tell them apart. */
+  onEnd?: (state: DragState, event: PointerEvent) => void;
+  /** Fired after `onEnd` on a successful pointerup only (never on cancel/abort). */
+  onCommit?: (state: DragState) => void;
+}
+
+/** Return value of {@link usePointerDrag}. */
+export interface UsePointerDragReturn {
+  /** Whether a drag is currently in progress (threshold crossed). */
+  isDragging: Readonly<Ref<boolean>>;
+  /** The reactive drag state (read-only view). */
+  state: DeepReadonly<DragState>;
+  /** The cumulative total of the latest frame. */
+  total: ComputedRef<Point>;
+  /** The per-frame delta of the latest frame. */
+  delta: ComputedRef<Point>;
+  /** The latest modifier flags (read-only view). */
+  modifiers: Readonly<DragModifiers>;
+  /** Imperatively abort an active gesture (fires `onEnd`, never `onCommit`). */
+  cancel: () => void;
+}
+
+/** Frozen zero point reused for resetting state. */
+function zero(): Point {
+  return { x: 0, y: 0 };
+}
+
+/**
+ * Normalized pointer-capture drag composable. The single drag primitive every
+ * draggable media-editor control builds on.
+ *
+ * Binds `pointerdown` to `target`, captures the pointer on press, and retargets
+ * `pointermove` / `pointerup` / `pointercancel` to the same element (capture
+ * invariant: capture node === listen node). Pointer moves are coalesced into
+ * exactly one `requestAnimationFrame` flush per event burst, where the frame is
+ * computed via {@link computeFrame} (axis lock → snap → clamp) and the reactive
+ * state updated once. A press that never crosses `threshold` stays a click:
+ * `isDragging` never flips and `onStart`/`onMove`/`onCommit` never fire.
+ *
+ * @param target The element (ref/getter) that owns the drag. A lazy getter
+ *   rebinds the listener when a template ref resolves.
+ * @param options See {@link UsePointerDragOptions}.
+ */
+export function usePointerDrag(
+  target: MaybeRefOrGetter<HTMLElement | null | undefined>,
+  options: UsePointerDragOptions = {},
+): UsePointerDragReturn {
+  const {
+    axis = 'both',
+    lockAxisOnShift = false,
+    threshold = 3,
+    snapGrid,
+    bounds,
+    trackElementRect = false,
+    getRect,
+    pointerTypes,
+    buttons,
+    disabled,
+    preventDefault,
+    stopPropagation,
+    onStart,
+    onMove,
+    onEnd,
+    onCommit,
+  } = options;
+
+  const isDragging = shallowRef(false);
+
+  // Plain (non-reactive) object. `flush()` writes ~13 of these fields every frame;
+  // as a `reactive()` proxy each write was a subscriber-less trigger + Proxy
+  // set-trap on the package's single shared drag primitive. Nothing reads these
+  // outputs reactively — consumers bind to `isDragging` (a shallowRef) and read
+  // `state` imperatively inside onMove/onStart/onEnd — so a plain object is the
+  // correct representation and removes the per-frame reactivity cost everywhere.
+  const state: DragState = {
+    startPoint: zero(),
+    point: zero(),
+    elementPoint: zero(),
+    delta: zero(),
+    total: zero(),
+    axis: axis === 'both' ? 'none' : axis,
+    modifiers: { shift: false, alt: false, ctrl: false, meta: false },
+    pointerId: -1,
+    pointerType: '',
+  };
+
+  // ── gesture-local mutable state (plain locals, not reactive) ──────────────
+  let pointerId = -1;
+  /** Gesture origin in client pixels. */
+  const start: Point = zero();
+  /** Latest pointer position in client pixels. */
+  const last: Point = zero();
+  /** Last committed total — `delta` is derived against this each frame. */
+  const prevTotal: Point = zero();
+  let rect: DOMRect | undefined;
+  /** Threshold crossed (drag begun). Gates `onStart`/`onMove`/`onCommit`. */
+  let started = false;
+  /** Gesture torn down. Makes `endDrag` idempotent across up/cancel/dispose. */
+  let ended = false;
+  let rafId: number | null = null;
+  /** Latest move event awaiting the next rAF flush. */
+  let pendingEvent: PointerEvent | null = null;
+  /** The window the gesture-scoped move/up/cancel listeners are attached to. */
+  let activeWindow: Window | null = null;
+
+  function setModifiers(event: PointerEvent): void {
+    state.modifiers.shift = event.shiftKey;
+    state.modifiers.alt = event.altKey;
+    state.modifiers.ctrl = event.ctrlKey;
+    state.modifiers.meta = event.metaKey;
+  }
+
+  function resolvedTarget(): HTMLElement | undefined {
+    return toValue(target) ?? undefined;
+  }
+
+  /**
+   * Compute the frame for `pendingEvent` and push it into reactive state.
+   * Single stash-and-flush rather than `useRafFn`: `useRafFn` runs a *continuous*
+   * loop, but a drag wants exactly one frame per pointer-event burst — so we
+   * coalesce moves into a single rAF and never spin when the pointer is still.
+   */
+  function flush(): void {
+    rafId = null;
+    const event = pendingEvent;
+    if (!event) return;
+    pendingEvent = null;
+
+    // Read modifiers live off the event (not `useKeyModifier`): an in-event read
+    // is the only source guaranteed correct for THIS frame's gesture decision.
+    setModifiers(event);
+
+    const rawTotal: Point = { x: last.x - start.x, y: last.y - start.y };
+    const effectiveAxis = resolveAxisLock(axis, lockAxisOnShift, state.modifiers, rawTotal);
+
+    const frame = computeFrame({
+      start,
+      last,
+      rect,
+      axis: effectiveAxis,
+      snapGrid: toValue(snapGrid),
+      bounds: toValue(bounds),
+      prevTotal,
+    });
+
+    prevTotal.x = frame.total.x;
+    prevTotal.y = frame.total.y;
+
+    state.point.x = last.x;
+    state.point.y = last.y;
+    state.elementPoint.x = frame.elementPoint.x;
+    state.elementPoint.y = frame.elementPoint.y;
+    state.delta.x = frame.delta.x;
+    state.delta.y = frame.delta.y;
+    state.total.x = frame.total.x;
+    state.total.y = frame.total.y;
+    state.axis = effectiveAxis;
+
+    if (!isDragging.value) isDragging.value = true;
+
+    onMove?.(state as DragState, event);
+  }
+
+  function schedule(): void {
+    if (rafId === null) rafId = requestAnimationFrame(flush);
+  }
+
+  function cancelRaf(): void {
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  }
+
+  const onUp = (event: PointerEvent): void => endDrag(event, true);
+  const onCancel = (event: PointerEvent): void => endDrag(event, false);
+
+  /**
+   * Attach move/up/cancel to `window` (the element's own window, so iframes work)
+   * for the duration of the gesture. Catching these on `window` rather than the
+   * target means a re-rendered target or a lost `setPointerCapture` can never
+   * strand the gesture — the up always arrives. Listeners are gesture-scoped, so
+   * idle instances cost nothing.
+   */
+  function addWindowListeners(): void {
+    const win = resolvedTarget()?.ownerDocument?.defaultView
+      ?? (globalThis.window !== undefined ? globalThis : null);
+    if (!win) return;
+    win.addEventListener('pointermove', onPointerMove);
+    win.addEventListener('pointerup', onUp);
+    win.addEventListener('pointercancel', onCancel);
+    activeWindow = win;
+  }
+
+  function removeWindowListeners(): void {
+    if (!activeWindow) return;
+    activeWindow.removeEventListener('pointermove', onPointerMove);
+    activeWindow.removeEventListener('pointerup', onUp);
+    activeWindow.removeEventListener('pointercancel', onCancel);
+    activeWindow = null;
+  }
+
+  /** Tear down gesture-local state without firing any callbacks. */
+  function reset(): void {
+    removeWindowListeners();
+    cancelRaf();
+    pendingEvent = null;
+    pointerId = -1;
+    rect = undefined;
+    started = false;
+    ended = true;
+    isDragging.value = false;
+    state.pointerId = -1;
+    state.pointerType = '';
+    state.axis = axis === 'both' ? 'none' : axis;
+    prevTotal.x = 0;
+    prevTotal.y = 0;
+  }
+
+  function onPointerDown(event: PointerEvent): void {
+    // A live gesture owns the pointer; ignore re-entrant downs.
+    if (pointerId !== -1) return;
+    if (toValue(disabled) ?? false) return;
+
+    const acceptedButtons = toValue(buttons) ?? [0];
+    if (!acceptedButtons.includes(event.button)) return;
+    if (pointerTypes && !pointerTypes.includes(event.pointerType as 'mouse' | 'touch' | 'pen')) return;
+
+    const el = resolvedTarget();
+
+    if (toValue(preventDefault) ?? true) event.preventDefault();
+    if (toValue(stopPropagation) ?? false) event.stopPropagation();
+
+    pointerId = event.pointerId;
+    start.x = last.x = event.clientX;
+    start.y = last.y = event.clientY;
+    prevTotal.x = 0;
+    prevTotal.y = 0;
+    started = false;
+    ended = false;
+
+    rect = (trackElementRect || getRect)
+      ? (getRect?.() ?? el?.getBoundingClientRect())
+      : undefined;
+
+    state.startPoint.x = start.x;
+    state.startPoint.y = start.y;
+    state.point.x = start.x;
+    state.point.y = start.y;
+    state.elementPoint.x = rect ? start.x - rect.left : 0;
+    state.elementPoint.y = rect ? start.y - rect.top : 0;
+    state.delta.x = 0;
+    state.delta.y = 0;
+    state.total.x = 0;
+    state.total.y = 0;
+    state.axis = axis === 'both' ? 'none' : axis;
+    state.pointerId = event.pointerId;
+    state.pointerType = event.pointerType;
+    setModifiers(event);
+
+    capturePointer(el, event.pointerId);
+    addWindowListeners();
+
+    // threshold 0 → engage immediately; otherwise wait for the first qualifying
+    // move. `beginDrag` may abort (onStart === false) and self-unwind.
+    if (threshold === 0) beginDrag(event);
+  }
+
+  /**
+   * Cross the threshold: fire `onStart`. Returns `false` (and fully unwinds) if
+   * the consumer aborts — so an immediate re-press starts clean.
+   */
+  function beginDrag(event: PointerEvent): boolean {
+    started = true;
+    if (onStart?.(state as DragState, event) === false) {
+      releasePointer(resolvedTarget(), pointerId);
+      reset();
+      return false;
+    }
+    // The gesture has begun (threshold crossed / `threshold: 0`). `flush` also
+    // sets this on the first frame; the assignment here is idempotent and makes
+    // `isDragging` true the instant `onStart` is accepted, even before a move.
+    isDragging.value = true;
+    return true;
+  }
+
+  function onPointerMove(event: PointerEvent): void {
+    // Multi-touch guard: only the locked pointer drives the gesture.
+    if (event.pointerId !== pointerId) return;
+    last.x = event.clientX;
+    last.y = event.clientY;
+
+    if (!started) {
+      if (Math.abs(last.x - start.x) < threshold && Math.abs(last.y - start.y) < threshold) return;
+      if (!beginDrag(event)) return;
+    }
+
+    pendingEvent = event;
+    schedule();
+  }
+
+  /**
+   * Idempotent end-of-gesture. `commit` distinguishes a real pointerup (commit)
+   * from a cancel/abort (no commit). The `ended` guard means pointerup,
+   * pointercancel, `onScopeDispose`, and synthetic test events can't double-fire.
+   */
+  function endDrag(event: PointerEvent | null, commit: boolean): void {
+    if (ended) return;
+    if (event && event.pointerId !== pointerId) return;
+    ended = true;
+
+    cancelRaf();
+
+    // Final synchronous flush so the last sub-frame move is never dropped.
+    if (event && pendingEvent) flush();
+
+    isDragging.value = false;
+
+    if (started && event) {
+      onEnd?.(state as DragState, event);
+      if (commit) onCommit?.(state as DragState);
+    }
+
+    removeWindowListeners();
+    releasePointer(resolvedTarget(), pointerId);
+    pointerId = -1;
+    rect = undefined;
+    started = false;
+    pendingEvent = null;
+  }
+
+  /** Lazy getter target so the listener rebinds when a template ref resolves. */
+  const targetGetter = () => resolvedTarget() ?? null;
+
+  // Only pointerdown lives on the target; move/up/cancel are added to `window`
+  // for the duration of the gesture (see addWindowListeners) so a re-rendered
+  // target or a lost pointer-capture can never strand the gesture.
+  useEventListener(targetGetter, 'pointerdown', onPointerDown);
+
+  onScopeDispose(() => {
+    // Treat teardown like a cancel: release + cancel rAF, no commit.
+    cancelRaf();
+    removeWindowListeners();
+    if (pointerId !== -1) releasePointer(resolvedTarget(), pointerId);
+  });
+
+  function cancel(): void {
+    // Imperative abort: fire onEnd (synthesizing a cancel-shaped event) but
+    // never onCommit.
+    if (ended || pointerId === -1) return;
+    const el = resolvedTarget();
+    const synthetic = new PointerEvent('pointercancel', { pointerId });
+    cancelRaf();
+    removeWindowListeners();
+    ended = true;
+    isDragging.value = false;
+    if (started) onEnd?.(state as DragState, synthetic);
+    releasePointer(el, pointerId);
+    pointerId = -1;
+    rect = undefined;
+    started = false;
+    pendingEvent = null;
+  }
+
+  return {
+    isDragging,
+    state: readonly(state),
+    // Live read-the-latest views over the plain state (intentionally NOT reactive
+    // computeds — `state` no longer triggers, and nothing subscribes to these).
+    // Each `.value` read returns a fresh snapshot, matching the previous behaviour.
+    total: { get value() { return { x: state.total.x, y: state.total.y }; } } as unknown as ComputedRef<Point>,
+    delta: { get value() { return { x: state.delta.x, y: state.delta.y }; } } as unknown as ComputedRef<Point>,
+    modifiers: shallowReadonly(state.modifiers),
+    cancel,
+  };
+}
diff --git a/vue/primitives/src/primitive/Primitive.ts b/vue/primitives/src/internal/primitive/Primitive.ts
similarity index 100%
rename from vue/primitives/src/primitive/Primitive.ts
rename to vue/primitives/src/internal/primitive/Primitive.ts
diff --git a/vue/primitives/src/primitive/Slot.ts b/vue/primitives/src/internal/primitive/Slot.ts
similarity index 100%
rename from vue/primitives/src/primitive/Slot.ts
rename to vue/primitives/src/internal/primitive/Slot.ts
diff --git a/vue/primitives/src/primitive/__test__/Primitive.test.ts b/vue/primitives/src/internal/primitive/__test__/Primitive.test.ts
similarity index 100%
rename from vue/primitives/src/primitive/__test__/Primitive.test.ts
rename to vue/primitives/src/internal/primitive/__test__/Primitive.test.ts
diff --git a/vue/primitives/src/primitive/index.ts b/vue/primitives/src/internal/primitive/index.ts
similarity index 100%
rename from vue/primitives/src/primitive/index.ts
rename to vue/primitives/src/internal/primitive/index.ts
diff --git a/vue/primitives/src/internal/scale/__test__/scale.test.ts b/vue/primitives/src/internal/scale/__test__/scale.test.ts
new file mode 100644
index 0000000..75abbd8
--- /dev/null
+++ b/vue/primitives/src/internal/scale/__test__/scale.test.ts
@@ -0,0 +1,246 @@
+import { describe, expect, it } from 'vitest';
+import { ref } from 'vue';
+import {
+  formatClock,
+  formatFrames,
+  framesToTimecode,
+  getStepDecimals,
+  niceNum,
+  niceTicks,
+  roundToStep,
+  scaleLinear,
+  timeTicks,
+  useScale,
+} from '..';
+
+describe('math', () => {
+  it('scaleLinear projects linearly', () => {
+    expect(scaleLinear(50, 0, 100, 0, 1000)).toBe(500);
+    expect(scaleLinear(0, 0, 100, 0, 1000)).toBe(0);
+    expect(scaleLinear(100, 0, 100, 0, 1000)).toBe(1000);
+  });
+
+  it('scaleLinear returns r0 for degenerate domain/range', () => {
+    expect(scaleLinear(5, 10, 10, 0, 1000)).toBe(0);
+    expect(scaleLinear(5, 0, 100, 7, 7)).toBe(7);
+  });
+
+  it('roundToStep cleans float drift', () => {
+    expect(roundToStep(1.3, 0.1, 0, getStepDecimals(0.1))).toBe(1.3);
+    expect(roundToStep(1.30000001, 0.1, 0, getStepDecimals(0.1))).toBe(1.3);
+    expect(roundToStep(0.1 + 0.2, 0.1, 0, getStepDecimals(0.1))).toBe(0.3);
+    expect(getStepDecimals(0.001)).toBe(3);
+    expect(getStepDecimals(5)).toBe(0);
+  });
+});
+
+describe('niceNum', () => {
+  it('rounds to nice 1/2/5/10 multiples', () => {
+    expect(niceNum(0.66, true)).toBe(0.5);
+    expect(niceNum(1.3, true)).toBe(1);
+    expect(niceNum(4, true)).toBe(5);
+    expect(niceNum(8, true)).toBe(10);
+    expect(niceNum(120, true)).toBe(100);
+  });
+
+  it('ceils when round is false', () => {
+    expect(niceNum(1.1, false)).toBe(2);
+    expect(niceNum(3, false)).toBe(5);
+    expect(niceNum(6, false)).toBe(10);
+  });
+
+  it('returns 0 for non-positive input', () => {
+    expect(niceNum(0, true)).toBe(0);
+    expect(niceNum(-5, true)).toBe(0);
+  });
+});
+
+describe('niceTicks', () => {
+  it('anchors ticks to integer-aligned step (no pan-jitter)', () => {
+    const ticks = niceTicks({ domain: [10.3, 20.7], range: [0, 500] });
+    const values = ticks.map(t => t.value);
+    // Step resolves to 1 -> all ticks are integers, NOT 10.3, 11.3, ...
+    for (const v of values) {
+      expect(Number.isInteger(v)).toBe(true);
+    }
+    // 11..20 must all be present.
+    for (let v = 11; v <= 20; v++) {
+      expect(values).toContain(v);
+    }
+    // No fractional anchor leakage.
+    expect(values).not.toContain(10.3);
+    expect(values).not.toContain(11.3);
+  });
+
+  it('caps candidate count at maxTicks (no OOM on huge axes)', () => {
+    // 10h frame-rate axis at 1px/frame would be ~36M candidates without a cap.
+    const ticks = niceTicks({ domain: [0, 36_000_000], range: [0, 36_000_000], maxTicks: 100 });
+    expect(ticks.length).toBeLessThanOrEqual(101);
+  });
+
+  it('returns [] for zero-span domain', () => {
+    expect(niceTicks({ domain: [5, 5], range: [0, 100] })).toEqual([]);
+  });
+
+  it('honors a custom format on major ticks', () => {
+    const ticks = niceTicks({
+      domain: [0, 10],
+      range: [0, 200],
+      format: v => `#${v}`,
+    });
+    const major = ticks.find(t => t.major);
+    expect(major?.label.startsWith('#')).toBe(true);
+  });
+});
+
+describe('timeTicks', () => {
+  it('uses the human time ladder and marks minute boundaries major', () => {
+    // Range wide enough that the chosen rung is sub-minute (step 30s),
+    // so a tick lands exactly on the 60s minute boundary.
+    const ticks = timeTicks({ domain: [0, 600], range: [0, 2000] });
+    expect(ticks.length).toBeGreaterThan(0);
+    const minuteTick = ticks.find(t => t.value === 60);
+    expect(minuteTick?.major).toBe(true);
+    expect(minuteTick?.label).toBe(formatClock(60));
+    // A 30s sub-minute tick is minor.
+    expect(ticks.find(t => t.value === 30)?.major).toBe(false);
+  });
+
+  it('only uses ladder-rung steps', () => {
+    const ticks = timeTicks({ domain: [0, 3600], range: [0, 1000] });
+    // Consecutive tick spacing must be a single ladder rung.
+    const diffs = new Set(ticks.slice(1).map((t, i) => t.value - ticks[i]!.value));
+    expect(diffs.size).toBe(1);
+  });
+});
+
+describe('timecode', () => {
+  it('matches known drop-frame vectors', () => {
+    expect(framesToTimecode(17982, 29.97, true)).toBe('00:10:00;00');
+    expect(framesToTimecode(1800, 29.97, true)).toBe('00:01:00;02');
+  });
+
+  it('matches non-drop vectors', () => {
+    expect(framesToTimecode(0, 30)).toBe('00:00:00:00');
+    expect(framesToTimecode(30, 30)).toBe('00:00:01:00');
+  });
+
+  it('handles 59.94 drop-frame', () => {
+    expect(framesToTimecode(35964, 59.94, true)).toBe('00:10:00;00');
+    expect(framesToTimecode(3600, 59.94, true)).toBe('00:01:00;04');
+  });
+
+  it('formatClock switches on magnitude', () => {
+    expect(formatClock(5)).toBe('0:05');
+    expect(formatClock(65)).toBe('1:05');
+    expect(formatClock(3665)).toBe('1:01:05');
+  });
+
+  it('formatFrames renders the frame number', () => {
+    expect(formatFrames(1234)).toBe('1,234');
+  });
+});
+
+describe('useScale flip composition', () => {
+  // domain [0,100] -> range [0,1000]. Expected px for value 0 across all 8 combos.
+  const cases: Array<[
+    'horizontal' | 'vertical',
+    boolean,
+    boolean,
+    number,
+  ]> = [
+    ['horizontal', false, false, 0],
+    ['horizontal', false, true, 1000],
+    ['horizontal', true, false, 1000],
+    ['horizontal', true, true, 0],
+    ['vertical', false, false, 1000],
+    ['vertical', false, true, 1000],
+    ['vertical', true, false, 0],
+    ['vertical', true, true, 0],
+  ];
+
+  for (const [orientation, inverted, rtl, expectedPx] of cases) {
+    it(`orientation=${orientation} inverted=${inverted} rtl=${rtl} -> px(0)=${expectedPx}`, () => {
+      const { scale } = useScale({
+        domain: [0, 100],
+        range: [0, 1000],
+        orientation,
+        inverted,
+        rtl,
+      });
+      expect(scale(0)).toBe(expectedPx);
+      // value 100 is always the opposite endpoint.
+      expect(scale(100)).toBe(expectedPx === 0 ? 1000 : 0);
+    });
+  }
+});
+
+describe('useScale behaviour', () => {
+  it('scale and invert round-trip', () => {
+    const { scale, invert } = useScale({ domain: [0, 100], range: [0, 1000] });
+    expect(scale(25)).toBe(250);
+    expect(invert(250)).toBe(25);
+  });
+
+  it('reacts to reactive domain changes (stable closure)', () => {
+    const domain = ref<readonly [number, number]>([0, 100]);
+    const { scale } = useScale({ domain, range: [0, 1000] });
+    expect(scale(50)).toBe(500);
+    domain.value = [0, 200];
+    expect(scale(50)).toBe(250);
+  });
+
+  it('clamps when clamp option is true', () => {
+    const { scale, invert } = useScale({ domain: [0, 100], range: [0, 1000], clamp: true });
+    expect(scale(200)).toBe(1000);
+    expect(scale(-50)).toBe(0);
+    expect(invert(5000)).toBe(100);
+    expect(invert(-100)).toBe(0);
+  });
+
+  it('roundValue snaps to step then clamps', () => {
+    const { roundValue } = useScale({ domain: [0, 100], range: [0, 1000], step: 5 });
+    expect(roundValue(12)).toBe(10);
+    expect(roundValue(13)).toBe(15);
+    expect(roundValue(120)).toBe(100);
+  });
+
+  it('roundValue is a no-op snap when step is undefined (clamp only)', () => {
+    const { roundValue } = useScale({ domain: [0, 100], range: [0, 1000] });
+    expect(roundValue(12.345)).toBe(12.345);
+    expect(roundValue(200)).toBe(100);
+  });
+
+  it('clampValue honors explicit min/max', () => {
+    const { clampValue } = useScale({ domain: [0, 100], range: [0, 1000], min: 10, max: 90 });
+    expect(clampValue(5)).toBe(10);
+    expect(clampValue(95)).toBe(90);
+    expect(clampValue(50)).toBe(50);
+  });
+
+  it('pxPerUnit guards divide-by-zero', () => {
+    const { pxPerUnit } = useScale({ domain: [0, 100], range: [0, 1000] });
+    expect(pxPerUnit.value).toBe(10);
+    const { pxPerUnit: zero } = useScale({ domain: [5, 5], range: [0, 1000] });
+    expect(zero.value).toBe(0);
+  });
+
+  it('ticks dispatch on tickKind and split into major/minor', () => {
+    const { ticks, majorTicks, minorTicks } = useScale({
+      domain: [0, 100],
+      range: [0, 1000],
+      tickKind: 'nice',
+    });
+    expect(ticks.value.length).toBeGreaterThan(0);
+    expect(majorTicks.value.length + minorTicks.value.length).toBe(ticks.value.length);
+    expect(majorTicks.value.every(t => t.major)).toBe(true);
+    expect(minorTicks.value.every(t => !t.major)).toBe(true);
+  });
+
+  it('ticks are [] for tickKind none or zero range span', () => {
+    const { ticks: none } = useScale({ domain: [0, 100], range: [0, 1000], tickKind: 'none' });
+    expect(none.value).toEqual([]);
+    const { ticks: flat } = useScale({ domain: [0, 100], range: [50, 50], tickKind: 'nice' });
+    expect(flat.value).toEqual([]);
+  });
+});
diff --git a/vue/primitives/src/internal/scale/index.ts b/vue/primitives/src/internal/scale/index.ts
new file mode 100644
index 0000000..0b32d10
--- /dev/null
+++ b/vue/primitives/src/internal/scale/index.ts
@@ -0,0 +1,10 @@
+export * from './math';
+export * from './ticks';
+export * from './timecode';
+export { useScale } from './useScale';
+export type {
+  ScaleOrientation,
+  TickKind,
+  UseScaleOptions,
+  UseScaleReturn,
+} from './useScale';
diff --git a/vue/primitives/src/slider/utils.ts b/vue/primitives/src/internal/scale/math.ts
similarity index 89%
rename from vue/primitives/src/slider/utils.ts
rename to vue/primitives/src/internal/scale/math.ts
index e6e8c39..961e4c6 100644
--- a/vue/primitives/src/slider/utils.ts
+++ b/vue/primitives/src/internal/scale/math.ts
@@ -25,31 +25,17 @@ export function roundToStep(value: number, step: number, min: number, decimals:
 }
 
 /**
- * Linear projection of `value` from the input domain onto the output range.
+ * Linear projection of `value` from the input domain `[d0, d1]` onto the output
+ * range `[r0, r1]`.
  *
- * Plain (non-curried) form — no per-call closure allocation.
+ * Plain (non-curried) form — no per-call closure allocation. Returns `r0` when
+ * the domain or range is degenerate (`d0 === d1` or `r0 === r1`).
  */
 export function scaleLinear(value: number, d0: number, d1: number, r0: number, r1: number): number {
   if (d0 === d1 || r0 === r1) return r0;
   return r0 + ((r1 - r0) / (d1 - d0)) * (value - d0);
 }
 
-/**
- * Verify that adjacent values in an already-sorted `values` array differ by
- * at least `minStepsBetween * step`.
- *
- * The caller is expected to maintain the invariant that `values` is sorted
- * ascending (the slider Root guarantees this by construction).
- */
-export function hasMinStepsBetweenSortedValues(values: number[], minStepsBetween: number, step: number): boolean {
-  if (minStepsBetween <= 0 || values.length < 2) return true;
-  const minGap = minStepsBetween * step;
-  for (let i = 1; i < values.length; i++) {
-    if (values[i]! - values[i - 1]! < minGap) return false;
-  }
-  return true;
-}
-
 /**
  * Index of the value in `values` closest to `nextValue`.
  *
@@ -68,3 +54,19 @@ export function getClosestValueIndex(values: number[], nextValue: number): numbe
   }
   return bestIdx;
 }
+
+/**
+ * Verify that adjacent values in an already-sorted `values` array differ by
+ * at least `minStepsBetween * step`.
+ *
+ * The caller is expected to maintain the invariant that `values` is sorted
+ * ascending.
+ */
+export function hasMinStepsBetweenSortedValues(values: number[], minStepsBetween: number, step: number): boolean {
+  if (minStepsBetween <= 0 || values.length < 2) return true;
+  const minGap = minStepsBetween * step;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i]! - values[i - 1]! < minGap) return false;
+  }
+  return true;
+}
diff --git a/vue/primitives/src/internal/scale/ticks.ts b/vue/primitives/src/internal/scale/ticks.ts
new file mode 100644
index 0000000..09d53c5
--- /dev/null
+++ b/vue/primitives/src/internal/scale/ticks.ts
@@ -0,0 +1,341 @@
+import { getStepDecimals, roundToStep, scaleLinear } from './math';
+import { formatClock, formatFrames, framesToTimecode, secondsToFrames } from './timecode';
+
+/**
+ * A single axis tick: its domain `value`, projected pixel position `px`, whether
+ * it is a `major` (labelled / emphasised) tick, and its rendered `label`.
+ */
+export interface Tick {
+  value: number;
+  px: number;
+  major: boolean;
+  label: string;
+}
+
+/** Default upper bound on generated ticks before the step is coarsened. */
+const DEFAULT_MAX_TICKS = 1000;
+
+/** Default target pixel spacing between adjacent ticks. */
+const DEFAULT_TARGET_DENSITY = 64;
+
+/**
+ * Format callback for tick labels. Receives the (already step-cleaned) `value`
+ * and a small context describing the active `step`, its `decimals`, and whether
+ * the tick is `major`.
+ */
+export type TickFormatter = (value: number, ctx: { step: number; decimals: number; major: boolean }) => string;
+
+/** Shared geometry inputs for every tick generator. */
+interface BaseTickOptions {
+  /** Value-space extent `[start, end]` of the visible axis. */
+  domain: readonly [number, number];
+  /** Pixel-space extent `[start, end]` the domain projects onto. */
+  range: readonly [number, number];
+  /** Flip the value→pixel mapping (domain start maps to range end). @default false */
+  reverse?: boolean;
+  /** Desired pixel spacing between adjacent ticks. @default 64 */
+  targetDensity?: number;
+  /** Hard cap on candidate ticks; the step is coarsened until under it. @default 1000 */
+  maxTicks?: number;
+}
+
+/**
+ * Round `value` to the nearest "nice" number — a `1`, `2`, `5`, or `10` times a
+ * power of ten. With `round` false the result is rounded up (ceil semantics),
+ * producing a step no finer than `value`.
+ */
+export function niceNum(value: number, round: boolean): number {
+  if (value <= 0 || !Number.isFinite(value)) return 0;
+  const exponent = Math.floor(Math.log10(value));
+  const fraction = value / 10 ** exponent;
+
+  let niceFraction: number;
+  if (round) {
+    if (fraction < 1.5) niceFraction = 1;
+    else if (fraction < 3) niceFraction = 2;
+    else if (fraction < 7) niceFraction = 5;
+    else niceFraction = 10;
+  }
+  else if (fraction <= 1) niceFraction = 1;
+  else if (fraction <= 2) niceFraction = 2;
+  else if (fraction <= 5) niceFraction = 5;
+  else niceFraction = 10;
+
+  return niceFraction * 10 ** exponent;
+}
+
+/** Effective (possibly reversed) range tuple for projection. */
+function effectiveRange(range: readonly [number, number], reverse: boolean | undefined): [number, number] {
+  return reverse ? [range[1], range[0]] : [range[0], range[1]];
+}
+
+/**
+ * Coarsen `step` (by the next nice multiple) until the number of ticks spanning
+ * `[d0, d1]` drops below `maxTicks`. Guards against OOM on huge axes.
+ */
+function capStep(step: number, d0: number, d1: number, maxTicks: number): number {
+  let s = step;
+  while (s > 0 && (d1 - d0) / s > maxTicks) {
+    s = niceNum(s * 2, false);
+  }
+  return s;
+}
+
+/** Default minor subdivision count derived from the leading digit of `step`. */
+function defaultMinorSubdivisions(step: number): number {
+  const exponent = Math.floor(Math.log10(step));
+  const lead = Math.round(step / 10 ** exponent);
+  if (lead === 2) return 2;
+  if (lead === 5) return 5;
+  return 2;
+}
+
+/**
+ * Generate "nice" linearly-spaced ticks across the visible `domain`.
+ *
+ * Ticks are anchored to absolute step multiples (`start = floor(d0 / step) *
+ * step`) and walked by an integer index to avoid float drift / pan-jitter, then
+ * culled to the visible window. `major` ticks fall on a coarser nice multiple;
+ * minor ticks subdivide between majors. Labels default to the step-cleaned
+ * value (using {@link getStepDecimals} so artefacts like `1.3000001` never
+ * appear).
+ */
+export function niceTicks(opts: BaseTickOptions & {
+  /** Minor ticks per major interval. @default derived from step (2→2, 5→5, else 2) */
+  minorSubdivisions?: number;
+  /** Custom label formatter. */
+  format?: TickFormatter;
+}): Tick[] {
+  const { domain, range, reverse, format } = opts;
+  const targetDensity = opts.targetDensity ?? DEFAULT_TARGET_DENSITY;
+  const maxTicks = opts.maxTicks ?? DEFAULT_MAX_TICKS;
+
+  const d0 = Math.min(domain[0], domain[1]);
+  const d1 = Math.max(domain[0], domain[1]);
+  const span = d1 - d0;
+  if (span <= 0) return [];
+
+  const er = effectiveRange(range, reverse);
+  const pxSpan = Math.abs(range[1] - range[0]);
+
+  // Approximate tick count from the desired pixel density, then nice-round it.
+  const targetCount = Math.max(1, pxSpan / targetDensity);
+  const rawStep = span / targetCount;
+  let minorStep = niceNum(rawStep, true);
+  if (minorStep <= 0) minorStep = span;
+
+  minorStep = capStep(minorStep, d0, d1, maxTicks);
+  if (minorStep <= 0) return [];
+
+  const decimals = getStepDecimals(minorStep);
+  const minorSubdivisions = opts.minorSubdivisions ?? defaultMinorSubdivisions(minorStep);
+  const majorStep = minorStep * Math.max(1, minorSubdivisions);
+  const majorDecimals = getStepDecimals(majorStep);
+
+  const ticks: Tick[] = [];
+  const start = Math.floor(d0 / minorStep) * minorStep;
+  const count = Math.ceil((d1 - start) / minorStep);
+
+  for (let i = 0; i <= count; i++) {
+    const raw = start + i * minorStep;
+    const value = roundToStep(raw, minorStep, 0, decimals);
+    if (value < d0 - minorStep * 0.5 || value > d1 + minorStep * 0.5) continue;
+
+    // A tick is major when it lands on a major-step boundary.
+    const major = Math.abs(value / majorStep - Math.round(value / majorStep)) < 1e-9;
+    const step = major ? majorStep : minorStep;
+    const dec = major ? majorDecimals : decimals;
+    const label = major
+      ? (format ? format(value, { step, decimals: dec, major }) : String(value))
+      : '';
+
+    ticks.push({ value, px: scaleLinear(value, d0, d1, er[0], er[1]), major, label });
+  }
+
+  return ticks;
+}
+
+/** Human time ladder in seconds (1s → 1 day). */
+const TIME_LADDER = [1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200, 21600, 43200, 86400] as const;
+
+/** Pick the coarsest ladder rung whose pixel spacing meets `targetDensity`. */
+function pickRung(ladder: readonly number[], unitsPerPx: number, targetDensity: number): number {
+  for (const rung of ladder) {
+    if (rung / unitsPerPx >= targetDensity) return rung;
+  }
+  return ladder[ladder.length - 1]!;
+}
+
+/**
+ * Generate ticks on the human time ladder (seconds): `1, 2, 5, 10, 15, 30, 60,
+ * …, 86400`. The coarsest rung whose pixel spacing meets `targetDensity` is
+ * chosen; minute / hour / day boundaries are marked `major`. Labels default to
+ * {@link formatClock}.
+ */
+export function timeTicks(opts: BaseTickOptions & {
+  /** Custom label formatter (value in seconds). */
+  format?: TickFormatter;
+}): Tick[] {
+  const { domain, range, reverse, format } = opts;
+  const targetDensity = opts.targetDensity ?? DEFAULT_TARGET_DENSITY;
+  const maxTicks = opts.maxTicks ?? DEFAULT_MAX_TICKS;
+
+  const d0 = Math.min(domain[0], domain[1]);
+  const d1 = Math.max(domain[0], domain[1]);
+  const span = d1 - d0;
+  if (span <= 0) return [];
+
+  const er = effectiveRange(range, reverse);
+  const pxSpan = Math.abs(range[1] - range[0]);
+  const unitsPerPx = pxSpan > 0 ? span / pxSpan : span;
+
+  let step = pickRung(TIME_LADDER, unitsPerPx, targetDensity);
+  step = capStep(step, d0, d1, maxTicks);
+  if (step <= 0) return [];
+
+  const ticks: Tick[] = [];
+  const start = Math.floor(d0 / step) * step;
+  const count = Math.ceil((d1 - start) / step);
+
+  for (let i = 0; i <= count; i++) {
+    const value = start + i * step;
+    if (value < d0 - step * 0.5 || value > d1 + step * 0.5) continue;
+
+    // Major on minute / hour / day boundaries; when the step is itself a whole
+    // minute or coarser, promote hour (or day) boundaries to keep majors sparse.
+    const major = step >= 3600
+      ? value % 86400 === 0
+      : step >= 60
+        ? value % 3600 === 0
+        : value % 60 === 0;
+    const label = format ? format(value, { step, decimals: 0, major }) : formatClock(value);
+
+    ticks.push({ value, px: scaleLinear(value, d0, d1, er[0], er[1]), major, label });
+  }
+
+  return ticks;
+}
+
+/** Build a frame-based ladder seeded by `fps`. */
+function frameLadder(fps: number): number[] {
+  const half = Math.max(1, Math.round(fps / 2));
+  const base = [1, 2, 5, 10, half, Math.round(fps)];
+  const ladder: number[] = [];
+  for (const v of base) {
+    if (v > 0 && !ladder.includes(v)) ladder.push(v);
+  }
+  ladder.sort((a, b) => a - b);
+  // Extend in multiples of fps up to a day.
+  const f = Math.round(fps);
+  for (const mult of [2, 5, 10, 30, 60, 300, 600, 1800, 3600, 21600, 43200, 86400]) {
+    ladder.push(mult * f);
+  }
+  return ladder;
+}
+
+/**
+ * Generate timecode ticks. The ladder is computed in INTEGER FRAMES internally
+ * (the seconds domain is converted to frames via `fps` once), so positions
+ * never drift. Labels default to {@link framesToTimecode}. The `domain` /
+ * `range` remain in seconds.
+ */
+export function timecodeTicks(opts: BaseTickOptions & {
+  /** Frame rate used to convert the seconds domain into frames. */
+  fps: number;
+  /** Whether labels use drop-frame timecode. @default false */
+  dropFrame?: boolean;
+  /** Custom label formatter (value in seconds). */
+  format?: TickFormatter;
+}): Tick[] {
+  const { domain, range, reverse, fps, dropFrame, format } = opts;
+  const targetDensity = opts.targetDensity ?? DEFAULT_TARGET_DENSITY;
+  const maxTicks = opts.maxTicks ?? DEFAULT_MAX_TICKS;
+
+  const d0 = Math.min(domain[0], domain[1]);
+  const d1 = Math.max(domain[0], domain[1]);
+  if (d1 - d0 <= 0 || fps <= 0) return [];
+
+  const f0 = secondsToFrames(d0, fps);
+  const f1 = secondsToFrames(d1, fps);
+  const frameSpan = f1 - f0;
+  if (frameSpan <= 0) return [];
+
+  const er = effectiveRange(range, reverse);
+  const pxSpan = Math.abs(range[1] - range[0]);
+  const framesPerPx = pxSpan > 0 ? frameSpan / pxSpan : frameSpan;
+
+  const ladder = frameLadder(fps);
+  let stepFrames = pickRung(ladder, framesPerPx, targetDensity);
+  stepFrames = Math.round(capStep(stepFrames, f0, f1, maxTicks));
+  if (stepFrames <= 0) return [];
+
+  const fpsInt = Math.round(fps);
+  const ticks: Tick[] = [];
+  const startFrame = Math.floor(f0 / stepFrames) * stepFrames;
+  const count = Math.ceil((f1 - startFrame) / stepFrames);
+
+  for (let i = 0; i <= count; i++) {
+    const frame = startFrame + i * stepFrames;
+    if (frame < f0 - stepFrames * 0.5 || frame > f1 + stepFrames * 0.5) continue;
+
+    const seconds = frame / fps;
+    // Major on whole-second boundaries (or coarser when the step exceeds 1s).
+    const major = stepFrames >= fpsInt ? frame % (fpsInt * 60) === 0 : frame % fpsInt === 0;
+    const label = format
+      ? format(seconds, { step: stepFrames, decimals: 0, major })
+      : framesToTimecode(frame, fps, dropFrame);
+
+    ticks.push({ value: seconds, px: scaleLinear(seconds, d0, d1, er[0], er[1]), major, label });
+  }
+
+  return ticks;
+}
+
+/** Integer frame ladder (frames), scaled until spacing meets density. */
+const FRAME_LADDER = [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 25000, 50000, 100000] as const;
+
+/**
+ * Generate an integer-frame axis. The `domain` / `range` are in frames; the step
+ * is forced to integer ladder multiples (`1, 2, 5, 10, 25, 50, 100, …`) scaled
+ * so spacing meets `targetDensity`. Labels default to {@link formatFrames}.
+ */
+export function frameTicks(opts: BaseTickOptions & {
+  /** Frame rate; when given, ticks at one-second multiples are marked `major`. */
+  fps?: number;
+  /** Custom label formatter (value in frames). */
+  format?: TickFormatter;
+}): Tick[] {
+  const { domain, range, reverse, fps, format } = opts;
+  const targetDensity = opts.targetDensity ?? DEFAULT_TARGET_DENSITY;
+  const maxTicks = opts.maxTicks ?? DEFAULT_MAX_TICKS;
+
+  const d0 = Math.min(domain[0], domain[1]);
+  const d1 = Math.max(domain[0], domain[1]);
+  const span = d1 - d0;
+  if (span <= 0) return [];
+
+  const er = effectiveRange(range, reverse);
+  const pxSpan = Math.abs(range[1] - range[0]);
+  const framesPerPx = pxSpan > 0 ? span / pxSpan : span;
+
+  let step = pickRung(FRAME_LADDER, framesPerPx, targetDensity);
+  step = Math.round(capStep(step, d0, d1, maxTicks));
+  if (step <= 0) return [];
+
+  const fpsInt = fps ? Math.round(fps) : 0;
+  const ticks: Tick[] = [];
+  const start = Math.floor(d0 / step) * step;
+  const count = Math.ceil((d1 - start) / step);
+
+  for (let i = 0; i <= count; i++) {
+    const value = Math.round(start + i * step);
+    if (value < d0 - step * 0.5 || value > d1 + step * 0.5) continue;
+
+    const major = fpsInt > 0 ? value % fpsInt === 0 : value % (step * 5) === 0;
+    const label = format ? format(value, { step, decimals: 0, major }) : formatFrames(value);
+
+    ticks.push({ value, px: scaleLinear(value, d0, d1, er[0], er[1]), major, label });
+  }
+
+  return ticks;
+}
diff --git a/vue/primitives/src/internal/scale/timecode.ts b/vue/primitives/src/internal/scale/timecode.ts
new file mode 100644
index 0000000..2ae6139
--- /dev/null
+++ b/vue/primitives/src/internal/scale/timecode.ts
@@ -0,0 +1,102 @@
+/**
+ * Pad a non-negative integer to a fixed width with leading zeros.
+ */
+function pad(value: number, width = 2): string {
+  return String(value).padStart(width, '0');
+}
+
+/**
+ * Convert a duration in seconds to a whole number of frames at `fps`.
+ */
+export function secondsToFrames(seconds: number, fps: number): number {
+  return Math.round(seconds * fps);
+}
+
+/**
+ * Convert a whole number of frames back to seconds at `fps`.
+ */
+export function framesToSeconds(frames: number, fps: number): number {
+  return fps === 0 ? 0 : frames / fps;
+}
+
+/**
+ * Format an integer frame count as an SMPTE timecode string.
+ *
+ * Returns `"HH:MM:SS:FF"` for non-drop-frame timecode and `"HH:MM:SS;FF"`
+ * (semicolon separator) when `dropFrame` is `true`. Drop-frame uses the integer
+ * standard algorithm: `dropFrames = round(fps * 0.066666)` (2 for ~30, 4 for
+ * ~60), dropping that many frame numbers every minute except every 10th minute.
+ * The `HH:MM:SS:FF` breakdown uses `timeBase = round(fps)`.
+ *
+ * @param frames Integer frame number (clamped at 0 for negative input).
+ * @param fps Frame rate (e.g. `29.97`, `30`, `59.94`, `60`).
+ * @param dropFrame Whether to apply drop-frame compensation. @default false
+ */
+export function framesToTimecode(frames: number, fps: number, dropFrame = false): string {
+  let frameNumber = frames < 0 ? 0 : Math.round(frames);
+  const timeBase = Math.round(fps);
+
+  const sep = dropFrame ? ';' : ':';
+
+  if (dropFrame && timeBase > 0) {
+    const dropFrames = Math.round(fps * 0.066666);
+    const framesPerMinute = timeBase * 60 - dropFrames;
+    const framesPer10Minutes = timeBase * 600 - dropFrames * 9;
+
+    const tenMinutes = Math.floor(frameNumber / framesPer10Minutes);
+    let remainder = frameNumber % framesPer10Minutes;
+
+    // The first minute of each 10-minute block has no dropped frames.
+    if (remainder >= dropFrames) {
+      remainder -= dropFrames;
+      const minuteWithin = Math.floor(remainder / framesPerMinute);
+      frameNumber += dropFrames * 9 * tenMinutes + dropFrames * minuteWithin;
+    }
+    else {
+      frameNumber += dropFrames * 9 * tenMinutes;
+    }
+  }
+
+  const ff = frameNumber % timeBase;
+  const totalSeconds = Math.floor(frameNumber / timeBase);
+  const ss = totalSeconds % 60;
+  const mm = Math.floor(totalSeconds / 60) % 60;
+  const hh = Math.floor(totalSeconds / 3600);
+
+  return `${pad(hh)}:${pad(mm)}:${pad(ss)}${sep}${pad(ff)}`;
+}
+
+/**
+ * Format a duration in seconds as an SMPTE timecode string at `fps`.
+ *
+ * Thin wrapper over {@link framesToTimecode}.
+ *
+ * @param dropFrame Whether to apply drop-frame compensation. @default false
+ */
+export function formatTimecode(seconds: number, fps: number, dropFrame = false): string {
+  return framesToTimecode(secondsToFrames(seconds, fps), fps, dropFrame);
+}
+
+/**
+ * Format a duration in seconds as a wall-clock string.
+ *
+ * Renders `"M:SS"` under an hour and `"H:MM:SS"` at or above an hour, with
+ * zero-padded minutes/seconds.
+ */
+export function formatClock(seconds: number): string {
+  const sign = seconds < 0 ? '-' : '';
+  const total = Math.floor(Math.abs(seconds));
+  const ss = total % 60;
+  const mm = Math.floor(total / 60) % 60;
+  const hh = Math.floor(total / 3600);
+
+  if (hh > 0) return `${sign}${hh}:${pad(mm)}:${pad(ss)}`;
+  return `${sign}${mm}:${pad(ss)}`;
+}
+
+/**
+ * Format an integer frame count as a localized frame-number string.
+ */
+export function formatFrames(frames: number): string {
+  return Math.round(frames).toLocaleString('en-US');
+}
diff --git a/vue/primitives/src/internal/scale/useScale.ts b/vue/primitives/src/internal/scale/useScale.ts
new file mode 100644
index 0000000..5bbf2a1
--- /dev/null
+++ b/vue/primitives/src/internal/scale/useScale.ts
@@ -0,0 +1,190 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { computed, toValue } from 'vue';
+import { clamp } from '@robonen/stdlib';
+import { getStepDecimals, roundToStep, scaleLinear } from './math';
+import type { Tick } from './ticks';
+import { frameTicks, niceTicks, timeTicks, timecodeTicks } from './ticks';
+
+/** Axis orientation. `'vertical'` defaults to value-up (domain start at range end). */
+export type ScaleOrientation = 'horizontal' | 'vertical';
+
+/** Which tick generator the composable dispatches to. */
+export type TickKind = 'nice' | 'time' | 'timecode' | 'frame' | 'none';
+
+/**
+ * Reactive options for {@link useScale}. Every value may be a ref, getter, or
+ * plain value (resolved via `toValue` on read).
+ */
+export interface UseScaleOptions {
+  /** Value-space extent `[start, end]`. */
+  domain: MaybeRefOrGetter<readonly [number, number]>;
+  /** Pixel-space extent `[start, end]`. */
+  range: MaybeRefOrGetter<readonly [number, number]>;
+  /** Axis orientation. @default 'horizontal' */
+  orientation?: MaybeRefOrGetter<ScaleOrientation>;
+  /** Flip the mapping independent of orientation. @default false */
+  inverted?: MaybeRefOrGetter<boolean>;
+  /** Right-to-left; flips horizontal axes only. @default false */
+  rtl?: MaybeRefOrGetter<boolean>;
+  /** Clamp `scale`/`invert` outputs to the bounds. @default false */
+  clamp?: MaybeRefOrGetter<boolean>;
+  /** Snap step for {@link roundValue}. @default undefined (no snapping) */
+  step?: MaybeRefOrGetter<number | undefined>;
+  /** Lower clamp bound; falls back to `domain[0]`. @default undefined */
+  min?: MaybeRefOrGetter<number | undefined>;
+  /** Upper clamp bound; falls back to `domain[1]`. @default undefined */
+  max?: MaybeRefOrGetter<number | undefined>;
+  /** Tick generator selector. @default 'nice' */
+  tickKind?: MaybeRefOrGetter<TickKind>;
+  /** Extra options forwarded to the active tick generator. @default {} */
+  tickOptions?: MaybeRefOrGetter<Record<string, unknown>>;
+}
+
+/** Reactive scale returned by {@link useScale}. */
+export interface UseScaleReturn {
+  /** Project a value to a pixel position. Stable function identity. */
+  scale: (value: number) => number;
+  /** Invert a pixel position back to a value. Stable function identity. */
+  invert: (px: number) => number;
+  /** Clamp a value to `[min ?? d0, max ?? d1]`. */
+  clampValue: (value: number) => number;
+  /** Snap a value to `step` then clamp (no-op when `step` is undefined). */
+  roundValue: (value: number) => number;
+  /** All ticks for the current geometry. */
+  ticks: ComputedRef<Tick[]>;
+  /** Ticks where `major` is true. */
+  majorTicks: ComputedRef<Tick[]>;
+  /** Ticks where `major` is false. */
+  minorTicks: ComputedRef<Tick[]>;
+  /** Absolute pixels-per-value-unit; guards divide-by-zero. */
+  pxPerUnit: ComputedRef<number>;
+  /** The resolved domain. */
+  domain: ComputedRef<readonly [number, number]>;
+  /** The resolved range. */
+  range: ComputedRef<readonly [number, number]>;
+}
+
+/**
+ * Compose orientation / inverted / rtl into the effective reverse flag.
+ *
+ * Three independent flips XOR-composed: vertical reverses (value-up), `inverted`
+ * reverses unconditionally, and `rtl` reverses horizontal axes only.
+ */
+function computeReverse(orientation: ScaleOrientation, inverted: boolean, rtl: boolean): boolean {
+  return (orientation === 'vertical') !== inverted !== (rtl && orientation === 'horizontal');
+}
+
+/**
+ * Reactive value↔pixel scale with tick generation for rulers, axes, histograms,
+ * and waveforms.
+ *
+ * `scale`/`invert` are stable closures that read the current domain/range/flips
+ * at call time (no per-change projection rebuild), so they stay cheap on the
+ * pointer hot path.
+ */
+export function useScale(options: UseScaleOptions): UseScaleReturn {
+  const domain = computed<readonly [number, number]>(() => toValue(options.domain));
+  const range = computed<readonly [number, number]>(() => toValue(options.range));
+
+  const reverse = computed(() => computeReverse(
+    toValue(options.orientation) ?? 'horizontal',
+    toValue(options.inverted) ?? false,
+    toValue(options.rtl) ?? false,
+  ));
+
+  // Cache decimals per step value to avoid re-deriving on every roundValue call.
+  const decimals = computed(() => {
+    const step = toValue(options.step);
+    return step !== undefined ? getStepDecimals(step) : 0;
+  });
+
+  const scale = (value: number): number => {
+    const [d0, d1] = domain.value;
+    const [r0, r1] = range.value;
+    const [er0, er1] = reverse.value ? [r1, r0] : [r0, r1];
+    const px = scaleLinear(value, d0, d1, er0, er1);
+    if (toValue(options.clamp)) {
+      const lo = Math.min(er0, er1);
+      const hi = Math.max(er0, er1);
+      return clamp(px, lo, hi);
+    }
+    return px;
+  };
+
+  const invert = (px: number): number => {
+    const [d0, d1] = domain.value;
+    const [r0, r1] = range.value;
+    const [er0, er1] = reverse.value ? [r1, r0] : [r0, r1];
+    const value = scaleLinear(px, er0, er1, d0, d1);
+    if (toValue(options.clamp)) {
+      const lo = Math.min(d0, d1);
+      const hi = Math.max(d0, d1);
+      return clamp(value, lo, hi);
+    }
+    return value;
+  };
+
+  const clampValue = (value: number): number => {
+    const [d0, d1] = domain.value;
+    const lo = toValue(options.min) ?? d0;
+    const hi = toValue(options.max) ?? d1;
+    return clamp(value, lo, hi);
+  };
+
+  const roundValue = (value: number): number => {
+    const step = toValue(options.step);
+    if (step === undefined) return clampValue(value);
+    const [d0] = domain.value;
+    const min = toValue(options.min) ?? d0;
+    // Round THEN clamp.
+    return clampValue(roundToStep(value, step, min, decimals.value));
+  };
+
+  const pxPerUnit = computed(() => {
+    const [d0, d1] = domain.value;
+    const [r0, r1] = range.value;
+    const dSpan = d1 - d0;
+    if (dSpan === 0) return 0;
+    return Math.abs(r1 - r0) / Math.abs(dSpan);
+  });
+
+  const ticks = computed<Tick[]>(() => {
+    const kind = (toValue(options.tickKind) ?? 'nice') as TickKind;
+    if (kind === 'none') return [];
+
+    const d = domain.value;
+    const r = range.value;
+    if (r[1] - r[0] === 0) return [];
+
+    const extra = toValue(options.tickOptions) ?? {};
+    const base = { domain: d, range: r, reverse: reverse.value, ...extra };
+
+    switch (kind) {
+      case 'time':
+        return timeTicks(base);
+      case 'timecode':
+        return timecodeTicks(base as typeof base & { fps: number });
+      case 'frame':
+        return frameTicks(base);
+      case 'nice':
+      default:
+        return niceTicks(base);
+    }
+  });
+
+  const majorTicks = computed(() => ticks.value.filter(t => t.major));
+  const minorTicks = computed(() => ticks.value.filter(t => !t.major));
+
+  return {
+    scale,
+    invert,
+    clampValue,
+    roundValue,
+    ticks,
+    majorTicks,
+    minorTicks,
+    pxPerUnit,
+    domain,
+    range,
+  };
+}
diff --git a/vue/primitives/src/internal/snapping/__test__/snapping.test.ts b/vue/primitives/src/internal/snapping/__test__/snapping.test.ts
new file mode 100644
index 0000000..7d281d9
--- /dev/null
+++ b/vue/primitives/src/internal/snapping/__test__/snapping.test.ts
@@ -0,0 +1,293 @@
+import { describe, expect, it } from 'vitest';
+import { ref } from 'vue';
+import type { SnapTarget } from '..';
+import {
+  applyHysteresis,
+  edgeTargets,
+  findNearestTarget,
+  gridTargets,
+  pointTargets,
+  useSnapping,
+} from '..';
+
+function target(px: number, kind: SnapTarget['kind'] = 'grid', id?: string): SnapTarget {
+  return { axis: 'x', px, value: px, kind, id };
+}
+
+describe('findNearestTarget', () => {
+  it('picks the nearest target within threshold', () => {
+    const targets = [target(0), target(10), target(25)];
+    const { index, deltaPx } = findNearestTarget(12, targets, 8);
+    expect(index).toBe(1);
+    // target.px - targetPx = 10 - 12 = -2
+    expect(deltaPx).toBe(-2);
+  });
+
+  it('returns -1 / Infinity when none are in range', () => {
+    const targets = [target(0), target(100)];
+    const { index, deltaPx } = findNearestTarget(50, targets, 8);
+    expect(index).toBe(-1);
+    expect(deltaPx).toBe(Infinity);
+  });
+
+  it('handles an empty target list', () => {
+    const { index, deltaPx } = findNearestTarget(5, [], 8);
+    expect(index).toBe(-1);
+    expect(deltaPx).toBe(Infinity);
+  });
+
+  it('lets a higher-priority kind win within relaxPx even if farther', () => {
+    // grid at 10 (dist 2), playhead at 14 (dist 2 vs target 12)... make playhead farther.
+    const targets = [
+      target(10, 'grid'), // dist from 12 = 2
+      target(15, 'playhead'), // dist from 12 = 3
+    ];
+    const priority = { order: ['playhead', 'grid'] as Array<SnapTarget['kind']>, relaxPx: 2 };
+    const { index } = findNearestTarget(12, targets, 8, priority);
+    // playhead is 1px farther but within relaxPx=2, and higher priority -> wins.
+    expect(index).toBe(1);
+    expect(targets[index]!.kind).toBe('playhead');
+  });
+
+  it('does NOT let a higher-priority kind win beyond relaxPx', () => {
+    const targets = [
+      target(10, 'grid'), // dist 2
+      target(18, 'playhead'), // dist 6
+    ];
+    const priority = { order: ['playhead', 'grid'] as Array<SnapTarget['kind']>, relaxPx: 2 };
+    const { index } = findNearestTarget(12, targets, 8, priority);
+    // playhead is 4px farther (> relaxPx 2) -> nearest grid wins.
+    expect(targets[index]!.kind).toBe('grid');
+  });
+
+  it('skips excluded ids (string)', () => {
+    const targets = [target(11, 'edge', 'self'), target(20, 'edge', 'other')];
+    const { index } = findNearestTarget(12, targets, 10, undefined, 'self');
+    expect(index).toBe(1);
+    expect(targets[index]!.id).toBe('other');
+  });
+
+  it('skips excluded ids (set)', () => {
+    const targets = [target(11, 'edge', 'a'), target(13, 'edge', 'b'), target(20, 'edge', 'c')];
+    const exclude = new Set(['a', 'b']);
+    const { index } = findNearestTarget(12, targets, 10, undefined, exclude);
+    expect(targets[index]!.id).toBe('c');
+  });
+
+  it('widens the locked target threshold by hysteresisPx', () => {
+    // locked target at 0, candidate at 9. Base threshold 8 would miss it,
+    // but hysteresisPx 4 widens reach to 12 -> hit.
+    const targets = [target(0, 'edge', 'locked')];
+    const miss = findNearestTarget(9, targets, 8);
+    expect(miss.index).toBe(-1);
+    const hit = findNearestTarget(9, targets, 8, undefined, undefined, 'locked', 4);
+    expect(hit.index).toBe(0);
+  });
+});
+
+describe('applyHysteresis', () => {
+  it('takes a fresh lock when there is no prior lock', () => {
+    expect(applyHysteresis(undefined, 'a', 3, Infinity, 8, 0.5)).toBe(true);
+  });
+
+  it('keeps the lock when best is still the locked target', () => {
+    expect(applyHysteresis('a', 'a', 5, 5, 8, 0.5)).toBe(true);
+  });
+
+  it('does not steal when prior lock is in band and new best is not strictly closer', () => {
+    // prevDist 4 within release band 8*1.5=12; bestDist 4 not < 4 -> keep lock.
+    expect(applyHysteresis('a', 'b', 4, 4, 8, 0.5)).toBe(false);
+  });
+
+  it('steals when the new best is strictly closer and prior still in band', () => {
+    expect(applyHysteresis('a', 'b', 2, 5, 8, 0.5)).toBe(true);
+  });
+
+  it('releases the lock once the prior target leaves the widened band', () => {
+    // releaseBand = 8 * 1.5 = 12; prevDist 13 > 12 -> release/steal even though farther.
+    expect(applyHysteresis('a', 'b', 20, 13, 8, 0.5)).toBe(true);
+  });
+
+  it('returns false when nothing is in range', () => {
+    expect(applyHysteresis('a', undefined, Infinity, Infinity, 8, 0.5)).toBe(false);
+  });
+});
+
+describe('gridTargets', () => {
+  it('anchors lines at floor(domainStart/step)*step and projects', () => {
+    const project = (v: number) => v * 2; // px = value * 2
+    const targets = gridTargets(3, 12, 5, project, 'x');
+    // anchor = floor(3/5)*5 = 0; first line >= 3 is 5, then 10.
+    expect(targets.map(t => t.value)).toEqual([5, 10]);
+    expect(targets.map(t => t.px)).toEqual([10, 20]);
+    expect(targets.every(t => t.kind === 'grid' && t.axis === 'x')).toBe(true);
+  });
+
+  it('includes a line exactly at domainStart when aligned', () => {
+    const targets = gridTargets(10, 20, 5, v => v, 'x');
+    expect(targets.map(t => t.value)).toEqual([10, 15, 20]);
+  });
+
+  it('returns empty for non-positive or non-finite step', () => {
+    expect(gridTargets(0, 10, 0, v => v, 'x')).toEqual([]);
+    expect(gridTargets(0, 10, -1, v => v, 'x')).toEqual([]);
+    expect(gridTargets(0, 10, Infinity, v => v, 'x')).toEqual([]);
+  });
+
+  it('returns empty when domainEnd precedes domainStart', () => {
+    expect(gridTargets(20, 10, 5, v => v, 'x')).toEqual([]);
+  });
+});
+
+describe('edgeTargets', () => {
+  it('emits left/right/center on x', () => {
+    const rects = [{ left: 0, right: 10, top: 0, bottom: 4, id: 'clip' }];
+    const targets = edgeTargets(rects, 'x', v => v);
+    expect(targets.map(t => [t.value, t.kind])).toEqual([
+      [0, 'edge'],
+      [10, 'edge'],
+      [5, 'center'],
+    ]);
+    expect(targets.every(t => t.id === 'clip' && t.axis === 'x')).toBe(true);
+  });
+
+  it('emits top/bottom/center on y', () => {
+    const rects = [{ left: 0, right: 10, top: 2, bottom: 8 }];
+    const targets = edgeTargets(rects, 'y', v => v);
+    expect(targets.map(t => t.value)).toEqual([2, 8, 5]);
+  });
+});
+
+describe('pointTargets', () => {
+  it('builds projected targets with optional ids', () => {
+    const targets = pointTargets([10, 20], 'marker', 'x', v => v * 3, ['m1', 'm2']);
+    expect(targets.map(t => [t.value, t.px, t.id, t.kind])).toEqual([
+      [10, 30, 'm1', 'marker'],
+      [20, 60, 'm2', 'marker'],
+    ]);
+  });
+
+  it('omits ids when not supplied', () => {
+    const targets = pointTargets([5], 'stop', 'x', v => v);
+    expect(targets[0]!.id).toBeUndefined();
+  });
+});
+
+describe('useSnapping', () => {
+  const targets: SnapTarget[] = [
+    { axis: 'x', px: 100, value: 1, kind: 'grid' },
+    { axis: 'x', px: 200, value: 2, kind: 'grid' },
+  ];
+
+  it('snaps when within threshold (identity projection)', () => {
+    const engine = useSnapping({ targets, thresholdPx: 8 });
+    const r = engine.snap1d(104); // 4px from px=100 -> snaps to value 1
+    expect(r.snapped).toBe(true);
+    expect(r.value).toBe(1);
+    expect(r.target?.px).toBe(100);
+    expect(r.deltaPx).toBe(-4);
+    expect(engine.isSnapped.value).toBe(true);
+    expect(engine.activeTargets.value).toHaveLength(1);
+  });
+
+  it('passes through unchanged when out of range', () => {
+    const engine = useSnapping({ targets, thresholdPx: 8 });
+    const r = engine.snap1d(150);
+    expect(r.snapped).toBe(false);
+    expect(r.value).toBe(150);
+    expect(r.target).toBeNull();
+    expect(r.deltaPx).toBe(0);
+    expect(engine.isSnapped.value).toBe(false);
+    expect(engine.activeTargets.value).toEqual([]);
+  });
+
+  it('passes through unchanged when disabled', () => {
+    const enabled = ref(false);
+    const engine = useSnapping({ targets, thresholdPx: 8, enabled });
+    const r = engine.snap1d(104);
+    expect(r.snapped).toBe(false);
+    expect(r.value).toBe(104);
+    expect(engine.isSnapped.value).toBe(false);
+  });
+
+  it('reacts to a ref/getter threshold', () => {
+    const thresholdPx = ref(2);
+    const engine = useSnapping({ targets, thresholdPx });
+    expect(engine.snap1d(104).snapped).toBe(false); // 4 > 2
+    thresholdPx.value = 8;
+    expect(engine.snap1d(104).snapped).toBe(true); // 4 <= 8
+  });
+
+  it('bypasses for a single call without disabling', () => {
+    const engine = useSnapping({ targets, thresholdPx: 8 });
+    const r = engine.snap1d(104, { bypass: true });
+    expect(r.snapped).toBe(false);
+    expect(r.value).toBe(104);
+    // a normal call still snaps
+    expect(engine.snap1d(104).snapped).toBe(true);
+  });
+
+  it('excludes a target id per call', () => {
+    const withId: SnapTarget[] = [
+      { axis: 'x', px: 100, value: 1, kind: 'edge', id: 'self' },
+      { axis: 'x', px: 110, value: 1.1, kind: 'edge', id: 'other' },
+    ];
+    const engine = useSnapping({ targets: withId, thresholdPx: 20 });
+    const r = engine.snap1d(102, { exclude: 'self' });
+    expect(r.target?.id).toBe('other');
+  });
+
+  it('uses the consumer-supplied projection', () => {
+    // values are domain units; project maps value -> px = value * 100.
+    const domainTargets: SnapTarget[] = [{ axis: 'x', px: 100, value: 1, kind: 'grid' }];
+    const engine = useSnapping({
+      targets: domainTargets,
+      thresholdPx: 8,
+      project: value => value * 100,
+    });
+    // candidate value 1.05 -> px 105, 5px from target px 100 -> snaps to value 1.
+    const r = engine.snap1d(1.05);
+    expect(r.snapped).toBe(true);
+    expect(r.value).toBe(1);
+  });
+
+  it('snap2d resolves each axis independently', () => {
+    const xy: SnapTarget[] = [
+      { axis: 'x', px: 100, value: 1, kind: 'grid' },
+      { axis: 'y', px: 50, value: 9, kind: 'grid' },
+    ];
+    const engine = useSnapping({ targets: xy, thresholdPx: 8, axis: '2d' });
+    const r = engine.snap2d({ x: 104, y: 500 });
+    expect(r.snappedX).toBe(true);
+    expect(r.point.x).toBe(1);
+    expect(r.snappedY).toBe(false);
+    expect(r.point.y).toBe(500);
+    expect(engine.activeTargets.value).toHaveLength(1);
+  });
+
+  it('reset clears snapped/active state', () => {
+    const engine = useSnapping({ targets, thresholdPx: 8 });
+    engine.snap1d(104);
+    expect(engine.isSnapped.value).toBe(true);
+    engine.reset();
+    expect(engine.isSnapped.value).toBe(false);
+    expect(engine.activeTargets.value).toEqual([]);
+  });
+
+  it('keeps a locked target sticky across drifting calls (hysteresis)', () => {
+    // two close targets; once snapped to the first, small drift toward the
+    // second should not immediately flip while the first stays in the band.
+    const close: SnapTarget[] = [
+      { axis: 'x', px: 100, value: 1, kind: 'grid', id: 'a' },
+      { axis: 'x', px: 108, value: 2, kind: 'grid', id: 'b' },
+    ];
+    const engine = useSnapping({ targets: close, thresholdPx: 6, hysteresisRatio: 1 });
+    // 102 -> nearest 'a' (dist 2) vs 'b' (dist 6, out of base range) -> locks 'a'.
+    expect(engine.snap1d(102).target?.id).toBe('a');
+    // drift to 105: 'a' dist 5, 'b' dist 3. 'b' is closer but 'a' is still in the
+    // widened release band -> hysteresis keeps 'a' (b not strictly closer? it is,
+    // so it should steal only if strictly closer). Here b IS strictly closer.
+    // Use a value where b is NOT strictly closer to prove stickiness:
+    expect(engine.snap1d(104).target?.id).toBe('a'); // a dist 4, b dist 4 -> keep a
+  });
+});
diff --git a/vue/primitives/src/internal/snapping/context.ts b/vue/primitives/src/internal/snapping/context.ts
new file mode 100644
index 0000000..ce50464
--- /dev/null
+++ b/vue/primitives/src/internal/snapping/context.ts
@@ -0,0 +1,35 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { UseSnappingReturn } from './useSnapping';
+
+/**
+ * Shared snapping context a Root (e.g. `TimelineRoot`, `CropRoot`) provides so
+ * every descendant handle drives the *same* engine — one source of truth for
+ * locked targets, threshold, and the enable switch.
+ */
+export interface SnappingContext {
+  /** The shared snap engine. */
+  engine: UseSnappingReturn;
+  /** Master enable switch, reactive and writable by the Root. */
+  enabled: Ref<boolean>;
+  /** Snap radius in pixels, reactive and writable by the Root. */
+  thresholdPx: Ref<number>;
+}
+
+const ctx = useContextFactory<SnappingContext>('SnappingContext');
+
+/**
+ * Provide a {@link SnappingContext} to descendants. Call from a Root setup.
+ */
+export const provideSnappingContext = ctx.provide;
+
+/**
+ * Inject the shared {@link SnappingContext}. Unlike the strict factory default,
+ * this returns `null` when no Root provided one — so a handle can run
+ * standalone with its own {@link useSnapping} engine instead of throwing.
+ */
+export function useSnappingContext(): SnappingContext | null {
+  // Passing an explicit `null` fallback makes the factory return it (instead of
+  // throwing) when no provider exists upward in the tree.
+  return ctx.inject(null as unknown as SnappingContext) ?? null;
+}
diff --git a/vue/primitives/src/internal/snapping/index.ts b/vue/primitives/src/internal/snapping/index.ts
new file mode 100644
index 0000000..a29adb9
--- /dev/null
+++ b/vue/primitives/src/internal/snapping/index.ts
@@ -0,0 +1,30 @@
+export type {
+  Point,
+  SnapKind,
+  SnapPriority,
+  SnapResult1D,
+  SnapResult2D,
+  SnapTarget,
+} from './types';
+
+export {
+  applyHysteresis,
+  edgeTargets,
+  findNearestTarget,
+  gridTargets,
+  pointTargets,
+} from './snap';
+
+export { useSnapping } from './useSnapping';
+export type {
+  SnapAxisMode,
+  SnapCallContext,
+  SnappingOptions,
+  UseSnappingReturn,
+} from './useSnapping';
+
+export {
+  provideSnappingContext,
+  useSnappingContext,
+} from './context';
+export type { SnappingContext } from './context';
diff --git a/vue/primitives/src/internal/snapping/snap.ts b/vue/primitives/src/internal/snapping/snap.ts
new file mode 100644
index 0000000..8a5699e
--- /dev/null
+++ b/vue/primitives/src/internal/snapping/snap.ts
@@ -0,0 +1,234 @@
+import type { SnapKind, SnapPriority, SnapTarget } from './types';
+
+/**
+ * Rank of `kind` within a priority order: lower number = higher priority.
+ * Kinds not listed sort after every listed kind (and tie among themselves).
+ */
+function priorityRank(kind: SnapKind, order: SnapKind[] | undefined): number {
+  if (order === undefined) return 0;
+  const i = order.indexOf(kind);
+  return i === -1 ? order.length : i;
+}
+
+/** Whether `id` is excluded, accepting a single id or a set of ids. */
+function isExcluded(id: string | undefined, exclude: string | Set<string> | undefined): boolean {
+  if (id === undefined || exclude === undefined) return false;
+  return typeof exclude === 'string' ? id === exclude : exclude.has(id);
+}
+
+/**
+ * Single-pass nearest-target search within `thresholdPx`, honoring priority
+ * order. A higher-priority {@link SnapKind} can win even when a few pixels
+ * farther than the closest candidate, bounded by `priority.relaxPx`. Targets
+ * whose `id` is in `excludeId` are skipped (e.g. a clip snapping to itself).
+ *
+ * When `lockedId` matches a candidate, its effective threshold is widened by
+ * `hysteresisPx` so an already-snapped handle stays sticky and resists
+ * flickering as the pointer drifts near the edge of the snap band.
+ *
+ * Allocation-free. Returns `{ index: -1, deltaPx: Infinity }` when no target is
+ * in range.
+ *
+ * @param targetPx Pixel position being tested (the dragged edge/handle).
+ * @param targets Candidate targets (mixed axes allowed; caller pre-filters axis).
+ * @param thresholdPx Base snap radius in pixels.
+ * @param priority Optional kind ordering + relax band for tie-breaking.
+ * @param excludeId Id (or set) to skip.
+ * @param lockedId Currently locked target id, widened by `hysteresisPx`.
+ * @param hysteresisPx Extra radius granted to the locked target. @default 0
+ */
+export function findNearestTarget(
+  targetPx: number,
+  targets: SnapTarget[],
+  thresholdPx: number,
+  priority?: SnapPriority,
+  excludeId?: string | Set<string>,
+  lockedId?: string,
+  hysteresisPx = 0,
+): { index: number; deltaPx: number } {
+  const order = priority?.order;
+  const relaxPx = priority?.relaxPx ?? 0;
+
+  let bestIndex = -1;
+  let bestDist = Infinity;
+  let bestSignedDelta = Infinity;
+  let bestRank = Infinity;
+
+  for (let i = 0; i < targets.length; i++) {
+    const t = targets[i]!;
+    if (isExcluded(t.id, excludeId)) continue;
+
+    // Sticky targets earn a wider capture radius while they hold the lock.
+    const reach = lockedId !== undefined && t.id === lockedId
+      ? thresholdPx + hysteresisPx
+      : thresholdPx;
+
+    const signedDelta = t.px - targetPx;
+    const dist = signedDelta < 0 ? -signedDelta : signedDelta;
+    if (dist > reach) continue;
+
+    if (bestIndex === -1) {
+      bestIndex = i;
+      bestDist = dist;
+      bestSignedDelta = signedDelta;
+      bestRank = priorityRank(t.kind, order);
+      continue;
+    }
+
+    const rank = priorityRank(t.kind, order);
+    let wins: boolean;
+    if (order === undefined) {
+      // Pure nearest.
+      wins = dist < bestDist;
+    }
+    else if (rank < bestRank) {
+      // Higher priority: wins outright if within the relax band of the best.
+      wins = dist <= bestDist + relaxPx;
+    }
+    else if (rank > bestRank) {
+      // Lower priority: may only win if strictly nearer beyond the relax band.
+      wins = dist + relaxPx < bestDist;
+    }
+    else {
+      // Same priority: nearest wins.
+      wins = dist < bestDist;
+    }
+
+    if (wins) {
+      bestIndex = i;
+      bestDist = dist;
+      bestSignedDelta = signedDelta;
+      bestRank = rank;
+    }
+  }
+
+  return { index: bestIndex, deltaPx: bestIndex === -1 ? Infinity : bestSignedDelta };
+}
+
+/**
+ * Pure hysteresis gate: decides whether a newly-computed best target should
+ * steal the lock from `prevLockedId`.
+ *
+ * - When there is no prior lock, any best target takes it.
+ * - When the prior lock is still the best candidate, it keeps the lock.
+ * - When a different target is now best, it must be *strictly closer* than the
+ *   prior lock's current distance — and the prior lock only releases once the
+ *   pointer leaves a release band widened to `thresholdPx * (1 + hysteresisRatio)`.
+ *
+ * This keeps a snapped handle from chattering between two adjacent targets.
+ *
+ * @param prevLockedId Previously locked target id (`undefined` if none).
+ * @param bestId Id of the current best candidate (`undefined` if none in range).
+ * @param bestDistPx Distance of the current best candidate, in pixels.
+ * @param prevDistPx Distance of `prevLockedId` this frame (`Infinity` if gone).
+ * @param thresholdPx Base snap radius in pixels.
+ * @param hysteresisRatio Fraction of `thresholdPx` added to the release band.
+ */
+export function applyHysteresis(
+  prevLockedId: string | undefined,
+  bestId: string | undefined,
+  bestDistPx: number,
+  prevDistPx: number,
+  thresholdPx: number,
+  hysteresisRatio: number,
+): boolean {
+  // Nothing in range — best (if any) takes a fresh lock.
+  if (bestId === undefined) return false;
+
+  // No prior lock, or the best candidate *is* the prior lock: take/keep it.
+  if (prevLockedId === undefined || bestId === prevLockedId) return true;
+
+  const releaseBand = thresholdPx * (1 + hysteresisRatio);
+
+  // Prior lock has left its (widened) release band — let the new best take over.
+  if (prevDistPx > releaseBand) return true;
+
+  // Prior lock is still within reach: only yield to a strictly closer target.
+  return bestDistPx < prevDistPx;
+}
+
+/**
+ * Build grid-line targets at integer multiples of `step`, anchored at
+ * `floor(domainStart / step) * step` so lines stay phase-stable as the visible
+ * domain pans. Each line is pre-projected to pixels via `project`.
+ *
+ * @param domainStart Inclusive start of the visible domain.
+ * @param domainEnd Inclusive end of the visible domain.
+ * @param step Grid spacing in domain units (must be `> 0`).
+ * @param project Domain→pixel projection supplied by the consumer.
+ * @param axis Axis the produced targets constrain.
+ */
+export function gridTargets(
+  domainStart: number,
+  domainEnd: number,
+  step: number,
+  project: (v: number) => number,
+  axis: 'x' | 'y',
+): SnapTarget[] {
+  const out: SnapTarget[] = [];
+  if (!(step > 0) || !Number.isFinite(step)) return out;
+  if (domainEnd < domainStart) return out;
+
+  const anchor = Math.floor(domainStart / step) * step;
+  for (let v = anchor; v <= domainEnd; v += step) {
+    // Anchor below domainStart is possible by one step; skip lines fully before it.
+    if (v < domainStart) continue;
+    out.push({ axis, px: project(v), value: v, kind: 'grid' });
+  }
+  return out;
+}
+
+/**
+ * Build edge + center targets from a set of rectangles. On the `x` axis each
+ * rect contributes `left`, `right`, and horizontal center; on `y` it contributes
+ * `top`, `bottom`, and vertical center. Edges carry kind `'edge'`, centers
+ * `'center'`. The rect's `id` (if any) propagates to every produced target so a
+ * dragged clip can exclude its own edges.
+ *
+ * @param rects Rectangles in domain space.
+ * @param axis Axis to extract targets for.
+ * @param project Domain→pixel projection supplied by the consumer.
+ */
+export function edgeTargets(
+  rects: Array<{ left: number; right: number; top: number; bottom: number; id?: string }>,
+  axis: 'x' | 'y',
+  project: (v: number) => number,
+): SnapTarget[] {
+  const out: SnapTarget[] = [];
+  for (let i = 0; i < rects.length; i++) {
+    const r = rects[i]!;
+    const lo = axis === 'x' ? r.left : r.top;
+    const hi = axis === 'x' ? r.right : r.bottom;
+    const mid = (lo + hi) / 2;
+    out.push({ axis, px: project(lo), value: lo, kind: 'edge', id: r.id });
+    out.push({ axis, px: project(hi), value: hi, kind: 'edge', id: r.id });
+    out.push({ axis, px: project(mid), value: mid, kind: 'center', id: r.id });
+  }
+  return out;
+}
+
+/**
+ * Build point targets (playhead, markers, guides, gradient stops, …) from a
+ * list of domain values. Each value is pre-projected to pixels. When `ids` is
+ * supplied, `ids[i]` is attached to the target produced from `values[i]`.
+ *
+ * @param values Domain values to turn into targets.
+ * @param kind Kind stamped on every produced target.
+ * @param axis Axis the produced targets constrain.
+ * @param project Domain→pixel projection supplied by the consumer.
+ * @param ids Optional per-value ids (positionally aligned with `values`).
+ */
+export function pointTargets(
+  values: number[],
+  kind: SnapKind,
+  axis: 'x' | 'y',
+  project: (v: number) => number,
+  ids?: string[],
+): SnapTarget[] {
+  const out: SnapTarget[] = [];
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i]!;
+    out.push({ axis, px: project(v), value: v, kind, id: ids?.[i] });
+  }
+  return out;
+}
diff --git a/vue/primitives/src/internal/snapping/types.ts b/vue/primitives/src/internal/snapping/types.ts
new file mode 100644
index 0000000..688b753
--- /dev/null
+++ b/vue/primitives/src/internal/snapping/types.ts
@@ -0,0 +1,84 @@
+import type { Point } from '../utils/geometry';
+
+// Re-export the package-canonical 2D point so consumers can name it from this
+// module without reaching into `utils/geometry`, while avoiding a second
+// `Point` declaration that would clash in the root barrel.
+export type { Point };
+
+/**
+ * Categories of snap target an editor surface can expose. The kind drives both
+ * styling (a playhead guide looks different from a grid line) and tie-breaking
+ * via {@link SnapPriority}.
+ */
+export type SnapKind = 'grid' | 'edge' | 'center' | 'playhead' | 'marker' | 'guide' | 'stop' | 'neighbor';
+
+/**
+ * A single candidate the engine can snap to. Targets live in PIXEL space (`px`)
+ * for distance math but carry their domain `value` so a match maps straight back
+ * without re-inverting the projection.
+ */
+export interface SnapTarget {
+  /** Axis this target constrains. */
+  axis: 'x' | 'y';
+  /** Pre-projected pixel position (what distances are measured against). */
+  px: number;
+  /** Domain-space value returned verbatim on a match. */
+  value: number;
+  /** Category used for styling and priority tie-breaking. */
+  kind: SnapKind;
+  /** Optional stable identity (e.g. a clip id) for exclusion/locking. */
+  id?: string;
+  /** Optional per-target pull weight; reserved for consumer weighting. */
+  strength?: number;
+}
+
+/**
+ * Outcome of a one-dimensional snap. `value` is always usable: it is either the
+ * snapped target value or the untouched candidate when nothing matched.
+ */
+export interface SnapResult1D {
+  /** Resolved domain value (snapped or pass-through). */
+  value: number;
+  /** Whether a target was within range and applied. */
+  snapped: boolean;
+  /** The matched target, or `null` when none. */
+  target: SnapTarget | null;
+  /** Signed pixel correction applied (`target.px - candidatePx`); `0` when not snapped. */
+  deltaPx: number;
+}
+
+/**
+ * Outcome of a two-dimensional snap. Each axis resolves independently, so a
+ * point can snap on `x` only, `y` only, both, or neither.
+ */
+export interface SnapResult2D {
+  /** Resolved point (per-axis snapped or pass-through). */
+  point: Point;
+  /** Whether the `x` axis snapped. */
+  snappedX: boolean;
+  /** Whether the `y` axis snapped. */
+  snappedY: boolean;
+  /** The matched `x` target, or `null`. */
+  targetX: SnapTarget | null;
+  /** The matched `y` target, or `null`. */
+  targetY: SnapTarget | null;
+}
+
+/**
+ * Tie-breaking policy. Within a `relaxPx` band of the nearest candidate, a kind
+ * appearing earlier in `order` wins even if it is a few pixels farther — so a
+ * playhead can "out-pull" a grid line the eye treats as less important.
+ */
+export interface SnapPriority {
+  /**
+   * Kinds from highest to lowest priority. Kinds absent from the list rank
+   * after all listed kinds, in target order.
+   * @default undefined (pure nearest-distance)
+   */
+  order?: SnapKind[];
+  /**
+   * Pixel slack within which a higher-priority kind may beat a nearer one.
+   * @default 0
+   */
+  relaxPx?: number;
+}
diff --git a/vue/primitives/src/internal/snapping/useSnapping.ts b/vue/primitives/src/internal/snapping/useSnapping.ts
new file mode 100644
index 0000000..2b56195
--- /dev/null
+++ b/vue/primitives/src/internal/snapping/useSnapping.ts
@@ -0,0 +1,279 @@
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import { readonly, ref, toValue } from 'vue';
+import type { Point, SnapPriority, SnapResult1D, SnapResult2D, SnapTarget } from './types';
+import { applyHysteresis, findNearestTarget } from './snap';
+
+/**
+ * Axis mode for {@link useSnapping}:
+ * - `'1d'` — a scalar snap (use `snap1d`); the engine treats all targets as a
+ *   single pool.
+ * - `'2d'` — a point snap (use `snap2d`); targets are bucketed by their `axis`.
+ * - `'x'` / `'y'` — like `'1d'` but only targets on that axis are considered.
+ */
+export type SnapAxisMode = '1d' | '2d' | 'x' | 'y';
+
+/**
+ * Per-call override passed to `snap1d` / `snap2d` for live, transient tweaks
+ * that should not live in reactive options.
+ */
+export interface SnapCallContext {
+  /** Skip snapping entirely for this call (e.g. a modifier key held down). */
+  bypass?: boolean;
+  /** Target id(s) to exclude (e.g. a clip must not snap to its own edges). */
+  exclude?: string | Set<string>;
+}
+
+/** Reactive options for {@link useSnapping}. */
+export interface SnappingOptions {
+  /** Master enable switch. @default true */
+  enabled?: MaybeRefOrGetter<boolean>;
+  /** Snap radius in pixels. @default 8 */
+  thresholdPx?: MaybeRefOrGetter<number>;
+  /** Axis mode. @default '1d' */
+  axis?: MaybeRefOrGetter<SnapAxisMode>;
+  /**
+   * Domain→pixel projection supplied by the consumer — the engine NEVER owns
+   * the projection. Only needed when the consumer relies on the engine to map a
+   * candidate value into pixel space; targets are expected to be pre-projected.
+   */
+  project?: (value: number, axis: 'x' | 'y') => number;
+  /** Candidate targets (pre-projected to pixels). @default [] */
+  targets?: MaybeRefOrGetter<SnapTarget[]>;
+  /** Tie-breaking policy. @default undefined */
+  priority?: MaybeRefOrGetter<SnapPriority>;
+  /** Fraction of `thresholdPx` added to the lock release band. @default 0.5 */
+  hysteresisRatio?: MaybeRefOrGetter<number>;
+}
+
+/** Reactive snap engine returned by {@link useSnapping}. */
+export interface UseSnappingReturn {
+  /**
+   * Snap a scalar candidate. The candidate may be a domain `value` (the engine
+   * projects it via `options.project`) — when no projection is configured the
+   * candidate is treated as already being in pixel space.
+   */
+  snap1d: (value: number, ctx?: SnapCallContext) => SnapResult1D;
+  /** Snap a 2D point, resolving each axis independently. */
+  snap2d: (point: Point, ctx?: SnapCallContext) => SnapResult2D;
+  /** Whether the most recent snap call matched a target. */
+  isSnapped: Readonly<Ref<boolean>>;
+  /** Targets matched by the most recent snap call (0–2 entries). */
+  activeTargets: Readonly<Ref<SnapTarget[]>>;
+  /** Clear locked targets and the active/snapped state. */
+  reset: () => void;
+}
+
+/**
+ * Reactive magnetic-snap engine for editor surfaces (timeline clip edges,
+ * crop/transform handles, gradient stops). Distance math runs in PIXEL space
+ * while values live in domain space, so the consumer supplies a `project`
+ * callback and pre-projected targets — the engine never owns the projection.
+ *
+ * The hot path (`snap1d` with no match) is allocation-free: it mutates a single
+ * pre-built result object and returns the candidate untouched. Per-axis locked
+ * targets are kept between calls to drive hysteresis so a snapped handle does
+ * not flicker between adjacent targets.
+ */
+export function useSnapping(options: SnappingOptions = {}): UseSnappingReturn {
+  const isSnappedRef = ref(false);
+  const activeTargetsRef = ref<SnapTarget[]>([]);
+
+  // Locked target ids per axis power the hysteresis stickiness across calls.
+  let lockedX: string | undefined;
+  let lockedY: string | undefined;
+
+  // Pre-allocated result objects mutated in place — the no-match hot path must
+  // not allocate.
+  const result1d: SnapResult1D = { value: 0, snapped: false, target: null, deltaPx: 0 };
+  const result2d: SnapResult2D = {
+    point: { x: 0, y: 0 },
+    snappedX: false,
+    snappedY: false,
+    targetX: null,
+    targetY: null,
+  };
+
+  function projectValue(value: number, axis: 'x' | 'y'): number {
+    return options.project ? options.project(value, axis) : value;
+  }
+
+  /** Resolve one axis against the supplied target pool, mutating shared lock state. */
+  function resolveAxis(
+    value: number,
+    axis: 'x' | 'y',
+    targets: SnapTarget[],
+    thresholdPx: number,
+    priority: SnapPriority | undefined,
+    hysteresisRatio: number,
+    exclude: string | Set<string> | undefined,
+    locked: string | undefined,
+  ): { snapped: boolean; target: SnapTarget | null; deltaPx: number; nextLocked: string | undefined } {
+    const candidatePx = projectValue(value, axis);
+    const hysteresisPx = thresholdPx * hysteresisRatio;
+
+    const { index, deltaPx } = findNearestTarget(
+      candidatePx,
+      targets,
+      thresholdPx,
+      priority,
+      exclude,
+      locked,
+      hysteresisPx,
+    );
+
+    if (index === -1) {
+      // No candidate in range: drop any prior lock.
+      return { snapped: false, target: null, deltaPx: 0, nextLocked: undefined };
+    }
+
+    const best = targets[index]!;
+    const bestDistPx = deltaPx < 0 ? -deltaPx : deltaPx;
+
+    // Distance of the prior lock this frame (Infinity if it left range / is gone).
+    let prevDistPx = Infinity;
+    if (locked !== undefined) {
+      for (let i = 0; i < targets.length; i++) {
+        const t = targets[i]!;
+        if (t.id === locked) {
+          const d = t.px - candidatePx;
+          prevDistPx = d < 0 ? -d : d;
+          break;
+        }
+      }
+    }
+
+    const steal = applyHysteresis(locked, best.id, bestDistPx, prevDistPx, thresholdPx, hysteresisRatio);
+
+    if (!steal && locked !== undefined) {
+      // Keep the prior lock if it is still a valid (in-range) target.
+      for (let i = 0; i < targets.length; i++) {
+        const t = targets[i]!;
+        if (t.id === locked) {
+          const heldDelta = t.px - candidatePx;
+          return { snapped: true, target: t, deltaPx: heldDelta, nextLocked: locked };
+        }
+      }
+    }
+
+    return { snapped: true, target: best, deltaPx, nextLocked: best.id };
+  }
+
+  function snap1d(value: number, ctx?: SnapCallContext): SnapResult1D {
+    const enabled = toValue(options.enabled) ?? true;
+
+    // Disabled or per-call bypass: pass through with no allocation.
+    if (!enabled || ctx?.bypass) {
+      result1d.value = value;
+      result1d.snapped = false;
+      result1d.target = null;
+      result1d.deltaPx = 0;
+      if (isSnappedRef.value) isSnappedRef.value = false;
+      if (activeTargetsRef.value.length) activeTargetsRef.value = [];
+      lockedX = undefined;
+      return result1d;
+    }
+
+    const mode = toValue(options.axis) ?? '1d';
+    const axis: 'x' | 'y' = mode === 'y' ? 'y' : 'x';
+    const thresholdPx = toValue(options.thresholdPx) ?? 8;
+    const hysteresisRatio = toValue(options.hysteresisRatio) ?? 0.5;
+    const priority = toValue(options.priority);
+    const allTargets = toValue(options.targets) ?? [];
+
+    // For 'x'/'y' modes filter to the axis; '1d' uses all targets as one pool.
+    const targets = mode === 'x' || mode === 'y'
+      ? allTargets.filter(t => t.axis === axis)
+      : allTargets;
+
+    const r = resolveAxis(
+      value,
+      axis,
+      targets,
+      thresholdPx,
+      priority,
+      hysteresisRatio,
+      ctx?.exclude,
+      lockedX,
+    );
+    lockedX = r.nextLocked;
+
+    if (!r.snapped || r.target === null) {
+      // Hot path: no match — return the candidate untouched, zero allocation.
+      result1d.value = value;
+      result1d.snapped = false;
+      result1d.target = null;
+      result1d.deltaPx = 0;
+      if (isSnappedRef.value) isSnappedRef.value = false;
+      if (activeTargetsRef.value.length) activeTargetsRef.value = [];
+      return result1d;
+    }
+
+    result1d.value = r.target.value;
+    result1d.snapped = true;
+    result1d.target = r.target;
+    result1d.deltaPx = r.deltaPx;
+    isSnappedRef.value = true;
+    activeTargetsRef.value = [r.target];
+    return result1d;
+  }
+
+  function snap2d(point: Point, ctx?: SnapCallContext): SnapResult2D {
+    const enabled = toValue(options.enabled) ?? true;
+
+    if (!enabled || ctx?.bypass) {
+      result2d.point.x = point.x;
+      result2d.point.y = point.y;
+      result2d.snappedX = false;
+      result2d.snappedY = false;
+      result2d.targetX = null;
+      result2d.targetY = null;
+      if (isSnappedRef.value) isSnappedRef.value = false;
+      if (activeTargetsRef.value.length) activeTargetsRef.value = [];
+      lockedX = undefined;
+      lockedY = undefined;
+      return result2d;
+    }
+
+    const thresholdPx = toValue(options.thresholdPx) ?? 8;
+    const hysteresisRatio = toValue(options.hysteresisRatio) ?? 0.5;
+    const priority = toValue(options.priority);
+    const allTargets = toValue(options.targets) ?? [];
+
+    const xTargets = allTargets.filter(t => t.axis === 'x');
+    const yTargets = allTargets.filter(t => t.axis === 'y');
+
+    const rx = resolveAxis(point.x, 'x', xTargets, thresholdPx, priority, hysteresisRatio, ctx?.exclude, lockedX);
+    const ry = resolveAxis(point.y, 'y', yTargets, thresholdPx, priority, hysteresisRatio, ctx?.exclude, lockedY);
+    lockedX = rx.nextLocked;
+    lockedY = ry.nextLocked;
+
+    result2d.point.x = rx.snapped && rx.target ? rx.target.value : point.x;
+    result2d.point.y = ry.snapped && ry.target ? ry.target.value : point.y;
+    result2d.snappedX = rx.snapped;
+    result2d.snappedY = ry.snapped;
+    result2d.targetX = rx.target;
+    result2d.targetY = ry.target;
+
+    const matched: SnapTarget[] = [];
+    if (rx.target) matched.push(rx.target);
+    if (ry.target) matched.push(ry.target);
+    isSnappedRef.value = matched.length > 0;
+    activeTargetsRef.value = matched;
+    return result2d;
+  }
+
+  function reset(): void {
+    lockedX = undefined;
+    lockedY = undefined;
+    isSnappedRef.value = false;
+    activeTargetsRef.value = [];
+  }
+
+  return {
+    snap1d,
+    snap2d,
+    isSnapped: readonly(isSnappedRef),
+    activeTargets: readonly(activeTargetsRef) as Readonly<Ref<SnapTarget[]>>,
+    reset,
+  };
+}
diff --git a/vue/primitives/src/internal/spline/__test__/spline.test.ts b/vue/primitives/src/internal/spline/__test__/spline.test.ts
new file mode 100644
index 0000000..f8b029f
--- /dev/null
+++ b/vue/primitives/src/internal/spline/__test__/spline.test.ts
@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildBezierPath,
+  buildPolylinePath,
+  buildSmoothPath,
+  catmullRom,
+  cubicBezierTangent,
+  evalCubicBezier,
+  linearInterpolate,
+  monotoneCubic,
+  sampleFnToPolyline,
+  sampleToPolyline,
+  solveBezierX,
+  toLUT,
+} from '../index';
+import type { Point } from '../index';
+
+describe('evalCubicBezier', () => {
+  const p0: Point = { x: 0, y: 0 };
+  const p1: Point = { x: 0, y: 1 };
+  const p2: Point = { x: 1, y: 1 };
+  const p3: Point = { x: 1, y: 0 };
+
+  it('returns p0 at t=0 and p3 at t=1', () => {
+    expect(evalCubicBezier(p0, p1, p2, p3, 0)).toEqual(p0);
+    expect(evalCubicBezier(p0, p1, p2, p3, 1)).toEqual(p3);
+  });
+
+  it('midpoint sits inside the convex hull', () => {
+    const mid = evalCubicBezier(p0, p1, p2, p3, 0.5);
+    expect(mid.x).toBeCloseTo(0.5, 10);
+    expect(mid.y).toBeGreaterThan(0);
+    expect(mid.y).toBeLessThanOrEqual(1);
+  });
+
+  it('straight diagonal stays linear', () => {
+    const a: Point = { x: 0, y: 0 };
+    const b: Point = { x: 1, y: 1 };
+    const c: Point = { x: 2, y: 2 };
+    const d: Point = { x: 3, y: 3 };
+    const mid = evalCubicBezier(a, b, c, d, 0.5);
+    expect(mid.x).toBeCloseTo(1.5, 10);
+    expect(mid.y).toBeCloseTo(1.5, 10);
+  });
+});
+
+describe('cubicBezierTangent', () => {
+  it('points along the curve direction at the start', () => {
+    const t = cubicBezierTangent({ x: 0, y: 0 }, { x: 1, y: 0 }, { x: 2, y: 1 }, { x: 3, y: 1 }, 0);
+    // Initial tangent is 3*(p1-p0).
+    expect(t.x).toBeCloseTo(3, 10);
+    expect(t.y).toBeCloseTo(0, 10);
+  });
+});
+
+describe('solveBezierX', () => {
+  it('linear cubic-bezier(0,0,1,1) gives y ≈ x', () => {
+    for (const x of [0, 0.1, 0.25, 0.5, 0.75, 0.9, 1]) {
+      expect(solveBezierX(0, 0, 1, 1, x)).toBeCloseTo(x, 6);
+    }
+  });
+
+  it('ease cubic-bezier(0.42,0,0.58,1): endpoints, midpoint, monotonic', () => {
+    expect(solveBezierX(0.42, 0, 0.58, 1, 0)).toBeCloseTo(0, 6);
+    expect(solveBezierX(0.42, 0, 0.58, 1, 1)).toBeCloseTo(1, 6);
+    expect(solveBezierX(0.42, 0, 0.58, 1, 0.5)).toBeCloseTo(0.5, 4);
+
+    let prev = -Infinity;
+    for (let i = 0; i <= 20; i++) {
+      const y = solveBezierX(0.42, 0, 0.58, 1, i / 20);
+      expect(y).toBeGreaterThanOrEqual(prev - 1e-9);
+      prev = y;
+    }
+  });
+
+  it('clamps x outside [0,1]', () => {
+    expect(solveBezierX(0.42, 0, 0.58, 1, -1)).toBeCloseTo(0, 6);
+    expect(solveBezierX(0.42, 0, 0.58, 1, 2)).toBeCloseTo(1, 6);
+  });
+});
+
+describe('catmullRom', () => {
+  const pts: Point[] = [
+    { x: 0, y: 0 },
+    { x: 1, y: 1 },
+    { x: 2, y: 0 },
+    { x: 3, y: 1 },
+  ];
+
+  it('hits the first and last point at t=0 and t=1', () => {
+    const a = catmullRom(pts, 0);
+    const b = catmullRom(pts, 1);
+    expect(a.x).toBeCloseTo(0, 10);
+    expect(a.y).toBeCloseTo(0, 10);
+    expect(b.x).toBeCloseTo(3, 10);
+    expect(b.y).toBeCloseTo(1, 10);
+  });
+
+  it('passes through interior knots at segment boundaries', () => {
+    // 3 segments → knot 1 at t=1/3, knot 2 at t=2/3.
+    const k1 = catmullRom(pts, 1 / 3);
+    expect(k1.x).toBeCloseTo(1, 6);
+    expect(k1.y).toBeCloseTo(1, 6);
+  });
+});
+
+describe('monotoneCubic', () => {
+  it('passes exactly through input points at their x', () => {
+    const pts: Point[] = [
+      { x: 0, y: 0 },
+      { x: 1, y: 2 },
+      { x: 2, y: 1 },
+      { x: 4, y: 5 },
+    ];
+    const f = monotoneCubic(pts);
+    for (const p of pts)
+      expect(f(p.x)).toBeCloseTo(p.y, 10);
+  });
+
+  it('no overshoot on a step-like dataset', () => {
+    const f = monotoneCubic([
+      { x: 0, y: 0 },
+      { x: 1, y: 0 },
+      { x: 2, y: 1 },
+    ]);
+    for (let i = 0; i <= 40; i++) {
+      const x = (i / 40) * 2;
+      const y = f(x);
+      expect(y).toBeGreaterThanOrEqual(-1e-9);
+      expect(y).toBeLessThanOrEqual(1 + 1e-9);
+    }
+  });
+
+  it('clamps x to [x0, xn]', () => {
+    const f = monotoneCubic([{ x: 1, y: 3 }, { x: 2, y: 7 }]);
+    expect(f(-5)).toBeCloseTo(3, 10);
+    expect(f(99)).toBeCloseTo(7, 10);
+  });
+});
+
+describe('linearInterpolate', () => {
+  const pts: Point[] = [{ x: 0, y: 0 }, { x: 2, y: 4 }, { x: 4, y: 0 }];
+
+  it('interpolates and clamps', () => {
+    expect(linearInterpolate(pts, 1)).toBeCloseTo(2, 10);
+    expect(linearInterpolate(pts, 3)).toBeCloseTo(2, 10);
+    expect(linearInterpolate(pts, -1)).toBeCloseTo(0, 10);
+    expect(linearInterpolate(pts, 10)).toBeCloseTo(0, 10);
+  });
+});
+
+describe('sampleToPolyline / sampleFnToPolyline', () => {
+  it('produces segments + 1 points', () => {
+    const poly = sampleToPolyline(t => ({ x: t, y: t * t }), 10);
+    expect(poly).toHaveLength(11);
+    expect(poly[0]).toEqual({ x: 0, y: 0 });
+    expect(poly[10]).toEqual({ x: 1, y: 1 });
+  });
+
+  it('samples y=f(x) across the range', () => {
+    const poly = sampleFnToPolyline(x => 2 * x, 0, 5, 5);
+    expect(poly).toHaveLength(6);
+    expect(poly[0]).toEqual({ x: 0, y: 0 });
+    expect(poly[5]).toEqual({ x: 5, y: 10 });
+  });
+});
+
+describe('path builders', () => {
+  it('buildPolylinePath format', () => {
+    const d = buildPolylinePath([{ x: 0, y: 0 }, { x: 1, y: 2 }, { x: 3, y: 4 }]);
+    expect(d).toBe('M 0,0 L 1,2 L 3,4');
+  });
+
+  it('buildPolylinePath empty', () => {
+    expect(buildPolylinePath([])).toBe('');
+  });
+
+  it('buildBezierPath format', () => {
+    const d = buildBezierPath({ x: 0, y: 0 }, { x: 1, y: 0 }, { x: 1, y: 1 }, { x: 2, y: 1 });
+    expect(d).toBe('M 0,0 C 1,0 1,1 2,1');
+  });
+
+  it('buildSmoothPath starts with a moveto and emits cubic segments', () => {
+    const d = buildSmoothPath([{ x: 0, y: 0 }, { x: 1, y: 1 }, { x: 2, y: 0 }, { x: 3, y: 1 }]);
+    expect(d.startsWith('M 0,0')).toBe(true);
+    expect(d).toContain('C ');
+  });
+});
+
+describe('toLUT', () => {
+  it('has the requested length with correct endpoints', () => {
+    const lut = toLUT(x => x * x, 256);
+    expect(lut).toHaveLength(256);
+    expect(lut[0]).toBeCloseTo(0, 10);
+    expect(lut[255]).toBeCloseTo(1, 10);
+  });
+
+  it('respects a custom range', () => {
+    const lut = toLUT(x => x, 3, 0, 10);
+    expect(lut).toEqual([0, 5, 10]);
+  });
+});
diff --git a/vue/primitives/src/internal/spline/bezier.ts b/vue/primitives/src/internal/spline/bezier.ts
new file mode 100644
index 0000000..2782a92
--- /dev/null
+++ b/vue/primitives/src/internal/spline/bezier.ts
@@ -0,0 +1,95 @@
+import type { Point } from './types';
+
+/**
+ * Evaluate a cubic bezier (control points `p0..p3`) at parameter `t ∈ [0,1]`
+ * using the Bernstein basis. Returns the point on the curve.
+ */
+export function evalCubicBezier(p0: Point, p1: Point, p2: Point, p3: Point, t: number): Point {
+  const u = 1 - t;
+  const uu = u * u;
+  const tt = t * t;
+  const b0 = uu * u;
+  const b1 = 3 * uu * t;
+  const b2 = 3 * u * tt;
+  const b3 = tt * t;
+  return {
+    x: b0 * p0.x + b1 * p1.x + b2 * p2.x + b3 * p3.x,
+    y: b0 * p0.y + b1 * p1.y + b2 * p2.y + b3 * p3.y,
+  };
+}
+
+/**
+ * Evaluate a single scalar component of a cubic bezier with control values
+ * `a,b,c,d` at parameter `t ∈ [0,1]` (Bernstein basis). Used by the easing solver.
+ */
+export function cubicBezier1D(a: number, b: number, c: number, d: number, t: number): number {
+  const u = 1 - t;
+  const uu = u * u;
+  const tt = t * t;
+  return uu * u * a + 3 * uu * t * b + 3 * u * tt * c + tt * d * t;
+}
+
+/**
+ * Evaluate a CSS `cubic-bezier(x1,y1,x2,y2)` easing curve: given progress
+ * `x ∈ [0,1]` return the eased `y`. The implicit control points are
+ * `(0,0),(x1,y1),(x2,y2),(1,1)`. Solves `x→t` with Newton-Raphson (a few
+ * iterations) and a binary-search fallback, matching the browser implementation.
+ */
+export function solveBezierX(x1: number, y1: number, x2: number, y2: number, x: number, epsilon = 1e-6): number {
+  const cx = Math.min(Math.max(x, 0), 1);
+
+  // Identity easing: y === x.
+  if (x1 === y1 && x2 === y2)
+    return cx;
+
+  const sampleX = (t: number): number => cubicBezier1D(0, x1, x2, 1, t);
+  const sampleY = (t: number): number => cubicBezier1D(0, y1, y2, 1, t);
+  // dx/dt of the x-component cubic with endpoints 0 and 1.
+  const sampleDX = (t: number): number => {
+    const u = 1 - t;
+    return 3 * u * u * x1 + 6 * u * t * (x2 - x1) + 3 * t * t * (1 - x2);
+  };
+
+  // Newton-Raphson from x as the initial guess.
+  let t = cx;
+  for (let i = 0; i < 8; i++) {
+    const fx = sampleX(t) - cx;
+    if (Math.abs(fx) < epsilon)
+      return sampleY(t);
+    const dx = sampleDX(t);
+    if (Math.abs(dx) < epsilon)
+      break;
+    t -= fx / dx;
+  }
+
+  // Binary-search fallback when the derivative is too small or Newton diverges.
+  let lo = 0;
+  let hi = 1;
+  t = cx;
+  while (lo < hi) {
+    const fx = sampleX(t);
+    if (Math.abs(fx - cx) < epsilon)
+      return sampleY(t);
+    if (cx > fx)
+      lo = t;
+    else
+      hi = t;
+    t = (lo + hi) / 2;
+  }
+  return sampleY(t);
+}
+
+/**
+ * First derivative (tangent vector) of a cubic bezier at `t ∈ [0,1]`. Useful for
+ * rendering handles/normals along the curve.
+ */
+export function cubicBezierTangent(p0: Point, p1: Point, p2: Point, p3: Point, t: number): Point {
+  const u = 1 - t;
+  const a = 3 * u * u;
+  const b = 6 * u * t;
+  const c = 3 * t * t;
+  return {
+    x: a * (p1.x - p0.x) + b * (p2.x - p1.x) + c * (p3.x - p2.x),
+    y: a * (p1.y - p0.y) + b * (p2.y - p1.y) + c * (p3.y - p2.y),
+  };
+}
diff --git a/vue/primitives/src/internal/spline/index.ts b/vue/primitives/src/internal/spline/index.ts
new file mode 100644
index 0000000..40fc203
--- /dev/null
+++ b/vue/primitives/src/internal/spline/index.ts
@@ -0,0 +1,5 @@
+export * from './types';
+export * from './bezier';
+export * from './interpolation';
+export * from './sample';
+export * from './path';
diff --git a/vue/primitives/src/internal/spline/interpolation.ts b/vue/primitives/src/internal/spline/interpolation.ts
new file mode 100644
index 0000000..450f406
--- /dev/null
+++ b/vue/primitives/src/internal/spline/interpolation.ts
@@ -0,0 +1,188 @@
+import type { Point } from './types';
+
+/**
+ * Evaluate a Catmull-Rom spline passing through `points` at `t ∈ [0,1]` spanning
+ * the whole spline. `tension` (0 = uniform Catmull-Rom) and `closed` (loop the
+ * curve) are optional. Each segment is evaluated via its equivalent cubic.
+ */
+export function catmullRom(points: Point[], t: number, options?: { tension?: number; closed?: boolean }): Point {
+  const n = points.length;
+  if (n === 0)
+    return { x: 0, y: 0 };
+  if (n === 1)
+    return { x: points[0]!.x, y: points[0]!.y };
+
+  const tension = options?.tension ?? 0;
+  const closed = options?.closed ?? false;
+  // Catmull-Rom "tension" scales the tangents: alpha = (1 - tension) / 6.
+  const alpha = (1 - tension) / 6;
+
+  const segments = closed ? n : n - 1;
+  const u = Math.min(Math.max(t, 0), 1) * segments;
+  let seg = Math.floor(u);
+  if (seg >= segments)
+    seg = segments - 1;
+  const local = u - seg;
+
+  const at = (i: number): Point => {
+    if (closed)
+      return points[((i % n) + n) % n]!;
+    const c = Math.min(Math.max(i, 0), n - 1);
+    return points[c]!;
+  };
+
+  const p0 = at(seg - 1);
+  const p1 = at(seg);
+  const p2 = at(seg + 1);
+  const p3 = at(seg + 2);
+
+  // Convert Catmull-Rom to a cubic and evaluate at `local`.
+  const tt = local * local;
+  const ttt = tt * local;
+
+  const eval1 = (a0: number, a1: number, a2: number, a3: number): number => {
+    const m1 = alpha * 3 * (a2 - a0);
+    const m2 = alpha * 3 * (a3 - a1);
+    return (
+      (2 * ttt - 3 * tt + 1) * a1
+      + (ttt - 2 * tt + local) * m1
+      + (-2 * ttt + 3 * tt) * a2
+      + (ttt - tt) * m2
+    );
+  };
+
+  return {
+    x: eval1(p0.x, p1.x, p2.x, p3.x),
+    y: eval1(p0.y, p1.y, p2.y, p3.y),
+  };
+}
+
+/**
+ * Build a Fritsch-Carlson monotone cubic interpolant through `points` (sorted
+ * ascending by `x`). Returns `y = f(x)` that preserves monotonicity (no
+ * overshoot); `x` is clamped to `[x0, xn]`. Load-bearing for tone/gamma curves.
+ */
+export function monotoneCubic(points: Point[]): (x: number) => number {
+  const n = points.length;
+
+  if (n === 0)
+    return () => 0;
+  if (n === 1) {
+    const y = points[0]!.y;
+    return () => y;
+  }
+
+  const xs = points.map(p => p.x);
+  const ys = points.map(p => p.y);
+
+  // Secant slopes between consecutive points.
+  const dx: number[] = [];
+  const slope: number[] = [];
+  for (let i = 0; i < n - 1; i++) {
+    const h = xs[i + 1]! - xs[i]!;
+    dx.push(h);
+    slope.push(h === 0 ? 0 : (ys[i + 1]! - ys[i]!) / h);
+  }
+
+  // Tangents `m` at each knot (Fritsch-Carlson). Built in ascending index order
+  // so the array stays packed (PACKED_DOUBLE_ELEMENTS).
+  const m: number[] = [];
+  m.push(slope[0]!);
+  for (let i = 1; i < n - 1; i++) {
+    const s0 = slope[i - 1]!;
+    const s1 = slope[i]!;
+    // A local extremum (sign change or flat) forces a zero tangent.
+    if (s0 * s1 <= 0)
+      m.push(0);
+    else
+      m.push((s0 + s1) / 2);
+  }
+  m.push(slope[n - 2]!);
+
+  // Adjust tangents to enforce monotonicity (no overshoot) on each segment.
+  for (let i = 0; i < n - 1; i++) {
+    const s = slope[i]!;
+    if (s === 0) {
+      m[i] = 0;
+      m[i + 1] = 0;
+      continue;
+    }
+    const a = m[i]! / s;
+    const b = m[i + 1]! / s;
+    const h = a * a + b * b;
+    if (h > 9) {
+      const tau = 3 / Math.sqrt(h);
+      m[i] = tau * a * s;
+      m[i + 1] = tau * b * s;
+    }
+  }
+
+  return (x: number): number => {
+    const x0 = xs[0]!;
+    const xn = xs[n - 1]!;
+    const cx = Math.min(Math.max(x, x0), xn);
+
+    // Binary search for the segment containing `cx`.
+    let lo = 0;
+    let hi = n - 1;
+    while (hi - lo > 1) {
+      const mid = (lo + hi) >> 1;
+      if (xs[mid]! <= cx)
+        lo = mid;
+      else
+        hi = mid;
+    }
+
+    const h = dx[lo]!;
+    if (h === 0)
+      return ys[lo]!;
+    const t = (cx - xs[lo]!) / h;
+    const t2 = t * t;
+    const t3 = t2 * t;
+
+    // Hermite basis functions.
+    const h00 = 2 * t3 - 3 * t2 + 1;
+    const h10 = t3 - 2 * t2 + t;
+    const h01 = -2 * t3 + 3 * t2;
+    const h11 = t3 - t2;
+
+    return h00 * ys[lo]! + h10 * h * m[lo]! + h01 * ys[lo + 1]! + h11 * h * m[lo + 1]!;
+  };
+}
+
+/**
+ * Piecewise-linear interpolation of `y` at `x` through `points` (sorted
+ * ascending by `x`). `x` is clamped to the points' x-range.
+ */
+export function linearInterpolate(points: Point[], x: number): number {
+  const n = points.length;
+  if (n === 0)
+    return 0;
+  if (n === 1)
+    return points[0]!.y;
+
+  const first = points[0]!;
+  const last = points[n - 1]!;
+  if (x <= first.x)
+    return first.y;
+  if (x >= last.x)
+    return last.y;
+
+  let lo = 0;
+  let hi = n - 1;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (points[mid]!.x <= x)
+      lo = mid;
+    else
+      hi = mid;
+  }
+
+  const a = points[lo]!;
+  const b = points[lo + 1]!;
+  const span = b.x - a.x;
+  if (span === 0)
+    return a.y;
+  const t = (x - a.x) / span;
+  return a.y + t * (b.y - a.y);
+}
diff --git a/vue/primitives/src/internal/spline/path.ts b/vue/primitives/src/internal/spline/path.ts
new file mode 100644
index 0000000..fd0d005
--- /dev/null
+++ b/vue/primitives/src/internal/spline/path.ts
@@ -0,0 +1,27 @@
+import type { Point } from './types';
+
+/**
+ * Build the SVG path `d` for a single cubic bezier ("M x,y C c1 c2 p3").
+ * Domain-agnostic generalization of flow's bezier path (no handle-side logic).
+ */
+export function buildBezierPath(p0: Point, c1: Point, c2: Point, p3: Point): string {
+  return `M ${p0.x},${p0.y} C ${c1.x},${c1.y} ${c2.x},${c2.y} ${p3.x},${p3.y}`;
+}
+
+/**
+ * Sample a `y = f(x)` curve into a `size`-length lookup table across `[x0, x1]`
+ * (defaults `0..1`). Useful for color/levels/gamma application.
+ */
+export function toLUT(fn: (x: number) => number, size: number, x0 = 0, x1 = 1): number[] {
+  const count = Math.max(1, Math.floor(size));
+  const lut: number[] = [];
+  if (count === 1) {
+    lut.push(fn(x0));
+    return lut;
+  }
+  for (let i = 0; i < count; i++) {
+    const x = x0 + ((x1 - x0) * i) / (count - 1);
+    lut.push(fn(x));
+  }
+  return lut;
+}
diff --git a/vue/primitives/src/internal/spline/sample.ts b/vue/primitives/src/internal/spline/sample.ts
new file mode 100644
index 0000000..a5b3682
--- /dev/null
+++ b/vue/primitives/src/internal/spline/sample.ts
@@ -0,0 +1,79 @@
+import type { Point } from './types';
+
+/**
+ * Sample a parametric curve `t → Point` into `segments + 1` evenly spaced points
+ * over `t ∈ [0,1]`.
+ */
+export function sampleToPolyline(curve: (t: number) => Point, segments: number): Point[] {
+  const count = Math.max(1, Math.floor(segments));
+  const out: Point[] = [];
+  for (let i = 0; i <= count; i++)
+    out.push(curve(i / count));
+  return out;
+}
+
+/**
+ * Sample a `y = f(x)` function across `[x0, x1]` into `segments + 1` points.
+ */
+export function sampleFnToPolyline(fn: (x: number) => number, x0: number, x1: number, segments: number): Point[] {
+  const count = Math.max(1, Math.floor(segments));
+  const out: Point[] = [];
+  for (let i = 0; i <= count; i++) {
+    const x = x0 + ((x1 - x0) * i) / count;
+    out.push({ x, y: fn(x) });
+  }
+  return out;
+}
+
+/**
+ * Build an SVG path `d` string for a polyline through `points` ("M …L …").
+ */
+export function buildPolylinePath(points: Point[]): string {
+  if (points.length === 0)
+    return '';
+  const first = points[0]!;
+  let d = `M ${first.x},${first.y}`;
+  for (let i = 1; i < points.length; i++) {
+    const p = points[i]!;
+    d += ` L ${p.x},${p.y}`;
+  }
+  return d;
+}
+
+/**
+ * Build a smooth SVG path `d` through `points` using Catmull-Rom-derived cubic
+ * bezier segments. `tension` (0 = uniform Catmull-Rom) controls the bow.
+ */
+export function buildSmoothPath(points: Point[], tension = 0): string {
+  const n = points.length;
+  if (n === 0)
+    return '';
+  if (n === 1) {
+    const p = points[0]!;
+    return `M ${p.x},${p.y}`;
+  }
+  if (n === 2) {
+    const a = points[0]!;
+    const b = points[1]!;
+    return `M ${a.x},${a.y} L ${b.x},${b.y}`;
+  }
+
+  const alpha = (1 - tension) / 6;
+  const at = (i: number): Point => points[Math.min(Math.max(i, 0), n - 1)]!;
+
+  const start = points[0]!;
+  let d = `M ${start.x},${start.y}`;
+  for (let i = 0; i < n - 1; i++) {
+    const p0 = at(i - 1);
+    const p1 = at(i);
+    const p2 = at(i + 1);
+    const p3 = at(i + 2);
+    // Catmull-Rom → cubic bezier control points.
+    const c1x = p1.x + alpha * (p2.x - p0.x);
+    const c1y = p1.y + alpha * (p2.y - p0.y);
+    const c2x = p2.x - alpha * (p3.x - p1.x);
+    const c2y = p2.y - alpha * (p3.y - p1.y);
+    d += ` C ${c1x},${c1y} ${c2x},${c2y} ${p2.x},${p2.y}`;
+  }
+  return d;
+}
diff --git a/vue/primitives/src/internal/spline/types.ts b/vue/primitives/src/internal/spline/types.ts
new file mode 100644
index 0000000..4ed9c39
--- /dev/null
+++ b/vue/primitives/src/internal/spline/types.ts
@@ -0,0 +1,7 @@
+// Re-export the package-canonical 2D point so every infra/component module
+// shares a single `Point` declaration. This keeps the root barrel free of a
+// TS2308 ambiguity (spline and pointer-drag would otherwise each declare their
+// own `Point`). `utils/geometry` is internal-only (not in the root barrel), so
+// re-exporting the same symbol here makes both star-exports identical.
+/** A 2D point in curve/screen space. */
+export type { Point } from '../utils/geometry';
diff --git a/vue/primitives/src/utils/__test__/getRawChildren.test.ts b/vue/primitives/src/internal/utils/__test__/getRawChildren.test.ts
similarity index 100%
rename from vue/primitives/src/utils/__test__/getRawChildren.test.ts
rename to vue/primitives/src/internal/utils/__test__/getRawChildren.test.ts
diff --git a/vue/primitives/src/listbox/utils.ts b/vue/primitives/src/internal/utils/compare-values.ts
similarity index 52%
rename from vue/primitives/src/listbox/utils.ts
rename to vue/primitives/src/internal/utils/compare-values.ts
index d708357..3eae1be 100644
--- a/vue/primitives/src/listbox/utils.ts
+++ b/vue/primitives/src/internal/utils/compare-values.ts
@@ -1,5 +1,14 @@
-export type ListboxValue = string | number | boolean | Record<string, unknown>;
+/**
+ * Value-equality helpers shared by the listbox/combobox-style selection
+ * primitives, which compare option values either by reference, by a property
+ * key, or with a custom comparator.
+ */
 
+/**
+ * Compare two (possibly undefined) values. `by` selects the comparison: omitted
+ * → strict `===`; a function → custom comparator; a string → compare that
+ * property key. Either value being `undefined` is never a match.
+ */
 export function compare<T>(
   a: T | undefined,
   b: T | undefined,
@@ -9,9 +18,13 @@ export function compare<T>(
   if (by === undefined) return a === b;
   if (typeof by === 'function') return by(a as T, b as T);
   // string key lookup
-  return (a as any)?.[by] === (b as any)?.[by];
+  return (a as Record<string, unknown>)?.[by] === (b as Record<string, unknown>)?.[by];
 }
 
+/**
+ * Whether `current` is contained in `value` (a single value or an array),
+ * using {@link compare} for each element.
+ */
 export function includes<T>(
   value: T | T[] | undefined,
   current: T,
diff --git a/vue/primitives/src/internal/utils/geometry.ts b/vue/primitives/src/internal/utils/geometry.ts
new file mode 100644
index 0000000..d9c9ee7
--- /dev/null
+++ b/vue/primitives/src/internal/utils/geometry.ts
@@ -0,0 +1,21 @@
+export interface Point { x: number; y: number }
+export type Polygon = Point[];
+
+/**
+ * Ray-casting point-in-polygon test: returns `true` when `point` lies inside
+ * `polygon` (a list of vertices). Shared by the menu and hover-card grace-area
+ * logic that decide whether the pointer is still within a "safe" travel region.
+ */
+export function isPointInPolygon(point: Point, polygon: Polygon): boolean {
+  const { x, y } = point;
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    const xi = polygon[i]!.x;
+    const yi = polygon[i]!.y;
+    const xj = polygon[j]!.x;
+    const yj = polygon[j]!.y;
+    const intersects = (yi > y) !== (yj > y) && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+    if (intersects) inside = !inside;
+  }
+  return inside;
+}
diff --git a/vue/primitives/src/utils/getRawChildren.ts b/vue/primitives/src/internal/utils/getRawChildren.ts
similarity index 100%
rename from vue/primitives/src/utils/getRawChildren.ts
rename to vue/primitives/src/internal/utils/getRawChildren.ts
diff --git a/vue/primitives/src/utils/roving-focus.ts b/vue/primitives/src/internal/utils/roving-focus.ts
similarity index 100%
rename from vue/primitives/src/utils/roving-focus.ts
rename to vue/primitives/src/internal/utils/roving-focus.ts
diff --git a/vue/primitives/src/utils/useGraceArea.ts b/vue/primitives/src/internal/utils/useGraceArea.ts
similarity index 69%
rename from vue/primitives/src/utils/useGraceArea.ts
rename to vue/primitives/src/internal/utils/useGraceArea.ts
index 1d92f99..576f932 100644
--- a/vue/primitives/src/utils/useGraceArea.ts
+++ b/vue/primitives/src/internal/utils/useGraceArea.ts
@@ -1,5 +1,7 @@
-import { onScopeDispose, ref, watchEffect } from 'vue';
+import { onScopeDispose, ref } from 'vue';
 import type { Ref } from 'vue';
+import { useEventListener } from '@robonen/vue';
+import { isPointInPolygon } from './geometry';
 
 interface Point { x: number; y: number }
 type Polygon = Point[];
@@ -59,49 +61,38 @@ export function useGraceArea(
     scheduleTransitReset();
   }
 
-  watchEffect((cleanup) => {
-    const trigger = triggerElement.value;
-    const container = containerElement.value;
-    if (!trigger || !container) return;
+  // A pointerleave on the trigger starts a transit toward the container, and
+  // vice versa. `handleCreateGraceArea` no-ops when the other element is absent,
+  // so the listeners are safe to bind whenever their own element exists.
+  useEventListener(triggerElement, 'pointerleave', (event: PointerEvent) => handleCreateGraceArea(event, containerElement.value));
+  useEventListener(containerElement, 'pointerleave', (event: PointerEvent) => handleCreateGraceArea(event, triggerElement.value));
 
-    const onTriggerLeave = (event: PointerEvent) => handleCreateGraceArea(event, containerElement.value);
-    const onContentLeave = (event: PointerEvent) => handleCreateGraceArea(event, triggerElement.value);
+  const onMove = (event: PointerEvent) => {
+    if (!pointerGraceArea.value || !(event.target instanceof Element)) return;
+    const target = event.target;
+    const point = { x: event.clientX, y: event.clientY };
+    const hasEnteredTarget
+      = triggerElement.value?.contains(target) || containerElement.value?.contains(target);
+    const outside = !isPointInPolygon(point, pointerGraceArea.value);
+    const isAnotherGraceTrigger = !!target.closest('[data-grace-area-trigger]');
 
-    trigger.addEventListener('pointerleave', onTriggerLeave);
-    container.addEventListener('pointerleave', onContentLeave);
+    if (hasEnteredTarget) {
+      handleRemoveGraceArea();
+    }
+    else if (outside || isAnotherGraceTrigger) {
+      handleRemoveGraceArea();
+      for (const fn of exitListeners) fn();
+    }
+  };
 
-    cleanup(() => {
-      trigger.removeEventListener('pointerleave', onTriggerLeave);
-      container.removeEventListener('pointerleave', onContentLeave);
-    });
-  });
-
-  watchEffect((cleanup) => {
-    if (!pointerGraceArea.value) return;
-    const doc = triggerElement.value?.ownerDocument;
-    if (!doc) return;
-
-    const onMove = (event: PointerEvent) => {
-      if (!pointerGraceArea.value || !(event.target instanceof Element)) return;
-      const target = event.target;
-      const point = { x: event.clientX, y: event.clientY };
-      const hasEnteredTarget
-        = triggerElement.value?.contains(target) || containerElement.value?.contains(target);
-      const outside = !isPointInPolygon(point, pointerGraceArea.value);
-      const isAnotherGraceTrigger = !!target.closest('[data-grace-area-trigger]');
-
-      if (hasEnteredTarget) {
-        handleRemoveGraceArea();
-      }
-      else if (outside || isAnotherGraceTrigger) {
-        handleRemoveGraceArea();
-        for (const fn of exitListeners) fn();
-      }
-    };
-
-    doc.addEventListener('pointermove', onMove);
-    cleanup(() => doc.removeEventListener('pointermove', onMove));
-  });
+  // Reactive target getter: the document `pointermove` listener attaches only
+  // while a grace area is active (and re-binds if the owning document changes),
+  // matching the previous conditional `watchEffect` — auto-removed on dispose.
+  useEventListener(
+    () => (pointerGraceArea.value ? (triggerElement.value?.ownerDocument ?? null) : null),
+    'pointermove',
+    onMove,
+  );
 
   onScopeDispose(() => {
     clearResetTimer();
@@ -165,20 +156,6 @@ function getPointsFromRect(rect: DOMRect): Point[] {
   ];
 }
 
-function isPointInPolygon(point: Point, polygon: Polygon): boolean {
-  const { x, y } = point;
-  let inside = false;
-  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
-    const xi = polygon[i]!.x;
-    const yi = polygon[i]!.y;
-    const xj = polygon[j]!.x;
-    const yj = polygon[j]!.y;
-    const intersect = ((yi > y) !== (yj > y)) && (x < (xj - xi) * (y - yi) / (yj - yi) + xi);
-    if (intersect) inside = !inside;
-  }
-  return inside;
-}
-
 function getHull<P extends Point>(points: readonly P[]): P[] {
   const sorted = points.slice().sort((a, b) => {
     if (a.x !== b.x) return a.x - b.x;
diff --git a/vue/primitives/src/utils/useHideOthers.ts b/vue/primitives/src/internal/utils/useHideOthers.ts
similarity index 100%
rename from vue/primitives/src/utils/useHideOthers.ts
rename to vue/primitives/src/internal/utils/useHideOthers.ts
diff --git a/vue/primitives/src/label/__test__/Label.test.ts b/vue/primitives/src/label/__test__/Label.test.ts
deleted file mode 100644
index 166f099..0000000
--- a/vue/primitives/src/label/__test__/Label.test.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { defineComponent, h } from 'vue';
-import { Label } from '../index';
-
-describe('Label', () => {
-  it('renders a native <label>', () => {
-    const wrapper = mount(Label, { slots: { default: 'Name' } });
-    expect(wrapper.element.tagName).toBe('LABEL');
-    expect(wrapper.text()).toBe('Name');
-  });
-
-  it('forwards `for` to the `for` attribute', () => {
-    const wrapper = mount(Label, { props: { for: 'my-input' } });
-    expect(wrapper.attributes('for')).toBe('my-input');
-  });
-
-  it('prevents text selection on multi-click', () => {
-    const wrapper = mount(defineComponent({
-      setup: () => () => h(Label, null, { default: () => 'x' }),
-    }));
-    const event = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 2 });
-    wrapper.element.dispatchEvent(event);
-    expect(event.defaultPrevented).toBe(true);
-  });
-
-  it('does not prevent default on single click', () => {
-    const wrapper = mount(Label);
-    const event = new MouseEvent('mousedown', { bubbles: true, cancelable: true, detail: 1 });
-    wrapper.element.dispatchEvent(event);
-    expect(event.defaultPrevented).toBe(false);
-  });
-});
diff --git a/vue/primitives/src/menu/MenuLabel.vue b/vue/primitives/src/menu/MenuLabel.vue
deleted file mode 100644
index 281ac5b..0000000
--- a/vue/primitives/src/menu/MenuLabel.vue
+++ /dev/null
@@ -1,22 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A non-interactive heading for a section of the menu. It is skipped by keyboard
- * navigation and typeahead, so use it to title a group of items rather than as a
- * selectable entry.
- */
-export interface MenuLabelProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-
-const { as = 'div' } = defineProps<MenuLabelProps>();
-</script>
-
-<template>
-  <Primitive :as="as">
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/menu/MenuSub.vue b/vue/primitives/src/menu/MenuSub.vue
deleted file mode 100644
index e22d229..0000000
--- a/vue/primitives/src/menu/MenuSub.vue
+++ /dev/null
@@ -1,52 +0,0 @@
-<script lang="ts">
-/**
- * Establishes a nested submenu. It provides a fresh menu context plus a sub
- * context shared by its MenuSubTrigger and MenuSubContent, owning the submenu's
- * open state. Bind `v-model:open` (or listen to `update:open`) to control it;
- * the default slot also exposes the current `open` value.
- */
-export interface MenuSubProps {
-  /** The controlled open state of the submenu. Use together with `update:open`. */
-  open?: boolean;
-}
-export interface MenuSubEmits {
-  'update:open': [value: boolean];
-}
-</script>
-
-<script setup lang="ts">
-import { shallowRef, toRef } from 'vue';
-
-import { useId } from '../config-provider';
-import { PopperRoot } from '../popper';
-import { provideMenuContext, provideMenuSubContext } from './context';
-
-const { open = false } = defineProps<MenuSubProps>();
-const emit = defineEmits<MenuSubEmits>();
-defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
-
-const openRef = toRef(() => open);
-const trigger = shallowRef<HTMLElement | null>(null);
-const contentId = useId(undefined, 'menu-sub-content');
-const triggerId = useId(undefined, 'menu-sub-trigger');
-
-provideMenuContext({
-  open: openRef,
-  onOpenChange: v => emit('update:open', v),
-  content: shallowRef<HTMLElement | null>(null),
-  onContentChange: () => {},
-});
-
-provideMenuSubContext({
-  contentId,
-  triggerId,
-  trigger,
-  onTriggerChange: (el) => { trigger.value = el; },
-});
-</script>
-
-<template>
-  <PopperRoot>
-    <slot :open="open" />
-  </PopperRoot>
-</template>
diff --git a/vue/primitives/src/menubar/MenubarContent.vue b/vue/primitives/src/menubar/MenubarContent.vue
deleted file mode 100644
index bb38c4a..0000000
--- a/vue/primitives/src/menubar/MenubarContent.vue
+++ /dev/null
@@ -1,52 +0,0 @@
-<script lang="ts">
-import type { MenuContentEmits, MenuContentProps } from '../menu';
-
-/**
- * The floating surface that holds a menu's items, positioned below its
- * MenubarTrigger. Handles focus management, typeahead, and dismissal on outside
- * click or Escape; render it inside a MenubarPortal so it escapes overflow
- * clipping.
- */
-export interface MenubarContentProps extends MenuContentProps {}
-export type MenubarContentEmits = MenuContentEmits;
-</script>
-
-<script setup lang="ts">
-import { MenuContent } from '../menu';
-import { useMenubarMenuContext, useMenubarRootContext } from './context';
-
-const props = defineProps<MenubarContentProps>();
-const emit = defineEmits<MenubarContentEmits>();
-
-const rootCtx = useMenubarRootContext();
-const menuCtx = useMenubarMenuContext();
-</script>
-
-<template>
-  <MenuContent
-    :id="menuCtx.contentId.value"
-    v-bind="props"
-    align="start"
-    :aria-labelledby="menuCtx.triggerId.value"
-    @close-auto-focus="(event: Event) => {
-      if (!menuCtx.wasKeyboardTriggerOpenRef.value) event.preventDefault()
-      menuCtx.wasKeyboardTriggerOpenRef.value = false
-      menuCtx.triggerRef.value?.focus({ preventScroll: true })
-      emit('closeAutoFocus', event)
-    }"
-    @escape-key-down="emit('escapeKeyDown', $event)"
-    @pointer-down-outside="(event: PointerEvent | MouseEvent) => {
-      const target = event.target as Node
-      const isMenubarTrigger = menuCtx.triggerRef.value?.contains(target)
-      if (isMenubarTrigger) event.preventDefault()
-      emit('pointerDownOutside', event)
-    }"
-    @focus-outside="emit('focusOutside', $event)"
-    @interact-outside="emit('interactOutside', $event)"
-    @dismiss="rootCtx.onMenuClose()"
-    @entry-focus="emit('entryFocus', $event)"
-    @open-auto-focus="emit('openAutoFocus', $event)"
-  >
-    <slot />
-  </MenuContent>
-</template>
diff --git a/vue/primitives/src/menubar/MenubarSub.vue b/vue/primitives/src/menubar/MenubarSub.vue
deleted file mode 100644
index 8b49363..0000000
--- a/vue/primitives/src/menubar/MenubarSub.vue
+++ /dev/null
@@ -1,22 +0,0 @@
-<script lang="ts">
-import type { MenuSubEmits, MenuSubProps } from '../menu';
-
-/**
- * Wraps a nested submenu, pairing a MenubarSubTrigger with its
- * MenubarSubContent. Owns the submenu's open state; bind `v-model:open` to
- * control or observe it.
- */
-export interface MenubarSubProps extends MenuSubProps {}
-export type MenubarSubEmits = MenuSubEmits;
-</script>
-
-<script setup lang="ts">
-import { MenuSub } from '../menu';
-
-const props = defineProps<MenubarSubProps>();
-const emit = defineEmits<MenubarSubEmits>();
-</script>
-
-<template>
-  <MenuSub v-bind="props" @update:open="emit('update:open', $event)"><slot /></MenuSub>
-</template>
diff --git a/vue/primitives/src/menubar/MenubarSubContent.vue b/vue/primitives/src/menubar/MenubarSubContent.vue
deleted file mode 100644
index 5938920..0000000
--- a/vue/primitives/src/menubar/MenubarSubContent.vue
+++ /dev/null
@@ -1,31 +0,0 @@
-<script lang="ts">
-import type { MenuSubContentEmits, MenuSubContentProps } from '../menu';
-
-/**
- * The floating surface for a submenu's items, positioned alongside its
- * MenubarSubTrigger. Place it inside a MenubarSub.
- */
-export interface MenubarSubContentProps extends MenuSubContentProps {}
-export type MenubarSubContentEmits = MenuSubContentEmits;
-</script>
-
-<script setup lang="ts">
-import { MenuSubContent } from '../menu';
-
-const props = defineProps<MenubarSubContentProps>();
-const emit = defineEmits<MenubarSubContentEmits>();
-</script>
-
-<template>
-  <MenuSubContent
-    v-bind="props"
-    @close-auto-focus="emit('closeAutoFocus', $event)"
-    @escape-key-down="emit('escapeKeyDown', $event)"
-    @pointer-down-outside="emit('pointerDownOutside', $event)"
-    @focus-outside="emit('focusOutside', $event)"
-    @interact-outside="emit('interactOutside', $event)"
-    @dismiss="emit('dismiss')"
-    @entry-focus="emit('entryFocus', $event)"
-    @open-auto-focus="emit('openAutoFocus', $event)"
-  ><slot /></MenuSubContent>
-</template>
diff --git a/vue/primitives/src/menus/command/CommandCancel.vue b/vue/primitives/src/menus/command/CommandCancel.vue
new file mode 100644
index 0000000..dc73c8d
--- /dev/null
+++ b/vue/primitives/src/menus/command/CommandCancel.vue
@@ -0,0 +1,48 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A clear/reset affordance for the palette: on click it empties the search term,
+ * refocuses the input, and — when `resetValue` is set — also clears the committed
+ * `modelValue`. Renders a `<button>` by default. Pair it with `CommandInput`.
+ */
+export interface CommandCancelProps extends PrimitiveProps {
+  /** Also clear the committed `modelValue`, not just the search term. */
+  resetValue?: boolean;
+  /** Accessible label for the control. @default 'Clear search' */
+  label?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useCommandContext } from './context';
+
+const {
+  as = 'button',
+  resetValue = false,
+  label = 'Clear search',
+} = defineProps<CommandCancelProps>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useCommandContext();
+
+function handleClick() {
+  ctx.clear(resetValue);
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :type="as === 'button' ? 'button' : undefined"
+    :aria-label="label"
+    tabindex="-1"
+    data-primitives-command-cancel
+    @click="handleClick"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/command/CommandEmpty.vue b/vue/primitives/src/menus/command/CommandEmpty.vue
similarity index 89%
rename from vue/primitives/src/command/CommandEmpty.vue
rename to vue/primitives/src/menus/command/CommandEmpty.vue
index ecbb772..e57df3a 100644
--- a/vue/primitives/src/command/CommandEmpty.vue
+++ b/vue/primitives/src/menus/command/CommandEmpty.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Empty-state message shown when the search yields no matching items. By default
@@ -16,7 +16,7 @@ export interface CommandEmptyProps extends PrimitiveProps {
 import { computed } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCommandContext } from './context';
 
 const { as = 'div', always = false } = defineProps<CommandEmptyProps>();
diff --git a/vue/primitives/src/command/CommandGroup.vue b/vue/primitives/src/menus/command/CommandGroup.vue
similarity index 92%
rename from vue/primitives/src/command/CommandGroup.vue
rename to vue/primitives/src/menus/command/CommandGroup.vue
index b8bfdc4..349ef4f 100644
--- a/vue/primitives/src/command/CommandGroup.vue
+++ b/vue/primitives/src/menus/command/CommandGroup.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Labelled section that visually clusters related items under an optional
@@ -20,8 +20,8 @@ export interface CommandGroupProps extends PrimitiveProps {
 import { computed, onBeforeUnmount, onMounted, toRef } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
-import { Primitive } from '../primitive';
+import { useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { provideCommandGroupContext, useCommandContext } from './context';
 
 const {
diff --git a/vue/primitives/src/command/CommandInput.vue b/vue/primitives/src/menus/command/CommandInput.vue
similarity index 86%
rename from vue/primitives/src/command/CommandInput.vue
rename to vue/primitives/src/menus/command/CommandInput.vue
index 1a3d4f2..9465bfd 100644
--- a/vue/primitives/src/command/CommandInput.vue
+++ b/vue/primitives/src/menus/command/CommandInput.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Search box that drives the command palette: typing updates the root search
@@ -22,10 +22,10 @@ export interface CommandInputEmits {
 </script>
 
 <script setup lang="ts">
-import { computed, onMounted, watch } from 'vue';
+import { computed, onBeforeUnmount, onMounted, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCommandContext } from './context';
 
 const {
@@ -48,6 +48,7 @@ const activeDescendant = computed(() => {
 onMounted(() => {
   const el = currentElement.value as HTMLInputElement | undefined;
   if (!el) return;
+  ctx.setInputElement(el);
   if (modelValue !== undefined && modelValue !== ctx.searchTerm.value) {
     ctx.setSearchTerm(modelValue);
   }
@@ -55,6 +56,10 @@ onMounted(() => {
   if (autoFocus) setTimeout(() => el.focus(), 0);
 });
 
+onBeforeUnmount(() => {
+  if (ctx.inputElement.value === currentElement.value) ctx.setInputElement(undefined);
+});
+
 watch(
   () => modelValue,
   (v) => {
@@ -136,7 +141,18 @@ function handleKeyDown(event: KeyboardEvent) {
       event.preventDefault();
       moveTo('last');
       break;
+    case 'PageUp':
+      event.preventDefault();
+      moveTo('first');
+      break;
+    case 'PageDown':
+      event.preventDefault();
+      moveTo('last');
+      break;
     case 'Enter':
+      // Don't commit while an IME candidate is being composed (e.g. CJK input);
+      // Enter confirms the candidate first.
+      if (event.isComposing || event.keyCode === 229) break;
       if (ctx.selectedValue.value !== undefined) {
         event.preventDefault();
         ctx.commitSelected();
diff --git a/vue/primitives/src/command/CommandItem.vue b/vue/primitives/src/menus/command/CommandItem.vue
similarity index 80%
rename from vue/primitives/src/command/CommandItem.vue
rename to vue/primitives/src/menus/command/CommandItem.vue
index 2e7b4f0..1a932f9 100644
--- a/vue/primitives/src/command/CommandItem.vue
+++ b/vue/primitives/src/menus/command/CommandItem.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A selectable option in the list. Registers itself with the root (so it can be
@@ -7,8 +7,14 @@ import type { PrimitiveProps } from '../primitive';
  * state via data attributes, and emits `select` when chosen by click or Enter.
  */
 export interface CommandItemProps extends PrimitiveProps {
-  /** Item value — used by filter, selection, and `data-value`. */
+  /** Item value — the identity used by selection and `data-value`. */
   value: string;
+  /**
+   * Plain-text representation the filter should match against. Use it when the
+   * `value` is an opaque identity key and the searchable label differs (e.g.
+   * non-text children). Falls back to `value` when omitted.
+   */
+  textValue?: string;
   /** Extra terms the default filter should match against. */
   keywords?: string[];
   /** Disable this item — it is skipped by keyboard nav and filtering. */
@@ -26,12 +32,13 @@ export interface CommandItemEmits {
 import { computed, onBeforeUnmount, onMounted, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { useCommandContext, useCommandGroupContext } from './context';
+import { Primitive } from '../../internal/primitive';
+import { provideCommandItemContext, useCommandContext, useCommandGroupContext } from './context';
 
 const {
   as = 'div',
   value,
+  textValue,
   keywords,
   disabled = false,
   forceMount = false,
@@ -55,9 +62,12 @@ const isVisible = computed(() => forceMount || ctx.filteredItems.value.has(value
 const isHighlighted = computed(() => ctx.selectedValue.value === value);
 const isSelected = computed(() => ctx.modelValue.value === value);
 
+provideCommandItemContext({ isSelected });
+
 function syncRegistration() {
   ctx.registerItem({
     value,
+    textValue: textValue ?? value,
     keywords: keywords ?? [],
     disabled,
     onSelect: () => emit('select', value),
@@ -70,7 +80,7 @@ onMounted(() => {
 });
 
 watch(
-  () => [value, disabled, (keywords ?? []).join('\u0001')] as const,
+  () => [value, textValue, disabled, (keywords ?? []).join('\u0001')] as const,
   (_next, prev) => {
     const [prevValue] = prev ?? [];
     if (prevValue !== undefined && prevValue !== value) {
@@ -115,9 +125,10 @@ function handleClick(event: MouseEvent) {
     :id="itemId"
     :as="as"
     role="option"
-    :aria-selected="isHighlighted || undefined"
+    :aria-selected="isSelected || undefined"
     :aria-disabled="disabled || undefined"
     :data-state="isHighlighted ? 'selected' : ''"
+    :data-highlighted="isHighlighted ? '' : undefined"
     :data-selected="isSelected ? '' : undefined"
     :data-disabled="disabled ? '' : undefined"
     :data-primitives-state="isVisible ? 'visible' : 'hidden'"
diff --git a/vue/primitives/src/menus/command/CommandItemIndicator.vue b/vue/primitives/src/menus/command/CommandItemIndicator.vue
new file mode 100644
index 0000000..949e716
--- /dev/null
+++ b/vue/primitives/src/menus/command/CommandItemIndicator.vue
@@ -0,0 +1,37 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Renders its content only while the parent `CommandItem` matches the committed
+ * `modelValue` — use it to show a check (or any marker) on the selected row of a
+ * palette that keeps a persistent selection. Marked `aria-hidden` because the
+ * selection state is already conveyed by the item's `aria-selected`.
+ */
+export interface CommandItemIndicatorProps extends PrimitiveProps {
+  /** Render even when the parent item is not the committed selection. */
+  forceMount?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useCommandItemContext } from './context';
+
+const { as = 'span', forceMount = false } = defineProps<CommandItemIndicatorProps>();
+
+const { forwardRef } = useForwardExpose();
+const itemCtx = useCommandItemContext();
+</script>
+
+<template>
+  <Primitive
+    v-if="forceMount || itemCtx.isSelected.value"
+    :ref="forwardRef"
+    :as="as"
+    aria-hidden="true"
+    data-primitives-command-item-indicator
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/command/CommandList.vue b/vue/primitives/src/menus/command/CommandList.vue
similarity index 95%
rename from vue/primitives/src/command/CommandList.vue
rename to vue/primitives/src/menus/command/CommandList.vue
index b2086db..3f37156 100644
--- a/vue/primitives/src/command/CommandList.vue
+++ b/vue/primitives/src/menus/command/CommandList.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Scrollable listbox container that holds the items, groups, and empty/loading
@@ -13,7 +13,7 @@ export interface CommandListProps extends PrimitiveProps {}
 import { onBeforeUnmount, onMounted, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCommandContext } from './context';
 
 const { as = 'div' } = defineProps<CommandListProps>();
diff --git a/vue/primitives/src/command/CommandLoading.vue b/vue/primitives/src/menus/command/CommandLoading.vue
similarity index 90%
rename from vue/primitives/src/command/CommandLoading.vue
rename to vue/primitives/src/menus/command/CommandLoading.vue
index 84caf92..41b1140 100644
--- a/vue/primitives/src/command/CommandLoading.vue
+++ b/vue/primitives/src/menus/command/CommandLoading.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Progress indicator for asynchronous results — render it inside the list while
@@ -17,7 +17,7 @@ export interface CommandLoadingProps extends PrimitiveProps {
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const {
   as = 'div',
diff --git a/vue/primitives/src/command/CommandRoot.vue b/vue/primitives/src/menus/command/CommandRoot.vue
similarity index 85%
rename from vue/primitives/src/command/CommandRoot.vue
rename to vue/primitives/src/menus/command/CommandRoot.vue
index 46360eb..daa4423 100644
--- a/vue/primitives/src/command/CommandRoot.vue
+++ b/vue/primitives/src/menus/command/CommandRoot.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Direction } from '../../utilities/config-provider';
 import type { CommandFilterFunction } from './utils';
 
 /**
@@ -28,6 +29,11 @@ export interface CommandRootProps extends PrimitiveProps {
   loop?: boolean;
   /** Accessible label announced to assistive tech. */
   label?: string;
+  /**
+   * Writing direction. When omitted, inherits from a `ConfigProvider`,
+   * falling back to `'ltr'`.
+   */
+  dir?: Direction;
 }
 
 export interface CommandRootEmits {
@@ -40,9 +46,9 @@ export interface CommandRootEmits {
 import { computed, ref, shallowRef, toRef, triggerRef, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
-import { Primitive } from '../primitive';
-import { VisuallyHidden } from '../visually-hidden';
+import { useDirection, useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
 import { provideCommandContext } from './context';
 import type { CommandItemInfo } from './context';
 import { COMMAND_ITEM_ATTR, COMMAND_VALUE_ATTR, defaultFilter } from './utils';
@@ -57,9 +63,10 @@ const {
   shouldFilter = true,
   loop = false,
   label,
+  dir,
 } = defineProps<CommandRootProps>();
 
-const { forwardRef } = useForwardExpose();
+const direction = useDirection(() => dir);
 
 const localValue = ref<string | undefined>(defaultValue);
 const value = defineModel<string | undefined>('modelValue', {
@@ -87,6 +94,7 @@ const listId = useId(undefined, 'command-list');
 const labelId = useId(undefined, 'command-label');
 
 const listElement = shallowRef<HTMLElement | undefined>(undefined);
+const inputElement = shallowRef<HTMLElement | undefined>(undefined);
 
 const allItems = shallowRef(new Map<string, CommandItemInfo>());
 const allGroups = shallowRef(new Map<string, Set<string>>());
@@ -137,7 +145,7 @@ const filteredItems = computed<Map<string, number>>(() => {
   const fn = filterRef.value ?? defaultFilter;
 
   for (const [val, info] of allItems.value) {
-    const score = useFilter ? fn(val, term, info.keywords) : 1;
+    const score = useFilter ? fn(info.textValue, term, info.keywords) : 1;
     if (score > 0) out.set(val, score);
   }
   return out;
@@ -200,6 +208,20 @@ function setListElement(el: HTMLElement | undefined) {
   listElement.value = el;
 }
 
+function setInputElement(el: HTMLElement | undefined) {
+  inputElement.value = el;
+}
+
+function clear(resetValue = false) {
+  setSearchTerm('');
+  if (resetValue) setModelValue(undefined);
+  const el = inputElement.value as HTMLInputElement | undefined;
+  if (el) {
+    if (el.value !== '') el.value = '';
+    el.focus();
+  }
+}
+
 function commitSelected() {
   const v = selectedValue.value;
   if (v === undefined) return;
@@ -239,6 +261,7 @@ provideCommandContext({
   shouldFilter: toRef(() => shouldFilter),
   loop: toRef(() => loop),
   filterFunction: filterRef,
+  dir: direction,
   listId,
   labelId,
   getItemId,
@@ -255,6 +278,9 @@ provideCommandContext({
   setListElement,
   getSelectableItems,
   commitSelected,
+  clear,
+  inputElement,
+  setInputElement,
 });
 
 defineExpose({
@@ -263,7 +289,14 @@ defineExpose({
   selectedValue,
   setSelectedValue,
   commitSelected,
+  clear,
 });
+
+// `useForwardExpose` runs AFTER `defineExpose` so the composable absorbs and
+// merges the prior expose bindings (plus props + `$el`) instead of
+// `defineExpose`'s `expose()` clobbering them and warning
+// "expose() should be called only once per setup()".
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
@@ -273,6 +306,7 @@ defineExpose({
     role="application"
     :aria-label="label"
     :aria-labelledby="label ? undefined : labelId"
+    :dir="direction"
     data-primitives-command-root
     v-bind="$attrs"
   >
diff --git a/vue/primitives/src/command/CommandSeparator.vue b/vue/primitives/src/menus/command/CommandSeparator.vue
similarity index 89%
rename from vue/primitives/src/command/CommandSeparator.vue
rename to vue/primitives/src/menus/command/CommandSeparator.vue
index 221e7e9..3716bed 100644
--- a/vue/primitives/src/command/CommandSeparator.vue
+++ b/vue/primitives/src/menus/command/CommandSeparator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Visual divider between groups or items. Hidden automatically while a search
@@ -15,7 +15,7 @@ export interface CommandSeparatorProps extends PrimitiveProps {
 import { computed } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCommandContext } from './context';
 
 const { as = 'div', alwaysRender = false } = defineProps<CommandSeparatorProps>();
diff --git a/vue/primitives/src/menus/command/__test__/Command.test.ts b/vue/primitives/src/menus/command/__test__/Command.test.ts
new file mode 100644
index 0000000..2a42e14
--- /dev/null
+++ b/vue/primitives/src/menus/command/__test__/Command.test.ts
@@ -0,0 +1,617 @@
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+
+import {
+  CommandCancel,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandItemIndicator,
+  CommandList,
+  CommandRoot,
+  CommandSeparator,
+} from '../index';
+
+interface Opt {
+  value: string;
+  label?: string;
+  keywords?: string[];
+  disabled?: boolean;
+  textValue?: string;
+}
+
+function createCommand(
+  options: Opt[],
+  rootProps: Record<string, unknown> = {},
+  inputProps: Record<string, unknown> = {},
+) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () =>
+          h(CommandRoot, { label: 'Test palette', ...rootProps }, {
+            default: () => [
+              h(CommandInput, { ...inputProps }),
+              h(CommandList, null, {
+                default: () => [
+                  h(CommandEmpty, null, { default: () => 'No results' }),
+                  ...options.map(o =>
+                    h(
+                      CommandItem,
+                      {
+                        value: o.value,
+                        keywords: o.keywords,
+                        disabled: o.disabled,
+                        textValue: o.textValue,
+                      },
+                      {
+                        default: () => [
+                          o.label ?? o.value,
+                          h(CommandItemIndicator, null, { default: () => 'X' }),
+                        ],
+                      },
+                    ),
+                  ),
+                ],
+              }),
+            ],
+          });
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+function press(el: Element, key: string, opts: Record<string, unknown> = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...opts }));
+}
+
+function setInput(el: HTMLInputElement, value: string) {
+  el.value = value;
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+const sample: Opt[] = [
+  { value: 'apple', keywords: ['fruit'] },
+  { value: 'banana', keywords: ['fruit', 'yellow'] },
+  { value: 'cherry', keywords: ['fruit', 'red'] },
+];
+
+describe('Command — ARIA skeleton', () => {
+  it('renders combobox input, listbox and options with correct roles', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    expect(w.find('[role="combobox"]').exists()).toBe(true);
+    expect(w.find('[role="listbox"]').exists()).toBe(true);
+    expect(w.findAll('[role="option"]')).toHaveLength(3);
+    const input = w.find('[role="combobox"]');
+    expect(input.attributes('aria-controls')).toBe(w.find('[role="listbox"]').attributes('id'));
+    w.unmount();
+  });
+
+  it('exposes a polite live region announcing result count', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const status = w.find('[role="status"]');
+    expect(status.exists()).toBe(true);
+    expect(status.text()).toContain('3 results available.');
+    w.unmount();
+  });
+
+  it('drives aria-activedescendant from the highlighted item', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const input = w.find('[role="combobox"]');
+    const active = input.attributes('aria-activedescendant');
+    expect(active).toBeTruthy();
+    const highlighted = w.find('[data-highlighted]');
+    expect(highlighted.attributes('id')).toBe(active);
+    w.unmount();
+  });
+});
+
+describe('Command — aria-selected semantics', () => {
+  it('sets aria-selected from committed modelValue, not the highlight', async () => {
+    const w = createCommand(sample, { modelValue: 'banana' });
+    await nextTick();
+    const options = w.findAll('[role="option"]');
+    const selected = options.filter(o => o.attributes('aria-selected') === 'true');
+    expect(selected).toHaveLength(1);
+    expect(selected[0]!.attributes('data-value')).toBe('banana');
+    w.unmount();
+  });
+
+  it('highlight is conveyed via data-highlighted, separate from aria-selected', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    // First item auto-highlighted, but nothing committed → no aria-selected.
+    expect(w.findAll('[aria-selected="true"]')).toHaveLength(0);
+    expect(w.findAll('[data-highlighted]')).toHaveLength(1);
+    w.unmount();
+  });
+
+  it('renders ItemIndicator only on the committed item', async () => {
+    const w = createCommand(sample, { modelValue: 'cherry' });
+    await nextTick();
+    const indicators = w.findAll('[data-primitives-command-item-indicator]');
+    expect(indicators).toHaveLength(1);
+    const cherryRow = w.findAll('[role="option"]').find(o => o.attributes('data-value') === 'cherry')!;
+    expect(cherryRow.find('[data-primitives-command-item-indicator]').exists()).toBe(true);
+    w.unmount();
+  });
+});
+
+describe('Command — filtering', () => {
+  it('filters by substring of value', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    setInput(input, 'ban');
+    await nextTick();
+    const visible = w.findAll('[role="option"]').filter(o => (o.element as HTMLElement).style.display !== 'none');
+    expect(visible.map(o => o.attributes('data-value'))).toEqual(['banana']);
+    w.unmount();
+  });
+
+  it('matches keywords', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    setInput(input, 'yellow');
+    await nextTick();
+    const visible = w.findAll('[role="option"]').filter(o => (o.element as HTMLElement).style.display !== 'none');
+    expect(visible.map(o => o.attributes('data-value'))).toEqual(['banana']);
+    w.unmount();
+  });
+
+  it('filters by textValue when the value is an opaque key', async () => {
+    const w = createCommand([
+      { value: 'id-1', textValue: 'Zebra' },
+      { value: 'id-2', textValue: 'Lion' },
+    ]);
+    await nextTick();
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    setInput(input, 'zeb');
+    await nextTick();
+    const visible = w.findAll('[role="option"]').filter(o => (o.element as HTMLElement).style.display !== 'none');
+    expect(visible.map(o => o.attributes('data-value'))).toEqual(['id-1']);
+    w.unmount();
+  });
+
+  it('shows the empty state when nothing matches', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    setInput(input, 'zzzz');
+    await nextTick();
+    expect(w.find('[data-primitives-command-empty]').exists()).toBe(true);
+    w.unmount();
+  });
+
+  it('respects shouldFilter=false (no filtering)', async () => {
+    const w = createCommand(sample, { shouldFilter: false });
+    await nextTick();
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    setInput(input, 'zzzz');
+    await nextTick();
+    const visible = w.findAll('[role="option"]').filter(o => (o.element as HTMLElement).style.display !== 'none');
+    expect(visible).toHaveLength(3);
+    w.unmount();
+  });
+});
+
+describe('Command — keyboard navigation', () => {
+  it('ArrowDown / ArrowUp move the highlight', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const input = w.find('[role="combobox"]');
+    press(input.element, 'ArrowDown');
+    await nextTick();
+    expect(w.find('[data-highlighted]').attributes('data-value')).toBe('banana');
+    press(input.element, 'ArrowUp');
+    await nextTick();
+    expect(w.find('[data-highlighted]').attributes('data-value')).toBe('apple');
+    w.unmount();
+  });
+
+  it('Home / End jump to first / last', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const input = w.find('[role="combobox"]');
+    press(input.element, 'End');
+    await nextTick();
+    expect(w.find('[data-highlighted]').attributes('data-value')).toBe('cherry');
+    press(input.element, 'Home');
+    await nextTick();
+    expect(w.find('[data-highlighted]').attributes('data-value')).toBe('apple');
+    w.unmount();
+  });
+
+  it('PageDown / PageUp jump to last / first', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    const input = w.find('[role="combobox"]');
+    press(input.element, 'PageDown');
+    await nextTick();
+    expect(w.find('[data-highlighted]').attributes('data-value')).toBe('cherry');
+    press(input.element, 'PageUp');
+    await nextTick();
+    expect(w.find('[data-highlighted]').attributes('data-value')).toBe('apple');
+    w.unmount();
+  });
+
+  it('clamps at the ends by default and wraps with loop', async () => {
+    const clamp = createCommand(sample);
+    await nextTick();
+    let input = clamp.find('[role="combobox"]');
+    press(input.element, 'ArrowUp');
+    await nextTick();
+    expect(clamp.find('[data-highlighted]').attributes('data-value')).toBe('apple');
+    clamp.unmount();
+
+    const loop = createCommand(sample, { loop: true });
+    await nextTick();
+    input = loop.find('[role="combobox"]');
+    press(input.element, 'ArrowUp');
+    await nextTick();
+    expect(loop.find('[data-highlighted]').attributes('data-value')).toBe('cherry');
+    loop.unmount();
+  });
+
+  it('Enter commits the highlighted item and updates modelValue', async () => {
+    const model = ref<string | undefined>(undefined);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, { modelValue: model.value, 'onUpdate:modelValue': (v: string | undefined) => (model.value = v) }, {
+              default: () => [
+                h(CommandInput),
+                h(CommandList, null, {
+                  default: () => sample.map(o => h(CommandItem, { value: o.value }, { default: () => o.value })),
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const input = w.find('[role="combobox"]');
+    press(input.element, 'ArrowDown');
+    await nextTick();
+    press(input.element, 'Enter');
+    await nextTick();
+    expect(model.value).toBe('banana');
+    w.unmount();
+  });
+
+  it('Enter does NOT commit while IME composition is active', async () => {
+    const model = ref<string | undefined>(undefined);
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, { modelValue: model.value, 'onUpdate:modelValue': (v: string | undefined) => (model.value = v) }, {
+              default: () => [
+                h(CommandInput),
+                h(CommandList, null, {
+                  default: () => sample.map(o => h(CommandItem, { value: o.value }, { default: () => o.value })),
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const input = w.find('[role="combobox"]');
+    press(input.element, 'Enter', { isComposing: true });
+    await nextTick();
+    expect(model.value).toBeUndefined();
+    // Without composition it commits.
+    press(input.element, 'Enter');
+    await nextTick();
+    expect(model.value).toBe('apple');
+    w.unmount();
+  });
+});
+
+describe('Command — selection & emit', () => {
+  it('click commits and emits select on the item', async () => {
+    const selected: string[] = [];
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, null, {
+              default: () => [
+                h(CommandInput),
+                h(CommandList, null, {
+                  default: () =>
+                    sample.map(o =>
+                      h(CommandItem, { value: o.value, onSelect: (v: string) => selected.push(v) }, { default: () => o.value }),
+                    ),
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const banana = w.findAll('[role="option"]').find(o => o.attributes('data-value') === 'banana')!;
+    await banana.trigger('click');
+    await nextTick();
+    expect(selected).toEqual(['banana']);
+    w.unmount();
+  });
+
+  it('disabled item blocks click selection and is skipped by keyboard', async () => {
+    const selected: string[] = [];
+    const opts: Opt[] = [
+      { value: 'a' },
+      { value: 'b', disabled: true },
+      { value: 'c' },
+    ];
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, null, {
+              default: () => [
+                h(CommandInput),
+                h(CommandList, null, {
+                  default: () =>
+                    opts.map(o =>
+                      h(
+                        CommandItem,
+                        { value: o.value, disabled: o.disabled, onSelect: (v: string) => selected.push(v) },
+                        { default: () => o.value },
+                      ),
+                    ),
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const disabled = w.findAll('[role="option"]').find(o => o.attributes('data-value') === 'b')!;
+    expect(disabled.attributes('aria-disabled')).toBe('true');
+    await disabled.trigger('click');
+    await nextTick();
+    expect(selected).toEqual([]);
+
+    const input = w.find('[role="combobox"]');
+    press(input.element, 'ArrowDown');
+    await nextTick();
+    // skips disabled 'b' → goes to 'c'
+    expect(w.find('[data-highlighted]').attributes('data-value')).toBe('c');
+    w.unmount();
+  });
+});
+
+describe('Command — uncontrolled & controlled search', () => {
+  it('uncontrolled defaultSearchTerm seeds the search', async () => {
+    const w = createCommand(sample, { defaultSearchTerm: 'cher' });
+    await nextTick();
+    const visible = w.findAll('[role="option"]').filter(o => (o.element as HTMLElement).style.display !== 'none');
+    expect(visible.map(o => o.attributes('data-value'))).toEqual(['cherry']);
+    w.unmount();
+  });
+
+  it('controlled searchTerm v-model reflects into the list', async () => {
+    const term = ref('app');
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, { searchTerm: term.value, 'onUpdate:searchTerm': (v: string) => (term.value = v) }, {
+              default: () => [
+                h(CommandInput),
+                h(CommandList, null, {
+                  default: () => sample.map(o => h(CommandItem, { value: o.value }, { default: () => o.value })),
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    let visible = w.findAll('[role="option"]').filter(o => (o.element as HTMLElement).style.display !== 'none');
+    expect(visible.map(o => o.attributes('data-value'))).toEqual(['apple']);
+    term.value = 'ban';
+    await nextTick();
+    visible = w.findAll('[role="option"]').filter(o => (o.element as HTMLElement).style.display !== 'none');
+    expect(visible.map(o => o.attributes('data-value'))).toEqual(['banana']);
+    w.unmount();
+  });
+});
+
+describe('Command — Cancel / clear', () => {
+  it('clears the search term and refocuses the input on click', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, { defaultSearchTerm: 'banana' }, {
+              default: () => [
+                h(CommandInput),
+                h(CommandCancel, null, { default: () => 'Clear' }),
+                h(CommandList, null, {
+                  default: () => sample.map(o => h(CommandItem, { value: o.value }, { default: () => o.value })),
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    expect(input.value).toBe('banana');
+    await w.find('[data-primitives-command-cancel]').trigger('click');
+    await nextTick();
+    expect(input.value).toBe('');
+    expect(document.activeElement).toBe(input);
+    w.unmount();
+  });
+
+  it('resetValue also clears the committed modelValue', async () => {
+    const model = ref<string | undefined>('apple');
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, { modelValue: model.value, 'onUpdate:modelValue': (v: string | undefined) => (model.value = v) }, {
+              default: () => [
+                h(CommandInput),
+                h(CommandCancel, { resetValue: true }, { default: () => 'Clear' }),
+                h(CommandList, null, {
+                  default: () => sample.map(o => h(CommandItem, { value: o.value }, { default: () => o.value })),
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    await w.find('[data-primitives-command-cancel]').trigger('click');
+    await nextTick();
+    expect(model.value).toBeUndefined();
+    w.unmount();
+  });
+
+  it('renders a button with type=button and an accessible label', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, null, {
+              default: () => [h(CommandInput), h(CommandCancel, null, { default: () => 'Clear' })],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const btn = w.find('[data-primitives-command-cancel]');
+    expect(btn.attributes('type')).toBe('button');
+    expect(btn.attributes('aria-label')).toBe('Clear search');
+    w.unmount();
+  });
+});
+
+describe('Command — dir / RTL', () => {
+  it('reflects dir on the root', async () => {
+    const w = createCommand(sample, { dir: 'rtl' });
+    await nextTick();
+    expect(w.find('[data-primitives-command-root]').attributes('dir')).toBe('rtl');
+    w.unmount();
+  });
+
+  it('defaults to ltr', async () => {
+    const w = createCommand(sample);
+    await nextTick();
+    expect(w.find('[data-primitives-command-root]').attributes('dir')).toBe('ltr');
+    w.unmount();
+  });
+});
+
+describe('Command — separator', () => {
+  it('hides the separator while a search term is active', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, null, {
+              default: () => [
+                h(CommandInput),
+                h(CommandList, null, {
+                  default: () => [
+                    h(CommandItem, { value: 'a' }, { default: () => 'a' }),
+                    h(CommandSeparator),
+                    h(CommandItem, { value: 'b' }, { default: () => 'b' }),
+                  ],
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(w.find('[data-primitives-command-separator]').exists()).toBe(true);
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    setInput(input, 'a');
+    await nextTick();
+    expect(w.find('[data-primitives-command-separator]').exists()).toBe(false);
+    w.unmount();
+  });
+});
+
+describe('Command — groups', () => {
+  it('hides a group when all its items are filtered out', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(CommandRoot, null, {
+              default: () => [
+                h(CommandInput),
+                h(CommandList, null, {
+                  default: () => [
+                    h(CommandGroup, { heading: 'Fruit', value: 'fruit' }, {
+                      default: () => [
+                        h(CommandItem, { value: 'apple' }, { default: () => 'apple' }),
+                      ],
+                    }),
+                    h(CommandGroup, { heading: 'Veg', value: 'veg' }, {
+                      default: () => [
+                        h(CommandItem, { value: 'carrot' }, { default: () => 'carrot' }),
+                      ],
+                    }),
+                  ],
+                }),
+              ],
+            });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const input = w.find('[role="combobox"]').element as HTMLInputElement;
+    setInput(input, 'apple');
+    await nextTick();
+    const groups = w.findAll('[data-primitives-command-group]');
+    const fruit = groups.find(g => g.text().includes('Fruit'))!;
+    const veg = groups.find(g => g.text().includes('Veg'))!;
+    expect(fruit.attributes('hidden')).toBeUndefined();
+    expect(veg.attributes('hidden')).toBe('');
+    w.unmount();
+  });
+});
+
+describe('Command — edge cases', () => {
+  it('handles an empty item list', async () => {
+    const w = createCommand([]);
+    await nextTick();
+    expect(w.findAll('[role="option"]')).toHaveLength(0);
+    const status = w.find('[role="status"]');
+    expect(status.text()).toContain('0 results available.');
+    w.unmount();
+  });
+
+  it('singular vs plural in the live region', async () => {
+    const w = createCommand([{ value: 'only' }]);
+    await nextTick();
+    expect(w.find('[role="status"]').text()).toContain('1 result available.');
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/command/context.ts b/vue/primitives/src/menus/command/context.ts
similarity index 73%
rename from vue/primitives/src/command/context.ts
rename to vue/primitives/src/menus/command/context.ts
index 68ad0d4..c5db915 100644
--- a/vue/primitives/src/command/context.ts
+++ b/vue/primitives/src/menus/command/context.ts
@@ -5,6 +5,8 @@ import { useContextFactory } from '@robonen/vue';
 
 export interface CommandItemInfo {
   value: string;
+  /** Display/searchable text. Filtering targets this instead of the identity `value`. */
+  textValue: string;
   keywords: string[];
   disabled: boolean;
   onSelect?: () => void;
@@ -27,6 +29,8 @@ export interface CommandContext {
   shouldFilter: Ref<boolean>;
   loop: Ref<boolean>;
   filterFunction: Ref<CommandFilterFunction | undefined>;
+  /** Effective reading direction (per-root override or `ConfigProvider`). */
+  dir: Ref<'ltr' | 'rtl'>;
 
   /** A11y identifiers. */
   listId: Ref<string>;
@@ -53,6 +57,11 @@ export interface CommandContext {
   getSelectableItems: () => string[];
   /** Commits the currently-highlighted item: updates modelValue + fires its select callback. */
   commitSelected: () => void;
+  /** Clears the search term and, when `resetValue`, the committed selection too. */
+  clear: (resetValue?: boolean) => void;
+  /** Registered input element (so a clear/cancel affordance can refocus it). */
+  inputElement: ShallowRef<HTMLElement | undefined>;
+  setInputElement: (el: HTMLElement | undefined) => void;
 }
 
 export interface CommandGroupContext {
@@ -60,6 +69,11 @@ export interface CommandGroupContext {
   forceMount: Ref<boolean>;
 }
 
+export interface CommandItemContext {
+  /** Whether this item matches the committed `modelValue`. */
+  isSelected: Ref<boolean>;
+}
+
 export const {
   inject: useCommandContext,
   provide: provideCommandContext,
@@ -69,3 +83,8 @@ export const {
   inject: useCommandGroupContext,
   provide: provideCommandGroupContext,
 } = useContextFactory<CommandGroupContext>('CommandGroup');
+
+export const {
+  inject: useCommandItemContext,
+  provide: provideCommandItemContext,
+} = useContextFactory<CommandItemContext>('CommandItem');
diff --git a/vue/primitives/src/menus/command/demo.vue b/vue/primitives/src/menus/command/demo.vue
new file mode 100644
index 0000000..362a5ce
--- /dev/null
+++ b/vue/primitives/src/menus/command/demo.vue
@@ -0,0 +1,162 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+
+import {
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandRoot,
+  CommandSeparator,
+} from '@robonen/primitives';
+
+interface Action {
+  value: string;
+  label: string;
+  /** Inline-SVG path data (24×24 viewBox, stroked with `currentColor`). */
+  icon: string;
+  keywords?: string[];
+  shortcut?: string;
+}
+
+const navigation: Action[] = [
+  { value: 'home', label: 'Go to Dashboard', icon: 'M3 3h8v8H3z M13 3h8v8h-8z M13 13h8v8h-8z M3 13h8v8H3z', keywords: ['overview', 'start'] },
+  { value: 'projects', label: 'Open Projects', icon: 'M3 7a1 1 0 0 1 1-1h5l2 2h9a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1z', keywords: ['repos', 'work'] },
+  { value: 'settings', label: 'Open Settings', icon: 'M4 21v-7 M4 10V3 M12 21v-9 M12 8V3 M20 21v-5 M20 12V3 M2 14h4 M10 8h4 M18 16h4', keywords: ['preferences', 'config'], shortcut: ',' },
+];
+
+const actions: Action[] = [
+  { value: 'new-file', label: 'Create new file', icon: 'M13 3H6a1 1 0 0 0-1 1v16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1V9z M13 3v6h6 M12 12v6 M9 15h6', keywords: ['add'], shortcut: 'N' },
+  { value: 'invite', label: 'Invite teammate', icon: 'M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2 M9 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8z M19 8v6 M22 11h-6', keywords: ['member', 'share'] },
+  { value: 'theme', label: 'Toggle dark mode', icon: 'M21 12.8A9 9 0 1 1 11.2 3 7 7 0 0 0 21 12.8z', keywords: ['appearance', 'light'] },
+  { value: 'archive', label: 'Archive workspace', icon: 'M4 8h16v11a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1z M3 4h18v4H3z M10 12h4', keywords: ['delete'] },
+];
+
+const selected = ref<string>();
+const lastRun = ref<string>();
+
+function run(value: string) {
+  lastRun.value = value;
+}
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4 p-6 bg-bg-inset text-fg">
+    <CommandRoot
+      v-model="selected"
+      label="Command palette"
+      loop
+      class="demo-card w-full max-w-100 overflow-hidden shadow-lg"
+    >
+      <template #default="{ filteredCount }">
+        <!-- Search -->
+        <div class="flex items-center gap-2.5 border-b border-border px-3.5">
+          <svg
+            viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75"
+            stroke-linecap="round" stroke-linejoin="round"
+            class="size-4 shrink-0 text-fg-subtle" aria-hidden="true"
+          >
+            <path d="M11 19a8 8 0 1 1 0-16 8 8 0 0 1 0 16z M21 21l-4.3-4.3" />
+          </svg>
+          <CommandInput
+            auto-focus
+            placeholder="Type a command or search…"
+            class="w-full bg-transparent py-3 text-sm text-fg outline-none placeholder:text-fg-subtle"
+          />
+          <span class="shrink-0 rounded bg-bg-subtle px-1.5 py-0.5 text-[11px] font-medium tabular-nums text-fg-subtle">{{ filteredCount }}</span>
+        </div>
+
+        <!-- Results -->
+        <CommandList class="max-h-72 overflow-y-auto p-2">
+          <CommandEmpty class="px-3 py-10 text-center text-sm text-fg-muted">
+            No results found.
+          </CommandEmpty>
+
+          <CommandGroup
+            heading="Navigation"
+            class="[&_[data-primitives-command-group-heading]]:px-2 [&_[data-primitives-command-group-heading]]:pb-1 [&_[data-primitives-command-group-heading]]:pt-2 [&_[data-primitives-command-group-heading]]:text-xs [&_[data-primitives-command-group-heading]]:font-medium [&_[data-primitives-command-group-heading]]:text-fg-subtle"
+          >
+            <template #default>
+              <CommandItem
+                v-for="item in navigation"
+                :key="item.value"
+                :value="item.value"
+                :text-value="item.label"
+                :keywords="item.keywords"
+                class="group flex cursor-pointer items-center gap-2.5 rounded-md px-2 py-2 text-sm data-[state=selected]:bg-accent data-[state=selected]:text-accent-fg"
+                @select="run"
+              >
+                <template #default="{ selected: isSelected }">
+                  <svg
+                    viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75"
+                    stroke-linecap="round" stroke-linejoin="round"
+                    class="size-4 shrink-0 text-fg-muted group-data-[state=selected]:text-accent-fg" aria-hidden="true"
+                  >
+                    <path :d="item.icon" />
+                  </svg>
+                  <span class="flex-1">{{ item.label }}</span>
+                  <kbd
+                    v-if="item.shortcut"
+                    class="rounded border border-border bg-bg-subtle px-1.5 text-xs text-fg-muted group-data-[state=selected]:border-transparent group-data-[state=selected]:bg-transparent group-data-[state=selected]:text-accent-fg"
+                  >⌘{{ item.shortcut }}</kbd>
+                  <svg
+                    v-if="isSelected"
+                    viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25"
+                    stroke-linecap="round" stroke-linejoin="round"
+                    class="size-4 shrink-0 text-emerald-500 group-data-[state=selected]:text-accent-fg dark:text-emerald-400" aria-hidden="true"
+                  >
+                    <path d="M20 6 9 17l-5-5" />
+                  </svg>
+                </template>
+              </CommandItem>
+            </template>
+          </CommandGroup>
+
+          <CommandSeparator class="my-2 h-px bg-border" />
+
+          <CommandGroup
+            heading="Actions"
+            class="[&_[data-primitives-command-group-heading]]:px-2 [&_[data-primitives-command-group-heading]]:pb-1 [&_[data-primitives-command-group-heading]]:pt-2 [&_[data-primitives-command-group-heading]]:text-xs [&_[data-primitives-command-group-heading]]:font-medium [&_[data-primitives-command-group-heading]]:text-fg-subtle"
+          >
+            <template #default>
+              <CommandItem
+                v-for="item in actions"
+                :key="item.value"
+                :value="item.value"
+                :text-value="item.label"
+                :keywords="item.keywords"
+                :disabled="item.value === 'archive'"
+                class="group flex cursor-pointer items-center gap-2.5 rounded-md px-2 py-2 text-sm data-[state=selected]:bg-accent data-[state=selected]:text-accent-fg data-[disabled]:cursor-not-allowed data-[disabled]:opacity-40"
+                @select="run"
+              >
+                <svg
+                  viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75"
+                  stroke-linecap="round" stroke-linejoin="round"
+                  class="size-4 shrink-0 text-fg-muted group-data-[state=selected]:text-accent-fg" aria-hidden="true"
+                >
+                  <path :d="item.icon" />
+                </svg>
+                <span class="flex-1">{{ item.label }}</span>
+                <span v-if="item.value === 'archive'" class="rounded bg-bg-subtle px-1.5 py-0.5 text-[11px] font-medium text-fg-subtle">soon</span>
+                <kbd
+                  v-else-if="item.shortcut"
+                  class="rounded border border-border bg-bg-subtle px-1.5 text-xs text-fg-muted group-data-[state=selected]:border-transparent group-data-[state=selected]:bg-transparent group-data-[state=selected]:text-accent-fg"
+                >⌘{{ item.shortcut }}</kbd>
+              </CommandItem>
+            </template>
+          </CommandGroup>
+        </CommandList>
+      </template>
+    </CommandRoot>
+
+    <p class="text-sm text-fg-muted">
+      <template v-if="lastRun">
+        Ran: <code class="rounded bg-bg-subtle px-1.5 py-0.5 font-medium text-fg">{{ lastRun }}</code>
+      </template>
+      <template v-else>
+        Use ↑ ↓ to navigate, Enter to run.
+      </template>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/command/index.ts b/vue/primitives/src/menus/command/index.ts
similarity index 79%
rename from vue/primitives/src/command/index.ts
rename to vue/primitives/src/menus/command/index.ts
index 9da1105..e50630c 100644
--- a/vue/primitives/src/command/index.ts
+++ b/vue/primitives/src/menus/command/index.ts
@@ -1,7 +1,9 @@
+export { default as CommandCancel } from './CommandCancel.vue';
 export { default as CommandEmpty } from './CommandEmpty.vue';
 export { default as CommandGroup } from './CommandGroup.vue';
 export { default as CommandInput } from './CommandInput.vue';
 export { default as CommandItem } from './CommandItem.vue';
+export { default as CommandItemIndicator } from './CommandItemIndicator.vue';
 export { default as CommandList } from './CommandList.vue';
 export { default as CommandLoading } from './CommandLoading.vue';
 export { default as CommandRoot } from './CommandRoot.vue';
@@ -10,20 +12,24 @@ export { default as CommandSeparator } from './CommandSeparator.vue';
 export {
   useCommandContext,
   useCommandGroupContext,
+  useCommandItemContext,
 } from './context';
 
 export type {
   CommandContext,
   CommandGroupContext,
+  CommandItemContext,
   CommandItemInfo,
 } from './context';
 
 export type { CommandFilterFunction } from './utils';
 
+export type { CommandCancelProps } from './CommandCancel.vue';
 export type { CommandEmptyProps } from './CommandEmpty.vue';
 export type { CommandGroupProps } from './CommandGroup.vue';
 export type { CommandInputEmits, CommandInputProps } from './CommandInput.vue';
 export type { CommandItemEmits, CommandItemProps } from './CommandItem.vue';
+export type { CommandItemIndicatorProps } from './CommandItemIndicator.vue';
 export type { CommandListProps } from './CommandList.vue';
 export type { CommandLoadingProps } from './CommandLoading.vue';
 export type { CommandRootEmits, CommandRootProps } from './CommandRoot.vue';
diff --git a/vue/primitives/src/command/utils.ts b/vue/primitives/src/menus/command/utils.ts
similarity index 100%
rename from vue/primitives/src/command/utils.ts
rename to vue/primitives/src/menus/command/utils.ts
diff --git a/vue/primitives/src/context-menu/ContextMenuArrow.vue b/vue/primitives/src/menus/context-menu/ContextMenuArrow.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuArrow.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuArrow.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuCheckboxItem.vue b/vue/primitives/src/menus/context-menu/ContextMenuCheckboxItem.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuCheckboxItem.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuCheckboxItem.vue
diff --git a/vue/primitives/src/menus/context-menu/ContextMenuContent.vue b/vue/primitives/src/menus/context-menu/ContextMenuContent.vue
new file mode 100644
index 0000000..f434954
--- /dev/null
+++ b/vue/primitives/src/menus/context-menu/ContextMenuContent.vue
@@ -0,0 +1,94 @@
+<script lang="ts">
+import type { MenuContentEmits, MenuContentProps } from '../menu';
+
+/**
+ * The floating surface that holds the menu items, positioned at the pointer
+ * where the menu was invoked. Handles focus management, typeahead, and
+ * dismissal on outside click or Escape; render it inside a portal.
+ *
+ * Cursor-anchored positioning (`side`/`align`) is fixed by this part; pass
+ * collision/sizing props as needed.
+ */
+export interface ContextMenuContentProps extends MenuContentProps {}
+export type ContextMenuContentEmits = MenuContentEmits;
+</script>
+
+<script setup lang="ts">
+import { shallowRef } from 'vue';
+
+import { MenuContent } from '../menu';
+import { useContextMenuRootContext } from './context';
+
+const {
+  sideOffset = 2,
+  alignOffset = 0,
+  avoidCollisions = true,
+  collisionPadding = 0,
+  sticky = 'partial',
+  hideWhenDetached = false,
+  ...rest
+} = defineProps<ContextMenuContentProps>();
+const emit = defineEmits<ContextMenuContentEmits>();
+
+const rootCtx = useContextMenuRootContext();
+// In non-modal mode, an outside interaction should dismiss the menu but must
+// not yank focus back to the trigger afterwards.
+const hasInteractedOutside = shallowRef(false);
+
+function handleInteractOutside(event: PointerEvent | MouseEvent | FocusEvent) {
+  // Right-clicking the trigger while the menu is open would otherwise dismiss
+  // (via pointerdown-outside) and immediately reopen (via contextmenu), causing
+  // a flicker and lost focus. Suppress the dismiss in that case.
+  const trigger = rootCtx.triggerElement.value;
+  const target = event.target as Node | null;
+  if (
+    'button' in event
+    && event.button === 2
+    && trigger !== undefined
+    && target !== null
+    && (trigger === target || trigger.contains(target))
+  ) {
+    event.preventDefault();
+    return;
+  }
+  if (!event.defaultPrevented && !rootCtx.modal.value) hasInteractedOutside.value = true;
+}
+
+function handleCloseAutoFocus(event: Event) {
+  if (!event.defaultPrevented && hasInteractedOutside.value) event.preventDefault();
+  hasInteractedOutside.value = false;
+  emit('closeAutoFocus', event);
+}
+</script>
+
+<template>
+  <MenuContent
+    v-bind="rest"
+    side="right"
+    :side-offset="sideOffset"
+    align="start"
+    :align-offset="alignOffset"
+    :avoid-collisions="avoidCollisions"
+    :collision-padding="collisionPadding"
+    :sticky="sticky"
+    :hide-when-detached="hideWhenDetached"
+    update-position-strategy="optimized"
+    :style="{
+      '--primitives-context-menu-content-transform-origin': 'var(--popper-transform-origin)',
+      '--primitives-context-menu-content-available-width': 'var(--popper-available-width)',
+      '--primitives-context-menu-content-available-height': 'var(--popper-available-height)',
+      '--primitives-context-menu-trigger-width': 'var(--popper-anchor-width)',
+      '--primitives-context-menu-trigger-height': 'var(--popper-anchor-height)',
+    }"
+    @close-auto-focus="handleCloseAutoFocus"
+    @escape-key-down="emit('escapeKeyDown', $event)"
+    @pointer-down-outside="emit('pointerDownOutside', $event)"
+    @focus-outside="emit('focusOutside', $event)"
+    @interact-outside="(event) => { handleInteractOutside(event); emit('interactOutside', event); }"
+    @dismiss="emit('dismiss')"
+    @entry-focus="emit('entryFocus', $event)"
+    @open-auto-focus="emit('openAutoFocus', $event)"
+  >
+    <slot />
+  </MenuContent>
+</template>
diff --git a/vue/primitives/src/context-menu/ContextMenuGroup.vue b/vue/primitives/src/menus/context-menu/ContextMenuGroup.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuGroup.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuGroup.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuItem.vue b/vue/primitives/src/menus/context-menu/ContextMenuItem.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuItem.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuItem.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuItemIndicator.vue b/vue/primitives/src/menus/context-menu/ContextMenuItemIndicator.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuItemIndicator.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuItemIndicator.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuLabel.vue b/vue/primitives/src/menus/context-menu/ContextMenuLabel.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuLabel.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuLabel.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuPortal.vue b/vue/primitives/src/menus/context-menu/ContextMenuPortal.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuPortal.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuPortal.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuRadioGroup.vue b/vue/primitives/src/menus/context-menu/ContextMenuRadioGroup.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuRadioGroup.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuRadioGroup.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuRadioItem.vue b/vue/primitives/src/menus/context-menu/ContextMenuRadioItem.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuRadioItem.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuRadioItem.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuRoot.vue b/vue/primitives/src/menus/context-menu/ContextMenuRoot.vue
similarity index 64%
rename from vue/primitives/src/context-menu/ContextMenuRoot.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuRoot.vue
index fe23009..fd135a7 100644
--- a/vue/primitives/src/context-menu/ContextMenuRoot.vue
+++ b/vue/primitives/src/menus/context-menu/ContextMenuRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { Direction } from '../config-provider';
+import type { Direction } from '../../utilities/config-provider';
 
 /**
  * A menu that opens at the pointer on right-click (or a long-press on touch),
@@ -15,24 +15,38 @@ import type { Direction } from '../config-provider';
 export interface ContextMenuRootProps {
   dir?: Direction;
   modal?: boolean;
+  /**
+   * The duration in milliseconds from when a touch/pen press starts until the
+   * menu opens (long-press). Right-click opens immediately regardless.
+   * @default 700
+   */
+  pressOpenDelay?: number;
 }
 </script>
 
 <script setup lang="ts">
-import { toRef } from 'vue';
+import { shallowRef, toRef } from 'vue';
 
+import { useConfig } from '../../utilities/config-provider';
 import { MenuRoot } from '../menu';
 import { provideContextMenuRootContext } from './context';
 
-const { dir, modal = true } = defineProps<ContextMenuRootProps>();
+const { dir: dirProp, modal = true, pressOpenDelay = 700 } = defineProps<ContextMenuRootProps>();
 defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
 
 const open = defineModel<boolean>('open', { default: false });
 
+const config = useConfig();
+const triggerElement = shallowRef<HTMLElement>();
+const dir = toRef(() => dirProp ?? config.dir.value);
+
 provideContextMenuRootContext({
   open,
   onOpenChange: (v) => { open.value = v; },
   modal: toRef(() => modal),
+  dir,
+  triggerElement,
+  pressOpenDelay: toRef(() => pressOpenDelay),
 });
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuSeparator.vue b/vue/primitives/src/menus/context-menu/ContextMenuSeparator.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuSeparator.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuSeparator.vue
diff --git a/vue/primitives/src/menus/context-menu/ContextMenuSub.vue b/vue/primitives/src/menus/context-menu/ContextMenuSub.vue
new file mode 100644
index 0000000..27d70fd
--- /dev/null
+++ b/vue/primitives/src/menus/context-menu/ContextMenuSub.vue
@@ -0,0 +1,58 @@
+<script lang="ts">
+import type { MenuSubEmits, MenuSubProps } from '../menu';
+
+/**
+ * Wraps a nested submenu, pairing a `ContextMenuSubTrigger` with its
+ * `ContextMenuSubContent` and owning that submenu's open state. Bind
+ * `v-model:open` to control it, or leave it unbound and pass `defaultOpen` to
+ * use it uncontrolled. Listen to `update:open` to track expansion; the default
+ * slot also exposes the current `open` value.
+ */
+export interface ContextMenuSubProps extends MenuSubProps {
+  /** The open state of the submenu when initially rendered. Use when you do not need to control its open state. */
+  defaultOpen?: boolean;
+}
+export type ContextMenuSubEmits = MenuSubEmits;
+</script>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+
+import { MenuSub } from '../menu';
+
+// `open: undefined` opts out of Vue's boolean-prop coercion (an absent boolean
+// prop would otherwise become `false`), so we can tell "uncontrolled" (use
+// `defaultOpen`) apart from an explicit `:open="false"` (controlled).
+// `open: undefined` is load-bearing: it keeps an absent boolean prop `undefined`
+// instead of letting Vue coerce it to `false`, so the `open ?? defaultOpen`
+// uncontrolled seed works. Reactive props destructure can't preserve this, so
+// this stays as `withDefaults` + `props`.
+const props = withDefaults(defineProps<ContextMenuSubProps>(), {
+  open: undefined,
+  defaultOpen: false,
+});
+const emit = defineEmits<ContextMenuSubEmits>();
+defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
+
+// Controlled when the `open` prop is supplied; otherwise the local ref (seeded
+// by `defaultOpen`) drives it.
+const local = ref(props.open ?? props.defaultOpen);
+
+watch(() => props.open, (value) => {
+  if (value !== undefined) local.value = value;
+});
+
+function setOpen(value: boolean) {
+  local.value = value;
+  emit('update:open', value);
+}
+</script>
+
+<template>
+  <MenuSub
+    :open="local"
+    @update:open="setOpen"
+  >
+    <slot :open="local" />
+  </MenuSub>
+</template>
diff --git a/vue/primitives/src/context-menu/ContextMenuSubContent.vue b/vue/primitives/src/menus/context-menu/ContextMenuSubContent.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuSubContent.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuSubContent.vue
diff --git a/vue/primitives/src/context-menu/ContextMenuSubTrigger.vue b/vue/primitives/src/menus/context-menu/ContextMenuSubTrigger.vue
similarity index 100%
rename from vue/primitives/src/context-menu/ContextMenuSubTrigger.vue
rename to vue/primitives/src/menus/context-menu/ContextMenuSubTrigger.vue
diff --git a/vue/primitives/src/menus/context-menu/ContextMenuTrigger.vue b/vue/primitives/src/menus/context-menu/ContextMenuTrigger.vue
new file mode 100644
index 0000000..e277c23
--- /dev/null
+++ b/vue/primitives/src/menus/context-menu/ContextMenuTrigger.vue
@@ -0,0 +1,127 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The region that captures right-click (and touch/pen long-press), preventing the
+ * native context menu and opening the menu anchored at the pointer position.
+ * Wrap whatever area should respond to a secondary click.
+ */
+export interface ContextMenuTriggerProps extends PrimitiveProps {
+  disabled?: boolean;
+}
+
+// Fully static; hoisted so the trigger does not reallocate it on every render.
+const TRIGGER_STYLE = {
+  WebkitTouchCallout: 'none',
+  pointerEvents: 'auto',
+} as const;
+</script>
+
+<script setup lang="ts">
+import { nextTick, onMounted, onScopeDispose, shallowRef } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
+import { MenuAnchor, useMenuContext } from '../menu';
+import { Primitive } from '../../internal/primitive';
+import { useContextMenuRootContext } from './context';
+
+const { disabled = false, as = 'span' } = defineProps<ContextMenuTriggerProps>();
+
+const menuCtx = useMenuContext();
+const ctxMenuCtx = useContextMenuRootContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const point = shallowRef({ x: 0, y: 0 });
+// Reused scratch rect: getBoundingClientRect is polled by floating-ui on
+// scroll/resize, so we mutate a single object in place (stable hidden class,
+// zero per-call allocation) instead of returning a fresh literal each time.
+const scratchRect = {
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+  toJSON: () => {},
+};
+const virtualEl = {
+  getBoundingClientRect: () => {
+    const { x, y } = point.value;
+    scratchRect.x = x;
+    scratchRect.y = y;
+    scratchRect.top = y;
+    scratchRect.right = x;
+    scratchRect.bottom = y;
+    scratchRect.left = x;
+    return scratchRect;
+  },
+};
+
+let longPressTimer: ReturnType<typeof setTimeout> | undefined;
+
+function clearLongPress() {
+  clearTimeout(longPressTimer);
+}
+
+onScopeDispose(clearLongPress);
+
+// Long-press applies to touch AND pen; mouse uses the native contextmenu event.
+function isTouchOrPen(event: PointerEvent): boolean {
+  return event.pointerType !== 'mouse';
+}
+
+function handleOpen(event: MouseEvent | PointerEvent) {
+  point.value = { x: event.clientX, y: event.clientY };
+  ctxMenuCtx.onOpenChange(true);
+}
+
+async function handleContextMenu(event: MouseEvent) {
+  if (disabled) return;
+  // Wait a microtask so a nested ContextMenuTrigger (whose own handler runs
+  // first as the event bubbles inward-out) can call `preventDefault()` and
+  // suppress this outer one. Also lets a consumer cancel the open by calling
+  // `preventDefault()` on the contextmenu event.
+  await nextTick();
+  if (event.defaultPrevented) return;
+  clearLongPress();
+  handleOpen(event);
+  event.preventDefault();
+}
+
+function handlePointerDown(event: PointerEvent) {
+  if (disabled || event.button !== 0 || !isTouchOrPen(event)) return;
+  // Clear here in case there are multiple touch points.
+  clearLongPress();
+  longPressTimer = setTimeout(handleOpen, ctxMenuCtx.pressOpenDelay.value, event);
+}
+
+function handlePointerEvent(event: PointerEvent) {
+  // A drag/scroll/lift gesture must cancel the pending long-press open.
+  if (isTouchOrPen(event)) clearLongPress();
+}
+
+onMounted(() => {
+  if (currentElement.value) ctxMenuCtx.triggerElement.value = currentElement.value;
+});
+</script>
+
+<template>
+  <MenuAnchor as="template" :reference="virtualEl">
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :data-state="menuCtx.open.value ? 'open' : 'closed'"
+      :data-disabled="disabled ? '' : undefined"
+      :style="TRIGGER_STYLE"
+      @contextmenu="handleContextMenu"
+      @pointerdown="handlePointerDown"
+      @pointermove="handlePointerEvent"
+      @pointercancel="handlePointerEvent"
+      @pointerup="handlePointerEvent"
+    >
+      <slot />
+    </Primitive>
+  </MenuAnchor>
+</template>
diff --git a/vue/primitives/src/menus/context-menu/__test__/ContextMenu.test.ts b/vue/primitives/src/menus/context-menu/__test__/ContextMenu.test.ts
new file mode 100644
index 0000000..8ee0f3c
--- /dev/null
+++ b/vue/primitives/src/menus/context-menu/__test__/ContextMenu.test.ts
@@ -0,0 +1,335 @@
+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 } from 'vue';
+
+import {
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuPortal,
+  ContextMenuRoot,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuTrigger,
+} from '../../../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  document.body.removeAttribute('style');
+  vi.useRealTimers();
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function mountContextMenu(options: {
+  triggerAttrs?: Record<string, unknown>;
+  rootProps?: Record<string, unknown>;
+  onUpdateOpen?: (v: boolean) => void;
+} = {}) {
+  const Harness = defineComponent({
+    setup() {
+      return () =>
+        h(
+          ContextMenuRoot,
+          { ...options.rootProps, 'onUpdate:open': options.onUpdateOpen },
+          {
+            default: () => [
+              h(
+                ContextMenuTrigger,
+                { 'data-testid': 'trigger', ...options.triggerAttrs },
+                { default: () => 'Right-click me' },
+              ),
+              h(ContextMenuPortal, null, {
+                default: () =>
+                  h(ContextMenuContent, null, {
+                    default: () => h(ContextMenuItem, null, { default: () => 'Item' }),
+                  }),
+              }),
+            ],
+          },
+        );
+    },
+  });
+  return track(mount(Harness, { attachTo: document.body }));
+}
+
+function getTrigger(): HTMLElement {
+  return document.querySelector('[data-testid="trigger"]') as HTMLElement;
+}
+
+function dispatchContextMenu(el: HTMLElement, x = 100, y = 80) {
+  el.dispatchEvent(new MouseEvent('contextmenu', {
+    bubbles: true,
+    cancelable: true,
+    clientX: x,
+    clientY: y,
+  }));
+}
+
+describe('context-menu — trigger element', () => {
+  it('merges fallthrough attrs onto the element carrying data-state (no anchor wrapper div)', () => {
+    mountContextMenu({ triggerAttrs: { id: 'trigger-el', class: 'canvas-area' } });
+    const trigger = getTrigger();
+    expect(trigger).toBeTruthy();
+    expect(trigger.id).toBe('trigger-el');
+    expect(trigger.classList.contains('canvas-area')).toBe(true);
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+    // No intermediate anchor element between the harness root and the trigger.
+    expect(trigger.parentElement).toBe(wrappers[0]!.element);
+  });
+
+  it('opens the menu when contextmenu is dispatched on the attr-bearing element', async () => {
+    const onUpdateOpen = vi.fn();
+    mountContextMenu({ triggerAttrs: { class: 'canvas-area' }, onUpdateOpen });
+    const trigger = getTrigger();
+
+    dispatchContextMenu(trigger);
+    await nextTick();
+    await nextTick();
+
+    expect(onUpdateOpen).toHaveBeenCalledWith(true);
+    expect(trigger.getAttribute('data-state')).toBe('open');
+    expect(document.querySelector('[role="menu"]')).toBeTruthy();
+  });
+});
+
+describe('context-menu — long-press', () => {
+  function pointerDown(el: HTMLElement, pointerType: string, x = 50, y = 60) {
+    el.dispatchEvent(new PointerEvent('pointerdown', {
+      bubbles: true,
+      button: 0,
+      pointerType,
+      clientX: x,
+      clientY: y,
+    }));
+  }
+
+  it('opens after a 700ms touch long-press', async () => {
+    vi.useFakeTimers();
+    mountContextMenu();
+    const trigger = getTrigger();
+
+    pointerDown(trigger, 'touch');
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+
+    vi.advanceTimersByTime(700);
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('open');
+  });
+
+  it('opens after a pen long-press', async () => {
+    vi.useFakeTimers();
+    mountContextMenu();
+    const trigger = getTrigger();
+
+    pointerDown(trigger, 'pen');
+    vi.advanceTimersByTime(700);
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('open');
+  });
+
+  it('cancels the long-press when the pointer moves (drag/scroll gesture)', async () => {
+    vi.useFakeTimers();
+    mountContextMenu();
+    const trigger = getTrigger();
+
+    pointerDown(trigger, 'touch');
+    vi.advanceTimersByTime(300);
+    trigger.dispatchEvent(new PointerEvent('pointermove', {
+      bubbles: true,
+      pointerType: 'touch',
+      clientX: 50,
+      clientY: 120,
+    }));
+    vi.advanceTimersByTime(700);
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+  });
+
+  it('cancels the long-press on pointerup', async () => {
+    vi.useFakeTimers();
+    mountContextMenu();
+    const trigger = getTrigger();
+
+    pointerDown(trigger, 'touch');
+    vi.advanceTimersByTime(300);
+    trigger.dispatchEvent(new PointerEvent('pointerup', { bubbles: true, pointerType: 'touch' }));
+    vi.advanceTimersByTime(700);
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+  });
+
+  it('does not start a long-press for mouse pointers', async () => {
+    vi.useFakeTimers();
+    mountContextMenu();
+    const trigger = getTrigger();
+
+    pointerDown(trigger, 'mouse');
+    vi.advanceTimersByTime(700);
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+  });
+
+  it('honours a custom pressOpenDelay on the root', async () => {
+    vi.useFakeTimers();
+    mountContextMenu({ rootProps: { pressOpenDelay: 300 } });
+    const trigger = getTrigger();
+
+    pointerDown(trigger, 'touch');
+    vi.advanceTimersByTime(299);
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+
+    vi.advanceTimersByTime(1);
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('open');
+  });
+});
+
+describe('context-menu — contextmenu open semantics', () => {
+  it('does not open when the contextmenu event was already defaultPrevented (nested / consumer suppression)', async () => {
+    const onUpdateOpen = vi.fn();
+    mountContextMenu({ onUpdateOpen });
+    const trigger = getTrigger();
+
+    const event = new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: 10, clientY: 10 });
+    event.preventDefault();
+    trigger.dispatchEvent(event);
+    await nextTick();
+    await nextTick();
+
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+  });
+
+  it('does not open when the trigger is disabled', async () => {
+    const onUpdateOpen = vi.fn();
+    mountContextMenu({ triggerAttrs: { disabled: true }, onUpdateOpen });
+    const trigger = getTrigger();
+
+    dispatchContextMenu(trigger);
+    await nextTick();
+    await nextTick();
+
+    expect(onUpdateOpen).not.toHaveBeenCalled();
+    expect(trigger.getAttribute('data-state')).toBe('closed');
+    expect(trigger.getAttribute('data-disabled')).toBe('');
+  });
+});
+
+describe('context-menu — trigger defensive styles', () => {
+  it('applies pointerEvents:auto so the trigger always receives the secondary click', () => {
+    mountContextMenu();
+    const trigger = getTrigger();
+    expect(trigger.style.pointerEvents).toBe('auto');
+  });
+});
+
+describe('context-menu — right-click-on-trigger guard', () => {
+  it('does not dismiss the open menu when the trigger is right-clicked again', async () => {
+    const onUpdateOpen = vi.fn();
+    mountContextMenu({ onUpdateOpen });
+    const trigger = getTrigger();
+
+    dispatchContextMenu(trigger);
+    await nextTick();
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('open');
+
+    onUpdateOpen.mockClear();
+    // A right-click (button=2) pointerdown lands "outside" the content but on
+    // the trigger; the guard must preventDefault so the layer does not dismiss.
+    trigger.dispatchEvent(new PointerEvent('pointerdown', {
+      bubbles: true,
+      cancelable: true,
+      button: 2,
+      clientX: 100,
+      clientY: 80,
+    }));
+    await nextTick();
+    await nextTick();
+
+    expect(onUpdateOpen).not.toHaveBeenCalledWith(false);
+    expect(trigger.getAttribute('data-state')).toBe('open');
+  });
+});
+
+describe('context-menu — content positioning', () => {
+  it('anchors the content to the cursor side/align and exposes trigger-size CSS vars', async () => {
+    mountContextMenu();
+    const trigger = getTrigger();
+
+    dispatchContextMenu(trigger);
+    await nextTick();
+    await nextTick();
+
+    const content = document.querySelector('[role="menu"]') as HTMLElement;
+    expect(content).toBeTruthy();
+    expect(content.getAttribute('data-side')).toBe('right');
+    expect(content.getAttribute('data-align')).toBe('start');
+    expect(content.style.getPropertyValue('--primitives-context-menu-trigger-width')).toBe('var(--popper-anchor-width)');
+    expect(content.style.getPropertyValue('--primitives-context-menu-trigger-height')).toBe('var(--popper-anchor-height)');
+  });
+});
+
+describe('context-menu — submenu uncontrolled', () => {
+  function mountWithSub(subProps: Record<string, unknown> = {}) {
+    const Harness = defineComponent({
+      setup() {
+        return () =>
+          h(ContextMenuRoot, { open: true }, {
+            default: () => [
+              h(ContextMenuTrigger, { 'data-testid': 'trigger' }, { default: () => 'Right-click me' }),
+              h(ContextMenuPortal, null, {
+                default: () =>
+                  h(ContextMenuContent, null, {
+                    default: () =>
+                      h(ContextMenuSub, subProps, {
+                        default: () => [
+                          h(ContextMenuSubTrigger, { 'data-testid': 'sub-trigger' }, { default: () => 'More' }),
+                          h(ContextMenuPortal, null, {
+                            default: () =>
+                              h(ContextMenuSubContent, null, {
+                                default: () => h(ContextMenuItem, { 'data-testid': 'sub-item' }, { default: () => 'Sub item' }),
+                              }),
+                          }),
+                        ],
+                      }),
+                  }),
+              }),
+            ],
+          });
+      },
+    });
+    return track(mount(Harness, { attachTo: document.body }));
+  }
+
+  it('renders the submenu open from the start when defaultOpen is set (uncontrolled)', async () => {
+    mountWithSub({ defaultOpen: true });
+    await nextTick();
+    await nextTick();
+
+    const subTrigger = document.querySelector('[data-testid="sub-trigger"]') as HTMLElement;
+    expect(subTrigger).toBeTruthy();
+    expect(subTrigger.getAttribute('data-state')).toBe('open');
+    expect(document.querySelector('[data-testid="sub-item"]')).toBeTruthy();
+  });
+
+  it('keeps the submenu closed by default when defaultOpen is omitted', async () => {
+    mountWithSub();
+    await nextTick();
+    await nextTick();
+
+    const subTrigger = document.querySelector('[data-testid="sub-trigger"]') as HTMLElement;
+    expect(subTrigger).toBeTruthy();
+    expect(subTrigger.getAttribute('data-state')).toBe('closed');
+    expect(document.querySelector('[data-testid="sub-item"]')).toBeFalsy();
+  });
+});
diff --git a/vue/primitives/src/menus/context-menu/context.ts b/vue/primitives/src/menus/context-menu/context.ts
new file mode 100644
index 0000000..5a55768
--- /dev/null
+++ b/vue/primitives/src/menus/context-menu/context.ts
@@ -0,0 +1,25 @@
+import type { Ref } from 'vue';
+import type { Direction } from '../../utilities/config-provider';
+
+import { useContextFactory } from '@robonen/vue';
+
+export interface ContextMenuRootContext {
+  open: Ref<boolean>;
+  onOpenChange: (open: boolean) => void;
+  modal: Ref<boolean>;
+  /** Resolved reading direction (prop on root falls back to the global ConfigProvider dir). */
+  dir: Ref<Direction>;
+  /**
+   * The trigger element captured once mounted. Used by the content's
+   * interact-outside guard so a right-click on the trigger while the menu is
+   * open does not dismiss-then-reopen (flicker / lost focus).
+   */
+  triggerElement: Ref<HTMLElement | undefined>;
+  /** Delay in ms from a touch/pen press until the menu opens (long-press). */
+  pressOpenDelay: Ref<number>;
+}
+
+export const {
+  inject: useContextMenuRootContext,
+  provide: provideContextMenuRootContext,
+} = useContextFactory<ContextMenuRootContext>('ContextMenuRootContext');
diff --git a/vue/primitives/src/context-menu/demo.vue b/vue/primitives/src/menus/context-menu/demo.vue
similarity index 86%
rename from vue/primitives/src/context-menu/demo.vue
rename to vue/primitives/src/menus/context-menu/demo.vue
index 0bd4eee..ae16884 100644
--- a/vue/primitives/src/context-menu/demo.vue
+++ b/vue/primitives/src/menus/context-menu/demo.vue
@@ -26,8 +26,8 @@ function run(action: string) {
   lastAction.value = action;
 }
 
-const itemClass = 'flex items-center justify-between gap-6 rounded px-2 py-1.5 text-sm outline-none cursor-default select-none data-[highlighted]:bg-(--accent) data-[highlighted]:text-(--accent-fg) data-[disabled]:opacity-40 data-[disabled]:pointer-events-none';
-const contentClass = 'min-w-52 rounded-lg border border-(--border) bg-(--bg-elevated) p-1 text-(--fg) shadow-lg shadow-black/10';
+const itemClass = 'flex items-center justify-between gap-6 rounded px-2 py-1.5 text-sm outline-none cursor-default select-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-fg data-[disabled]:opacity-40 data-[disabled]:pointer-events-none';
+const contentClass = 'min-w-52 rounded-lg border border-border bg-bg-elevated p-1 text-fg shadow-lg shadow-black/10';
 </script>
 
 <template>
@@ -35,7 +35,7 @@ const contentClass = 'min-w-52 rounded-lg border border-(--border) bg-(--bg-elev
     <ContextMenuRoot>
       <ContextMenuTrigger
         as="div"
-        class="flex h-44 w-80 items-center justify-center rounded-xl border border-dashed border-(--border) bg-(--bg-subtle) text-sm text-(--fg-muted) select-none"
+        class="flex h-44 w-80 items-center justify-center rounded-xl border border-dashed border-border bg-bg-subtle text-sm text-fg-muted select-none"
       >
         Right-click anywhere in this area
       </ContextMenuTrigger>
@@ -47,26 +47,26 @@ const contentClass = 'min-w-52 rounded-lg border border-(--border) bg-(--bg-elev
             @select="run('Cut')"
           >
             Cut
-            <span class="text-xs text-(--fg-subtle)">⌘X</span>
+            <span class="text-xs text-fg-subtle">⌘X</span>
           </ContextMenuItem>
           <ContextMenuItem
             :class="itemClass"
             @select="run('Copy')"
           >
             Copy
-            <span class="text-xs text-(--fg-subtle)">⌘C</span>
+            <span class="text-xs text-fg-subtle">⌘C</span>
           </ContextMenuItem>
           <ContextMenuItem
             :class="itemClass"
             disabled
           >
             Paste
-            <span class="text-xs text-(--fg-subtle)">⌘V</span>
+            <span class="text-xs text-fg-subtle">⌘V</span>
           </ContextMenuItem>
 
-          <ContextMenuSeparator class="my-1 h-px bg-(--border)" />
+          <ContextMenuSeparator class="my-1 h-px bg-border" />
 
-          <ContextMenuLabel class="px-2 py-1 text-xs font-medium text-(--fg-subtle)">
+          <ContextMenuLabel class="px-2 py-1 text-xs font-medium text-fg-subtle">
             View
           </ContextMenuLabel>
 
@@ -121,11 +121,11 @@ const contentClass = 'min-w-52 rounded-lg border border-(--border) bg-(--bg-elev
           <ContextMenuSub>
             <ContextMenuSubTrigger
               :class="itemClass"
-              class="data-[state=open]:bg-(--bg-subtle)"
+              class="data-[state=open]:bg-bg-subtle"
             >
               Zoom
               <svg
-                class="size-4 text-(--fg-subtle)"
+                class="size-4 text-fg-subtle"
                 viewBox="0 0 24 24"
                 fill="none"
                 stroke="currentColor"
@@ -162,7 +162,7 @@ const contentClass = 'min-w-52 rounded-lg border border-(--border) bg-(--bg-elev
             </ContextMenuPortal>
           </ContextMenuSub>
 
-          <ContextMenuSeparator class="my-1 h-px bg-(--border)" />
+          <ContextMenuSeparator class="my-1 h-px bg-border" />
 
           <ContextMenuItem
             :class="itemClass"
@@ -176,7 +176,7 @@ const contentClass = 'min-w-52 rounded-lg border border-(--border) bg-(--bg-elev
       </ContextMenuPortal>
     </ContextMenuRoot>
 
-    <p class="text-xs text-(--fg-muted)">
+    <p class="text-xs text-fg-muted">
       {{ lastAction }} · grid {{ showGrid ? 'on' : 'off' }} · zoom {{ zoom }}%
     </p>
   </div>
diff --git a/vue/primitives/src/context-menu/index.ts b/vue/primitives/src/menus/context-menu/index.ts
similarity index 100%
rename from vue/primitives/src/context-menu/index.ts
rename to vue/primitives/src/menus/context-menu/index.ts
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuArrow.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuArrow.vue
similarity index 88%
rename from vue/primitives/src/dropdown-menu/DropdownMenuArrow.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuArrow.vue
index 0c2d8fd..14289f7 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuArrow.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuArrow.vue
@@ -9,9 +9,11 @@ export interface DropdownMenuArrowProps extends MenuArrowProps {}
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuArrow } from '../menu';
 
 const props = defineProps<DropdownMenuArrowProps>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuCheckboxItem.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuCheckboxItem.vue
similarity index 92%
rename from vue/primitives/src/dropdown-menu/DropdownMenuCheckboxItem.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuCheckboxItem.vue
index 563ff26..50077eb 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuCheckboxItem.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuCheckboxItem.vue
@@ -11,10 +11,12 @@ export type DropdownMenuCheckboxItemEmits = MenuCheckboxItemEmits;
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuCheckboxItem } from '../menu';
 
 const props = defineProps<DropdownMenuCheckboxItemProps>();
 const emit = defineEmits<DropdownMenuCheckboxItemEmits>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/menus/dropdown-menu/DropdownMenuContent.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuContent.vue
new file mode 100644
index 0000000..9490c83
--- /dev/null
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuContent.vue
@@ -0,0 +1,89 @@
+<script lang="ts">
+import type { MenuContentEmits, MenuContentProps } from '../menu';
+
+/**
+ * The floating surface that holds the menu items, positioned relative to the
+ * trigger. Handles focus management, typeahead, and dismissal on outside click
+ * or Escape; render it inside a portal so it escapes overflow clipping.
+ */
+export interface DropdownMenuContentProps extends MenuContentProps {}
+export type DropdownMenuContentEmits = MenuContentEmits;
+</script>
+
+<script setup lang="ts">
+import type { CSSProperties } from 'vue';
+
+import { ref } from 'vue';
+
+import { MenuContent } from '../menu';
+import { useDropdownMenuRootContext } from './context';
+
+const props = defineProps<DropdownMenuContentProps>();
+const emit = defineEmits<DropdownMenuContentEmits>();
+const ddCtx = useDropdownMenuRootContext();
+
+// Tracks whether the menu closed because of an outside / right-click / non-modal
+// interaction. When it did, focus must stay where the user pointed instead of
+// snapping back to the trigger (which would be jarring and steal the caret).
+const hasInteractedOutside = ref(false);
+
+// Map the Popper-computed measurements onto dropdown-scoped CSS custom
+// properties so consumers can size/animate the menu relative to its trigger.
+const contentStyle: CSSProperties = {
+  '--primitives-dropdown-menu-content-transform-origin': 'var(--popper-transform-origin)',
+  '--primitives-dropdown-menu-content-available-width': 'var(--popper-available-width)',
+  '--primitives-dropdown-menu-content-available-height': 'var(--popper-available-height)',
+  '--primitives-dropdown-menu-trigger-width': 'var(--popper-anchor-width)',
+  '--primitives-dropdown-menu-trigger-height': 'var(--popper-anchor-height)',
+} as CSSProperties;
+
+function handleCloseAutoFocus(event: Event) {
+  // Let the consumer opt out of the managed focus return entirely.
+  emit('closeAutoFocus', event);
+  if (event.defaultPrevented) return;
+  if (!hasInteractedOutside.value) {
+    ddCtx.triggerRef.value?.focus({ preventScroll: true });
+  }
+  hasInteractedOutside.value = false;
+  // Either we refocused the trigger ourselves or the user is interacting
+  // elsewhere — in both cases the underlying scope's default restore must not run.
+  event.preventDefault();
+}
+
+function handleInteractOutside(event: PointerEvent | MouseEvent | FocusEvent) {
+  if (!event.defaultPrevented) {
+    const originalEvent = event as Partial<MouseEvent>;
+    const ctrlLeftClick = originalEvent.button === 0 && originalEvent.ctrlKey === true;
+    const isRightClick = originalEvent.button === 2 || ctrlLeftClick;
+    if (!ddCtx.modal.value || isRightClick) hasInteractedOutside.value = true;
+  }
+  emit('interactOutside', event);
+}
+</script>
+
+<template>
+  <MenuContent
+    v-bind="props"
+    :id="ddCtx.contentId.value"
+    :aria-labelledby="ddCtx.triggerId.value"
+    :style="contentStyle"
+    @close-auto-focus="handleCloseAutoFocus"
+    @escape-key-down="emit('escapeKeyDown', $event)"
+    @pointer-down-outside="(event: PointerEvent | MouseEvent) => {
+      const target = event.target as Node
+      // The trigger owns pointerdown toggling — letting the layer also dismiss
+      // here would close the menu before the trigger handler runs and make its
+      // toggle reopen it.
+      const isTriggerPointerDown = ddCtx.triggerRef.value?.contains(target)
+      if (isTriggerPointerDown) event.preventDefault()
+      emit('pointerDownOutside', event)
+    }"
+    @focus-outside="emit('focusOutside', $event)"
+    @interact-outside="handleInteractOutside"
+    @dismiss="emit('dismiss')"
+    @entry-focus="emit('entryFocus', $event)"
+    @open-auto-focus="emit('openAutoFocus', $event)"
+  >
+    <slot />
+  </MenuContent>
+</template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuGroup.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuGroup.vue
similarity index 87%
rename from vue/primitives/src/dropdown-menu/DropdownMenuGroup.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuGroup.vue
index e011888..6f5b7b6 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuGroup.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuGroup.vue
@@ -9,9 +9,11 @@ export interface DropdownMenuGroupProps extends MenuGroupProps {}
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuGroup } from '../menu';
 
 const props = defineProps<DropdownMenuGroupProps>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuItem.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuItem.vue
similarity index 90%
rename from vue/primitives/src/dropdown-menu/DropdownMenuItem.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuItem.vue
index 91fa67a..e4571d9 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuItem.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuItem.vue
@@ -10,10 +10,12 @@ export type DropdownMenuItemEmits = MenuItemEmits;
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuItem } from '../menu';
 
 const props = defineProps<DropdownMenuItemProps>();
 const emit = defineEmits<DropdownMenuItemEmits>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuItemIndicator.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuItemIndicator.vue
similarity index 88%
rename from vue/primitives/src/dropdown-menu/DropdownMenuItemIndicator.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuItemIndicator.vue
index 74db411..7d0ccda 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuItemIndicator.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuItemIndicator.vue
@@ -9,9 +9,11 @@ export interface DropdownMenuItemIndicatorProps extends MenuItemIndicatorProps {
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuItemIndicator } from '../menu';
 
 const props = defineProps<DropdownMenuItemIndicatorProps>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuLabel.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuLabel.vue
similarity index 87%
rename from vue/primitives/src/dropdown-menu/DropdownMenuLabel.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuLabel.vue
index 98b27f1..0e6980d 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuLabel.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuLabel.vue
@@ -9,9 +9,11 @@ export interface DropdownMenuLabelProps extends MenuLabelProps {}
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuLabel } from '../menu';
 
 const props = defineProps<DropdownMenuLabelProps>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuPortal.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuPortal.vue
similarity index 100%
rename from vue/primitives/src/dropdown-menu/DropdownMenuPortal.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuPortal.vue
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuRadioGroup.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuRadioGroup.vue
similarity index 91%
rename from vue/primitives/src/dropdown-menu/DropdownMenuRadioGroup.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuRadioGroup.vue
index 639d777..74ef663 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuRadioGroup.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuRadioGroup.vue
@@ -10,10 +10,12 @@ export type DropdownMenuRadioGroupEmits = MenuRadioGroupEmits;
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuRadioGroup } from '../menu';
 
 const props = defineProps<DropdownMenuRadioGroupProps>();
 const emit = defineEmits<DropdownMenuRadioGroupEmits>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuRadioItem.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuRadioItem.vue
similarity index 91%
rename from vue/primitives/src/dropdown-menu/DropdownMenuRadioItem.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuRadioItem.vue
index 8682404..01583b4 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuRadioItem.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuRadioItem.vue
@@ -11,10 +11,12 @@ export type DropdownMenuRadioItemEmits = MenuRadioItemEmits;
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuRadioItem } from '../menu';
 
 const props = defineProps<DropdownMenuRadioItemProps>();
 const emit = defineEmits<DropdownMenuRadioItemEmits>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuRoot.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuRoot.vue
similarity index 81%
rename from vue/primitives/src/dropdown-menu/DropdownMenuRoot.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuRoot.vue
index 0a61f0c..8ae616f 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuRoot.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { Direction } from '../config-provider';
+import type { Direction } from '../../utilities/config-provider';
 
 /**
  * A button-triggered menu of actions, opened on click and built on top of Menu,
@@ -20,15 +20,15 @@ export interface DropdownMenuRootProps {
 </script>
 
 <script setup lang="ts">
-import { ref, shallowRef } from 'vue';
+import { ref, shallowRef, toRef } from 'vue';
 
-import { useId } from '../config-provider';
+import { useDirection, useId } from '../../utilities/config-provider';
 import { MenuRoot } from '../menu';
 import { provideDropdownMenuRootContext } from './context';
 
 const {
   defaultOpen = false,
-  dir,
+  dir: dirProp,
   modal = true,
 } = defineProps<DropdownMenuRootProps>();
 
@@ -44,6 +44,7 @@ const open = defineModel<boolean>('open', {
 });
 defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
 
+const dir = useDirection(() => dirProp);
 const triggerRef = shallowRef<HTMLElement | null>(null);
 const triggerId = useId(undefined, 'dropdown-trigger');
 const contentId = useId(undefined, 'dropdown-content');
@@ -55,6 +56,11 @@ provideDropdownMenuRootContext({
   onTriggerChange: (el) => {
     triggerRef.value = el;
   },
+  open,
+  onOpenChange: (v) => { open.value = v; },
+  onOpenToggle: () => { open.value = !open.value; },
+  modal: toRef(() => modal),
+  dir,
 });
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSeparator.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSeparator.vue
similarity index 87%
rename from vue/primitives/src/dropdown-menu/DropdownMenuSeparator.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuSeparator.vue
index 4d59044..7b0ca11 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSeparator.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSeparator.vue
@@ -9,9 +9,11 @@ export interface DropdownMenuSeparatorProps extends MenuSeparatorProps {}
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuSeparator } from '../menu';
 
 const props = defineProps<DropdownMenuSeparatorProps>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/menus/dropdown-menu/DropdownMenuSub.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSub.vue
new file mode 100644
index 0000000..6823eb9
--- /dev/null
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSub.vue
@@ -0,0 +1,41 @@
+<script lang="ts">
+import type { MenuSubEmits, MenuSubProps } from '../menu';
+
+/**
+ * Wraps a nested submenu, pairing a DropdownMenuSubTrigger with its
+ * DropdownMenuSubContent. Owns the submenu's open state; bind `v-model:open`
+ * to control or observe it, or leave it unbound and set `defaultOpen` to run
+ * uncontrolled. The default slot also exposes the current `open` value.
+ */
+export interface DropdownMenuSubProps extends MenuSubProps {
+  /** The submenu's open state when first rendered, for uncontrolled usage. */
+  defaultOpen?: boolean;
+}
+export type DropdownMenuSubEmits = MenuSubEmits;
+</script>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+
+import { MenuSub } from '../menu';
+
+const { defaultOpen = false } = defineProps<DropdownMenuSubProps>();
+defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
+
+const localOpen = ref<boolean>(defaultOpen);
+
+const open = defineModel<boolean>('open', {
+  default: undefined,
+  get: v => v ?? localOpen.value,
+  set: (v) => {
+    localOpen.value = v;
+    return v;
+  },
+});
+</script>
+
+<template>
+  <MenuSub v-model:open="open">
+    <slot :open="open" />
+  </MenuSub>
+</template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSubContent.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSubContent.vue
similarity index 63%
rename from vue/primitives/src/dropdown-menu/DropdownMenuSubContent.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuSubContent.vue
index 91d8486..1d5a4af 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSubContent.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSubContent.vue
@@ -10,15 +10,28 @@ export type DropdownMenuSubContentEmits = MenuSubContentEmits;
 </script>
 
 <script setup lang="ts">
+import type { CSSProperties } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
 import { MenuSubContent } from '../menu';
 
 const props = defineProps<DropdownMenuSubContentProps>();
 const emit = defineEmits<DropdownMenuSubContentEmits>();
+useForwardExpose();
+
+const contentStyle: CSSProperties = {
+  '--primitives-dropdown-menu-content-transform-origin': 'var(--popper-transform-origin)',
+  '--primitives-dropdown-menu-content-available-width': 'var(--popper-available-width)',
+  '--primitives-dropdown-menu-content-available-height': 'var(--popper-available-height)',
+  '--primitives-dropdown-menu-trigger-width': 'var(--popper-anchor-width)',
+  '--primitives-dropdown-menu-trigger-height': 'var(--popper-anchor-height)',
+} as CSSProperties;
 </script>
 
 <template>
   <MenuSubContent
     v-bind="props"
+    :style="contentStyle"
     @close-auto-focus="emit('closeAutoFocus', $event)"
     @escape-key-down="emit('escapeKeyDown', $event)"
     @pointer-down-outside="emit('pointerDownOutside', $event)"
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSubTrigger.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSubTrigger.vue
similarity index 89%
rename from vue/primitives/src/dropdown-menu/DropdownMenuSubTrigger.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuSubTrigger.vue
index dd2c2d0..a7fc821 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSubTrigger.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuSubTrigger.vue
@@ -10,9 +10,11 @@ export interface DropdownMenuSubTriggerProps extends MenuSubTriggerProps {}
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { MenuSubTrigger } from '../menu';
 
 const props = defineProps<DropdownMenuSubTriggerProps>();
+useForwardExpose();
 </script>
 
 <template>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuTrigger.vue b/vue/primitives/src/menus/dropdown-menu/DropdownMenuTrigger.vue
similarity index 90%
rename from vue/primitives/src/dropdown-menu/DropdownMenuTrigger.vue
rename to vue/primitives/src/menus/dropdown-menu/DropdownMenuTrigger.vue
index 7dac672..8b7fc96 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuTrigger.vue
+++ b/vue/primitives/src/menus/dropdown-menu/DropdownMenuTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button that toggles the menu open on click, Enter, Space, or the arrow
@@ -17,7 +17,7 @@ import { onMounted, onUnmounted } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
 import { MenuAnchor, useMenuContext } from '../menu';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useDropdownMenuRootContext } from './context';
 
 const { disabled = false, as = 'button' } = defineProps<DropdownMenuTriggerProps>();
@@ -62,9 +62,10 @@ function handleKeyDown(event: KeyboardEvent) {
       :ref="forwardRef"
       :as="as"
       :id="ddCtx.triggerId.value"
+      :type="as === 'button' ? 'button' : undefined"
       aria-haspopup="menu"
       :aria-expanded="menuCtx.open.value"
-      :aria-controls="ddCtx.contentId.value"
+      :aria-controls="menuCtx.open.value ? ddCtx.contentId.value : undefined"
       :data-state="menuCtx.open.value ? 'open' : 'closed'"
       :data-disabled="disabled ? '' : undefined"
       :disabled="as === 'button' ? disabled : undefined"
diff --git a/vue/primitives/src/menus/dropdown-menu/__test__/DropdownMenu.test.ts b/vue/primitives/src/menus/dropdown-menu/__test__/DropdownMenu.test.ts
new file mode 100644
index 0000000..1661379
--- /dev/null
+++ b/vue/primitives/src/menus/dropdown-menu/__test__/DropdownMenu.test.ts
@@ -0,0 +1,324 @@
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+
+import {
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuPortal,
+  DropdownMenuRoot,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+  useDropdownMenuRootContext,
+} from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function mountMenu(opts: { modal?: boolean } = {}) {
+  const Harness = defineComponent({
+    setup() {
+      return () => h(
+        DropdownMenuRoot,
+        { modal: opts.modal },
+        {
+          default: () => [
+            h(
+              DropdownMenuTrigger,
+              { 'data-testid': 'trigger', class: 'demo-trigger' },
+              { default: () => 'Open' },
+            ),
+            h(DropdownMenuPortal, null, {
+              default: () => h(DropdownMenuContent, null, {
+                default: () => [
+                  h(DropdownMenuItem, null, { default: () => 'One' }),
+                  h(DropdownMenuItem, null, { default: () => 'Two' }),
+                ],
+              }),
+            }),
+          ],
+        },
+      );
+    },
+  });
+  return track(mount(Harness, { attachTo: document.body }));
+}
+
+function trigger(): HTMLElement {
+  return document.querySelector<HTMLElement>('[data-testid="trigger"]')!;
+}
+
+function menu(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('[role="menu"]');
+}
+
+function pointerDown(el: EventTarget) {
+  el.dispatchEvent(new PointerEvent('pointerdown', {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    button: 0,
+    pointerId: 1,
+    pointerType: 'mouse',
+  }));
+}
+
+async function flush() {
+  await nextTick();
+  await nextTick();
+}
+
+describe('dropdownMenu — trigger renders as the anchor itself', () => {
+  it('merges fallthrough attrs onto the trigger button (no anchor wrapper element)', () => {
+    mountMenu();
+    const el = trigger();
+    // Pre-fix, MenuAnchor rendered a real <div> wrapper that swallowed
+    // fallthrough attrs while data-state/aria stayed on the inner button.
+    expect(el.tagName).toBe('BUTTON');
+    expect(el.classList.contains('demo-trigger')).toBe(true);
+    expect(el.getAttribute('aria-haspopup')).toBe('menu');
+    expect(el.getAttribute('data-state')).toBe('closed');
+    expect(el.querySelector('button')).toBeNull();
+  });
+
+  it('flips data-state/aria-expanded on the attr-bearing element when opened', async () => {
+    mountMenu({ modal: false });
+    pointerDown(trigger());
+    await flush();
+    expect(menu()).toBeTruthy();
+    expect(trigger().getAttribute('data-state')).toBe('open');
+    expect(trigger().getAttribute('aria-expanded')).toBe('true');
+  });
+});
+
+describe('dropdownMenu — trigger pointerdown toggling (non-modal)', () => {
+  it('closes on trigger pointerdown while open and does not reopen from the dismiss race', async () => {
+    mountMenu({ modal: false });
+
+    pointerDown(trigger());
+    await flush();
+    expect(menu()).toBeTruthy();
+
+    // The outside-pointerdown dismiss (window capture) runs before the
+    // trigger's own handler — without the content-side guard the menu would
+    // close via dismiss and instantly reopen via the trigger toggle.
+    pointerDown(trigger());
+    await flush();
+    expect(menu()).toBeNull();
+    expect(trigger().getAttribute('data-state')).toBe('closed');
+
+    await flush();
+    expect(menu()).toBeNull();
+  });
+
+  it('reopens on the next trigger pointerdown after a toggle-close', async () => {
+    mountMenu({ modal: false });
+
+    pointerDown(trigger());
+    await flush();
+    pointerDown(trigger());
+    await flush();
+    expect(menu()).toBeNull();
+
+    pointerDown(trigger());
+    await flush();
+    expect(menu()).toBeTruthy();
+    expect(trigger().getAttribute('data-state')).toBe('open');
+  });
+});
+
+describe('dropdownMenu — trigger keyboard open', () => {
+  it('opens the menu on Enter', async () => {
+    mountMenu({ modal: false });
+    trigger().dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+    await flush();
+    expect(menu()).toBeTruthy();
+    expect(trigger().getAttribute('data-state')).toBe('open');
+  });
+});
+
+describe('dropdownMenu — trigger forms safety + conditional aria-controls', () => {
+  it('renders type="button" on the default button trigger to avoid form submission', () => {
+    mountMenu();
+    expect(trigger().getAttribute('type')).toBe('button');
+  });
+
+  it('only sets aria-controls while the menu is open (WAI-ARIA menu-button pattern)', async () => {
+    mountMenu({ modal: false });
+    expect(trigger().getAttribute('aria-controls')).toBeNull();
+    expect(trigger().getAttribute('aria-expanded')).toBe('false');
+
+    pointerDown(trigger());
+    await flush();
+    const controls = trigger().getAttribute('aria-controls');
+    expect(controls).toBeTruthy();
+    // aria-controls must point at the content element id when open.
+    expect(menu()!.getAttribute('id')).toBe(controls);
+
+    pointerDown(trigger());
+    await flush();
+    expect(trigger().getAttribute('aria-controls')).toBeNull();
+  });
+
+  it('omits type on a non-button trigger element', () => {
+    const Harness = defineComponent({
+      setup() {
+        return () => h(DropdownMenuRoot, { modal: false }, {
+          default: () => [
+            h(DropdownMenuTrigger, { as: 'a', 'data-testid': 'trigger' }, { default: () => 'Open' }),
+            h(DropdownMenuPortal, null, {
+              default: () => h(DropdownMenuContent, null, { default: () => h(DropdownMenuItem, null, { default: () => 'One' }) }),
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    expect(trigger().tagName).toBe('A');
+    expect(trigger().getAttribute('type')).toBeNull();
+  });
+});
+
+describe('dropdownMenu — content sizing custom properties', () => {
+  it('exposes dropdown-scoped CSS variables mapped from the popper anchor measurements', async () => {
+    mountMenu({ modal: false });
+    pointerDown(trigger());
+    await flush();
+    const style = menu()!.getAttribute('style') ?? '';
+    expect(style).toContain('--primitives-dropdown-menu-trigger-width: var(--popper-anchor-width)');
+    expect(style).toContain('--primitives-dropdown-menu-trigger-height: var(--popper-anchor-height)');
+    expect(style).toContain('--primitives-dropdown-menu-content-transform-origin: var(--popper-transform-origin)');
+  });
+});
+
+describe('dropdownMenu — focus return to trigger on close', () => {
+  it('returns focus to the trigger when closed via Escape', async () => {
+    mountMenu({ modal: false });
+    pointerDown(trigger());
+    await flush();
+    expect(menu()).toBeTruthy();
+
+    document.body.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }));
+    await flush();
+    await flush();
+
+    expect(menu()).toBeNull();
+    expect(document.activeElement).toBe(trigger());
+  });
+
+  it('does not steal focus back to the trigger when the user interacts outside (non-modal)', async () => {
+    mountMenu({ modal: false });
+    pointerDown(trigger());
+    await flush();
+    expect(menu()).toBeTruthy();
+
+    const outside = document.createElement('button');
+    outside.id = 'outside';
+    document.body.appendChild(outside);
+
+    // A non-modal outside pointerdown dismisses the menu; focus must stay where
+    // the user pointed rather than snapping back to the trigger.
+    outside.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true, composed: true, button: 0, pointerId: 1, pointerType: 'mouse' }));
+    await flush();
+    await flush();
+
+    expect(menu()).toBeNull();
+    expect(document.activeElement).not.toBe(trigger());
+
+    outside.remove();
+  });
+});
+
+describe('dropdownMenu — Sub controlled / uncontrolled', () => {
+  function mountWithSub(opts: { defaultOpen?: boolean } = {}) {
+    const seenOpen = ref<boolean | undefined>(undefined);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(DropdownMenuRoot, { modal: false, defaultOpen: true }, {
+          default: () => h(DropdownMenuPortal, null, {
+            default: () => h(DropdownMenuContent, null, {
+              default: () => h(
+                DropdownMenuSub,
+                { defaultOpen: opts.defaultOpen },
+                {
+                  default: (slotProps: { open: boolean }) => {
+                    seenOpen.value = slotProps.open;
+                    return [
+                      h(DropdownMenuSubTrigger, { class: 'sub-trigger' }, { default: () => 'More' }),
+                      h(DropdownMenuSubContent, null, {
+                        default: () => h(DropdownMenuItem, { class: 'sub-item' }, { default: () => 'Sub One' }),
+                      }),
+                    ];
+                  },
+                },
+              ),
+            }),
+          }),
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    return { seenOpen };
+  }
+
+  it('exposes the current open value through the default slot', async () => {
+    const { seenOpen } = mountWithSub({ defaultOpen: false });
+    await flush();
+    expect(seenOpen.value).toBe(false);
+  });
+
+  it('honours defaultOpen for uncontrolled submenus (open slot reflects it)', async () => {
+    const { seenOpen } = mountWithSub({ defaultOpen: true });
+    await flush();
+    expect(seenOpen.value).toBe(true);
+    expect(document.querySelector('.sub-item')).toBeTruthy();
+  });
+});
+
+describe('dropdownMenu — enriched root context', () => {
+  it('exposes open / onOpenToggle / modal / dir for composition', async () => {
+    let ctx!: ReturnType<typeof useDropdownMenuRootContext>;
+    const Consumer = defineComponent({
+      setup() {
+        ctx = useDropdownMenuRootContext();
+        return () => null;
+      },
+    });
+    const Harness = defineComponent({
+      setup() {
+        return () => h(DropdownMenuRoot, { modal: false, dir: 'rtl' }, {
+          default: () => [
+            h(DropdownMenuTrigger, { 'data-testid': 'trigger' }, { default: () => 'Open' }),
+            h(Consumer),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await flush();
+
+    expect(ctx.open.value).toBe(false);
+    expect(ctx.modal.value).toBe(false);
+    expect(ctx.dir.value).toBe('rtl');
+
+    ctx.onOpenToggle();
+    await flush();
+    expect(ctx.open.value).toBe(true);
+
+    ctx.onOpenChange(false);
+    await flush();
+    expect(ctx.open.value).toBe(false);
+  });
+});
diff --git a/vue/primitives/src/menus/dropdown-menu/context.ts b/vue/primitives/src/menus/dropdown-menu/context.ts
new file mode 100644
index 0000000..44af043
--- /dev/null
+++ b/vue/primitives/src/menus/dropdown-menu/context.ts
@@ -0,0 +1,26 @@
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+
+import type { Direction } from '../../utilities/config-provider';
+import { useContextFactory } from '@robonen/vue';
+
+export interface DropdownMenuRootContext {
+  triggerId: ComputedRef<string>;
+  triggerRef: ShallowRef<HTMLElement | null>;
+  contentId: ComputedRef<string>;
+  onTriggerChange: (el: HTMLElement | null) => void;
+  /** Reactive open state, mirrored from the underlying menu, for composition. */
+  open: Ref<boolean>;
+  /** Sets the open state explicitly. */
+  onOpenChange: (open: boolean) => void;
+  /** Flips the open state. */
+  onOpenToggle: () => void;
+  /** Whether the menu blocks interaction with the rest of the page while open. */
+  modal: Ref<boolean>;
+  /** Resolved reading direction (`'ltr' | 'rtl'`). */
+  dir: Ref<Direction>;
+}
+
+export const {
+  inject: useDropdownMenuRootContext,
+  provide: provideDropdownMenuRootContext,
+} = useContextFactory<DropdownMenuRootContext>('DropdownMenuRootContext');
diff --git a/vue/primitives/src/dropdown-menu/demo.vue b/vue/primitives/src/menus/dropdown-menu/demo.vue
similarity index 67%
rename from vue/primitives/src/dropdown-menu/demo.vue
rename to vue/primitives/src/menus/dropdown-menu/demo.vue
index 3e20c19..1612fe1 100644
--- a/vue/primitives/src/dropdown-menu/demo.vue
+++ b/vue/primitives/src/menus/dropdown-menu/demo.vue
@@ -20,7 +20,7 @@ const showActivityBar = ref(false);
 const theme = ref('system');
 const lastAction = ref('');
 
-const itemClass = 'group flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1.5 text-sm text-(--fg) outline-none data-[highlighted]:bg-(--accent) data-[highlighted]:text-(--accent-fg) data-[disabled]:pointer-events-none data-[disabled]:opacity-50';
+const itemClass = 'group flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1.5 text-sm text-fg outline-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-fg data-[disabled]:pointer-events-none data-[disabled]:opacity-50';
 const checkItemClass = `${itemClass} pl-7 relative`;
 
 function run(action: string) {
@@ -29,14 +29,14 @@ function run(action: string) {
 </script>
 
 <template>
-  <div class="flex flex-col items-start gap-3 text-(--fg)">
+  <div class="flex flex-col items-start gap-3 text-fg">
     <DropdownMenuRoot v-model:open="open">
       <DropdownMenuTrigger
-        class="group inline-flex items-center gap-2 rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) data-[state=open]:bg-(--bg-subtle)"
+        class="group inline-flex items-center gap-2 rounded-md border border-border bg-bg px-3 py-1.5 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[state=open]:bg-bg-subtle"
       >
         Options
         <span
-          class="i-carbon-chevron-down text-(--fg-muted) transition-transform duration-150 group-data-[state=open]:rotate-180"
+          class="i-carbon-chevron-down text-fg-muted transition-transform duration-150 group-data-[state=open]:rotate-180"
           aria-hidden="true"
         />
       </DropdownMenuTrigger>
@@ -45,9 +45,9 @@ function run(action: string) {
         <DropdownMenuContent
           :side-offset="6"
           align="start"
-          class="z-50 min-w-56 rounded-lg border border-(--border) bg-(--bg-elevated) p-1 shadow-lg"
+          class="z-50 min-w-56 rounded-lg border border-border bg-bg-elevated p-1 shadow-lg"
         >
-          <DropdownMenuLabel class="px-2 py-1.5 text-xs font-medium text-(--fg-subtle)">
+          <DropdownMenuLabel class="px-2 py-1.5 text-xs font-medium text-fg-subtle">
             My account
           </DropdownMenuLabel>
 
@@ -60,53 +60,53 @@ function run(action: string) {
             Settings
           </DropdownMenuItem>
 
-          <DropdownMenuSeparator class="my-1 h-px bg-(--border)" />
+          <DropdownMenuSeparator class="my-1 h-px bg-border" />
 
-          <DropdownMenuLabel class="px-2 py-1.5 text-xs font-medium text-(--fg-subtle)">
+          <DropdownMenuLabel class="px-2 py-1.5 text-xs font-medium text-fg-subtle">
             View
           </DropdownMenuLabel>
 
           <DropdownMenuCheckboxItem v-model:checked="showStatusBar" :class="checkItemClass">
             <DropdownMenuItemIndicator class="absolute left-1.5 inline-flex">
-              <span class="i-carbon-checkmark text-(--accent)" aria-hidden="true" />
+              <span class="i-carbon-checkmark text-accent" aria-hidden="true" />
             </DropdownMenuItemIndicator>
             Status bar
           </DropdownMenuCheckboxItem>
           <DropdownMenuCheckboxItem v-model:checked="showActivityBar" :class="checkItemClass">
             <DropdownMenuItemIndicator class="absolute left-1.5 inline-flex">
-              <span class="i-carbon-checkmark text-(--accent)" aria-hidden="true" />
+              <span class="i-carbon-checkmark text-accent" aria-hidden="true" />
             </DropdownMenuItemIndicator>
             Activity bar
           </DropdownMenuCheckboxItem>
 
-          <DropdownMenuSeparator class="my-1 h-px bg-(--border)" />
+          <DropdownMenuSeparator class="my-1 h-px bg-border" />
 
-          <DropdownMenuLabel class="px-2 py-1.5 text-xs font-medium text-(--fg-subtle)">
+          <DropdownMenuLabel class="px-2 py-1.5 text-xs font-medium text-fg-subtle">
             Theme
           </DropdownMenuLabel>
 
           <DropdownMenuRadioGroup v-model="theme">
             <DropdownMenuRadioItem value="light" :class="checkItemClass">
               <DropdownMenuItemIndicator class="absolute left-1.5 inline-flex">
-                <span class="i-carbon-dot-mark text-(--accent)" aria-hidden="true" />
+                <span class="i-carbon-dot-mark text-accent" aria-hidden="true" />
               </DropdownMenuItemIndicator>
               Light
             </DropdownMenuRadioItem>
             <DropdownMenuRadioItem value="dark" :class="checkItemClass">
               <DropdownMenuItemIndicator class="absolute left-1.5 inline-flex">
-                <span class="i-carbon-dot-mark text-(--accent)" aria-hidden="true" />
+                <span class="i-carbon-dot-mark text-accent" aria-hidden="true" />
               </DropdownMenuItemIndicator>
               Dark
             </DropdownMenuRadioItem>
             <DropdownMenuRadioItem value="system" :class="checkItemClass">
               <DropdownMenuItemIndicator class="absolute left-1.5 inline-flex">
-                <span class="i-carbon-dot-mark text-(--accent)" aria-hidden="true" />
+                <span class="i-carbon-dot-mark text-accent" aria-hidden="true" />
               </DropdownMenuItemIndicator>
               System
             </DropdownMenuRadioItem>
           </DropdownMenuRadioGroup>
 
-          <DropdownMenuSeparator class="my-1 h-px bg-(--border)" />
+          <DropdownMenuSeparator class="my-1 h-px bg-border" />
 
           <DropdownMenuItem
             class="group flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1.5 text-sm text-red-600 outline-none data-[highlighted]:bg-red-600 data-[highlighted]:text-white dark:text-red-400"
@@ -119,12 +119,12 @@ function run(action: string) {
       </DropdownMenuPortal>
     </DropdownMenuRoot>
 
-    <p class="text-xs text-(--fg-muted)">
-      Theme: <span class="font-medium text-(--fg)">{{ theme }}</span>
-      &middot; Status bar: <span class="font-medium text-(--fg)">{{ showStatusBar ? 'on' : 'off' }}</span>
-      &middot; Activity bar: <span class="font-medium text-(--fg)">{{ showActivityBar ? 'on' : 'off' }}</span>
+    <p class="text-xs text-fg-muted">
+      Theme: <span class="font-medium text-fg">{{ theme }}</span>
+      &middot; Status bar: <span class="font-medium text-fg">{{ showStatusBar ? 'on' : 'off' }}</span>
+      &middot; Activity bar: <span class="font-medium text-fg">{{ showActivityBar ? 'on' : 'off' }}</span>
       <template v-if="lastAction">
-        &middot; Last action: <span class="font-medium text-(--fg)">{{ lastAction }}</span>
+        &middot; Last action: <span class="font-medium text-fg">{{ lastAction }}</span>
       </template>
     </p>
   </div>
diff --git a/vue/primitives/src/dropdown-menu/index.ts b/vue/primitives/src/menus/dropdown-menu/index.ts
similarity index 100%
rename from vue/primitives/src/dropdown-menu/index.ts
rename to vue/primitives/src/menus/dropdown-menu/index.ts
diff --git a/vue/primitives/src/menu/MenuAnchor.vue b/vue/primitives/src/menus/menu/MenuAnchor.vue
similarity index 82%
rename from vue/primitives/src/menu/MenuAnchor.vue
rename to vue/primitives/src/menus/menu/MenuAnchor.vue
index b396a26..6b706d0 100644
--- a/vue/primitives/src/menu/MenuAnchor.vue
+++ b/vue/primitives/src/menus/menu/MenuAnchor.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperAnchorProps } from '../popper';
+import type { PopperAnchorProps } from '../../overlays/popper';
 
 /**
  * An optional positioning anchor for the menu content. Render it around the
@@ -11,7 +11,7 @@ export interface MenuAnchorProps extends PopperAnchorProps {}
 </script>
 
 <script setup lang="ts">
-import { PopperAnchor } from '../popper';
+import { PopperAnchor } from '../../overlays/popper';
 
 const props = defineProps<MenuAnchorProps>();
 </script>
diff --git a/vue/primitives/src/menu/MenuArrow.vue b/vue/primitives/src/menus/menu/MenuArrow.vue
similarity index 79%
rename from vue/primitives/src/menu/MenuArrow.vue
rename to vue/primitives/src/menus/menu/MenuArrow.vue
index cb87088..269b0a4 100644
--- a/vue/primitives/src/menu/MenuArrow.vue
+++ b/vue/primitives/src/menus/menu/MenuArrow.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperArrowProps } from '../popper';
+import type { PopperArrowProps } from '../../overlays/popper';
 
 /**
  * An optional arrow that renders inside the menu content and points back toward
@@ -10,7 +10,7 @@ export interface MenuArrowProps extends PopperArrowProps {}
 </script>
 
 <script setup lang="ts">
-import { PopperArrow } from '../popper';
+import { PopperArrow } from '../../overlays/popper';
 
 const props = defineProps<MenuArrowProps>();
 </script>
diff --git a/vue/primitives/src/menu/MenuCheckboxItem.vue b/vue/primitives/src/menus/menu/MenuCheckboxItem.vue
similarity index 95%
rename from vue/primitives/src/menu/MenuCheckboxItem.vue
rename to vue/primitives/src/menus/menu/MenuCheckboxItem.vue
index f404e60..77d2412 100644
--- a/vue/primitives/src/menu/MenuCheckboxItem.vue
+++ b/vue/primitives/src/menus/menu/MenuCheckboxItem.vue
@@ -33,6 +33,7 @@ const {
 } = defineProps<MenuCheckboxItemProps>();
 
 const emit = defineEmits<MenuCheckboxItemEmits>();
+defineSlots<{ default?: (props: { checked: CheckedState }) => unknown }>();
 const rootCtx = useMenuRootContext();
 
 const local = ref<CheckedState>(defaultChecked);
@@ -62,6 +63,6 @@ function handleSelect(event: Event) {
     :data-state="getCheckedState(checkedState)"
     @select="handleSelect"
   >
-    <slot />
+    <slot :checked="checkedState" />
   </MenuItemImpl>
 </template>
diff --git a/vue/primitives/src/menu/MenuContent.vue b/vue/primitives/src/menus/menu/MenuContent.vue
similarity index 97%
rename from vue/primitives/src/menu/MenuContent.vue
rename to vue/primitives/src/menus/menu/MenuContent.vue
index acbef88..6c18f0e 100644
--- a/vue/primitives/src/menu/MenuContent.vue
+++ b/vue/primitives/src/menus/menu/MenuContent.vue
@@ -18,7 +18,7 @@ export type MenuContentEmits = MenuContentImplEmits;
 </script>
 
 <script setup lang="ts">
-import { Presence } from '../presence';
+import { Presence } from '../../utilities/presence';
 import { useMenuContext, useMenuRootContext } from './context';
 import MenuRootContentModal from './MenuRootContentModal.vue';
 import MenuRootContentNonModal from './MenuRootContentNonModal.vue';
diff --git a/vue/primitives/src/menu/MenuContentImpl.vue b/vue/primitives/src/menus/menu/MenuContentImpl.vue
similarity index 58%
rename from vue/primitives/src/menu/MenuContentImpl.vue
rename to vue/primitives/src/menus/menu/MenuContentImpl.vue
index 507ea97..c3127d6 100644
--- a/vue/primitives/src/menu/MenuContentImpl.vue
+++ b/vue/primitives/src/menus/menu/MenuContentImpl.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
-import type { PopperContentProps } from '../popper';
-import type { PrimitiveProps } from '../primitive';
+import type { PopperContentProps } from '../../overlays/popper';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Internal shared implementation behind MenuContent and MenuSubContent. It
@@ -32,18 +32,28 @@ export interface MenuContentImplEmits {
   entryFocus: [event: Event];
   openAutoFocus: [event: Event];
 }
+
+// Static CSS-variable bridge from Popper's exported vars to the menu-content
+// namespace. Hoisted to module scope so a stable reference is bound every
+// render (avoids per-render object allocation; the style values never change).
+const CONTENT_STYLE = {
+  '--primitives-menu-content-transform-origin': 'var(--popper-transform-origin)',
+  '--primitives-menu-content-available-width': 'var(--popper-available-width)',
+  '--primitives-menu-content-available-height': 'var(--popper-available-height)',
+} as const;
 </script>
 
 <script setup lang="ts">
-import { onScopeDispose, ref } from 'vue';
+import { computed, ref } from 'vue';
 
-import { DismissableLayer } from '../dismissable-layer';
-import { FocusScope } from '../focus-scope';
-import { PopperContent } from '../popper';
-import { RovingFocusGroup } from '../roving-focus';
-import { useForwardExpose } from '@robonen/vue';
-import { provideMenuContentContext, useMenuContext, useMenuRootContext } from './context';
-import { FIRST_LAST_KEYS, LAST_KEYS, focusFirst, getNextMatch, getOpenState, isPointerInGraceArea } from './utils';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
+import { FocusScope } from '../../utilities/focus-scope';
+import { PopperContent } from '../../overlays/popper';
+import { RovingFocusGroup } from '../../utilities/roving-focus';
+import { refAutoReset, useForwardExpose } from '@robonen/vue';
+import { provideMenuContentContext, provideMenuItemSelectContext, useMenuContext, useMenuRootContext } from './context';
+import type { GraceIntent, Side } from './utils';
+import { FIRST_LAST_KEYS, LAST_KEYS, focusFirst, getNextMatch, getOpenState, isMousePointer, isPointerInGraceArea } from './utils';
 
 const {
   loop = false,
@@ -62,34 +72,46 @@ const menuCtx = useMenuContext();
 const rootCtx = useMenuRootContext();
 const { forwardRef, currentElement: contentElement } = useForwardExpose();
 
-const searchRef = ref('');
-let searchTimer: ReturnType<typeof setTimeout> | undefined;
-
-function clearSearch() {
-  clearTimeout(searchTimer);
-  searchRef.value = '';
-}
-
-onScopeDispose(clearSearch);
+// Typeahead buffer that auto-clears 1s after the last keystroke — each write
+// restarts the idle timer (and it tears down on scope dispose). Mirrors the
+// Menubar/Select typeahead.
+const searchRef = refAutoReset('', 1000);
 
 const pointerGraceTimerRef = ref<number>(0);
-const pointerGraceIntentRef = ref<{ area: Array<{ x: number; y: number }>; side: 'left' | 'right' } | null>(null);
+const pointerGraceIntentRef = ref<GraceIntent | null>(null);
+
+// Track which way the pointer is travelling so the grace area only keeps the
+// submenu open when the cursor is heading *toward* it (a downward/sideways
+// drift back over the parent items must still close it).
+const pointerDirRef = ref<Side>('right');
+const lastPointerXRef = ref(0);
+
+function isPointerMovingToSubmenu(event: PointerEvent): boolean {
+  const isMovingTowards = pointerDirRef.value === pointerGraceIntentRef.value?.side;
+  return isMovingTowards && isPointerInGraceArea(event, pointerGraceIntentRef.value?.area);
+}
+
+function handlePointerMove(event: PointerEvent) {
+  if (!isMousePointer(event)) return;
+  const target = event.target as HTMLElement;
+  const pointerXHasChanged = lastPointerXRef.value !== event.clientX;
+  // Safari always reports `movementX === 0`, so compare clientX ourselves.
+  if ((event.currentTarget as HTMLElement)?.contains(target) && pointerXHasChanged) {
+    pointerDirRef.value = event.clientX > lastPointerXRef.value ? 'right' : 'left';
+    lastPointerXRef.value = event.clientX;
+  }
+}
 
 provideMenuContentContext({
   onItemEnter: (event) => {
-    if (pointerGraceIntentRef.value) {
-      return isPointerInGraceArea(event, pointerGraceIntentRef.value.area);
-    }
-    return false;
+    return isPointerMovingToSubmenu(event);
   },
-  onItemLeave: (_event) => {
+  onItemLeave: (event) => {
+    if (isPointerMovingToSubmenu(event)) return;
     contentElement.value?.focus({ preventScroll: true });
   },
   onTriggerLeave: (event) => {
-    if (pointerGraceIntentRef.value) {
-      return isPointerInGraceArea(event, pointerGraceIntentRef.value.area);
-    }
-    return false;
+    return isPointerMovingToSubmenu(event);
   },
   searchRef,
   pointerGraceTimerRef,
@@ -98,6 +120,11 @@ provideMenuContentContext({
   },
 });
 
+// Exposed to selectable items so Space can extend type-ahead instead of
+// activating the focused item while the user is mid-search.
+const isTypingAhead = computed(() => searchRef.value !== '');
+provideMenuItemSelectContext({ isTypingAhead });
+
 function handleMountAutoFocus(event: Event) {
   event.preventDefault();
   // Always focus the content so key events reach the menu even after a
@@ -107,9 +134,21 @@ function handleMountAutoFocus(event: Event) {
 }
 
 function handleKeyDown(event: KeyboardEvent) {
+  if (event.defaultPrevented) return;
+
+  const target = event.target as HTMLElement;
+  // Submenu key events bubble up through portals; only act on keys that
+  // originate inside *this* content, not a nested submenu's.
+  const isKeyDownInside = target.closest('[data-primitives-menu-content]') === event.currentTarget;
+  // Don't hijack typing inside an embedded input/textarea (e.g. a filter field).
+  const isKeyDownInTextField = ['input', 'textarea'].includes(target.tagName.toLowerCase());
+
+  // Menus must not be exited via Tab — keep focus inside (ARIA menu pattern).
+  if (isKeyDownInside && event.key === 'Tab') event.preventDefault();
+
   const isCharKey = event.key.length === 1 && !event.ctrlKey && !event.altKey && !event.metaKey;
-  if (isCharKey) {
-    clearTimeout(searchTimer);
+  // Space drives selection (handled by the item), never typeahead.
+  if (isCharKey && event.key !== ' ' && isKeyDownInside && !isKeyDownInTextField) {
     searchRef.value += event.key;
     const content = contentElement.value;
     if (!content) return;
@@ -119,7 +158,6 @@ function handleKeyDown(event: KeyboardEvent) {
     const currentItem = content.querySelector<HTMLElement>('[data-primitives-menu-item][data-highlighted]');
     const match = getNextMatch(items, searchRef.value, currentItem);
     if (match) match.focus({ preventScroll: true });
-    searchTimer = setTimeout(clearSearch, 1000);
     event.stopPropagation();
   }
 
@@ -143,7 +181,7 @@ function handleBlur(event: FocusEvent) {
   const content = contentElement.value;
   if (!content) return;
   if (!content.contains(event.relatedTarget as Node)) {
-    clearSearch();
+    searchRef.value = '';
   }
 }
 </script>
@@ -186,14 +224,11 @@ function handleBlur(event: FocusEvent) {
           :side="side"
           :side-offset="sideOffset"
           :align="align"
-          :style="{
-            '--primitives-menu-content-transform-origin': 'var(--popper-transform-origin)',
-            '--primitives-menu-content-available-width': 'var(--popper-available-width)',
-            '--primitives-menu-content-available-height': 'var(--popper-available-height)',
-          }"
+          :style="CONTENT_STYLE"
           v-bind="popperProps"
           @keydown="handleKeyDown"
           @blur="handleBlur"
+          @pointermove="handlePointerMove"
         >
           <slot />
         </PopperContent>
diff --git a/vue/primitives/src/menu/MenuGroup.vue b/vue/primitives/src/menus/menu/MenuGroup.vue
similarity index 69%
rename from vue/primitives/src/menu/MenuGroup.vue
rename to vue/primitives/src/menus/menu/MenuGroup.vue
index e6ab474..f2f2c7b 100644
--- a/vue/primitives/src/menu/MenuGroup.vue
+++ b/vue/primitives/src/menus/menu/MenuGroup.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Groups a set of related menu items under `role="group"` for accessibility.
@@ -9,8 +9,8 @@ export interface MenuGroupProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { useId } from '../config-provider';
-import { Primitive } from '../primitive';
+import { useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { provideMenuGroupContext } from './context';
 
 const { as = 'div' } = defineProps<MenuGroupProps>();
@@ -19,7 +19,7 @@ provideMenuGroupContext({ id: id.value });
 </script>
 
 <template>
-  <Primitive :as="as" role="group" :id="id">
+  <Primitive :as="as" role="group" :aria-labelledby="id">
     <slot />
   </Primitive>
 </template>
diff --git a/vue/primitives/src/menu/MenuItem.vue b/vue/primitives/src/menus/menu/MenuItem.vue
similarity index 61%
rename from vue/primitives/src/menu/MenuItem.vue
rename to vue/primitives/src/menus/menu/MenuItem.vue
index 6125abb..b120b93 100644
--- a/vue/primitives/src/menu/MenuItem.vue
+++ b/vue/primitives/src/menus/menu/MenuItem.vue
@@ -11,6 +11,8 @@ export type MenuItemEmits = MenuItemImplEmits;
 </script>
 
 <script setup lang="ts">
+import { ref } from 'vue';
+
 import { useMenuRootContext } from './context';
 import MenuItemImpl from './MenuItemImpl.vue';
 import { ITEM_SELECT } from './utils';
@@ -20,6 +22,12 @@ const emit = defineEmits<MenuItemEmits>();
 
 const rootCtx = useMenuRootContext();
 
+// Tracks whether the pointer went down on *this* item. If it went down
+// elsewhere and is released over this item (drag-select), we synthesise a click
+// so the item still activates — this also avoids Firefox getting stuck in text
+// selection when the menu closes.
+const isPointerDownRef = ref(false);
+
 function handleSelect(event: Event) {
   const target = event.currentTarget as HTMLElement;
   const selectEvent = new CustomEvent(ITEM_SELECT, { bubbles: true, cancelable: true });
@@ -31,10 +39,26 @@ function handleSelect(event: Event) {
     rootCtx.onClose();
   }
 }
+
+function handlePointerDown() {
+  isPointerDownRef.value = true;
+}
+
+function handlePointerUp(event: PointerEvent) {
+  if (event.defaultPrevented) return;
+  // Pointer started on another item then released here: activate via click.
+  if (!isPointerDownRef.value) (event.currentTarget as HTMLElement)?.click();
+  isPointerDownRef.value = false;
+}
 </script>
 
 <template>
-  <MenuItemImpl v-bind="props" @select="handleSelect">
+  <MenuItemImpl
+    v-bind="props"
+    @select="handleSelect"
+    @pointerdown="handlePointerDown"
+    @pointerup="handlePointerUp"
+  >
     <slot />
   </MenuItemImpl>
 </template>
diff --git a/vue/primitives/src/menu/MenuItemImpl.vue b/vue/primitives/src/menus/menu/MenuItemImpl.vue
similarity index 78%
rename from vue/primitives/src/menu/MenuItemImpl.vue
rename to vue/primitives/src/menus/menu/MenuItemImpl.vue
index 8e174d1..6d6d8da 100644
--- a/vue/primitives/src/menu/MenuItemImpl.vue
+++ b/vue/primitives/src/menus/menu/MenuItemImpl.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Internal base for every selectable menu item (MenuItem, MenuCheckboxItem,
@@ -21,9 +21,9 @@ export interface MenuItemImplEmits {
 <script setup lang="ts">
 import { computed, ref, shallowRef } from 'vue';
 
-import { RovingFocusItem } from '../roving-focus';
-import { Primitive } from '../primitive';
-import { useMenuContentContext } from './context';
+import { RovingFocusItem } from '../../utilities/roving-focus';
+import { Primitive } from '../../internal/primitive';
+import { useMenuContentContext, useMenuItemSelectContext } from './context';
 
 const {
   disabled = false,
@@ -34,8 +34,16 @@ const {
 const emit = defineEmits<MenuItemImplEmits>();
 
 const contentCtx = useMenuContentContext();
+// Optional: present inside a menu content, absent if an item is rendered
+// standalone in tests. Falls back to a never-typing stub.
+const selectCtx = useMenuItemSelectContext({ isTypingAhead: shallowRef(false) });
 
 const itemRef = shallowRef<HTMLElement | null>(null);
+// Stable ref setter: a fresh inline arrow per render would force Vue to tear
+// down (call with null) and re-bind the ref on every item patch.
+const setItemRef = (el: unknown) => {
+  itemRef.value = el as HTMLElement | null;
+};
 const isHighlighted = ref(false);
 
 const textValue = computed(() => textValueProp ?? itemRef.value?.textContent?.trim() ?? '');
@@ -69,6 +77,8 @@ function handleClick(event: MouseEvent) {
 
 function handleKeyDown(event: KeyboardEvent) {
   if (disabled) return;
+  // While typing ahead, Space extends the search rather than selecting.
+  if (selectCtx.isTypingAhead.value && event.key === ' ') return;
   if (event.key === 'Enter' || event.key === ' ') {
     event.preventDefault();
     const el = event.currentTarget as HTMLElement;
@@ -87,7 +97,7 @@ function handleKeyDown(event: KeyboardEvent) {
 <template>
   <RovingFocusItem as="template" :focusable="!disabled" :active="isHighlighted">
     <Primitive
-      :ref="(el: unknown) => { itemRef = el as HTMLElement | null }"
+      :ref="setItemRef"
       :as="as"
       role="menuitem"
       data-primitives-menu-item=""
diff --git a/vue/primitives/src/menu/MenuItemIndicator.vue b/vue/primitives/src/menus/menu/MenuItemIndicator.vue
similarity index 86%
rename from vue/primitives/src/menu/MenuItemIndicator.vue
rename to vue/primitives/src/menus/menu/MenuItemIndicator.vue
index e23f871..cbf2e72 100644
--- a/vue/primitives/src/menu/MenuItemIndicator.vue
+++ b/vue/primitives/src/menus/menu/MenuItemIndicator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Renders only while its parent MenuCheckboxItem or MenuRadioItem is checked (or
@@ -15,8 +15,8 @@ export interface MenuItemIndicatorProps extends PrimitiveProps {
 <script setup lang="ts">
 import { computed } from 'vue';
 
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
 import { useMenuItemIndicatorContext } from './context';
 import { getCheckedState, isIndeterminate } from './utils';
 
diff --git a/vue/primitives/src/menus/menu/MenuLabel.vue b/vue/primitives/src/menus/menu/MenuLabel.vue
new file mode 100644
index 0000000..905c133
--- /dev/null
+++ b/vue/primitives/src/menus/menu/MenuLabel.vue
@@ -0,0 +1,27 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A non-interactive heading for a section of the menu. It is skipped by keyboard
+ * navigation and typeahead, so use it to title a group of items rather than as a
+ * selectable entry.
+ */
+export interface MenuLabelProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { useMenuGroupContext } from './context';
+
+const { as = 'div' } = defineProps<MenuLabelProps>();
+
+// When rendered inside a MenuGroup, adopt the group's id so the group can point
+// `aria-labelledby` at this label. Falls back to no id when used standalone.
+const groupCtx = useMenuGroupContext({ id: '' });
+</script>
+
+<template>
+  <Primitive :as="as" :id="groupCtx.id || undefined">
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/menu/MenuPortal.vue b/vue/primitives/src/menus/menu/MenuPortal.vue
similarity index 82%
rename from vue/primitives/src/menu/MenuPortal.vue
rename to vue/primitives/src/menus/menu/MenuPortal.vue
index 084d850..a7bbd3f 100644
--- a/vue/primitives/src/menu/MenuPortal.vue
+++ b/vue/primitives/src/menus/menu/MenuPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PortalProps } from '../teleport';
+import type { PortalProps } from '../../utilities/teleport';
 
 /**
  * Teleports the menu content into a different part of the DOM (the document body
@@ -10,7 +10,7 @@ export interface MenuPortalProps extends PortalProps {}
 </script>
 
 <script setup lang="ts">
-import { Portal } from '../teleport';
+import { Portal } from '../../utilities/teleport';
 
 const { to, defer, disabled } = defineProps<MenuPortalProps>();
 </script>
diff --git a/vue/primitives/src/menu/MenuRadioGroup.vue b/vue/primitives/src/menus/menu/MenuRadioGroup.vue
similarity index 55%
rename from vue/primitives/src/menu/MenuRadioGroup.vue
rename to vue/primitives/src/menus/menu/MenuRadioGroup.vue
index 4d61d89..4fc5b35 100644
--- a/vue/primitives/src/menu/MenuRadioGroup.vue
+++ b/vue/primitives/src/menus/menu/MenuRadioGroup.vue
@@ -1,32 +1,36 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { AcceptableValue } from './utils';
 
 /**
  * Wraps a set of MenuRadioItems so that only one can be selected at a time,
  * managing the shared selected value. Bind `v-model` to control the selection,
- * or supply `defaultValue` to leave it uncontrolled.
+ * or supply `defaultValue` to leave it uncontrolled. Values may be any
+ * serialisable type (string / number / boolean / object), not just strings.
+ * Renders through MenuGroup so a nested MenuLabel labels the group.
  */
 export interface MenuRadioGroupProps extends PrimitiveProps {
   /** The controlled selected value. Use together with `update:modelValue`. */
-  modelValue?: string;
+  modelValue?: AcceptableValue;
   /** The selected value when uncontrolled. */
-  defaultValue?: string;
+  defaultValue?: AcceptableValue;
 }
 export interface MenuRadioGroupEmits {
-  'update:modelValue': [value: string];
+  'update:modelValue': [value: AcceptableValue];
 }
 </script>
 
 <script setup lang="ts">
-import { computed, ref } from 'vue';
+import { computed, shallowRef } from 'vue';
 
-import { Primitive } from '../primitive';
+import MenuGroup from './MenuGroup.vue';
 import { provideMenuRadioGroupContext } from './context';
 
 const { modelValue, defaultValue, as = 'div' } = defineProps<MenuRadioGroupProps>();
 const emit = defineEmits<MenuRadioGroupEmits>();
+defineSlots<{ default?: (props: { modelValue: AcceptableValue | undefined }) => unknown }>();
 
-const local = ref(defaultValue);
+const local = shallowRef(defaultValue);
 const value = computed(() => modelValue !== undefined ? modelValue : local.value);
 
 provideMenuRadioGroupContext({
@@ -39,7 +43,7 @@ provideMenuRadioGroupContext({
 </script>
 
 <template>
-  <Primitive :as="as" role="group">
-    <slot />
-  </Primitive>
+  <MenuGroup :as="as">
+    <slot :model-value="value" />
+  </MenuGroup>
 </template>
diff --git a/vue/primitives/src/menu/MenuRadioItem.vue b/vue/primitives/src/menus/menu/MenuRadioItem.vue
similarity index 76%
rename from vue/primitives/src/menu/MenuRadioItem.vue
rename to vue/primitives/src/menus/menu/MenuRadioItem.vue
index e33e312..f19146f 100644
--- a/vue/primitives/src/menu/MenuRadioItem.vue
+++ b/vue/primitives/src/menus/menu/MenuRadioItem.vue
@@ -1,15 +1,17 @@
 <script lang="ts">
 import type { MenuItemImplEmits, MenuItemImplProps } from './MenuItemImpl.vue';
+import type { AcceptableValue } from './utils';
 
 /**
  * A mutually-exclusive menu item rendered with `role="menuitemradio"`. Selecting
  * it sets the enclosing MenuRadioGroup's value to this item's `value`. Pair it
- * with MenuItemIndicator to show which option is active. Must be used inside a
- * MenuRadioGroup.
+ * with MenuItemIndicator to show which option is active. `value` may be any
+ * serialisable type, compared structurally to the group's selected value. Must
+ * be used inside a MenuRadioGroup.
  */
 export interface MenuRadioItemProps extends MenuItemImplProps {
   /** The unique value this item represents within its MenuRadioGroup. */
-  value: string;
+  value: AcceptableValue;
 }
 export type MenuRadioItemEmits = MenuItemImplEmits;
 </script>
@@ -17,16 +19,18 @@ export type MenuRadioItemEmits = MenuItemImplEmits;
 <script setup lang="ts">
 import { computed } from 'vue';
 
+import { compare } from '../../internal/utils/compare-values';
 import { provideMenuItemIndicatorContext, useMenuRadioGroupContext, useMenuRootContext } from './context';
 import MenuItemImpl from './MenuItemImpl.vue';
 import { ITEM_SELECT, getCheckedState } from './utils';
 
 const { value, ...itemProps } = defineProps<MenuRadioItemProps>();
 const emit = defineEmits<MenuRadioItemEmits>();
+defineSlots<{ default?: (props: { checked: boolean }) => unknown }>();
 
 const radioCtx = useMenuRadioGroupContext();
 const rootCtx = useMenuRootContext();
-const checkedState = computed(() => radioCtx.modelValue.value === value);
+const checkedState = computed(() => compare(radioCtx.modelValue.value, value));
 
 provideMenuItemIndicatorContext({ checkedState });
 
@@ -49,6 +53,6 @@ function handleSelect(event: Event) {
     :data-state="getCheckedState(checkedState)"
     @select="handleSelect"
   >
-    <slot />
+    <slot :checked="checkedState" />
   </MenuItemImpl>
 </template>
diff --git a/vue/primitives/src/menu/MenuRoot.vue b/vue/primitives/src/menus/menu/MenuRoot.vue
similarity index 90%
rename from vue/primitives/src/menu/MenuRoot.vue
rename to vue/primitives/src/menus/menu/MenuRoot.vue
index 39c6178..57d725c 100644
--- a/vue/primitives/src/menu/MenuRoot.vue
+++ b/vue/primitives/src/menus/menu/MenuRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { Direction } from '../config-provider';
+import type { Direction } from '../../utilities/config-provider';
 
 /**
  * The unstyled, low-level menu engine that powers DropdownMenu, ContextMenu, and
@@ -22,8 +22,8 @@ export interface MenuRootProps {
 <script setup lang="ts">
 import { shallowRef, toRef } from 'vue';
 
-import { useConfig } from '../config-provider';
-import { PopperRoot } from '../popper';
+import { useConfig } from '../../utilities/config-provider';
+import { PopperRoot } from '../../overlays/popper';
 import { provideMenuContext, provideMenuRootContext } from './context';
 import { useIsUsingKeyboard } from './useIsUsingKeyboard';
 
diff --git a/vue/primitives/src/menu/MenuRootContentModal.vue b/vue/primitives/src/menus/menu/MenuRootContentModal.vue
similarity index 92%
rename from vue/primitives/src/menu/MenuRootContentModal.vue
rename to vue/primitives/src/menus/menu/MenuRootContentModal.vue
index 5477a06..5e3d8f0 100644
--- a/vue/primitives/src/menu/MenuRootContentModal.vue
+++ b/vue/primitives/src/menus/menu/MenuRootContentModal.vue
@@ -7,7 +7,7 @@ import type { MenuContentImplEmits, MenuContentImplProps } from './MenuContentIm
 import { shallowRef, watchEffect } from 'vue';
 
 import { useBodyScrollLock, useFocusGuard } from '@robonen/vue';
-import { useHideOthers } from '../utils/useHideOthers';
+import { useHideOthers } from '../../internal/utils/useHideOthers';
 import MenuContentImpl from './MenuContentImpl.vue';
 import { useMenuContext } from './context';
 
@@ -33,7 +33,7 @@ useHideOthers(contentRef);
     @close-auto-focus="emit('closeAutoFocus', $event)"
     @escape-key-down="emit('escapeKeyDown', $event)"
     @pointer-down-outside="emit('pointerDownOutside', $event)"
-    @focus-outside="emit('focusOutside', $event)"
+    @focus-outside.prevent="emit('focusOutside', $event)"
     @interact-outside="emit('interactOutside', $event)"
     @dismiss="() => { menuCtx.onOpenChange(false); emit('dismiss') }"
     @entry-focus="emit('entryFocus', $event)"
diff --git a/vue/primitives/src/menu/MenuRootContentNonModal.vue b/vue/primitives/src/menus/menu/MenuRootContentNonModal.vue
similarity index 100%
rename from vue/primitives/src/menu/MenuRootContentNonModal.vue
rename to vue/primitives/src/menus/menu/MenuRootContentNonModal.vue
diff --git a/vue/primitives/src/menu/MenuSeparator.vue b/vue/primitives/src/menus/menu/MenuSeparator.vue
similarity index 80%
rename from vue/primitives/src/menu/MenuSeparator.vue
rename to vue/primitives/src/menus/menu/MenuSeparator.vue
index 3ebfe77..b92dd20 100644
--- a/vue/primitives/src/menu/MenuSeparator.vue
+++ b/vue/primitives/src/menus/menu/MenuSeparator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A visual and semantic divider (`role="separator"`) between groups of menu
@@ -9,7 +9,7 @@ export interface MenuSeparatorProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'div' } = defineProps<MenuSeparatorProps>();
 </script>
diff --git a/vue/primitives/src/menus/menu/MenuSub.vue b/vue/primitives/src/menus/menu/MenuSub.vue
new file mode 100644
index 0000000..66b07c3
--- /dev/null
+++ b/vue/primitives/src/menus/menu/MenuSub.vue
@@ -0,0 +1,74 @@
+<script lang="ts">
+/**
+ * Establishes a nested submenu. It provides a fresh menu context plus a sub
+ * context shared by its MenuSubTrigger and MenuSubContent, owning the submenu's
+ * open state. Bind `v-model:open` to control it, or leave it unbound to let the
+ * submenu manage its own open state (uncontrolled); the default slot also
+ * exposes the current `open` value.
+ */
+export interface MenuSubProps {
+  /** The controlled open state of the submenu. Use together with `update:open`. */
+  open?: boolean;
+}
+export interface MenuSubEmits {
+  'update:open': [value: boolean];
+}
+</script>
+
+<script setup lang="ts">
+import { shallowRef, watch } from 'vue';
+
+import { useId } from '../../utilities/config-provider';
+import { PopperRoot } from '../../overlays/popper';
+import { provideMenuContext, provideMenuSubContext, useMenuContext } from './context';
+
+defineProps<MenuSubProps>();
+defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
+
+// Controlled when `v-model:open` is bound; otherwise the local ref drives it.
+const local = shallowRef(false);
+// The model shares the declared prop name on purpose — controlled/uncontrolled
+// merge happens inside get/set — hence the dupe-keys exception.
+// eslint-disable-next-line vue/no-dupe-keys
+const open = defineModel<boolean>('open', {
+  get: external => external ?? local.value,
+  set: (value) => {
+    local.value = value;
+    return value;
+  },
+});
+
+const parentMenuCtx = useMenuContext();
+const trigger = shallowRef<HTMLElement | null>(null);
+// Real reactive content ref + working setter so the grace-area / positioning
+// logic that reads `menuCtx.content` works for submenus too.
+const content = shallowRef<HTMLElement | null>(null);
+const contentId = useId(undefined, 'menu-sub-content');
+const triggerId = useId(undefined, 'menu-sub-trigger');
+
+// A submenu must never outlive its parent: when the parent closes, close it
+// too, and always close on teardown so an orphaned submenu can't linger.
+watch(() => parentMenuCtx.open.value, (parentOpen) => {
+  if (!parentOpen) open.value = false;
+});
+
+provideMenuContext({
+  open,
+  onOpenChange: (v) => { open.value = v; },
+  content,
+  onContentChange: (el) => { content.value = el; },
+});
+
+provideMenuSubContext({
+  contentId,
+  triggerId,
+  trigger,
+  onTriggerChange: (el) => { trigger.value = el; },
+});
+</script>
+
+<template>
+  <PopperRoot>
+    <slot :open="open" />
+  </PopperRoot>
+</template>
diff --git a/vue/primitives/src/menu/MenuSubContent.vue b/vue/primitives/src/menus/menu/MenuSubContent.vue
similarity index 61%
rename from vue/primitives/src/menu/MenuSubContent.vue
rename to vue/primitives/src/menus/menu/MenuSubContent.vue
index f5b0ee2..5ba2651 100644
--- a/vue/primitives/src/menu/MenuSubContent.vue
+++ b/vue/primitives/src/menus/menu/MenuSubContent.vue
@@ -15,9 +15,12 @@ export type MenuSubContentEmits = MenuContentImplEmits;
 </script>
 
 <script setup lang="ts">
-import { Presence } from '../presence';
+import { shallowRef, watchEffect } from 'vue';
+
+import { Presence } from '../../utilities/presence';
 import { useMenuContext, useMenuRootContext, useMenuSubContext } from './context';
 import MenuContentImpl from './MenuContentImpl.vue';
+import { SUB_CLOSE_KEYS } from './utils';
 
 const { forceMount = false, ...contentProps } = defineProps<MenuSubContentProps>();
 const emit = defineEmits<MenuSubContentEmits>();
@@ -25,6 +28,30 @@ const emit = defineEmits<MenuSubContentEmits>();
 const menuCtx = useMenuContext();
 const subCtx = useMenuSubContext();
 const rootCtx = useMenuRootContext();
+
+// Track the sub-content element into this submenu's own MenuContext so the
+// grace-area logic can measure it. SubContent renders MenuContentImpl directly
+// (no modal/nonmodal wrapper), so we wire onContentChange here.
+const subContentEl = shallowRef<HTMLElement | null>(null);
+watchEffect(() => menuCtx.onContentChange(subContentEl.value));
+
+function handleKeyDown(event: KeyboardEvent) {
+  // Submenu key events bubble through portals; only act on keys from inside.
+  const isKeyDownInside = (event.currentTarget as HTMLElement)?.contains(event.target as Node);
+  const isCloseKey = SUB_CLOSE_KEYS[rootCtx.dir.value]?.includes(event.key);
+  if (isKeyDownInside && isCloseKey) {
+    menuCtx.onOpenChange(false);
+    // We prevented close-auto-focus, so return focus to the trigger manually.
+    subCtx.trigger.value?.focus();
+    event.preventDefault();
+  }
+}
+
+function handleOpenAutoFocus(event: Event) {
+  // When opening a submenu, focus its content for keyboard users only.
+  if (rootCtx.isUsingKeyboardRef.value) subContentEl.value?.focus();
+  emit('openAutoFocus', event);
+}
 </script>
 
 <template>
@@ -32,6 +59,7 @@ const rootCtx = useMenuRootContext();
     <MenuContentImpl
       :id="subCtx.contentId.value"
       v-bind="contentProps"
+      :ref="(comp: any) => { subContentEl = comp?.$el ?? null }"
       :aria-labelledby="subCtx.triggerId.value"
       :trap-focus="false"
       :disable-outside-pointer-events="false"
@@ -52,7 +80,8 @@ const rootCtx = useMenuRootContext();
       @interact-outside="emit('interactOutside', $event)"
       @dismiss="menuCtx.onOpenChange(false)"
       @entry-focus="emit('entryFocus', $event)"
-      @open-auto-focus="emit('openAutoFocus', $event)"
+      @open-auto-focus="handleOpenAutoFocus"
+      @keydown="handleKeyDown"
     >
       <slot />
     </MenuContentImpl>
diff --git a/vue/primitives/src/menu/MenuSubTrigger.vue b/vue/primitives/src/menus/menu/MenuSubTrigger.vue
similarity index 57%
rename from vue/primitives/src/menu/MenuSubTrigger.vue
rename to vue/primitives/src/menus/menu/MenuSubTrigger.vue
index d192bbf..5fc93de 100644
--- a/vue/primitives/src/menu/MenuSubTrigger.vue
+++ b/vue/primitives/src/menus/menu/MenuSubTrigger.vue
@@ -11,10 +11,13 @@ export interface MenuSubTriggerProps extends MenuItemImplProps {}
 </script>
 
 <script setup lang="ts">
-import { PopperAnchor } from '../popper';
-import { useMenuContentContext, useMenuContext, useMenuRootContext, useMenuSubContext } from './context';
+import { shallowRef } from 'vue';
+
+import { PopperAnchor } from '../../overlays/popper';
+import { useMenuContentContext, useMenuContext, useMenuItemSelectContext, useMenuRootContext, useMenuSubContext } from './context';
+import type { Side } from './utils';
 import MenuItemImpl from './MenuItemImpl.vue';
-import { SUB_CLOSE_KEYS, SUB_OPEN_KEYS, getOpenState } from './utils';
+import { SUB_CLOSE_KEYS, SUB_OPEN_KEYS, buildSubmenuGraceArea, getOpenState, isMousePointer } from './utils';
 
 const props = defineProps<MenuSubTriggerProps>();
 
@@ -22,6 +25,9 @@ const menuCtx = useMenuContext();
 const subCtx = useMenuSubContext();
 const rootCtx = useMenuRootContext();
 const contentCtx = useMenuContentContext();
+// Injected from the parent content (the sub-trigger lives inside it); falls
+// back to never-typing when used outside a content during isolated tests.
+const selectCtx = useMenuItemSelectContext({ isTypingAhead: shallowRef(false) });
 
 let openTimer: ReturnType<typeof setTimeout> | undefined;
 
@@ -36,24 +42,50 @@ function close() {
 }
 
 function handlePointerMove(event: PointerEvent) {
-  if (event.pointerType === 'touch') return;
+  if (!isMousePointer(event)) return;
   if (props.disabled) return;
   if (contentCtx.onItemEnter(event)) return;
-  if (!menuCtx.open.value) {
-    clearTimeout(openTimer);
-    openTimer = setTimeout(() => menuCtx.onOpenChange(true), 100);
+  if (!menuCtx.open.value && !openTimer) {
+    // Cancel any pending grace intent before scheduling this trigger's open.
+    contentCtx.onPointerGraceIntentChange(null);
+    openTimer = setTimeout(() => {
+      menuCtx.onOpenChange(true);
+      openTimer = undefined;
+    }, 100);
   }
 }
 
 function handlePointerLeave(event: PointerEvent) {
-  if (event.pointerType === 'touch') return;
+  if (!isMousePointer(event)) return;
   clearTimeout(openTimer);
-  if (contentCtx.onTriggerLeave(event)) return;
-  close();
+  openTimer = undefined;
+
+  const contentRect = menuCtx.content.value?.getBoundingClientRect();
+  if (contentRect?.width) {
+    const side = (menuCtx.content.value?.dataset['side'] as Side) ?? 'right';
+    // Register a safe diagonal triangle toward the open submenu so the cursor
+    // can travel to it without the submenu closing. Auto-expires after 300ms.
+    contentCtx.onPointerGraceIntentChange({
+      area: buildSubmenuGraceArea(event, contentRect, side),
+      side,
+    });
+    globalThis.clearTimeout(contentCtx.pointerGraceTimerRef.value);
+    contentCtx.pointerGraceTimerRef.value = globalThis.setTimeout(
+      () => contentCtx.onPointerGraceIntentChange(null),
+      300,
+    );
+  }
+  else {
+    if (contentCtx.onTriggerLeave(event)) return;
+    contentCtx.onPointerGraceIntentChange(null);
+    close();
+  }
 }
 
 function handleKeyDown(event: KeyboardEvent) {
   if (props.disabled) return;
+  // While typing ahead, Space extends the search instead of opening the submenu.
+  if (selectCtx.isTypingAhead.value && event.key === ' ') return;
   const openKeys = SUB_OPEN_KEYS[rootCtx.dir.value]!;
   const closeKeys = SUB_CLOSE_KEYS[rootCtx.dir.value]!;
   if (openKeys.includes(event.key)) {
diff --git a/vue/primitives/src/menus/menu/__test__/Menu.parity.test.ts b/vue/primitives/src/menus/menu/__test__/Menu.parity.test.ts
new file mode 100644
index 0000000..36b2355
--- /dev/null
+++ b/vue/primitives/src/menus/menu/__test__/Menu.parity.test.ts
@@ -0,0 +1,499 @@
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+
+import {
+  MenuAnchor,
+  MenuCheckboxItem,
+  MenuContent,
+  MenuGroup,
+  MenuItem,
+  MenuItemIndicator,
+  MenuLabel,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuRoot,
+  MenuSub,
+  MenuSubContent,
+  MenuSubTrigger,
+} from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  document.body.style.pointerEvents = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+// Writes back into a ref — keeps inline v-model handlers to a single statement.
+function setter<T>(r: { value: T }): (v: T) => void {
+  return (v: T) => {
+    r.value = v;
+  };
+}
+
+async function openMenu(open: { value: boolean }) {
+  open.value = true;
+  await nextTick();
+  await nextTick();
+}
+
+function content(): HTMLElement {
+  return document.querySelector<HTMLElement>('[role="menu"]')!;
+}
+
+function keydown(el: HTMLElement, key: string, init: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+}
+
+function usePointer() {
+  document.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }));
+}
+
+function useKeyboard() {
+  document.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true }));
+}
+
+describe('menu — Group / Label accessible name wiring', () => {
+  it('points group aria-labelledby at the nested label id', async () => {
+    const open = ref(false);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, {
+              default: () => h(MenuGroup, null, {
+                default: () => [
+                  h(MenuLabel, { class: 'lbl' }, { default: () => 'Section' }),
+                  h(MenuItem, null, { default: () => 'Alpha' }),
+                ],
+              }),
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await openMenu(open);
+
+    const group = document.querySelector<HTMLElement>('[role="group"]')!;
+    const label = document.querySelector<HTMLElement>('.lbl')!;
+    expect(group.getAttribute('aria-labelledby')).toBeTruthy();
+    expect(label.id).toBe(group.getAttribute('aria-labelledby'));
+  });
+});
+
+describe('menu — keyboard: Tab is trapped inside content', () => {
+  it('prevents default on Tab originating inside the content', async () => {
+    const open = ref(false);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, { default: () => h(MenuItem, null, { default: () => 'Alpha' }) }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await openMenu(open);
+
+    const event = new KeyboardEvent('keydown', { key: 'Tab', bubbles: true, cancelable: true });
+    content().dispatchEvent(event);
+    await nextTick();
+    expect(event.defaultPrevented).toBe(true);
+  });
+});
+
+describe('menu — keyboard: Space during typeahead does not select', () => {
+  function mountTypeahead() {
+    const open = ref(false);
+    const selected: Event[] = [];
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, {
+              default: () => [
+                h(MenuItem, { onSelect: (e: Event) => selected.push(e) }, { default: () => 'Alpha' }),
+                h(MenuItem, null, { default: () => 'Bravo' }),
+              ],
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    return { open, selected };
+  }
+
+  it('Space selects when not searching', async () => {
+    usePointer();
+    const { open, selected } = mountTypeahead();
+    await openMenu(open);
+    const item = document.querySelector<HTMLElement>('[role="menuitem"]')!;
+    item.focus();
+    keydown(item, ' ');
+    await nextTick();
+    expect(selected).toHaveLength(1);
+  });
+
+  it('Space is swallowed (no select) while a typeahead search is active', async () => {
+    usePointer();
+    const { open, selected } = mountTypeahead();
+    await openMenu(open);
+    // Begin a search by typing a character on the content.
+    keydown(content(), 'a');
+    await nextTick();
+    const item = document.querySelector<HTMLElement>('[role="menuitem"]')!;
+    item.focus();
+    keydown(item, ' ');
+    await nextTick();
+    expect(selected).toHaveLength(0);
+    expect(open.value).toBe(true);
+  });
+});
+
+describe('menu — MenuSub uncontrolled open + parent-close auto-dismiss', () => {
+  function mountSub() {
+    const open = ref(false);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, {
+              default: () => h(MenuSub, null, {
+                // No v-model:open bound -> uncontrolled.
+                default: () => [
+                  h(MenuSubTrigger, { class: 'sub-trigger' }, { default: () => 'More' }),
+                  h(MenuSubContent, null, { default: () => h(MenuItem, null, { default: () => 'Nested' }) }),
+                ],
+              }),
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    return { open };
+  }
+
+  it('opens the submenu without an external v-model (uncontrolled)', async () => {
+    const { open } = mountSub();
+    await openMenu(open);
+    const trigger = document.querySelector<HTMLElement>('.sub-trigger')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(trigger.getAttribute('data-state')).toBe('open');
+    expect(document.querySelectorAll('[role="menu"]').length).toBe(2);
+  });
+
+  it('closes the submenu when the parent menu closes', async () => {
+    const { open } = mountSub();
+    await openMenu(open);
+    const trigger = document.querySelector<HTMLElement>('.sub-trigger')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(document.querySelectorAll('[role="menu"]').length).toBe(2);
+
+    open.value = false;
+    await nextTick();
+    await nextTick();
+    // Both the parent and the orphaned submenu are gone.
+    expect(document.querySelectorAll('[role="menu"]').length).toBe(0);
+  });
+
+  it('reopening the parent does not reopen a previously open submenu', async () => {
+    const { open } = mountSub();
+    await openMenu(open);
+    const trigger = document.querySelector<HTMLElement>('.sub-trigger')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(document.querySelectorAll('[role="menu"]').length).toBe(2);
+
+    open.value = false;
+    await nextTick();
+    await nextTick();
+    await openMenu(open);
+    // Only the parent reopens.
+    expect(document.querySelectorAll('[role="menu"]').length).toBe(1);
+  });
+});
+
+describe('menu — submenu close key returns focus to the trigger', () => {
+  function mountSub(dir?: 'ltr' | 'rtl') {
+    const open = ref(false);
+    const subOpen = ref(false);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open), dir }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, {
+              default: () => h(MenuSub, { open: subOpen.value, 'onUpdate:open': setter(subOpen) }, {
+                default: () => [
+                  h(MenuSubTrigger, { class: 'sub-trigger' }, { default: () => 'More' }),
+                  h(MenuSubContent, null, { default: () => h(MenuItem, null, { default: () => 'Nested' }) }),
+                ],
+              }),
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    return { open, subOpen };
+  }
+
+  it('ArrowLeft inside an open submenu closes it and refocuses the trigger (ltr)', async () => {
+    useKeyboard();
+    const { open, subOpen } = mountSub('ltr');
+    await openMenu(open);
+    const trigger = document.querySelector<HTMLElement>('.sub-trigger')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(subOpen.value).toBe(true);
+
+    const subContent = document.querySelectorAll<HTMLElement>('[role="menu"]')[1]!;
+    keydown(subContent, 'ArrowLeft');
+    await nextTick();
+    await nextTick();
+
+    expect(subOpen.value).toBe(false);
+    expect(document.activeElement).toBe(trigger);
+  });
+});
+
+describe('menu — submenu pointer grace area', () => {
+  function mountSub() {
+    const open = ref(false);
+    const subOpen = ref(false);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, { style: 'width:200px' }, {
+              default: () => [
+                h(MenuSub, { open: subOpen.value, 'onUpdate:open': setter(subOpen) }, {
+                  default: () => [
+                    h(MenuSubTrigger, { class: 'sub-trigger' }, { default: () => 'More' }),
+                    h(MenuSubContent, { style: 'width:150px;height:80px' }, {
+                      default: () => h(MenuItem, null, { default: () => 'Nested' }),
+                    }),
+                  ],
+                }),
+                h(MenuItem, { class: 'sibling' }, { default: () => 'Sibling' }),
+              ],
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    return { open, subOpen };
+  }
+
+  function pointerMove(el: HTMLElement, x: number, y: number) {
+    el.dispatchEvent(new PointerEvent('pointermove', { bubbles: true, pointerType: 'mouse', clientX: x, clientY: y }));
+  }
+
+  it('keeps focus from being stolen by a sibling while the pointer travels toward the open submenu', async () => {
+    const { open, subOpen } = mountSub();
+    await openMenu(open);
+
+    const trigger = document.querySelector<HTMLElement>('.sub-trigger')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(subOpen.value).toBe(true);
+
+    const subContent = document.querySelectorAll<HTMLElement>('[role="menu"]')[1]!;
+    const subRect = subContent.getBoundingClientRect();
+    const parentContent = content();
+    const triggerRect = trigger.getBoundingClientRect();
+
+    // Establish rightward pointer direction on the parent content.
+    pointerMove(parentContent, triggerRect.left + 1, triggerRect.top + 5);
+    pointerMove(parentContent, triggerRect.left + 10, triggerRect.top + 5);
+
+    // Leave the trigger heading toward the submenu -> registers a grace area.
+    trigger.dispatchEvent(new PointerEvent('pointerleave', {
+      bubbles: true,
+      pointerType: 'mouse',
+      clientX: triggerRect.right,
+      clientY: triggerRect.top + 5,
+    }));
+    await nextTick();
+
+    // A pointermove over the sibling, but inside the grace triangle (between
+    // the trigger and the submenu, moving right), must NOT focus the sibling.
+    const sibling = document.querySelector<HTMLElement>('.sibling')!;
+    const insideGraceX = (triggerRect.right + subRect.left) / 2;
+    const insideGraceY = subRect.top + 2;
+    sibling.dispatchEvent(new PointerEvent('pointermove', {
+      bubbles: true,
+      pointerType: 'mouse',
+      clientX: insideGraceX,
+      clientY: insideGraceY,
+    }));
+    await nextTick();
+
+    // The grace area suppressed the sibling's focus steal mid-transit.
+    expect(document.activeElement).not.toBe(sibling);
+  });
+
+  it('focuses a sibling normally when moving away from the submenu (no grace match)', async () => {
+    const { open, subOpen } = mountSub();
+    await openMenu(open);
+
+    const trigger = document.querySelector<HTMLElement>('.sub-trigger')!;
+    trigger.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(subOpen.value).toBe(true);
+
+    const parentContent = content();
+    const triggerRect = trigger.getBoundingClientRect();
+
+    // Establish *leftward* pointer direction (away from the right-side submenu).
+    pointerMove(parentContent, triggerRect.left + 20, triggerRect.top + 5);
+    pointerMove(parentContent, triggerRect.left + 5, triggerRect.top + 5);
+
+    // No grace intent registered yet; a sibling pointermove should focus it.
+    const sibling = document.querySelector<HTMLElement>('.sibling')!;
+    const sibRect = sibling.getBoundingClientRect();
+    sibling.dispatchEvent(new PointerEvent('pointermove', {
+      bubbles: true,
+      pointerType: 'mouse',
+      clientX: sibRect.left + 2,
+      clientY: sibRect.top + 2,
+    }));
+    await nextTick();
+
+    expect(document.activeElement).toBe(sibling);
+  });
+});
+
+describe('menu — checkbox / radio expose checked state via slot', () => {
+  it('MenuCheckboxItem default slot receives the checked state', async () => {
+    const open = ref(false);
+    const seen: unknown[] = [];
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, {
+              default: () => h(MenuCheckboxItem, { checked: true }, {
+                default: (slotProps: { checked: unknown }) => {
+                  seen.push(slotProps.checked);
+                  return 'Toggle';
+                },
+              }),
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await openMenu(open);
+    expect(seen).toContain(true);
+  });
+
+  it('MenuRadioItem default slot receives whether it is checked', async () => {
+    const open = ref(false);
+    const seen: boolean[] = [];
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, {
+              default: () => h(MenuRadioGroup, { modelValue: 'a' }, {
+                default: () => [
+                  h(MenuRadioItem, { value: 'a' }, {
+                    default: (slotProps: { checked: boolean }) => {
+                      seen.push(slotProps.checked);
+                      return 'A';
+                    },
+                  }),
+                  h(MenuRadioItem, { value: 'b' }, {
+                    default: (slotProps: { checked: boolean }) => {
+                      seen.push(slotProps.checked);
+                      return 'B';
+                    },
+                  }),
+                ],
+              }),
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await openMenu(open);
+    expect(seen).toContain(true);
+    expect(seen).toContain(false);
+  });
+});
+
+describe('menu — radio group accepts non-string values and renders through a group', () => {
+  it('selects by numeric value and exposes role=group with a labelledby hook', async () => {
+    const open = ref(false);
+    const model = ref<number | undefined>(undefined);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(MenuRoot, { open: open.value, 'onUpdate:open': setter(open) }, {
+          default: () => [
+            h(MenuAnchor, null, { default: () => h('button', 'Anchor') }),
+            h(MenuContent, null, {
+              default: () => h(MenuRadioGroup, {
+                modelValue: model.value,
+                'onUpdate:modelValue': setter(model),
+              }, {
+                default: () => [
+                  h(MenuLabel, null, { default: () => 'Pick' }),
+                  h(MenuRadioItem, { value: 1, class: 'r1', onSelect: (e: Event) => e.preventDefault() }, {
+                    default: () => h(MenuItemIndicator, { class: 'ind' }, { default: () => '•' }),
+                  }),
+                  h(MenuRadioItem, { value: 2, class: 'r2' }, { default: () => 'Two' }),
+                ],
+              }),
+            }),
+          ],
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await openMenu(open);
+
+    const group = document.querySelector<HTMLElement>('[role="group"]')!;
+    expect(group).toBeTruthy();
+    expect(group.getAttribute('aria-labelledby')).toBeTruthy();
+
+    const r1 = document.querySelector<HTMLElement>('[role="menuitemradio"].r1')!;
+    expect(r1).toBeTruthy();
+    r1.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    await nextTick();
+    expect(model.value).toBe(1);
+    expect(r1.getAttribute('aria-checked')).toBe('true');
+  });
+});
diff --git a/vue/primitives/src/menu/__test__/Menu.test.ts b/vue/primitives/src/menus/menu/__test__/Menu.test.ts
similarity index 100%
rename from vue/primitives/src/menu/__test__/Menu.test.ts
rename to vue/primitives/src/menus/menu/__test__/Menu.test.ts
diff --git a/vue/primitives/src/menu/context.ts b/vue/primitives/src/menus/menu/context.ts
similarity index 80%
rename from vue/primitives/src/menu/context.ts
rename to vue/primitives/src/menus/menu/context.ts
index aebb2f1..0d698f8 100644
--- a/vue/primitives/src/menu/context.ts
+++ b/vue/primitives/src/menus/menu/context.ts
@@ -1,6 +1,7 @@
 import type { CheckedState } from './types';
+import type { AcceptableValue } from './utils';
 import type { ComputedRef, Ref, ShallowRef } from 'vue';
-import type { Direction } from '../config-provider';
+import type { Direction } from '../../utilities/config-provider';
 
 import { useContextFactory } from '@robonen/vue';
 
@@ -30,6 +31,13 @@ export interface MenuContentContext {
   pointerGraceTimerRef: Ref<number>;
   onPointerGraceIntentChange: (intent: { area: Array<{ x: number; y: number }>; side: 'left' | 'right' } | null) => void;
 }
+
+export interface MenuItemSelectContext {
+  /** Whether typeahead search is currently active — used to block Space from selecting mid-search. */
+  isTypingAhead: Ref<boolean>;
+}
+export const { inject: useMenuItemSelectContext, provide: provideMenuItemSelectContext }
+  = useContextFactory<MenuItemSelectContext>('MenuItemSelectContext');
 export const { inject: useMenuContentContext, provide: provideMenuContentContext }
   = useContextFactory<MenuContentContext>('MenuContentContext');
 
@@ -43,8 +51,8 @@ export const { inject: useMenuSubContext, provide: provideMenuSubContext }
   = useContextFactory<MenuSubContext>('MenuSubContext');
 
 export interface MenuRadioGroupContext {
-  modelValue: Ref<string | undefined>;
-  onValueChange: (value: string) => void;
+  modelValue: Ref<AcceptableValue | undefined>;
+  onValueChange: (value: AcceptableValue) => void;
 }
 export const { inject: useMenuRadioGroupContext, provide: provideMenuRadioGroupContext }
   = useContextFactory<MenuRadioGroupContext>('MenuRadioGroupContext');
diff --git a/vue/primitives/src/menu/index.ts b/vue/primitives/src/menus/menu/index.ts
similarity index 90%
rename from vue/primitives/src/menu/index.ts
rename to vue/primitives/src/menus/menu/index.ts
index e8b3a78..af314bd 100644
--- a/vue/primitives/src/menu/index.ts
+++ b/vue/primitives/src/menus/menu/index.ts
@@ -1,6 +1,7 @@
 export type { CheckedState } from './types';
+export type { AcceptableValue } from './utils';
 
-export { useMenuContext, useMenuContentContext, useMenuRootContext, useMenuSubContext } from './context';
+export { useMenuContext, useMenuContentContext, useMenuItemSelectContext, useMenuRootContext, useMenuSubContext } from './context';
 export { default as MenuAnchor, type MenuAnchorProps } from './MenuAnchor.vue';
 export { default as MenuArrow, type MenuArrowProps } from './MenuArrow.vue';
 export { default as MenuCheckboxItem, type MenuCheckboxItemEmits, type MenuCheckboxItemProps } from './MenuCheckboxItem.vue';
diff --git a/vue/primitives/src/menu/types.ts b/vue/primitives/src/menus/menu/types.ts
similarity index 100%
rename from vue/primitives/src/menu/types.ts
rename to vue/primitives/src/menus/menu/types.ts
diff --git a/vue/primitives/src/menu/useIsUsingKeyboard.ts b/vue/primitives/src/menus/menu/useIsUsingKeyboard.ts
similarity index 100%
rename from vue/primitives/src/menu/useIsUsingKeyboard.ts
rename to vue/primitives/src/menus/menu/useIsUsingKeyboard.ts
diff --git a/vue/primitives/src/menu/utils.ts b/vue/primitives/src/menus/menu/utils.ts
similarity index 62%
rename from vue/primitives/src/menu/utils.ts
rename to vue/primitives/src/menus/menu/utils.ts
index 1b06501..edd6cfc 100644
--- a/vue/primitives/src/menu/utils.ts
+++ b/vue/primitives/src/menus/menu/utils.ts
@@ -1,6 +1,10 @@
 import type { CheckedState } from './types';
 
 import { getActiveElement } from '@robonen/platform/browsers';
+import { isPointInPolygon } from '../../internal/utils/geometry';
+
+/** Any serialisable value a radio item can carry (not just strings). */
+export type AcceptableValue = string | number | boolean | Record<string, unknown>;
 
 export const ITEM_SELECT = 'menu.itemSelect';
 export const SELECTION_KEYS = ['Enter', ' '];
@@ -63,24 +67,40 @@ export type Polygon = Point[];
 export type Side = 'left' | 'right';
 export interface GraceIntent { area: Polygon; side: Side }
 
-export function isPointInPolygon(point: Point, polygon: Polygon): boolean {
-  const { x, y } = point;
-  let inside = false;
-  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
-    const xi = polygon[i]!.x;
-    const yi = polygon[i]!.y;
-    const xj = polygon[j]!.x;
-    const yj = polygon[j]!.y;
-    const intersects = (yi > y) !== (yj > y) && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
-    if (intersects) inside = !inside;
-  }
-  return inside;
-}
-
-export function isPointerInGraceArea(event: PointerEvent, area: Polygon): boolean {
+export function isPointerInGraceArea(event: PointerEvent, area?: Polygon | null): boolean {
+  if (!area) return false;
   return isPointInPolygon({ x: event.clientX, y: event.clientY }, area);
 }
 
 export function isMouseEvent(event: Event): event is MouseEvent {
   return ['mousedown', 'mouseup', 'mousemove', 'click'].includes(event.type);
 }
+
+/**
+ * Whether a pointer event came from a real mouse (not pen / touch). Hover-only
+ * menu behaviour (open-on-hover, highlight-on-move, grace area) must ignore pen
+ * and touch so taps don't trigger hover semantics.
+ */
+export function isMousePointer(event: PointerEvent): boolean {
+  return event.pointerType === 'mouse';
+}
+
+/**
+ * Builds the 5-point "grace area" polygon that lets the pointer travel
+ * diagonally from a sub-trigger toward its already-open submenu without the
+ * submenu closing. The polygon spans from the pointer exit point to the two
+ * vertical edges of the submenu content on the side it opened to.
+ */
+export function buildSubmenuGraceArea(event: PointerEvent, contentRect: DOMRect, side: Side): Polygon {
+  const rightSide = side === 'right';
+  const bleed = rightSide ? -5 : 5;
+  const contentNearEdge = contentRect[rightSide ? 'left' : 'right'];
+  const contentFarEdge = contentRect[rightSide ? 'right' : 'left'];
+  return [
+    { x: event.clientX + bleed, y: event.clientY },
+    { x: contentNearEdge, y: contentRect.top },
+    { x: contentFarEdge, y: contentRect.top },
+    { x: contentFarEdge, y: contentRect.bottom },
+    { x: contentNearEdge, y: contentRect.bottom },
+  ];
+}
diff --git a/vue/primitives/src/menubar/MenubarArrow.vue b/vue/primitives/src/menus/menubar/MenubarArrow.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarArrow.vue
rename to vue/primitives/src/menus/menubar/MenubarArrow.vue
diff --git a/vue/primitives/src/menubar/MenubarCheckboxItem.vue b/vue/primitives/src/menus/menubar/MenubarCheckboxItem.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarCheckboxItem.vue
rename to vue/primitives/src/menus/menubar/MenubarCheckboxItem.vue
diff --git a/vue/primitives/src/menus/menubar/MenubarContent.vue b/vue/primitives/src/menus/menubar/MenubarContent.vue
new file mode 100644
index 0000000..08acbd8
--- /dev/null
+++ b/vue/primitives/src/menus/menubar/MenubarContent.vue
@@ -0,0 +1,103 @@
+<script lang="ts">
+import type { MenuContentEmits, MenuContentProps } from '../menu';
+
+/**
+ * The floating surface that holds a menu's items, positioned below its
+ * MenubarTrigger. Handles focus management, typeahead, and dismissal on outside
+ * click or Escape; render it inside a MenubarPortal so it escapes overflow
+ * clipping.
+ *
+ * While open and focused, ArrowLeft / ArrowRight switch to the adjacent menubar
+ * menu (RTL-aware, loop-aware) — the core APG menubar interaction.
+ */
+export interface MenubarContentProps extends MenuContentProps {}
+export type MenubarContentEmits = MenuContentEmits;
+</script>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+
+import { MenuContent } from '../menu';
+import { SUBTRIGGER_ATTR, useMenubarMenuContext, useMenubarRootContext } from './context';
+
+const { align = 'start', ...props } = defineProps<MenubarContentProps>();
+const emit = defineEmits<MenubarContentEmits>();
+
+const rootCtx = useMenubarRootContext();
+const menuCtx = useMenubarMenuContext();
+
+// Set on @interact-outside so closeAutoFocus knows the user moved focus/clicked
+// outside the menu — in that case focus must stay where they put it instead of
+// snapping back to the trigger.
+const hasInteractedOutside = ref(false);
+
+const contentStyle = computed(() => ({
+  '--primitives-menubar-content-transform-origin': 'var(--popper-transform-origin)',
+  '--primitives-menubar-content-available-width': 'var(--popper-available-width)',
+  '--primitives-menubar-content-available-height': 'var(--popper-available-height)',
+  '--primitives-menubar-trigger-width': 'var(--popper-anchor-width)',
+  '--primitives-menubar-trigger-height': 'var(--popper-anchor-height)',
+}));
+
+// Switch to the adjacent menubar menu. Mirrors the trigger-level arrow nav but
+// fires while focus is inside the open content (APG menubar pattern).
+function handleArrowNavigation(event: KeyboardEvent) {
+  const target = event.target as HTMLElement;
+  // Opening a submenu uses the same arrow key as "next menu"; don't hijack it.
+  const targetIsSubTrigger = !!target.closest(`[${SUBTRIGGER_ATTR}]`);
+
+  const prevMenuKey = rootCtx.dir.value === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+  const isPrevKey = event.key === prevMenuKey;
+  if (!isPrevKey && targetIsSubTrigger) return;
+
+  const values = rootCtx.getTriggers().map(i => i.value).filter((v): v is string => v !== undefined);
+  if (values.length === 0) return;
+  if (isPrevKey) values.reverse();
+
+  const currentIndex = values.indexOf(menuCtx.value);
+  const len = values.length;
+  const startIndex = currentIndex + 1;
+  const next = rootCtx.loop.value
+    ? values[startIndex % len]
+    : (startIndex < len ? values[startIndex] : undefined);
+
+  if (next) rootCtx.onMenuOpen(next);
+}
+</script>
+
+<template>
+  <MenuContent
+    :id="menuCtx.contentId.value"
+    v-bind="props"
+    :align="align"
+    :aria-labelledby="menuCtx.triggerId.value"
+    :style="contentStyle"
+    @keydown.arrow-right.arrow-left="handleArrowNavigation"
+    @close-auto-focus="(event: Event) => {
+      if (!menuCtx.wasKeyboardTriggerOpenRef.value) event.preventDefault()
+      menuCtx.wasKeyboardTriggerOpenRef.value = false
+      // Refocus the trigger on close, but NOT when the user moved focus/clicked
+      // outside the menu (e.g. into an input) — leave focus where they put it.
+      if (!hasInteractedOutside) menuCtx.triggerRef.value?.focus({ preventScroll: true })
+      hasInteractedOutside = false
+      emit('closeAutoFocus', event)
+    }"
+    @escape-key-down="emit('escapeKeyDown', $event)"
+    @pointer-down-outside="(event: PointerEvent | MouseEvent) => {
+      const target = event.target as Node
+      const isMenubarTrigger = menuCtx.triggerRef.value?.contains(target)
+      if (isMenubarTrigger) event.preventDefault()
+      emit('pointerDownOutside', event)
+    }"
+    @focus-outside="emit('focusOutside', $event)"
+    @interact-outside="(event: PointerEvent | MouseEvent | FocusEvent) => {
+      hasInteractedOutside = true
+      emit('interactOutside', event)
+    }"
+    @dismiss="rootCtx.onMenuClose(menuCtx.value)"
+    @entry-focus="emit('entryFocus', $event)"
+    @open-auto-focus="emit('openAutoFocus', $event)"
+  >
+    <slot />
+  </MenuContent>
+</template>
diff --git a/vue/primitives/src/menubar/MenubarGroup.vue b/vue/primitives/src/menus/menubar/MenubarGroup.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarGroup.vue
rename to vue/primitives/src/menus/menubar/MenubarGroup.vue
diff --git a/vue/primitives/src/menubar/MenubarItem.vue b/vue/primitives/src/menus/menubar/MenubarItem.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarItem.vue
rename to vue/primitives/src/menus/menubar/MenubarItem.vue
diff --git a/vue/primitives/src/menubar/MenubarItemIndicator.vue b/vue/primitives/src/menus/menubar/MenubarItemIndicator.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarItemIndicator.vue
rename to vue/primitives/src/menus/menubar/MenubarItemIndicator.vue
diff --git a/vue/primitives/src/menubar/MenubarLabel.vue b/vue/primitives/src/menus/menubar/MenubarLabel.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarLabel.vue
rename to vue/primitives/src/menus/menubar/MenubarLabel.vue
diff --git a/vue/primitives/src/menubar/MenubarMenu.vue b/vue/primitives/src/menus/menubar/MenubarMenu.vue
similarity index 84%
rename from vue/primitives/src/menubar/MenubarMenu.vue
rename to vue/primitives/src/menus/menubar/MenubarMenu.vue
index cd9b043..5c485d1 100644
--- a/vue/primitives/src/menubar/MenubarMenu.vue
+++ b/vue/primitives/src/menus/menubar/MenubarMenu.vue
@@ -12,7 +12,7 @@ export interface MenubarMenuProps {
 <script setup lang="ts">
 import { computed, ref, shallowRef } from 'vue';
 
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 import { MenuRoot } from '../menu';
 import { provideMenubarMenuContext, useMenubarRootContext } from './context';
 
@@ -47,7 +47,9 @@ provideMenubarMenuContext({
     :dir="rootCtx.dir.value"
     :modal="false"
     @update:open="(v) => {
-      if (!v) rootCtx.onMenuClose()
+      // Pass our own value so a stale menu dismissing during a menu-switch can't
+      // clobber the sibling that just opened (only the active menu may close).
+      if (!v) rootCtx.onMenuClose(menuValue)
     }"
   >
     <slot :open="open" />
diff --git a/vue/primitives/src/menubar/MenubarPortal.vue b/vue/primitives/src/menus/menubar/MenubarPortal.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarPortal.vue
rename to vue/primitives/src/menus/menubar/MenubarPortal.vue
diff --git a/vue/primitives/src/menubar/MenubarRadioGroup.vue b/vue/primitives/src/menus/menubar/MenubarRadioGroup.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarRadioGroup.vue
rename to vue/primitives/src/menus/menubar/MenubarRadioGroup.vue
diff --git a/vue/primitives/src/menubar/MenubarRadioItem.vue b/vue/primitives/src/menus/menubar/MenubarRadioItem.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarRadioItem.vue
rename to vue/primitives/src/menus/menubar/MenubarRadioItem.vue
diff --git a/vue/primitives/src/menubar/MenubarRoot.vue b/vue/primitives/src/menus/menubar/MenubarRoot.vue
similarity index 55%
rename from vue/primitives/src/menubar/MenubarRoot.vue
rename to vue/primitives/src/menus/menubar/MenubarRoot.vue
index e868ec8..cb35f68 100644
--- a/vue/primitives/src/menubar/MenubarRoot.vue
+++ b/vue/primitives/src/menus/menubar/MenubarRoot.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
-import type { Direction } from '../config-provider';
-import type { PrimitiveProps } from '../primitive';
+import type { Direction } from '../../utilities/config-provider';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A horizontal bar of menus, like the File / Edit / View row in a desktop app.
@@ -21,13 +21,13 @@ export interface MenubarRootProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { onScopeDispose, ref, toRef } from 'vue';
+import { ref, toRef } from 'vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { provideMenubarRootContext } from './context';
-import { useCollectionProvider } from '../collection';
-import { useConfig } from '../config-provider';
-import { useForwardExpose } from '@robonen/vue';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useConfig } from '../../utilities/config-provider';
+import { refAutoReset, useForwardExpose } from '@robonen/vue';
 
 const {
   defaultValue,
@@ -36,6 +36,8 @@ const {
   as = 'div',
 } = defineProps<MenubarRootProps>();
 
+defineSlots<{ default?: (props: { modelValue: string | undefined }) => unknown }>();
+
 const localValue = ref<string | undefined>(defaultValue);
 
 const value = defineModel<string | undefined>('modelValue', {
@@ -53,31 +55,41 @@ const { forwardRef } = useForwardExpose();
 
 const { getItems, CollectionSlot } = useCollectionProvider<string>();
 
-const searchRef = ref('');
-let searchTimer: ReturnType<typeof setTimeout> | undefined;
+// Roving tabindex: exactly one trigger is the menubar's tab stop. Seeded to the
+// open menu's value (so reopening keeps the same stop) and updated on every
+// open/toggle, mirroring how a roving-focus group tracks its current item.
+const currentTabStopId = ref<string | undefined>(defaultValue);
 
-function clearSearch() {
-  clearTimeout(searchTimer);
-  searchRef.value = '';
-}
-
-onScopeDispose(clearSearch);
-
-// Reset the typeahead buffer once after every keystroke (1s idle window).
-function bumpSearchIdleTimer() {
-  clearTimeout(searchTimer);
-  searchTimer = setTimeout(clearSearch, 1000);
-}
+// Typeahead buffer that auto-clears 1s after the last keystroke — each write
+// restarts the idle timer (and it tears down on scope dispose). Mirrors the
+// Select trigger's typeahead.
+const searchRef = refAutoReset('', 1000);
 
 provideMenubarRootContext({
   value,
   dir: dirRef,
   loop: toRef(() => loop),
-  onMenuOpen: (v) => { value.value = v; },
-  onMenuClose: () => { value.value = undefined; },
-  onMenuToggle: (v) => { value.value = value.value === v ? undefined : v; },
+  onMenuOpen: (v) => {
+    value.value = v;
+    currentTabStopId.value = v;
+  },
+  onMenuClose: (v) => {
+    // Ignore a close request from a menu that is no longer the open one — this
+    // happens when switching menus and the outgoing content fires a late
+    // dismiss after the incoming menu has already been opened.
+    if (v !== undefined && value.value !== v) return;
+    value.value = undefined;
+  },
+  onMenuToggle: (v) => {
+    value.value = value.value === v ? undefined : v;
+    // `onMenuOpen` and `onMenuToggle` are mutually exclusive, so the tab stop is
+    // updated here too — toggling moves the single tab stop onto this trigger.
+    currentTabStopId.value = v;
+  },
   getTriggers: (includeDisabled = false) => getItems(includeDisabled),
   searchRef,
+  currentTabStopId,
+  onTabStopChange: (v) => { currentTabStopId.value = v; },
 });
 
 function onKeyDownCapture(event: KeyboardEvent) {
@@ -87,7 +99,6 @@ function onKeyDownCapture(event: KeyboardEvent) {
   if (event.ctrlKey || event.altKey || event.metaKey) return;
   if (event.key.length !== 1) return;
   searchRef.value += event.key;
-  bumpSearchIdleTimer();
 }
 </script>
 
@@ -102,7 +113,7 @@ function onKeyDownCapture(event: KeyboardEvent) {
       :dir="dirRef"
       @keydown.capture="onKeyDownCapture"
     >
-      <slot />
+      <slot :model-value="value" />
     </Primitive>
   </CollectionSlot>
 </template>
diff --git a/vue/primitives/src/menubar/MenubarSeparator.vue b/vue/primitives/src/menus/menubar/MenubarSeparator.vue
similarity index 100%
rename from vue/primitives/src/menubar/MenubarSeparator.vue
rename to vue/primitives/src/menus/menubar/MenubarSeparator.vue
diff --git a/vue/primitives/src/menus/menubar/MenubarSub.vue b/vue/primitives/src/menus/menubar/MenubarSub.vue
new file mode 100644
index 0000000..ab303fa
--- /dev/null
+++ b/vue/primitives/src/menus/menubar/MenubarSub.vue
@@ -0,0 +1,44 @@
+<script lang="ts">
+import type { MenuSubEmits, MenuSubProps } from '../menu';
+
+/**
+ * Wraps a nested submenu, pairing a MenubarSubTrigger with its
+ * MenubarSubContent. Owns the submenu's open state: bind `v-model:open` to
+ * control it, set `defaultOpen` to start open in uncontrolled mode, or leave
+ * both unset to let it manage its own open state. The default slot exposes the
+ * current `open` value.
+ */
+export interface MenubarSubProps extends MenuSubProps {
+  /** Open state when initially rendered. Use when you do not control `open`. */
+  defaultOpen?: boolean;
+}
+export type MenubarSubEmits = MenuSubEmits;
+</script>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+
+import { MenuSub } from '../menu';
+
+const { defaultOpen = false } = defineProps<MenubarSubProps>();
+defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
+
+const localOpen = ref<boolean>(defaultOpen);
+
+const open = defineModel<boolean>('open', {
+  default: undefined,
+  // Controlled when `v-model:open` is bound; otherwise the local ref (seeded
+  // from `defaultOpen`) drives it — uncontrolled mode with an initial state.
+  get: external => external ?? localOpen.value,
+  set: (value) => {
+    localOpen.value = value;
+    return value;
+  },
+});
+</script>
+
+<template>
+  <MenuSub :open="open" @update:open="open = $event">
+    <slot :open="open" />
+  </MenuSub>
+</template>
diff --git a/vue/primitives/src/menus/menubar/MenubarSubContent.vue b/vue/primitives/src/menus/menubar/MenubarSubContent.vue
new file mode 100644
index 0000000..f20844d
--- /dev/null
+++ b/vue/primitives/src/menus/menubar/MenubarSubContent.vue
@@ -0,0 +1,69 @@
+<script lang="ts">
+import type { MenuSubContentEmits, MenuSubContentProps } from '../menu';
+
+/**
+ * The floating surface for a submenu's items, positioned alongside its
+ * MenubarSubTrigger. Place it inside a MenubarSub.
+ *
+ * While open, ArrowRight (the "next menu" key, RTL-aware) switches to the
+ * adjacent menubar menu, matching the top-level content behaviour.
+ */
+export interface MenubarSubContentProps extends MenuSubContentProps {}
+export type MenubarSubContentEmits = MenuSubContentEmits;
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+
+import { MenuSubContent } from '../menu';
+import { SUBTRIGGER_ATTR, useMenubarMenuContext, useMenubarRootContext } from './context';
+
+const props = defineProps<MenubarSubContentProps>();
+const emit = defineEmits<MenubarSubContentEmits>();
+
+const rootCtx = useMenubarRootContext();
+const menuCtx = useMenubarMenuContext();
+
+const contentStyle = computed(() => ({
+  '--primitives-menubar-content-transform-origin': 'var(--popper-transform-origin)',
+  '--primitives-menubar-content-available-width': 'var(--popper-available-width)',
+  '--primitives-menubar-content-available-height': 'var(--popper-available-height)',
+  '--primitives-menubar-trigger-width': 'var(--popper-anchor-width)',
+  '--primitives-menubar-trigger-height': 'var(--popper-anchor-height)',
+}));
+
+// Inside a submenu, the "next menu" key (ArrowRight in LTR) jumps to the next
+// menubar menu — unless it is a deeper sub-trigger opening its own submenu.
+function handleArrowNavigation(event: KeyboardEvent) {
+  const target = event.target as HTMLElement;
+  if (target.closest(`[${SUBTRIGGER_ATTR}]`)) return;
+
+  const values = rootCtx.getTriggers().map(i => i.value).filter((v): v is string => v !== undefined);
+  if (values.length === 0) return;
+
+  const currentIndex = values.indexOf(menuCtx.value);
+  const len = values.length;
+  const startIndex = currentIndex + 1;
+  const next = rootCtx.loop.value
+    ? values[startIndex % len]
+    : (startIndex < len ? values[startIndex] : undefined);
+
+  if (next) rootCtx.onMenuOpen(next);
+}
+</script>
+
+<template>
+  <MenuSubContent
+    v-bind="props"
+    :style="contentStyle"
+    @keydown.arrow-right="handleArrowNavigation"
+    @close-auto-focus="emit('closeAutoFocus', $event)"
+    @escape-key-down="emit('escapeKeyDown', $event)"
+    @pointer-down-outside="emit('pointerDownOutside', $event)"
+    @focus-outside="emit('focusOutside', $event)"
+    @interact-outside="emit('interactOutside', $event)"
+    @dismiss="emit('dismiss')"
+    @entry-focus="emit('entryFocus', $event)"
+    @open-auto-focus="emit('openAutoFocus', $event)"
+  ><slot /></MenuSubContent>
+</template>
diff --git a/vue/primitives/src/menubar/MenubarSubTrigger.vue b/vue/primitives/src/menus/menubar/MenubarSubTrigger.vue
similarity index 79%
rename from vue/primitives/src/menubar/MenubarSubTrigger.vue
rename to vue/primitives/src/menus/menubar/MenubarSubTrigger.vue
index f10fb36..74eb7b1 100644
--- a/vue/primitives/src/menubar/MenubarSubTrigger.vue
+++ b/vue/primitives/src/menus/menubar/MenubarSubTrigger.vue
@@ -11,10 +11,11 @@ export interface MenubarSubTriggerProps extends MenuSubTriggerProps {}
 
 <script setup lang="ts">
 import { MenuSubTrigger } from '../menu';
+import { SUBTRIGGER_ATTR } from './context';
 
 const props = defineProps<MenubarSubTriggerProps>();
 </script>
 
 <template>
-  <MenuSubTrigger v-bind="props"><slot /></MenuSubTrigger>
+  <MenuSubTrigger v-bind="props" :[SUBTRIGGER_ATTR]="''"><slot /></MenuSubTrigger>
 </template>
diff --git a/vue/primitives/src/menubar/MenubarTrigger.vue b/vue/primitives/src/menus/menubar/MenubarTrigger.vue
similarity index 70%
rename from vue/primitives/src/menubar/MenubarTrigger.vue
rename to vue/primitives/src/menus/menubar/MenubarTrigger.vue
index dc9e19d..4249e1c 100644
--- a/vue/primitives/src/menubar/MenubarTrigger.vue
+++ b/vue/primitives/src/menus/menubar/MenubarTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button in the menubar that opens its menu and anchors the content.
@@ -13,13 +13,13 @@ export interface MenubarTriggerProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { onMounted, onUnmounted, watch } from 'vue';
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { useCollectionInjector } from '../collection';
+import { useCollectionInjector } from '../../utilities/collection';
 import { MenuAnchor, useMenuContext } from '../menu';
 import { getNextMatch } from '../menu/utils';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useMenubarMenuContext, useMenubarRootContext } from './context';
 
 const { disabled = false, as = 'button' } = defineProps<MenubarTriggerProps>();
@@ -30,9 +30,39 @@ const menuMenuCtx = useMenuContext();
 const collection = useCollectionInjector<string>();
 const { forwardRef, currentElement } = useForwardExpose();
 
+const isFocused = ref(false);
+
 onMounted(() => menuCtx.onTriggerChange(currentElement.value ?? null));
 onUnmounted(() => menuCtx.onTriggerChange(null));
 
+// Roving tabindex: the menubar is a single tab stop. A trigger is tabbable when
+// it owns the current tab stop, or — until one is chosen — when it is the first
+// enabled trigger in DOM order. Keeping the existing Arrow/Home/End handler
+// below means focus still moves with arrows once the bar is entered.
+const isCurrentTabStop = computed(() => {
+  if (disabled) return false;
+  const current = rootCtx.currentTabStopId.value;
+  if (current === menuCtx.value) return true;
+  // Fall back to the first enabled trigger when no tab stop is chosen yet, or
+  // when the chosen one is no longer mounted (e.g. its menu was v-if'd away) —
+  // otherwise the menubar could end up with zero tabbable triggers.
+  const enabled = rootCtx.getTriggers();
+  if (current !== undefined && enabled.some(i => i.value === current)) return false;
+  return enabled.at(0)?.value === menuCtx.value;
+});
+
+const tabindex = computed(() => (isCurrentTabStop.value ? 0 : -1));
+
+function handleFocus() {
+  isFocused.value = true;
+  // Entering this trigger (Tab, arrow, or programmatic) makes it the tab stop.
+  if (!disabled) rootCtx.onTabStopChange(menuCtx.value);
+}
+
+function handleBlur() {
+  isFocused.value = false;
+}
+
 function focusTrigger(el: HTMLElement | undefined) {
   if (!el) return;
   el.focus({ preventScroll: true });
@@ -54,7 +84,9 @@ function focusByIndex(items: HTMLElement[], from: number, delta: 1 | -1) {
 // Hover-switch: when a sibling menu is already open, hovering this trigger
 // (focused or not) opens this one and moves focus over.
 function handlePointerDown(event: PointerEvent) {
-  if (disabled || event.button !== 0) return;
+  // Left button only; `ctrlKey` filters out a macOS ctrl+click (context menu)
+  // that the OS reports as a left button press.
+  if (disabled || event.button !== 0 || event.ctrlKey) return;
   event.preventDefault();
   rootCtx.onMenuToggle(menuCtx.value);
 }
@@ -136,13 +168,18 @@ watch(() => rootCtx.searchRef.value, (search) => {
         role="menuitem"
         aria-haspopup="menu"
         :aria-expanded="menuMenuCtx.open.value"
-        :aria-controls="menuCtx.contentId.value"
+        :aria-controls="menuMenuCtx.open.value ? menuCtx.contentId.value : undefined"
+        :tabindex="tabindex"
         :data-state="menuMenuCtx.open.value ? 'open' : 'closed'"
+        :data-highlighted="isFocused ? '' : undefined"
         :data-disabled="disabled ? '' : undefined"
+        :data-value="menuCtx.value"
         :disabled="as === 'button' ? disabled : undefined"
         @pointerdown="handlePointerDown"
         @pointerenter="handlePointerEnter"
         @keydown="handleKeyDown"
+        @focus="handleFocus"
+        @blur="handleBlur"
       >
         <slot />
       </Primitive>
diff --git a/vue/primitives/src/menus/menubar/__test__/Menubar.parity.test.ts b/vue/primitives/src/menus/menubar/__test__/Menubar.parity.test.ts
new file mode 100644
index 0000000..d513032
--- /dev/null
+++ b/vue/primitives/src/menus/menubar/__test__/Menubar.parity.test.ts
@@ -0,0 +1,381 @@
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+
+import {
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarPortal,
+  MenubarRoot,
+  MenubarSub,
+  MenubarSubContent,
+  MenubarSubTrigger,
+  MenubarTrigger,
+} from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  document.body.style.pointerEvents = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function keydown(el: Element, key: string, init: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+}
+
+function triggers(): HTMLElement[] {
+  return Array.from(document.querySelectorAll<HTMLElement>('[data-value]'));
+}
+
+function content(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('[role="menu"]');
+}
+
+/** A menubar with a content panel under each menu, optional disabled triggers. */
+function mountFull(opts: { dir?: 'ltr' | 'rtl'; loop?: boolean; disabled?: string[] } = {}) {
+  const labels = ['File', 'Edit', 'View'];
+  const disabled = new Set(opts.disabled ?? []);
+  const Harness = defineComponent({
+    setup() {
+      return () =>
+        h(MenubarRoot, { dir: opts.dir, loop: opts.loop }, {
+          default: () =>
+            labels.map(label =>
+              h(MenubarMenu, { value: label.toLowerCase() }, {
+                default: () => [
+                  h(MenubarTrigger, { disabled: disabled.has(label.toLowerCase()) }, { default: () => label }),
+                  h(MenubarPortal, null, {
+                    default: () =>
+                      h(MenubarContent, null, {
+                        default: () => h(MenubarItem, null, { default: () => `${label} item` }),
+                      }),
+                  }),
+                ],
+              }),
+            ),
+        });
+    },
+  });
+  return track(mount(Harness, { attachTo: document.body }));
+}
+
+describe('menubar — roving tabindex (single tab stop)', () => {
+  it('makes exactly one trigger tabbable; the first by default', async () => {
+    mountFull();
+    await nextTick();
+    const all = triggers();
+    expect(all.map(t => t.getAttribute('tabindex'))).toEqual(['0', '-1', '-1']);
+  });
+
+  it('moves the single tab stop to whichever trigger is focused', async () => {
+    mountFull();
+    const [, edit] = triggers();
+    edit!.focus();
+    await nextTick();
+    expect(triggers().map(t => t.getAttribute('tabindex'))).toEqual(['-1', '0', '-1']);
+  });
+
+  it('never makes a disabled trigger the tab stop', async () => {
+    mountFull({ disabled: ['file'] });
+    await nextTick();
+    const all = triggers();
+    // File is disabled, so the first tabbable falls through to Edit.
+    expect(all[0]!.getAttribute('tabindex')).toBe('-1');
+    expect(all[1]!.getAttribute('tabindex')).toBe('0');
+  });
+});
+
+describe('menubar — trigger attributes', () => {
+  it('exposes data-value mirroring the menu value', () => {
+    mountFull();
+    expect(triggers().map(t => t.dataset['value'])).toEqual(['file', 'edit', 'view']);
+  });
+
+  it('sets data-highlighted only while the trigger has focus', async () => {
+    mountFull();
+    const [file] = triggers();
+    expect(file!.hasAttribute('data-highlighted')).toBe(false);
+    file!.focus();
+    await nextTick();
+    expect(file!.hasAttribute('data-highlighted')).toBe(true);
+    file!.blur();
+    await nextTick();
+    expect(file!.hasAttribute('data-highlighted')).toBe(false);
+  });
+
+  it('omits aria-controls while the menu is closed and sets it once open', async () => {
+    mountFull();
+    const [file] = triggers();
+    expect(file!.hasAttribute('aria-controls')).toBe(false);
+    keydown(file!, 'Enter');
+    await nextTick();
+    await nextTick();
+    expect(file!.getAttribute('aria-expanded')).toBe('true');
+    expect(file!.getAttribute('aria-controls')).toBeTruthy();
+  });
+});
+
+describe('menubar — content props', () => {
+  it('honors a consumer-supplied align instead of forcing start', async () => {
+    const Harness = defineComponent({
+      setup() {
+        return () =>
+          h(MenubarRoot, { defaultValue: 'file' }, {
+            default: () =>
+              h(MenubarMenu, { value: 'file' }, {
+                default: () => [
+                  h(MenubarTrigger, null, { default: () => 'File' }),
+                  h(MenubarPortal, null, {
+                    default: () =>
+                      h(MenubarContent, { align: 'end' }, {
+                        default: () => h(MenubarItem, null, { default: () => 'x' }),
+                      }),
+                  }),
+                ],
+              }),
+          });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    await nextTick();
+    expect(content()!.getAttribute('data-align')).toBe('end');
+  });
+
+  it('exposes the menubar trigger-size CSS custom properties on the content', async () => {
+    mountFull();
+    const [file] = triggers();
+    keydown(file!, 'Enter');
+    await nextTick();
+    await nextTick();
+    const style = content()!.getAttribute('style') ?? '';
+    expect(style).toContain('--primitives-menubar-trigger-width');
+    expect(style).toContain('--primitives-menubar-trigger-height');
+  });
+});
+
+describe('menubar — pointerdown guards', () => {
+  it('ignores a macOS ctrl+click (does not open the menu)', async () => {
+    mountFull();
+    const [file] = triggers();
+    file!.dispatchEvent(new PointerEvent('pointerdown', { button: 0, ctrlKey: true, bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(file!.getAttribute('data-state')).toBe('closed');
+  });
+
+  it('opens on a plain left click', async () => {
+    mountFull();
+    const [file] = triggers();
+    file!.dispatchEvent(new PointerEvent('pointerdown', { button: 0, bubbles: true, cancelable: true }));
+    await nextTick();
+    await nextTick();
+    expect(file!.getAttribute('data-state')).toBe('open');
+  });
+});
+
+describe('menubar — cross-menu arrow navigation while a menu is open', () => {
+  it('ArrowRight inside open content switches to the next menubar menu (ltr)', async () => {
+    mountFull();
+    const [file] = triggers();
+    keydown(file!, 'Enter');
+    await nextTick();
+    await nextTick();
+    const panel = content();
+    expect(panel).toBeTruthy();
+
+    keydown(panel!, 'ArrowRight');
+    await nextTick();
+    await nextTick();
+    // The Edit menu is now the open one.
+    expect(triggers()[1]!.getAttribute('data-state')).toBe('open');
+    expect(triggers()[0]!.getAttribute('data-state')).toBe('closed');
+  });
+
+  it('ArrowLeft inside open content switches to the previous menubar menu (ltr)', async () => {
+    mountFull();
+    const [, edit] = triggers();
+    keydown(edit!, 'Enter');
+    await nextTick();
+    await nextTick();
+
+    keydown(content()!, 'ArrowLeft');
+    await nextTick();
+    await nextTick();
+    expect(triggers()[0]!.getAttribute('data-state')).toBe('open');
+  });
+
+  it('ArrowRight on the last menu loops to the first when loop=true', async () => {
+    mountFull({ loop: true });
+    const all = triggers();
+    keydown(all.at(-1)!, 'Enter');
+    await nextTick();
+    await nextTick();
+
+    keydown(content()!, 'ArrowRight');
+    await nextTick();
+    await nextTick();
+    expect(triggers()[0]!.getAttribute('data-state')).toBe('open');
+  });
+
+  it('ArrowRight on the last menu stays put when loop=false', async () => {
+    mountFull({ loop: false });
+    const all = triggers();
+    keydown(all.at(-1)!, 'Enter');
+    await nextTick();
+    await nextTick();
+
+    keydown(content()!, 'ArrowRight');
+    await nextTick();
+    await nextTick();
+    expect(triggers().at(-1)!.getAttribute('data-state')).toBe('open');
+  });
+
+  it('reverses the arrow direction in RTL', async () => {
+    mountFull({ dir: 'rtl' });
+    const [file] = triggers();
+    keydown(file!, 'Enter');
+    await nextTick();
+    await nextTick();
+    // In RTL the "next" key is ArrowLeft.
+    keydown(content()!, 'ArrowLeft');
+    await nextTick();
+    await nextTick();
+    expect(triggers()[1]!.getAttribute('data-state')).toBe('open');
+  });
+});
+
+describe('menubar — focus restore on close', () => {
+  it('does not yank focus back to the trigger after interacting outside', async () => {
+    // An external focus target the user moves into.
+    const outside = document.createElement('input');
+    document.body.appendChild(outside);
+
+    mountFull();
+    const [file] = triggers();
+    // Keyboard-open so the trigger would normally be refocused on close.
+    keydown(file!, 'Enter');
+    await nextTick();
+    await nextTick();
+    expect(content()).toBeTruthy();
+
+    // User clicks/focuses an element outside the menu.
+    outside.focus();
+    outside.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true }));
+    document.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    await nextTick();
+
+    // Focus stayed where the user put it (not snapped back to the trigger).
+    expect(document.activeElement).not.toBe(file);
+    outside.remove();
+  });
+
+  it('refocuses the trigger after a keyboard-open menu is closed via Escape', async () => {
+    mountFull();
+    const [file] = triggers();
+    keydown(file!, 'Enter');
+    await nextTick();
+    await nextTick();
+    const panel = content();
+    expect(panel).toBeTruthy();
+
+    keydown(panel!, 'Escape');
+    await nextTick();
+    await nextTick();
+    await nextTick();
+    expect(document.activeElement).toBe(file);
+  });
+});
+
+describe('menubar — root slot', () => {
+  it('exposes the open menu value to the default slot', async () => {
+    const seen = ref<string | undefined>('untouched');
+    const Harness = defineComponent({
+      setup() {
+        return () =>
+          h(MenubarRoot, { defaultValue: 'edit' }, {
+
+            default: (slotProps: any) => {
+              seen.value = slotProps.modelValue;
+              return h(MenubarMenu, { value: 'edit' }, {
+                default: () => h(MenubarTrigger, null, { default: () => 'Edit' }),
+              });
+            },
+          });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    expect(seen.value).toBe('edit');
+  });
+});
+
+describe('menubar — submenu uncontrolled mode', () => {
+  function mountWithSub(props: { defaultOpen?: boolean } = {}) {
+    const Harness = defineComponent({
+      setup() {
+        return () =>
+          h(MenubarRoot, { defaultValue: 'file' }, {
+            default: () =>
+              h(MenubarMenu, { value: 'file' }, {
+                default: () => [
+                  h(MenubarTrigger, null, { default: () => 'File' }),
+                  h(MenubarPortal, null, {
+                    default: () =>
+                      h(MenubarContent, null, {
+                        default: () =>
+                          h(MenubarSub, { defaultOpen: props.defaultOpen }, {
+                            default: () => [
+                              h(MenubarSubTrigger, null, { default: () => 'More' }),
+                              h(MenubarPortal, null, {
+                                default: () =>
+                                  h(MenubarSubContent, null, {
+                                    default: () => h(MenubarItem, null, { default: () => 'Deep' }),
+                                  }),
+                              }),
+                            ],
+                          }),
+                      }),
+                  }),
+                ],
+              }),
+          });
+      },
+    });
+    return track(mount(Harness, { attachTo: document.body }));
+  }
+
+  it('opens the submenu initially when defaultOpen is true (uncontrolled)', async () => {
+    mountWithSub({ defaultOpen: true });
+    await nextTick();
+    await nextTick();
+    const subTrigger = document.querySelector<HTMLElement>('[data-primitives-menubar-subtrigger]');
+    expect(subTrigger).toBeTruthy();
+    expect(subTrigger!.getAttribute('data-state')).toBe('open');
+  });
+
+  it('keeps the submenu closed by default', async () => {
+    mountWithSub();
+    await nextTick();
+    await nextTick();
+    const subTrigger = document.querySelector<HTMLElement>('[data-primitives-menubar-subtrigger]');
+    expect(subTrigger!.getAttribute('data-state')).toBe('closed');
+  });
+
+  it('marks the sub-trigger so cross-menu nav does not hijack the open key', async () => {
+    mountWithSub();
+    await nextTick();
+    await nextTick();
+    expect(document.querySelector('[data-primitives-menubar-subtrigger]')).toBeTruthy();
+  });
+});
diff --git a/vue/primitives/src/menubar/__test__/Menubar.regression.test.ts b/vue/primitives/src/menus/menubar/__test__/Menubar.regression.test.ts
similarity index 100%
rename from vue/primitives/src/menubar/__test__/Menubar.regression.test.ts
rename to vue/primitives/src/menus/menubar/__test__/Menubar.regression.test.ts
diff --git a/vue/primitives/src/menubar/context.ts b/vue/primitives/src/menus/menubar/context.ts
similarity index 50%
rename from vue/primitives/src/menubar/context.ts
rename to vue/primitives/src/menus/menubar/context.ts
index e0fa40c..036c730 100644
--- a/vue/primitives/src/menubar/context.ts
+++ b/vue/primitives/src/menus/menubar/context.ts
@@ -1,20 +1,40 @@
 import type { ComputedRef, Ref, ShallowRef } from 'vue';
-import type { Direction } from '../config-provider';
-import type { CollectionItemData } from '../collection';
+import type { Direction } from '../../utilities/config-provider';
+import type { CollectionItemData } from '../../utilities/collection';
 
 import { useContextFactory } from '@robonen/vue';
 
+/**
+ * Marker attribute placed on a sub-trigger. Cross-menu arrow navigation reads it
+ * to avoid switching menubar menus while the same arrow key is opening a submenu.
+ */
+export const SUBTRIGGER_ATTR = 'data-primitives-menubar-subtrigger';
+
 export interface MenubarRootContext {
   value: Ref<string | undefined>;
   dir: Ref<Direction>;
   loop: Ref<boolean>;
   onMenuOpen: (value: string) => void;
-  onMenuClose: () => void;
+  /**
+   * Closes the menubar. Pass the value of the menu requesting the close so a
+   * stale menu dismissing mid-switch cannot clobber the sibling that just
+   * opened — only the currently-active menu actually closes. Omit the value to
+   * force-close whichever menu is open.
+   */
+  onMenuClose: (value?: string) => void;
   onMenuToggle: (value: string) => void;
   /** Ordered list of all currently-mounted menubar triggers (DOM order). */
   getTriggers: (includeDisabled?: boolean) => Array<CollectionItemData<string>>;
   /** Buffered typeahead search string (cleared after ~1000ms idle). */
   searchRef: Ref<string>;
+  /**
+   * Value of the trigger that is the menubar's single tab stop (roving tabindex).
+   * Exactly one trigger has `tabindex="0"`; the rest are `-1`, so the whole
+   * menubar is one tab stop and Arrow keys move between triggers.
+   */
+  currentTabStopId: Ref<string | undefined>;
+  /** Sets which trigger value owns the roving tab stop. */
+  onTabStopChange: (value: string | undefined) => void;
 }
 
 export const {
diff --git a/vue/primitives/src/menubar/demo.vue b/vue/primitives/src/menus/menubar/demo.vue
similarity index 100%
rename from vue/primitives/src/menubar/demo.vue
rename to vue/primitives/src/menus/menubar/demo.vue
diff --git a/vue/primitives/src/menubar/index.ts b/vue/primitives/src/menus/menubar/index.ts
similarity index 100%
rename from vue/primitives/src/menubar/index.ts
rename to vue/primitives/src/menus/menubar/index.ts
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuContent.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuContent.vue
similarity index 91%
rename from vue/primitives/src/navigation-menu/NavigationMenuContent.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuContent.vue
index 10ebcab..45149c4 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuContent.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuContent.vue
@@ -18,7 +18,7 @@ export type NavigationMenuContentEmits = NavigationMenuContentImplEmits;
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue';
 
-import { Presence } from '../presence';
+import { Presence } from '../../utilities/presence';
 import { useNavigationMenuContext, useNavigationMenuItemContext } from './context';
 import NavigationMenuContentImpl from './NavigationMenuContentImpl.vue';
 
@@ -71,9 +71,11 @@ function handlePointerLeave() {
 
 <template>
   <Teleport :to="menuContext.viewport.value ?? 'body'" :disabled="!menuContext.viewport.value">
-    <Presence :present="present" :force-mount="forceMount || !menuContext.unmountOnHide.value">
+    <Presence v-slot="{ present: isPresent }" :present="present" :force-mount="forceMount || !menuContext.unmountOnHide.value">
       <NavigationMenuContentImpl
         v-bind="{ ...rest, ...$attrs }"
+        :hidden="!isPresent"
+        :style="{ pointerEvents: !open && menuContext.isRootMenu ? 'none' : undefined }"
         @escape-key-down="emit('escapeKeyDown', $event)"
         @pointer-down-outside="emit('pointerDownOutside', $event)"
         @focus-outside="emit('focusOutside', $event)"
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuContentImpl.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuContentImpl.vue
similarity index 81%
rename from vue/primitives/src/navigation-menu/NavigationMenuContentImpl.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuContentImpl.vue
index ec85665..478a772 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuContentImpl.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuContentImpl.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { DismissableLayerEmits, DismissableLayerProps } from '../dismissable-layer';
+import type { DismissableLayerEmits, DismissableLayerProps } from '../../utilities/dismissable-layer';
 
 /**
  * Internal rendering body for `NavigationMenuContent`. Wraps the panel in a
@@ -16,19 +16,19 @@ export type NavigationMenuContentImplEmits = DismissableLayerEmits & {
 </script>
 
 <script setup lang="ts">
-import { computed, watchEffect } from 'vue';
+import { computed, onWatcherCleanup, watchEffect } from 'vue';
 
 import { focusFirst, getActiveElement, getTabbableCandidates } from '@robonen/platform/browsers';
 import { useForwardExpose } from '@robonen/vue';
-import { DismissableLayer } from '../dismissable-layer';
-import { FocusScope } from '../focus-scope';
-import { getFocusIntent, wrapArray } from '../roving-focus/utils';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
+import { FocusScope } from '../../utilities/focus-scope';
+import { getFocusIntent, wrapArray } from '../../utilities/roving-focus/utils';
 import { useNavigationMenuContext, useNavigationMenuItemContext } from './context';
 import { COLLECTION_ITEM_ATTR, EVENT_ROOT_CONTENT_DISMISS, getOpenState } from './utils';
 
 defineOptions({ inheritAttrs: false });
 
-const { as } = defineProps<NavigationMenuContentImplProps>();
+const { as = 'div', disableOutsidePointerEvents = false } = defineProps<NavigationMenuContentImplProps>();
 
 const emit = defineEmits<NavigationMenuContentImplEmits>();
 
@@ -58,7 +58,15 @@ const motionAttribute = computed<'from-start' | 'from-end' | 'to-start' | 'to-en
   return curIndex > index ? 'to-start' : 'to-end';
 });
 
+const IGNORED_ARROW_NAV_ELEMENTS = new Set(['INPUT', 'TEXTAREA']);
+
 function handleKeydown(ev: KeyboardEvent) {
+  // Don't double-handle keydown bubbling up from a nested submenu's content:
+  // only the content whose nearest navigation menu is this menu should act.
+  const target = ev.target as HTMLElement | null;
+  if (target?.closest('[data-primitives-navigation-menu]') !== menuContext.rootNavigationMenu.value)
+    return;
+
   const isMetaKey = ev.altKey || ev.ctrlKey || ev.metaKey;
 
   if (ev.key === 'Tab' && !isMetaKey) {
@@ -87,6 +95,11 @@ function handleKeydown(ev: KeyboardEvent) {
   const root = currentElement.value;
   if (!root) return;
 
+  const focusedEl = getActiveElement(document) as HTMLElement | null;
+  // Let text fields keep native caret movement: don't hijack arrows when focus
+  // is inside an INPUT/TEXTAREA within the panel.
+  if (focusedEl && IGNORED_ARROW_NAV_ELEMENTS.has(focusedEl.nodeName)) return;
+
   const linkItems = Array.from(root.querySelectorAll<HTMLElement>(`[${COLLECTION_ITEM_ATTR}]`));
   const focused = getActiveElement(document) as HTMLElement | null;
   const focusedIndex = focused ? linkItems.indexOf(focused) : -1;
@@ -149,14 +162,18 @@ function handleDismiss() {
 
 // Listen for sibling/global EVENT_ROOT_CONTENT_DISMISS for root menus so links
 // inside content can request the whole root close.
-watchEffect((onCleanup) => {
+watchEffect(() => {
   const el = currentElement.value;
   if (!el || !menuContext.isRootMenu) return;
   function onDismiss() {
     itemContext.onRootContentClose();
+    // Return focus to the trigger if it was still inside this content, otherwise
+    // a link-select-driven close drops focus to <body> after the panel unmounts.
+    if (el && el.contains(getActiveElement(document)))
+      itemContext.triggerRef.value?.focus();
   }
   el.addEventListener(EVENT_ROOT_CONTENT_DISMISS, onDismiss);
-  onCleanup(() => el.removeEventListener(EVENT_ROOT_CONTENT_DISMISS, onDismiss));
+  onWatcherCleanup(() => el.removeEventListener(EVENT_ROOT_CONTENT_DISMISS, onDismiss));
 });
 </script>
 
@@ -175,7 +192,7 @@ watchEffect((onCleanup) => {
       :data-state="getOpenState(menuContext.modelValue.value, itemContext.value)"
       :data-orientation="menuContext.orientation"
       :data-primitives-navigation-menu-content="itemContext.value"
-      :disable-outside-pointer-events="false"
+      :disable-outside-pointer-events="disableOutsidePointerEvents"
       v-bind="$attrs"
       @keydown="handleKeydown"
       @escape-key-down="handleEscapeKeyDown"
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuIndicator.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuIndicator.vue
similarity index 67%
rename from vue/primitives/src/navigation-menu/NavigationMenuIndicator.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuIndicator.vue
index 86c57a0..4c1bd05 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuIndicator.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuIndicator.vue
@@ -1,25 +1,27 @@
 <script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
 /**
  * An optional visual cue (e.g. an arrow or underline) that tracks the currently active
  * trigger. It teleports into the `NavigationMenuList` wrapper and exposes the active
  * trigger's size and position as CSS variables for animated highlighting.
  */
-export interface NavigationMenuIndicatorProps {
+export interface NavigationMenuIndicatorProps extends PrimitiveProps {
   forceMount?: boolean;
 }
 </script>
 
 <script setup lang="ts">
-import { computed, onScopeDispose, ref, watch } from 'vue';
+import { computed, ref, watch } from 'vue';
 
-import { useForwardExpose } from '@robonen/vue';
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
+import { useForwardExpose, useResizeObserver } from '@robonen/vue';
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
 import { useNavigationMenuContext } from './context';
 
 defineOptions({ inheritAttrs: false });
 
-const { forceMount = false } = defineProps<NavigationMenuIndicatorProps>();
+const { forceMount = false, as = 'div' } = defineProps<NavigationMenuIndicatorProps>();
 
 const menuContext = useNavigationMenuContext();
 const { forwardRef } = useForwardExpose();
@@ -29,9 +31,6 @@ const isHorizontal = computed(() => menuContext.orientation === 'horizontal');
 
 const rect = ref<{ size: number; position: number } | undefined>();
 
-let triggerObserver: ResizeObserver | undefined;
-let trackObserver: ResizeObserver | undefined;
-
 function recompute() {
   const trigger = menuContext.activeTrigger.value;
   if (!trigger) return;
@@ -43,27 +42,19 @@ function recompute() {
   }
 }
 
-watch(
-  () => [menuContext.activeTrigger.value, menuContext.indicatorTrack.value, isHorizontal.value],
-  () => {
-    triggerObserver?.disconnect();
-    trackObserver?.disconnect();
-    const trigger = menuContext.activeTrigger.value;
-    const track = menuContext.indicatorTrack.value;
-    if (!trigger || !track) return;
-    triggerObserver = new ResizeObserver(recompute);
-    trackObserver = new ResizeObserver(recompute);
-    triggerObserver.observe(trigger);
-    trackObserver.observe(track);
-    recompute();
-  },
-  { immediate: true },
+// Re-measure on resize of the active trigger or the track. The observer
+// re-targets automatically as those elements change and tears down on dispose.
+useResizeObserver(
+  [() => menuContext.activeTrigger.value, () => menuContext.indicatorTrack.value],
+  recompute,
 );
 
-onScopeDispose(() => {
-  triggerObserver?.disconnect();
-  trackObserver?.disconnect();
-});
+// Re-measure on trigger/track swap and orientation change (non-resize triggers).
+watch(
+  () => [menuContext.activeTrigger.value, menuContext.indicatorTrack.value, isHorizontal.value],
+  recompute,
+  { immediate: true },
+);
 
 const indicatorStyle = computed(() => {
   if (!rect.value) return {};
@@ -79,6 +70,8 @@ const indicatorStyle = computed(() => {
     <Presence :present="isVisible" :force-mount="forceMount">
       <Primitive
         :ref="forwardRef"
+        :as="as"
+        aria-hidden="true"
         :data-state="isVisible ? 'visible' : 'hidden'"
         :data-orientation="menuContext.orientation"
         data-primitives-navigation-menu-indicator
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuItem.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuItem.vue
similarity index 75%
rename from vue/primitives/src/navigation-menu/NavigationMenuItem.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuItem.vue
index d3ba217..1afb0f5 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuItem.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuItem.vue
@@ -1,10 +1,12 @@
 <script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
 /**
  * A single entry in a `NavigationMenuList`. Groups one trigger (or link) with its
  * associated content panel under a shared `value`, and provides the per-item context
  * that wires focus, tab order, and open state between them.
  */
-export interface NavigationMenuItemProps {
+export interface NavigationMenuItemProps extends PrimitiveProps {
   /**
    * Unique value associating this item with the active state. Generated
    * automatically when omitted.
@@ -18,11 +20,11 @@ import { computed, ref, shallowRef, toValue } from 'vue';
 
 import { focusFirst, getTabbableCandidates } from '@robonen/platform/browsers';
 import { useForwardExpose, useId } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { provideNavigationMenuItemContext, useNavigationMenuContext } from './context';
 import { makeContentId, makeTriggerId, removeFromTabOrder } from './utils';
 
-const { value: valueProp } = defineProps<NavigationMenuItemProps>();
+const { value: valueProp, as = 'li' } = defineProps<NavigationMenuItemProps>();
 
 useForwardExpose();
 
@@ -59,6 +61,21 @@ function handleContentExit() {
   }
 }
 
+function handleClose() {
+  context.onItemDismiss();
+  triggerRef.value?.focus();
+}
+
+// Enter/Space on the focused trigger: when this item is open, dismiss the menu
+// and return focus to the trigger so a keyboard-driven close lands focus
+// deterministically (otherwise it can fall to <body> after the panel unmounts).
+function handleKeydown(ev: KeyboardEvent) {
+  if (ev.key !== 'Enter' && ev.key !== ' ' && ev.key !== 'Spacebar') return;
+  if (context.modelValue.value !== value.value) return;
+  handleClose();
+  ev.preventDefault();
+}
+
 provideNavigationMenuItemContext({
   get value() { return value.value; },
   get contentId() { return contentId.value; },
@@ -77,8 +94,9 @@ provideNavigationMenuItemContext({
 
 <template>
   <Primitive
-    as="li"
+    :as="as"
     data-primitives-navigation-menu-item
+    @keydown="handleKeydown"
   >
     <slot />
   </Primitive>
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuLink.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuLink.vue
similarity index 59%
rename from vue/primitives/src/navigation-menu/NavigationMenuLink.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuLink.vue
index 5c27247..9d1cb8c 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuLink.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuLink.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A navigable link, rendered as an `<a>` by default, usable as a top-level menu item
@@ -12,13 +12,18 @@ export interface NavigationMenuLinkProps extends PrimitiveProps {
 }
 
 export interface NavigationMenuLinkEmits {
-  select: [event: CustomEvent];
+  /**
+   * Fired when the user selects the link (mouse or keyboard). Call
+   * `event.preventDefault()` to keep the menu open. The `detail.originalEvent`
+   * carries the originating click so consumers can inspect modifier keys etc.
+   */
+  select: [event: CustomEvent<{ originalEvent: Event }>];
 }
 </script>
 
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { COLLECTION_ITEM_ATTR, EVENT_ROOT_CONTENT_DISMISS, LINK_SELECT_EVENT } from './utils';
 
 const { as = 'a', active = false } = defineProps<NavigationMenuLinkProps>();
@@ -27,21 +32,27 @@ const emit = defineEmits<NavigationMenuLinkEmits>();
 const { forwardRef } = useForwardExpose();
 
 function handleClick(event: MouseEvent) {
-  const target = event.currentTarget as HTMLElement | null;
-  if (!target) return;
-  const linkSelectEvent = new CustomEvent(LINK_SELECT_EVENT, {
+  const currentTarget = event.currentTarget as HTMLElement | null;
+  if (!currentTarget) return;
+  const linkSelectEvent = new CustomEvent<{ originalEvent: Event }>(LINK_SELECT_EVENT, {
     bubbles: true,
     cancelable: true,
+    detail: { originalEvent: event },
   });
   // Browser event handlers run synchronously; listen once for prevention semantics.
-  target.addEventListener(LINK_SELECT_EVENT, e => emit('select', e as CustomEvent), { once: true });
-  target.dispatchEvent(linkSelectEvent);
+  currentTarget.addEventListener(
+    LINK_SELECT_EVENT,
+    e => emit('select', e as CustomEvent<{ originalEvent: Event }>),
+    { once: true },
+  );
+  currentTarget.dispatchEvent(linkSelectEvent);
   if (!linkSelectEvent.defaultPrevented && !event.metaKey) {
     const rootContentDismissEvent = new CustomEvent(EVENT_ROOT_CONTENT_DISMISS, {
       bubbles: true,
       cancelable: true,
     });
-    target.dispatchEvent(rootContentDismissEvent);
+    // Dispatch on the actual clicked target (matches APG/nested-link behavior).
+    (event.target ?? currentTarget).dispatchEvent(rootContentDismissEvent);
   }
 }
 </script>
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuList.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuList.vue
similarity index 75%
rename from vue/primitives/src/navigation-menu/NavigationMenuList.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuList.vue
index ebf0ea4..5aec0dc 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuList.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuList.vue
@@ -1,26 +1,25 @@
 <script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
 /**
  * The horizontal (or vertical) list of menu items. Renders a `RovingFocusGroup`
  * inside a positioned wrapper that also serves as the track for `NavigationMenuIndicator`.
  * Place one directly inside `NavigationMenuRoot` (or `NavigationMenuSub`) to hold its
  * `NavigationMenuItem`s.
  */
-// This component takes no props of its own (it renders a fixed wrapper + RovingFocusGroup
-// and forwards $attrs). The empty interface is the intentional public prop contract.
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface NavigationMenuListProps {}
+export interface NavigationMenuListProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
 import { onMounted, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { RovingFocusGroup } from '../roving-focus';
+import { RovingFocusGroup } from '../../utilities/roving-focus';
 import { useNavigationMenuContext } from './context';
 
 defineOptions({ inheritAttrs: false });
 
-defineProps<NavigationMenuListProps>();
+const { as = 'ul' } = defineProps<NavigationMenuListProps>();
 
 const menuContext = useNavigationMenuContext();
 const { forwardRef, currentElement } = useForwardExpose();
@@ -38,7 +37,7 @@ watch(currentElement, (el) => {
   <div :ref="forwardRef" data-primitives-navigation-menu-list-wrapper style="position: relative">
     <RovingFocusGroup
       v-bind="$attrs"
-      as="ul"
+      :as="as"
       :orientation="menuContext.orientation"
       :dir="menuContext.dir.value"
       :loop="false"
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuRoot.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuRoot.vue
similarity index 89%
rename from vue/primitives/src/navigation-menu/NavigationMenuRoot.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuRoot.vue
index 19cb04b..e0fb0a9 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuRoot.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuRoot.vue
@@ -1,6 +1,7 @@
 <script lang="ts">
-import type { Direction } from '../config-provider';
-import type { Orientation } from '../roving-focus';
+import type { Direction } from '../../utilities/config-provider';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Orientation } from '../../utilities/roving-focus';
 
 /**
  * A collection of navigation links and disclosure menus, typically used for the
@@ -10,7 +11,7 @@ import type { Orientation } from '../roving-focus';
  * for it over a generic dropdown when you need keyboard-accessible, animatable
  * mega-menu panels that share a single active state.
  */
-export interface NavigationMenuRootProps {
+export interface NavigationMenuRootProps extends PrimitiveProps {
   /** Uncontrolled initial value. */
   defaultValue?: string;
   /** Reading direction. Falls back to `ConfigProvider`. */
@@ -45,12 +46,12 @@ export interface NavigationMenuRootEmits {
 <script setup lang="ts">
 import type { Ref } from 'vue';
 
-import { computed, onScopeDispose, ref, shallowRef, toRef, watchEffect } from 'vue';
+import { computed, onScopeDispose, onWatcherCleanup, ref, shallowRef, toRef, watchEffect } from 'vue';
 
 import { useForwardExpose, useId } from '@robonen/vue';
-import { useCollectionProvider } from '../collection';
-import { useConfig } from '../config-provider';
-import { Primitive } from '../primitive';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useConfig } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { provideNavigationMenuContext } from './context';
 import { EVENT_ROOT_CONTENT_DISMISS, NAVIGATION_MENU_COLLECTION_KEY } from './utils';
 
@@ -66,12 +67,13 @@ const {
   disableHoverTrigger = false,
   disablePointerLeaveClose = false,
   unmountOnHide = true,
+  as = 'nav',
 } = defineProps<NavigationMenuRootProps>();
 
 defineEmits<NavigationMenuRootEmits>();
 
 defineSlots<{
-  default?: (props: { modelValue: string }) => any;
+  default?: (props: { modelValue: string }) => unknown;
 }>();
 
 const config = useConfig();
@@ -162,11 +164,11 @@ function onItemDismiss() {
 }
 
 // Custom event isn't part of HTMLElementEventMap so wire it up manually.
-watchEffect((onCleanup) => {
+watchEffect(() => {
   const el = rootNavigationMenu.value;
   if (!el) return;
   el.addEventListener(EVENT_ROOT_CONTENT_DISMISS, onItemDismiss);
-  onCleanup(() => el.removeEventListener(EVENT_ROOT_CONTENT_DISMISS, onItemDismiss));
+  onWatcherCleanup(() => el.removeEventListener(EVENT_ROOT_CONTENT_DISMISS, onItemDismiss));
 });
 
 onScopeDispose(() => {
@@ -218,7 +220,7 @@ provideNavigationMenuContext({
   <CollectionSlot>
     <Primitive
       :ref="forwardRef"
-      as="nav"
+      :as="as"
       :aria-label="($attrs['aria-label'] ?? 'Main') as string"
       :data-orientation="orientation"
       :dir="dirRef"
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuSub.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuSub.vue
similarity index 86%
rename from vue/primitives/src/navigation-menu/NavigationMenuSub.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuSub.vue
index 9b801be..7fb652a 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuSub.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuSub.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import type { Orientation } from '../roving-focus';
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Orientation } from '../../utilities/roving-focus';
 
 /**
  * Nests a second navigation menu inside a `NavigationMenuContent` panel, with its
@@ -7,7 +8,7 @@ import type { Orientation } from '../roving-focus';
  * Use it to build multi-level menus where a content panel itself contains a list of
  * triggers and sub-panels.
  */
-export interface NavigationMenuSubProps {
+export interface NavigationMenuSubProps extends PrimitiveProps {
   /** Uncontrolled initial value. */
   defaultValue?: string;
   /** Submenu orientation. @default 'horizontal' */
@@ -25,19 +26,19 @@ import type { Ref } from 'vue';
 import { ref, shallowRef, watchEffect } from 'vue';
 
 import { useForwardExpose, useId } from '@robonen/vue';
-import { useCollectionProvider } from '../collection';
-import { Primitive } from '../primitive';
+import { useCollectionProvider } from '../../utilities/collection';
+import { Primitive } from '../../internal/primitive';
 import { provideNavigationMenuContext, useNavigationMenuContext } from './context';
 import { NAVIGATION_MENU_COLLECTION_KEY } from './utils';
 
 defineOptions({ inheritAttrs: false });
 
-const { defaultValue, orientation = 'horizontal' } = defineProps<NavigationMenuSubProps>();
+const { defaultValue, orientation = 'horizontal', as = 'div' } = defineProps<NavigationMenuSubProps>();
 
 defineEmits<NavigationMenuSubEmits>();
 
 defineSlots<{
-  default?: (props: { modelValue: string }) => any;
+  default?: (props: { modelValue: string }) => unknown;
 }>();
 
 const localValue = ref<string>(defaultValue ?? '');
@@ -113,6 +114,7 @@ provideNavigationMenuContext({
   <CollectionSlot>
     <Primitive
       :ref="forwardRef"
+      :as="as"
       :data-orientation="orientation"
       data-primitives-navigation-menu
       v-bind="$attrs"
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuTrigger.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuTrigger.vue
similarity index 90%
rename from vue/primitives/src/navigation-menu/NavigationMenuTrigger.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuTrigger.vue
index 2c33935..538925c 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuTrigger.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuTrigger.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
 import type { ComponentPublicInstance } from 'vue';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button that opens its item's `NavigationMenuContent` on hover, click, or keyboard.
@@ -7,7 +8,7 @@ import type { ComponentPublicInstance } from 'vue';
  * timing handshake with the root. Use it inside a `NavigationMenuItem` for entries that
  * reveal a panel; use `NavigationMenuLink` instead for plain navigation links.
  */
-export interface NavigationMenuTriggerProps {
+export interface NavigationMenuTriggerProps extends PrimitiveProps {
   /** Disables interaction with this trigger. */
   disabled?: boolean;
 }
@@ -17,16 +18,16 @@ export interface NavigationMenuTriggerProps {
 import { computed, onMounted, ref, watch } from 'vue';
 
 import { unrefElement, useForwardExpose } from '@robonen/vue';
-import { useCollectionInjector } from '../collection';
-import { Primitive } from '../primitive';
-import { RovingFocusItem } from '../roving-focus';
-import { VisuallyHidden } from '../visually-hidden';
+import { useCollectionInjector } from '../../utilities/collection';
+import { Primitive } from '../../internal/primitive';
+import { RovingFocusItem } from '../../utilities/roving-focus';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
 import { useNavigationMenuContext, useNavigationMenuItemContext } from './context';
 import { NAVIGATION_MENU_COLLECTION_KEY, getOpenState } from './utils';
 
 defineOptions({ inheritAttrs: false });
 
-const { disabled = false } = defineProps<NavigationMenuTriggerProps>();
+const { disabled = false, as = 'button' } = defineProps<NavigationMenuTriggerProps>();
 
 const menuContext = useNavigationMenuContext();
 const itemContext = useNavigationMenuItemContext();
@@ -120,8 +121,8 @@ function handleVisuallyHiddenFocus(ev: FocusEvent) {
       <Primitive
         :id="itemContext.triggerId"
         :ref="forwardRef"
-        as="button"
-        type="button"
+        :as="as"
+        :type="as === 'button' ? 'button' : undefined"
         :disabled="disabled || undefined"
         :data-disabled="disabled ? '' : undefined"
         :data-state="getOpenState(menuContext.modelValue.value, itemContext.value)"
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuViewport.vue b/vue/primitives/src/menus/navigation-menu/NavigationMenuViewport.vue
similarity index 50%
rename from vue/primitives/src/navigation-menu/NavigationMenuViewport.vue
rename to vue/primitives/src/menus/navigation-menu/NavigationMenuViewport.vue
index 9eb4cd2..0e36b5a 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuViewport.vue
+++ b/vue/primitives/src/menus/navigation-menu/NavigationMenuViewport.vue
@@ -1,15 +1,18 @@
 <script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
 /**
  * An optional shared container that all `NavigationMenuContent` panels teleport into,
  * positioned beneath the active trigger and sized to the open panel (exposed as CSS
  * variables for animating between panels). Render one inside `NavigationMenuRoot` for
  * a single animated mega-menu surface; omit it to render each content inline.
  */
-export interface NavigationMenuViewportProps {
+export interface NavigationMenuViewportProps extends PrimitiveProps {
   /** Keep mounted regardless of open state. */
   forceMount?: boolean;
   /**
-   * Horizontal alignment of the viewport relative to the active trigger.
+   * Alignment of the viewport relative to the active trigger. Applies to the
+   * main axis (horizontal orientation) and the cross axis (vertical orientation).
    * @default 'center'
    */
   align?: 'start' | 'center' | 'end';
@@ -19,15 +22,16 @@ export interface NavigationMenuViewportProps {
 <script setup lang="ts">
 import { computed, onScopeDispose, ref, shallowRef, watch } from 'vue';
 
-import { useForwardExpose } from '@robonen/vue';
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
+import { useEventListener, useForwardExpose, useResizeObserver } from '@robonen/vue';
+import { Presence } from '../../utilities/presence';
+import { clamp } from '@robonen/stdlib';
+import { Primitive } from '../../internal/primitive';
 import { useNavigationMenuContext } from './context';
-import { clamp, whenMouse } from './utils';
+import { whenMouse } from './utils';
 
 defineOptions({ inheritAttrs: false });
 
-const { forceMount = false, align = 'center' } = defineProps<NavigationMenuViewportProps>();
+const { forceMount = false, align = 'center', as = 'div' } = defineProps<NavigationMenuViewportProps>();
 
 const menuContext = useNavigationMenuContext();
 const { forwardRef, currentElement } = useForwardExpose();
@@ -71,30 +75,72 @@ onScopeDispose(() => {
   contentObserver?.disconnect();
 });
 
-// Position based on active trigger, clamped to viewport edges.
+// Bumped whenever the layout viewport / body / root resizes so the position
+// recomputes (getBoundingClientRect isn't reactive on its own).
+const repositionTick = ref(0);
+function reposition() {
+  repositionTick.value++;
+}
+useEventListener('resize', reposition);
+useResizeObserver(currentElement, reposition);
+
+const SCREEN_OFFSET = 10;
+
+// Position based on active trigger, clamped to all four viewport edges. For
+// horizontal orientation `align` shifts the main (horizontal) axis; for vertical
+// orientation it shifts the cross (vertical) axis so a side-anchored panel can be
+// start/center/end aligned against its trigger.
 const positionStyle = computed(() => {
+  // Touch the tick so resize re-runs the computation.
+  void repositionTick.value;
   const viewport = currentElement.value;
   const trigger = menuContext.activeTrigger.value;
   if (!viewport || !trigger || !size.value) return {};
+
   const triggerRect = trigger.getBoundingClientRect();
   const viewportWidth = size.value.width;
+  const viewportHeight = size.value.height;
+  const isHorizontal = menuContext.orientation === 'horizontal';
+
   let left: number;
-  switch (align) {
-    case 'start':
-      left = triggerRect.left;
-      break;
-    case 'end':
-      left = triggerRect.right - viewportWidth;
-      break;
-    default:
-      left = triggerRect.left + (triggerRect.width / 2) - (viewportWidth / 2);
+  let top: number;
+
+  if (isHorizontal) {
+    switch (align) {
+      case 'start':
+        left = triggerRect.left;
+        break;
+      case 'end':
+        left = triggerRect.right - viewportWidth;
+        break;
+      default:
+        left = triggerRect.left + (triggerRect.width / 2) - (viewportWidth / 2);
+    }
+    top = triggerRect.bottom;
   }
-  const maxLeft = window.innerWidth - viewportWidth - 10;
-  left = clamp(left, 10, Math.max(10, maxLeft));
-  const top = triggerRect.bottom;
+  else {
+    // Vertical: open beside the trigger; `align` controls the cross (vertical) axis.
+    left = triggerRect.right;
+    switch (align) {
+      case 'start':
+        top = triggerRect.top;
+        break;
+      case 'end':
+        top = triggerRect.bottom - viewportHeight;
+        break;
+      default:
+        top = triggerRect.top + (triggerRect.height / 2) - (viewportHeight / 2);
+    }
+  }
+
+  const maxLeft = window.innerWidth - viewportWidth - SCREEN_OFFSET;
+  const maxTop = window.innerHeight - viewportHeight - SCREEN_OFFSET;
+  left = clamp(left, SCREEN_OFFSET, Math.max(SCREEN_OFFSET, maxLeft));
+  top = clamp(top, SCREEN_OFFSET, Math.max(SCREEN_OFFSET, maxTop));
+
   return {
-    '--primitives-navigation-menu-viewport-width': `${size.value.width}px`,
-    '--primitives-navigation-menu-viewport-height': `${size.value.height}px`,
+    '--primitives-navigation-menu-viewport-width': `${viewportWidth}px`,
+    '--primitives-navigation-menu-viewport-height': `${viewportHeight}px`,
     '--primitives-navigation-menu-viewport-left': `${left}px`,
     '--primitives-navigation-menu-viewport-top': `${top}px`,
   };
@@ -110,13 +156,19 @@ const handlePointerLeave = whenMouse(() => {
 </script>
 
 <template>
-  <Presence :present="present" :force-mount="forceMount || !menuContext.unmountOnHide.value">
+  <Presence v-slot="{ present: isPresent }" :present="present" :force-mount="forceMount || !menuContext.unmountOnHide.value">
     <Primitive
       :ref="forwardRef"
+      :as="as"
       :data-state="open ? 'open' : 'closed'"
       :data-orientation="menuContext.orientation"
       data-primitives-navigation-menu-viewport
-      :style="positionStyle"
+      :hidden="!isPresent"
+      :style="{
+        ...positionStyle,
+        // Prevent interaction while the panel is animating out.
+        pointerEvents: !open && menuContext.isRootMenu ? 'none' : undefined,
+      }"
       v-bind="$attrs"
       @pointerenter="handlePointerEnter"
       @pointerleave="handlePointerLeave"
diff --git a/vue/primitives/src/navigation-menu/__test__/NavigationMenu.landmark.test.ts b/vue/primitives/src/menus/navigation-menu/__test__/NavigationMenu.landmark.test.ts
similarity index 100%
rename from vue/primitives/src/navigation-menu/__test__/NavigationMenu.landmark.test.ts
rename to vue/primitives/src/menus/navigation-menu/__test__/NavigationMenu.landmark.test.ts
diff --git a/vue/primitives/src/menus/navigation-menu/__test__/NavigationMenu.parity.test.ts b/vue/primitives/src/menus/navigation-menu/__test__/NavigationMenu.parity.test.ts
new file mode 100644
index 0000000..6a8a372
--- /dev/null
+++ b/vue/primitives/src/menus/navigation-menu/__test__/NavigationMenu.parity.test.ts
@@ -0,0 +1,291 @@
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+
+import {
+  NavigationMenuContent,
+  NavigationMenuIndicator,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuRoot,
+  NavigationMenuTrigger,
+  NavigationMenuViewport,
+} from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function sleep(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function press(el: Element, key: string, init: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+}
+
+interface MenuMountOptions {
+  withViewport?: boolean;
+  contentProps?: Record<string, unknown>;
+  contentSlot?: () => any;
+  rootProps?: Record<string, unknown>;
+  triggerProps?: Record<string, unknown>;
+  itemProps?: Record<string, unknown>;
+  listProps?: Record<string, unknown>;
+}
+
+function mountMenu(opts: MenuMountOptions = {}) {
+  const {
+    withViewport = true,
+    contentProps = {},
+    contentSlot,
+    rootProps = {},
+    triggerProps = {},
+    itemProps = {},
+    listProps = {},
+  } = opts;
+  const items = ['products', 'company'];
+  const Harness = defineComponent({
+    setup() {
+      return () => h(NavigationMenuRoot, rootProps, {
+        default: () => [
+          h(NavigationMenuList, listProps, {
+            default: () => items.map(value =>
+              h(NavigationMenuItem, { value, ...itemProps }, {
+                default: () => [
+                  h(NavigationMenuTrigger, { 'data-testid': `trigger-${value}`, ...triggerProps }, { default: () => value }),
+                  h(NavigationMenuContent, { 'data-testid': `content-${value}`, ...contentProps }, {
+                    default: contentSlot ?? (() => h(NavigationMenuLink, { href: '#' }, { default: () => `${value} link` })),
+                  }),
+                ],
+              }),
+            ),
+          }),
+          withViewport ? h(NavigationMenuViewport) : null,
+        ],
+      });
+    },
+  });
+  return track(mount(Harness, { attachTo: document.body }));
+}
+
+function trigger(value = 'products'): HTMLElement {
+  return document.querySelector<HTMLElement>(`[data-testid="trigger-${value}"]`)!;
+}
+
+function content(value?: string): HTMLElement | null {
+  if (value) return document.querySelector<HTMLElement>(`[data-testid="content-${value}"]`);
+  return document.querySelector<HTMLElement>('[data-primitives-navigation-menu-content]');
+}
+
+describe('navigation-menu — polymorphism (as)', () => {
+  it('renders the root as a custom element when `as` is supplied', () => {
+    mountMenu({ rootProps: { as: 'div' } });
+    expect(document.querySelector('nav')).toBeNull();
+    const root = document.querySelector('[data-primitives-navigation-menu]') as HTMLElement;
+    expect(root.tagName).toBe('DIV');
+    // landmark label fallback still applies
+    expect(root.getAttribute('aria-label')).toBe('Main');
+  });
+
+  it('defaults the root to a <nav> landmark when `as` is omitted', () => {
+    mountMenu();
+    expect(document.querySelector('nav')).toBeTruthy();
+  });
+
+  it('renders the trigger as a custom element', async () => {
+    mountMenu({ triggerProps: { as: 'a', href: '#go' } });
+    const t = trigger();
+    expect(t.tagName).toBe('A');
+    // non-button triggers must not get type="button"
+    expect(t.getAttribute('type')).toBeNull();
+  });
+
+  it('keeps type="button" for the default button trigger', () => {
+    mountMenu();
+    expect(trigger().getAttribute('type')).toBe('button');
+  });
+
+  it('renders the item as a custom element (default li)', () => {
+    mountMenu();
+    expect(document.querySelector('li[data-primitives-navigation-menu-item]')).toBeTruthy();
+    mountMenu({ itemProps: { as: 'div' } });
+    expect(document.querySelector('div[data-primitives-navigation-menu-item]')).toBeTruthy();
+  });
+
+  it('renders the list inner element as a custom element (default ul)', () => {
+    mountMenu();
+    expect(document.querySelector('ul[data-primitives-navigation-menu-list]')).toBeTruthy();
+    mountMenu({ listProps: { as: 'div' } });
+    expect(document.querySelector('div[data-primitives-navigation-menu-list]')).toBeTruthy();
+  });
+});
+
+describe('navigation-menu — indicator a11y/polymorphism', () => {
+  it('marks the indicator aria-hidden and supports `as`', async () => {
+    const Harness = defineComponent({
+      setup() {
+        return () => h(NavigationMenuRoot, null, {
+          default: () => h(NavigationMenuList, null, {
+            default: () => [
+              h(NavigationMenuItem, { value: 'a' }, {
+                default: () => h(NavigationMenuTrigger, { 'data-testid': 'trigger-a' }, { default: () => 'a' }),
+              }),
+              h(NavigationMenuIndicator, { as: 'span' }),
+            ],
+          }),
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    // open so the indicator becomes present
+    trigger('a').click();
+    await nextTick();
+    await sleep(20);
+    const indicator = document.querySelector('[data-primitives-navigation-menu-indicator]') as HTMLElement;
+    expect(indicator).toBeTruthy();
+    expect(indicator.getAttribute('aria-hidden')).toBe('true');
+    expect(indicator.tagName).toBe('SPAN');
+  });
+});
+
+describe('navigation-menu — content hidden/pointer-events when not present', () => {
+  it('removes the hidden attribute on the open content panel', async () => {
+    mountMenu();
+    trigger().click();
+    await nextTick();
+    await sleep(50);
+    const panel = content('products')!;
+    expect(panel).toBeTruthy();
+    expect(panel.hasAttribute('hidden')).toBe(false);
+  });
+});
+
+describe('navigation-menu — DismissableLayer prop forwarding', () => {
+  it('forwards disableOutsidePointerEvents from content to the dismissable layer (body becomes inert)', async () => {
+    mountMenu({ contentProps: { disableOutsidePointerEvents: true } });
+    trigger().click();
+    await nextTick();
+    await sleep(50);
+    // DismissableLayer applies pointer-events:none to document.body when a layer
+    // with disableOutsidePointerEvents is active.
+    expect(document.body.style.pointerEvents).toBe('none');
+  });
+
+  it('does not make the body inert by default (disableOutsidePointerEvents off)', async () => {
+    mountMenu();
+    trigger().click();
+    await nextTick();
+    await sleep(50);
+    expect(document.body.style.pointerEvents).not.toBe('none');
+  });
+});
+
+describe('navigation-menu — arrow navigation bail-out for text fields', () => {
+  it('does not move focus away from an INPUT inside the content on ArrowDown', async () => {
+    mountMenu({
+      contentSlot: () => [
+        h('input', { 'data-testid': 'field', 'data-primitives-collection-item': '' }),
+        h(NavigationMenuLink, { href: '#', 'data-testid': 'link' }, { default: () => 'link' }),
+      ],
+    });
+    trigger().click();
+    await nextTick();
+    await sleep(50);
+    const field = document.querySelector<HTMLInputElement>('[data-testid="field"]')!;
+    field.focus();
+    expect(document.activeElement).toBe(field);
+    press(content('products')!, 'ArrowDown');
+    await nextTick();
+    // Focus must stay in the text field (native caret movement), not jump to the link.
+    expect(document.activeElement).toBe(field);
+  });
+});
+
+describe('navigation-menu — link select payload', () => {
+  it('emits select with detail.originalEvent', async () => {
+    const selectEvents: CustomEvent[] = [];
+    const Harness = defineComponent({
+      setup() {
+        return () => h(NavigationMenuRoot, null, {
+          default: () => h(NavigationMenuList, null, {
+            default: () => h(NavigationMenuItem, { value: 'a' }, {
+              default: () => h(NavigationMenuLink, {
+                href: '#',
+                'data-testid': 'plainlink',
+                onSelect: (e: CustomEvent) => selectEvents.push(e),
+              }, { default: () => 'link' }),
+            }),
+          }),
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    const link = document.querySelector<HTMLElement>('[data-testid="plainlink"]')!;
+    link.click();
+    await nextTick();
+    expect(selectEvents.length).toBe(1);
+    expect(selectEvents[0]!.detail).toBeTruthy();
+    expect(selectEvents[0]!.detail.originalEvent).toBeInstanceOf(Event);
+  });
+
+  it('keeps the menu open when select is prevented', async () => {
+    mountMenu({
+      contentSlot: () => h(NavigationMenuLink, {
+        href: '#',
+        'data-testid': 'prevlink',
+        onSelect: (e: CustomEvent) => e.preventDefault(),
+      }, { default: () => 'link' }),
+    });
+    trigger().click();
+    await nextTick();
+    await sleep(50);
+    expect(trigger().getAttribute('data-state')).toBe('open');
+    const link = document.querySelector<HTMLElement>('[data-testid="prevlink"]')!;
+    link.click();
+    await nextTick();
+    await sleep(50);
+    expect(trigger().getAttribute('data-state')).toBe('open');
+  });
+});
+
+describe('navigation-menu — item keyboard close + focus return', () => {
+  it('closes and returns focus to the trigger on Enter when open', async () => {
+    mountMenu();
+    const btn = trigger();
+    btn.click();
+    await nextTick();
+    await sleep(20);
+    expect(btn.getAttribute('data-state')).toBe('open');
+    btn.focus();
+    press(btn, 'Enter');
+    await nextTick();
+    await sleep(20);
+    expect(btn.getAttribute('data-state')).toBe('closed');
+    expect(document.activeElement).toBe(btn);
+  });
+
+  it('closes and returns focus to the trigger on Space when open', async () => {
+    mountMenu();
+    const btn = trigger();
+    btn.click();
+    await nextTick();
+    await sleep(20);
+    btn.focus();
+    press(btn, ' ');
+    await nextTick();
+    await sleep(20);
+    expect(btn.getAttribute('data-state')).toBe('closed');
+    expect(document.activeElement).toBe(btn);
+  });
+});
diff --git a/vue/primitives/src/navigation-menu/__test__/NavigationMenu.regression.test.ts b/vue/primitives/src/menus/navigation-menu/__test__/NavigationMenu.regression.test.ts
similarity index 100%
rename from vue/primitives/src/navigation-menu/__test__/NavigationMenu.regression.test.ts
rename to vue/primitives/src/menus/navigation-menu/__test__/NavigationMenu.regression.test.ts
diff --git a/vue/primitives/src/navigation-menu/context.ts b/vue/primitives/src/menus/navigation-menu/context.ts
similarity index 94%
rename from vue/primitives/src/navigation-menu/context.ts
rename to vue/primitives/src/menus/navigation-menu/context.ts
index b936e16..a022444 100644
--- a/vue/primitives/src/navigation-menu/context.ts
+++ b/vue/primitives/src/menus/navigation-menu/context.ts
@@ -1,6 +1,6 @@
 import type { ComputedRef, Ref, ShallowRef } from 'vue';
-import type { Direction } from '../config-provider';
-import type { Orientation } from '../roving-focus';
+import type { Direction } from '../../utilities/config-provider';
+import type { Orientation } from '../../utilities/roving-focus';
 
 import { useContextFactory } from '@robonen/vue';
 
diff --git a/vue/primitives/src/navigation-menu/demo.vue b/vue/primitives/src/menus/navigation-menu/demo.vue
similarity index 69%
rename from vue/primitives/src/navigation-menu/demo.vue
rename to vue/primitives/src/menus/navigation-menu/demo.vue
index a1e4205..b13a259 100644
--- a/vue/primitives/src/navigation-menu/demo.vue
+++ b/vue/primitives/src/menus/navigation-menu/demo.vue
@@ -26,21 +26,21 @@ const resources = [
   { title: 'Community', desc: 'Ask questions, share patterns.' },
 ];
 
-const triggerClass = 'group inline-flex items-center gap-1 rounded-md px-3 py-2 text-sm font-medium text-(--fg) outline-none transition-colors hover:bg-(--bg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring) data-[state=open]:bg-(--bg-subtle)';
-const linkClass = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium text-(--fg) no-underline outline-none transition-colors hover:bg-(--bg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring) data-[active]:text-(--accent)';
+const triggerClass = 'group inline-flex items-center gap-1 rounded-md px-3 py-2 text-sm font-medium text-fg outline-none transition-colors hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-ring data-[state=open]:bg-bg-subtle';
+const linkClass = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium text-fg no-underline outline-none transition-colors hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-ring data-[active]:text-accent';
 </script>
 
 <template>
   <NavigationMenuRoot
     v-model="value"
-    class="relative flex w-full justify-center rounded-xl border border-(--border) bg-(--bg-elevated) p-1.5 shadow-sm"
+    class="demo-card relative flex w-full justify-center p-1.5 shadow-sm"
   >
     <NavigationMenuList class="flex list-none items-center gap-1 p-0">
       <NavigationMenuItem value="products">
         <NavigationMenuTrigger :class="triggerClass">
           Products
           <span
-            class="i-carbon-chevron-down text-(--fg-muted) transition-transform duration-200 group-data-[state=open]:rotate-180"
+            class="i-carbon-chevron-down text-fg-muted transition-transform duration-200 group-data-[state=open]:rotate-180"
             aria-hidden="true"
           />
         </NavigationMenuTrigger>
@@ -51,12 +51,12 @@ const linkClass = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-me
             v-for="item in products"
             :key="item.title"
             href="#"
-            class="flex gap-3 rounded-lg p-3 no-underline outline-none transition-colors hover:bg-(--bg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring)"
+            class="flex gap-3 rounded-lg p-3 no-underline outline-none transition-colors hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-ring"
           >
-            <span :class="item.icon" class="mt-0.5 shrink-0 text-(--accent)" aria-hidden="true" />
+            <span :class="item.icon" class="mt-0.5 shrink-0 text-accent" aria-hidden="true" />
             <span class="flex flex-col gap-0.5">
-              <span class="text-sm font-medium text-(--fg)">{{ item.title }}</span>
-              <span class="text-xs text-(--fg-muted)">{{ item.desc }}</span>
+              <span class="text-sm font-medium text-fg">{{ item.title }}</span>
+              <span class="text-xs text-fg-muted">{{ item.desc }}</span>
             </span>
           </NavigationMenuLink>
         </NavigationMenuContent>
@@ -66,7 +66,7 @@ const linkClass = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-me
         <NavigationMenuTrigger :class="triggerClass">
           Resources
           <span
-            class="i-carbon-chevron-down text-(--fg-muted) transition-transform duration-200 group-data-[state=open]:rotate-180"
+            class="i-carbon-chevron-down text-fg-muted transition-transform duration-200 group-data-[state=open]:rotate-180"
             aria-hidden="true"
           />
         </NavigationMenuTrigger>
@@ -75,10 +75,10 @@ const linkClass = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-me
             v-for="item in resources"
             :key="item.title"
             href="#"
-            class="flex flex-col gap-0.5 rounded-lg p-3 no-underline outline-none transition-colors hover:bg-(--bg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring)"
+            class="flex flex-col gap-0.5 rounded-lg p-3 no-underline outline-none transition-colors hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-ring"
           >
-            <span class="text-sm font-medium text-(--fg)">{{ item.title }}</span>
-            <span class="text-xs text-(--fg-muted)">{{ item.desc }}</span>
+            <span class="text-sm font-medium text-fg">{{ item.title }}</span>
+            <span class="text-xs text-fg-muted">{{ item.desc }}</span>
           </NavigationMenuLink>
         </NavigationMenuContent>
       </NavigationMenuItem>
@@ -96,12 +96,12 @@ const linkClass = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-me
           transform: 'translateX(var(--primitives-navigation-menu-indicator-position))',
         }"
       >
-        <span class="relative top-1 h-2 w-2 rotate-45 rounded-tl-sm border-l border-t border-(--border) bg-(--bg-elevated)" />
+        <span class="relative top-1 h-2 w-2 rotate-45 rounded-tl-sm border-l border-t border-border bg-bg-elevated" />
       </NavigationMenuIndicator>
     </NavigationMenuList>
 
     <NavigationMenuViewport
-      class="fixed z-50 mt-2 overflow-hidden rounded-xl border border-(--border) bg-(--bg-elevated) shadow-lg transition-[width,height] duration-200 data-[state=closed]:animate-out data-[state=open]:animate-in"
+      class="demo-card fixed z-50 mt-2 overflow-hidden shadow-lg transition-[width,height] duration-200 data-[state=closed]:animate-out data-[state=open]:animate-in"
       :style="{
         left: 'var(--primitives-navigation-menu-viewport-left)',
         top: 'var(--primitives-navigation-menu-viewport-top)',
diff --git a/vue/primitives/src/navigation-menu/index.ts b/vue/primitives/src/menus/navigation-menu/index.ts
similarity index 100%
rename from vue/primitives/src/navigation-menu/index.ts
rename to vue/primitives/src/menus/navigation-menu/index.ts
diff --git a/vue/primitives/src/navigation-menu/utils.ts b/vue/primitives/src/menus/navigation-menu/utils.ts
similarity index 94%
rename from vue/primitives/src/navigation-menu/utils.ts
rename to vue/primitives/src/menus/navigation-menu/utils.ts
index d8f371f..7994d2e 100644
--- a/vue/primitives/src/navigation-menu/utils.ts
+++ b/vue/primitives/src/menus/navigation-menu/utils.ts
@@ -38,10 +38,6 @@ export function removeFromTabOrder(candidates: HTMLElement[]): () => void {
   };
 }
 
-export function clamp(value: number, min: number, max: number): number {
-  return Math.min(Math.max(value, min), max);
-}
-
 /** Selector identifying the link/item nodes for arrow navigation inside content. */
 export const COLLECTION_ITEM_ATTR = 'data-primitives-collection-item';
 
diff --git a/vue/primitives/src/toolbar/ToolbarButton.vue b/vue/primitives/src/menus/toolbar/ToolbarButton.vue
similarity index 68%
rename from vue/primitives/src/toolbar/ToolbarButton.vue
rename to vue/primitives/src/menus/toolbar/ToolbarButton.vue
index eed7072..39e22ab 100644
--- a/vue/primitives/src/toolbar/ToolbarButton.vue
+++ b/vue/primitives/src/menus/toolbar/ToolbarButton.vue
@@ -1,11 +1,11 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A focusable control within a `ToolbarRoot`. Registers itself with the
  * toolbar's roving-focus collection so arrow keys can move to it, carrying the
  * single `tabindex="0"` only while it is the active item. Renders a `<button>`
- * by default; use `as`/`asChild` to render a link or any other element.
+ * by default; use `as` / `as="template"` to render a link or any other element.
  */
 export interface ToolbarButtonProps extends PrimitiveProps {
 
@@ -14,26 +14,31 @@ export interface ToolbarButtonProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
-import { useCollectionInjector } from '../collection';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
-import { useToolbarContext } from './context';
+import { TOOLBAR_COLLECTION_KEY, useToolbarContext } from './context';
 
 const { as = 'button', disabled = false } = defineProps<ToolbarButtonProps>();
 const ctx = useToolbarContext();
 const { forwardRef, currentElement } = useForwardExpose();
-const { CollectionItem } = useCollectionInjector();
+const { CollectionItem } = useCollectionInjector(TOOLBAR_COLLECTION_KEY);
 
 const index = computed(() => (currentElement.value ? ctx.items.value.indexOf(currentElement.value) : -1));
 const isActive = computed(() => index.value === ctx.activeIndex.value);
 
 function onKeyDown(event: KeyboardEvent): void {
+  // Track Shift+Tab so the toolbar drops out of the tab order on the way out.
+  if (event.key === 'Tab' && event.shiftKey) {
+    ctx.onItemShiftTab();
+    return;
+  }
   if (!currentElement.value) return;
   ctx.onItemKeyDown(event, currentElement.value);
 }
 function onFocus(): void {
-  if (index.value !== -1) ctx.activeIndex.value = index.value;
+  if (currentElement.value) ctx.onItemFocus(currentElement.value);
 }
 </script>
 
diff --git a/vue/primitives/src/menus/toolbar/ToolbarLink.vue b/vue/primitives/src/menus/toolbar/ToolbarLink.vue
new file mode 100644
index 0000000..9fd7a17
--- /dev/null
+++ b/vue/primitives/src/menus/toolbar/ToolbarLink.vue
@@ -0,0 +1,60 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A link within a `ToolbarRoot`, rendered as an `<a>` by default. It joins the
+ * toolbar's roving-focus order like a `ToolbarButton`, and — because anchors do
+ * not activate on Space natively — pressing Space triggers a click so keyboard
+ * users can follow the link the same way they would a button.
+ */
+export interface ToolbarLinkProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { computed } from 'vue';
+import { useCollectionInjector } from '../../utilities/collection';
+import { useForwardExpose } from '@robonen/vue';
+import { TOOLBAR_COLLECTION_KEY, useToolbarContext } from './context';
+
+const { as = 'a' } = defineProps<ToolbarLinkProps>();
+const ctx = useToolbarContext();
+const { forwardRef, currentElement } = useForwardExpose();
+const { CollectionItem } = useCollectionInjector(TOOLBAR_COLLECTION_KEY);
+
+const index = computed(() => (currentElement.value ? ctx.items.value.indexOf(currentElement.value) : -1));
+const isActive = computed(() => index.value === ctx.activeIndex.value);
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (event.key === 'Tab' && event.shiftKey) {
+    ctx.onItemShiftTab();
+    return;
+  }
+  // Anchors do not fire a click on Space; do it ourselves so links behave like
+  // the other toolbar controls.
+  if (event.key === ' ' && event.target === event.currentTarget) {
+    event.preventDefault();
+    (event.currentTarget as HTMLElement | null)?.click();
+    return;
+  }
+  if (!currentElement.value) return;
+  ctx.onItemKeyDown(event, currentElement.value);
+}
+function onFocus(): void {
+  if (currentElement.value) ctx.onItemFocus(currentElement.value);
+}
+</script>
+
+<template>
+  <CollectionItem>
+    <Primitive
+      :as="as"
+      :ref="forwardRef"
+      :tabindex="isActive ? 0 : -1"
+      @keydown="onKeyDown"
+      @focus="onFocus"
+    >
+      <slot />
+    </Primitive>
+  </CollectionItem>
+</template>
diff --git a/vue/primitives/src/menus/toolbar/ToolbarRoot.vue b/vue/primitives/src/menus/toolbar/ToolbarRoot.vue
new file mode 100644
index 0000000..973295f
--- /dev/null
+++ b/vue/primitives/src/menus/toolbar/ToolbarRoot.vue
@@ -0,0 +1,240 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { RovingDirection } from '../../internal/utils/roving-focus';
+
+/**
+ * A container that groups a set of controls — buttons, toggles, links,
+ * separators — into a single keyboard-navigable strip (`role="toolbar"`). Like
+ * an editor's formatting bar, the whole toolbar is one tab stop: Tab moves into
+ * it, then arrow keys roam between items (Home/End and PageUp/PageDown jump to
+ * the ends), with optional wrap-around via `loop`. It owns the roving-focus
+ * state, exposes `data-orientation` for styling, and provides context to every
+ * `ToolbarButton`, `ToolbarLink`, `ToolbarToggleGroup` and `ToolbarSeparator`.
+ * Reach for it to assemble action bars, formatting toolbars, or any cluster of
+ * related controls.
+ */
+export interface ToolbarRootProps extends PrimitiveProps {
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * Writing direction. When omitted, inherits from a `ConfigProvider`,
+   * falling back to `'ltr'`.
+   */
+  dir?: RovingDirection;
+  loop?: boolean;
+  /**
+   * Controlled id of the item that currently holds the tab stop. Bind with
+   * `v-model:currentTabStopId`. When unbound the toolbar tracks it internally.
+   */
+  currentTabStopId?: string | null;
+  /** Initial current tab-stop id (uncontrolled). */
+  defaultCurrentTabStopId?: string;
+  /**
+   * Prevent scrolling the item into view when focus first enters the toolbar.
+   * @default false
+   */
+  preventScrollOnEntryFocus?: boolean;
+}
+
+export interface ToolbarRootEmits {
+  /**
+   * Fired the first time keyboard focus enters the toolbar. Call
+   * `event.preventDefault()` to override the default entry-focus target.
+   */
+  entryFocus: [event: Event];
+  /** Backs `v-model:currentTabStopId`. */
+  'update:currentTabStopId': [value: string | null | undefined];
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, toRef, watchSyncEffect } from 'vue';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useForwardExpose } from '@robonen/vue';
+import { useDirection } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
+import { TOOLBAR_COLLECTION_KEY, provideToolbarContext } from './context';
+
+const {
+  orientation = 'horizontal',
+  dir,
+  loop = true,
+  defaultCurrentTabStopId,
+  preventScrollOnEntryFocus = false,
+  as = 'div',
+} = defineProps<ToolbarRootProps>();
+
+const emit = defineEmits<ToolbarRootEmits>();
+
+const { forwardRef } = useForwardExpose();
+
+// `dir` falls back to the active `ConfigProvider` direction when not given as a
+// prop, so app-wide RTL config reaches the toolbar automatically.
+const direction = useDirection(() => dir);
+
+// DOM-order items via Collection primitive. Survives `v-for` reorders and
+// teleport/portal children, unlike a mount-order array.
+// Enabled-only: a disabled button is unfocusable, so letting it into the
+// roving list would freeze navigation on it and drop the toolbar's tab stop.
+const { getItems, CollectionSlot } = useCollectionProvider(TOOLBAR_COLLECTION_KEY);
+const items = computed(() => getItems().map(i => i.ref));
+
+const activeIndex = ref(0);
+
+// Controlled / uncontrolled current tab stop. The local ref drives the toolbar
+// when the parent does not bind `v-model:currentTabStopId`; otherwise the
+// external value is the source of truth and writes still emit the update.
+const localTabStopId = ref<string | null | undefined>(defaultCurrentTabStopId);
+// eslint-disable-next-line vue/no-dupe-keys
+const currentTabStopId = defineModel<string | null | undefined>('currentTabStopId', {
+  default: undefined,
+  get: external => external ?? localTabStopId.value,
+  set: (value) => {
+    localTabStopId.value = value;
+    return value;
+  },
+});
+
+// Group reachability: when the user tabs back out (Shift+Tab) we drop the group
+// from the tab order until focus returns; when every item is disabled there is
+// no roving item, so the group itself becomes the single tab stop instead of the
+// toolbar silently leaving the tab sequence.
+const isTabbingBackOut = ref(false);
+
+// Read fresh rather than through `items`: `getItems` filters on live
+// `data-disabled`, which the computed cannot track across runtime toggles.
+function enabledItems(): HTMLElement[] {
+  return getItems().map(i => i.ref);
+}
+
+const groupTabindex = computed(() =>
+  isTabbingBackOut.value || items.value.length === 0 ? -1 : 0,
+);
+
+function focusIndex(i: number): void {
+  const el = enabledItems()[i];
+  if (!el) return;
+  el.focus({ preventScroll: preventScrollOnEntryFocus });
+  // Commit only when focus actually landed, so the tab stop never moves
+  // onto an element that refused focus.
+  if (document.activeElement === el) {
+    activeIndex.value = i;
+    currentTabStopId.value = el.id || null;
+  }
+}
+
+function onItemFocus(el: HTMLElement): void {
+  const idx = enabledItems().indexOf(el);
+  if (idx === -1) return;
+  activeIndex.value = idx;
+  currentTabStopId.value = el.id || null;
+}
+
+function onItemShiftTab(): void {
+  isTabbingBackOut.value = true;
+}
+
+function onItemKeyDown(event: KeyboardEvent, el: HTMLElement): void {
+  // A keydown bubbling up from a descendant (e.g. an input nested in a custom
+  // item) must not be hijacked for roving navigation.
+  if (event.target !== event.currentTarget) return;
+
+  const action = rovingKeyToAction(event, { orientation, dir: direction.value, loop });
+  // `rovingKeyToAction` only handles Arrow/Home/End; map PageUp/PageDown to the
+  // first/last enabled item locally (the shared util is intentionally minimal).
+  const pageAbsolute = event.key === 'PageUp'
+    ? 'home'
+    : event.key === 'PageDown' ? 'end' : undefined;
+  if (!action && !pageAbsolute) return;
+
+  // Leave browser/OS shortcuts (Ctrl+Home, etc.) untouched.
+  if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
+
+  event.preventDefault();
+  const list = enabledItems();
+  const idx = list.indexOf(el);
+  const absolute = action?.absolute ?? pageAbsolute;
+  if (absolute === 'home') return focusIndex(0);
+  if (absolute === 'end') return focusIndex(list.length - 1);
+  focusIndex(resolveNextIndex(idx, action!.delta, list.length, loop));
+}
+
+// Entry focus: when keyboard focus first lands on the group element, redirect it
+// to the current / first enabled item instead of resting on the wrapper. A
+// mouse-driven focus skips this so clicking an item keeps that item focused.
+const isClickFocus = ref(false);
+
+function handleGroupFocus(event: FocusEvent): void {
+  const isKeyboardFocus = !isClickFocus.value;
+  if (
+    event.currentTarget
+    && event.target === event.currentTarget
+    && isKeyboardFocus
+    && !isTabbingBackOut.value
+  ) {
+    const entryFocusEvent = new CustomEvent('toolbar.entryFocus', {
+      bubbles: false,
+      cancelable: true,
+    });
+    event.currentTarget.dispatchEvent(entryFocusEvent);
+    emit('entryFocus', entryFocusEvent);
+
+    if (!entryFocusEvent.defaultPrevented) {
+      const list = enabledItems();
+      const current = list.find(el => el.id && el.id === currentTabStopId.value);
+      const target = current ?? list[activeIndex.value] ?? list[0];
+      if (target) target.focus({ preventScroll: preventScrollOnEntryFocus });
+    }
+  }
+  isClickFocus.value = false;
+}
+
+function handleGroupMouseUp(): void {
+  // Reset after a tick: a click may not raise a focus event on the wrapper.
+  setTimeout(() => {
+    isClickFocus.value = false;
+  }, 1);
+}
+
+// Keep the committed tab stop pointing at a still-enabled item: if items are
+// toggled disabled at runtime, fall back to the first enabled one.
+watchSyncEffect(() => {
+  const list = items.value;
+  if (list.length === 0) return;
+  if (activeIndex.value >= list.length) activeIndex.value = 0;
+});
+
+provideToolbarContext({
+  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
+  orientation: toRef(() => orientation),
+  direction,
+  loop: toRef(() => loop),
+  items,
+  activeIndex,
+  focusIndex,
+  onItemKeyDown,
+  onItemFocus,
+  onItemShiftTab,
+});
+</script>
+
+<template>
+  <CollectionSlot>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      role="toolbar"
+      :tabindex="groupTabindex"
+      :aria-orientation="orientation"
+      :dir="direction"
+      :data-orientation="orientation"
+      style="outline: none"
+      @mousedown="isClickFocus = true"
+      @mouseup="handleGroupMouseUp"
+      @focus="handleGroupFocus"
+      @blur="isTabbingBackOut = false"
+    >
+      <slot />
+    </Primitive>
+  </CollectionSlot>
+</template>
diff --git a/vue/primitives/src/toolbar/ToolbarSeparator.vue b/vue/primitives/src/menus/toolbar/ToolbarSeparator.vue
similarity index 58%
rename from vue/primitives/src/toolbar/ToolbarSeparator.vue
rename to vue/primitives/src/menus/toolbar/ToolbarSeparator.vue
index 3f246b1..904f0dc 100644
--- a/vue/primitives/src/toolbar/ToolbarSeparator.vue
+++ b/vue/primitives/src/menus/toolbar/ToolbarSeparator.vue
@@ -1,38 +1,48 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A visual divider that delimits groups of controls inside a `ToolbarRoot`,
  * exposed as `role="separator"`. When `orientation` is omitted it inherits the
  * opposite of the toolbar's orientation (a horizontal toolbar gets a vertical
- * separator), so it sits correctly across the line of items by default.
+ * separator), so it sits correctly across the line of items by default. Mark it
+ * `decorative` to drop it from the accessibility tree entirely.
  */
 export interface ToolbarSeparatorProps extends PrimitiveProps {
   orientation?: 'horizontal' | 'vertical';
-
+  /**
+   * When `true` the separator is purely decorative and is hidden from
+   * assistive technology (`role="none"`, no `aria-orientation`). Otherwise it
+   * exposes `role="separator"` and its `aria-orientation`.
+   * @default false
+   */
+  decorative?: boolean;
 }
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
 import { useToolbarContext } from './context';
 
-const { as = 'span', orientation } = defineProps<ToolbarSeparatorProps>();
+const { as = 'span', orientation, decorative = false } = defineProps<ToolbarSeparatorProps>();
 const { forwardRef } = useForwardExpose();
 const ctx = useToolbarContext();
 // If no orientation passed, inherit from toolbar — but invert (horizontal toolbar needs vertical separator).
 const effective = computed(() => orientation ?? (ctx.orientation.value === 'horizontal' ? 'vertical' : 'horizontal'));
+
+const ariaProps = computed(() => decorative
+  ? { role: 'none' as const, 'aria-orientation': undefined }
+  : { role: 'separator' as const, 'aria-orientation': effective.value });
 </script>
 
 <template>
   <Primitive
     :ref="forwardRef"
     :as="as"
-    role="separator"
-    :aria-orientation="effective"
     :data-orientation="effective"
+    v-bind="ariaProps"
   >
     <slot />
   </Primitive>
diff --git a/vue/primitives/src/menus/toolbar/ToolbarToggleGroup.vue b/vue/primitives/src/menus/toolbar/ToolbarToggleGroup.vue
new file mode 100644
index 0000000..b79c1b3
--- /dev/null
+++ b/vue/primitives/src/menus/toolbar/ToolbarToggleGroup.vue
@@ -0,0 +1,44 @@
+<script lang="ts">
+import type { ToggleGroupRootEmits, ToggleGroupRootProps } from '../../forms/toggle-group';
+
+/**
+ * A `ToggleGroupRoot` adapted for use inside a `ToolbarRoot`. It forwards the
+ * toolbar's orientation and reading direction, and disables the toggle group's
+ * own roving focus (`rovingFocus={false}`) so the toolbar stays the single
+ * keyboard-navigation owner — otherwise two competing roving controllers would
+ * fight over arrow keys. Supports the same single / multiple `v-model`,
+ * `defaultValue`, `type`, `disabled` and `loop` as `ToggleGroupRoot`.
+ */
+export interface ToolbarToggleGroupProps
+  extends Omit<ToggleGroupRootProps, 'rovingFocus' | 'orientation' | 'dir'> {}
+
+export type ToolbarToggleGroupEmits = ToggleGroupRootEmits;
+</script>
+
+<script setup lang="ts">
+import { ToggleGroupRoot } from '../../forms/toggle-group';
+import { useForwardExpose } from '@robonen/vue';
+import { useToolbarContext } from './context';
+
+// No `defineProps`: every consumer prop (`modelValue`, `defaultValue`, `type`,
+// `disabled`, `loop`) plus the `onUpdate:modelValue` / `onValueChange`
+// listeners stay in `$attrs` so they forward verbatim to `ToggleGroupRoot`.
+// `ToolbarToggleGroupProps` / `ToolbarToggleGroupEmits` are exported purely for
+// the public type surface.
+defineOptions({ inheritAttrs: false });
+
+const ctx = useToolbarContext();
+useForwardExpose();
+</script>
+
+<template>
+  <ToggleGroupRoot
+    v-bind="$attrs"
+    :orientation="ctx.orientation.value"
+    :dir="ctx.direction.value"
+    :roving-focus="false"
+    :data-orientation="ctx.orientation.value"
+  >
+    <slot />
+  </ToggleGroupRoot>
+</template>
diff --git a/vue/primitives/src/menus/toolbar/ToolbarToggleItem.vue b/vue/primitives/src/menus/toolbar/ToolbarToggleItem.vue
new file mode 100644
index 0000000..15586ac
--- /dev/null
+++ b/vue/primitives/src/menus/toolbar/ToolbarToggleItem.vue
@@ -0,0 +1,34 @@
+<script lang="ts">
+import type { ToggleGroupItemProps } from '../../forms/toggle-group';
+
+/**
+ * A single toggle button inside a `ToolbarToggleGroup`. It composes a
+ * `ToolbarButton` (which joins the toolbar's roving-focus order) with a
+ * `ToggleGroupItem` (which owns the pressed state, `aria-pressed` /
+ * `aria-checked` and `data-state`), so one control answers to both the
+ * toolbar's keyboard navigation and the toggle group's selection model.
+ */
+export interface ToolbarToggleItemProps extends ToggleGroupItemProps {}
+</script>
+
+<script setup lang="ts">
+import { ToggleGroupItem } from '../../forms/toggle-group';
+import { useForwardExpose } from '@robonen/vue';
+import ToolbarButton from './ToolbarButton.vue';
+
+const { as, value, disabled } = defineProps<ToolbarToggleItemProps>();
+const { forwardRef } = useForwardExpose();
+</script>
+
+<template>
+  <ToolbarButton as="template" :disabled="disabled">
+    <ToggleGroupItem
+      :ref="forwardRef"
+      :value="value"
+      :disabled="disabled"
+      :as="as"
+    >
+      <slot />
+    </ToggleGroupItem>
+  </ToolbarButton>
+</template>
diff --git a/vue/primitives/src/toolbar/__test__/Toolbar.test.ts b/vue/primitives/src/menus/toolbar/__test__/Toolbar.test.ts
similarity index 100%
rename from vue/primitives/src/toolbar/__test__/Toolbar.test.ts
rename to vue/primitives/src/menus/toolbar/__test__/Toolbar.test.ts
diff --git a/vue/primitives/src/menus/toolbar/__test__/ToolbarExtended.test.ts b/vue/primitives/src/menus/toolbar/__test__/ToolbarExtended.test.ts
new file mode 100644
index 0000000..37447cb
--- /dev/null
+++ b/vue/primitives/src/menus/toolbar/__test__/ToolbarExtended.test.ts
@@ -0,0 +1,330 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  ToolbarButton,
+  ToolbarLink,
+  ToolbarRoot,
+  ToolbarSeparator,
+  ToolbarToggleGroup,
+  ToolbarToggleItem,
+} from '../index';
+
+function press(el: Element, key: string, init: KeyboardEventInit = {}): boolean {
+  return el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+}
+
+function mountButtons(opts: Record<string, unknown> = {}, count = 3) {
+  const Harness = defineComponent({
+    setup: () => () => h(ToolbarRoot, opts, {
+      default: () => Array.from({ length: count }, (_, i) =>
+        h(ToolbarButton, { id: `b${i + 1}` }, { default: () => `Item ${i + 1}` })),
+    }),
+  });
+  return mount(Harness, { attachTo: document.body });
+}
+
+describe('Toolbar — group reachability', () => {
+  it('group has tabindex 0 when at least one item is enabled', async () => {
+    const w = mountButtons();
+    await nextTick();
+    expect((w.element as HTMLElement).getAttribute('tabindex')).toBe('0');
+    w.unmount();
+  });
+
+  it('group falls back to tabindex 0 even if no items mounted yet', () => {
+    const Harness = defineComponent({ setup: () => () => h(ToolbarRoot, {}, { default: () => [] }) });
+    const w = mount(Harness, { attachTo: document.body });
+    // No enabled items -> group itself carries the tab stop (-1 once empty).
+    expect((w.element as HTMLElement).getAttribute('tabindex')).toBe('-1');
+    w.unmount();
+  });
+
+  it('Shift+Tab on an item drops the group out of the tab order until blur', async () => {
+    const w = mountButtons();
+    await nextTick();
+    const btns = document.querySelectorAll<HTMLElement>('button');
+    btns[0]!.focus();
+    press(btns[0]!, 'Tab', { shiftKey: true });
+    await nextTick();
+    expect((w.element as HTMLElement).getAttribute('tabindex')).toBe('-1');
+    // blur on the group resets the tabbing-back-out flag
+    (w.element as HTMLElement).dispatchEvent(new FocusEvent('blur'));
+    await nextTick();
+    expect((w.element as HTMLElement).getAttribute('tabindex')).toBe('0');
+    w.unmount();
+  });
+});
+
+describe('Toolbar — PageUp / PageDown', () => {
+  it('PageDown jumps to last, PageUp to first', async () => {
+    const w = mountButtons();
+    await nextTick();
+    const btns = document.querySelectorAll<HTMLElement>('button');
+    btns[0]!.focus();
+    press(btns[0]!, 'PageDown');
+    await nextTick();
+    expect(document.activeElement).toBe(btns[2]);
+    press(btns[2]!, 'PageUp');
+    await nextTick();
+    expect(document.activeElement).toBe(btns[0]);
+    w.unmount();
+  });
+});
+
+describe('Toolbar — keyboard guards', () => {
+  it('ignores arrow navigation when a modifier key is held', async () => {
+    const w = mountButtons();
+    await nextTick();
+    const btns = document.querySelectorAll<HTMLElement>('button');
+    btns[0]!.focus();
+    const notPrevented = press(btns[0]!, 'ArrowRight', { ctrlKey: true });
+    await nextTick();
+    expect(document.activeElement).toBe(btns[0]);
+    // event was not preventDefault'd, so the browser shortcut is left intact
+    expect(notPrevented).toBe(true);
+    w.unmount();
+  });
+
+  it('does not hijack keys originating from a nested element', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, {}, {
+        default: () => [
+          h(ToolbarButton, { id: 'b1' }, { default: () => [h('input', { id: 'nested' })] }),
+          h(ToolbarButton, { id: 'b2' }, { default: () => 'Two' }),
+        ],
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const input = document.getElementById('nested')!;
+    const btns = document.querySelectorAll<HTMLElement>('button');
+    btns[0]!.focus();
+    // keydown bubbling from the nested input must not move roving focus
+    press(input, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).not.toBe(btns[1]);
+    w.unmount();
+  });
+});
+
+describe('Toolbar — entry focus', () => {
+  it('focusing the group element redirects focus to the first item', async () => {
+    const w = mountButtons();
+    await nextTick();
+    const root = w.element as HTMLElement;
+    const btns = document.querySelectorAll<HTMLElement>('button');
+    root.dispatchEvent(new FocusEvent('focus'));
+    await nextTick();
+    expect(document.activeElement).toBe(btns[0]);
+    w.unmount();
+  });
+
+  it('entryFocus emit can preventDefault to keep focus on the group', async () => {
+    const onEntry = vi.fn((e: Event) => e.preventDefault());
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, { onEntryFocus: onEntry }, {
+        default: () => [h(ToolbarButton, { id: 'b1' }, { default: () => 'One' })],
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const root = w.element as HTMLElement;
+    const btn = document.querySelector<HTMLElement>('button')!;
+    root.dispatchEvent(new FocusEvent('focus'));
+    await nextTick();
+    expect(onEntry).toHaveBeenCalled();
+    expect(document.activeElement).not.toBe(btn);
+    w.unmount();
+  });
+});
+
+describe('Toolbar — currentTabStopId v-model', () => {
+  it('emits update:currentTabStopId when focus moves between items', async () => {
+    const current = ref<string | null>(null);
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, {
+        currentTabStopId: current.value,
+        'onUpdate:currentTabStopId': (v: string | null | undefined) => { current.value = v ?? null; },
+      }, {
+        default: () => [
+          h(ToolbarButton, { id: 'b1' }, { default: () => 'One' }),
+          h(ToolbarButton, { id: 'b2' }, { default: () => 'Two' }),
+        ],
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const btns = document.querySelectorAll<HTMLElement>('button');
+    btns[0]!.focus();
+    btns[0]!.dispatchEvent(new FocusEvent('focus'));
+    await nextTick();
+    expect(current.value).toBe('b1');
+    btns[0]!.focus();
+    press(btns[0]!, 'ArrowRight');
+    await nextTick();
+    expect(current.value).toBe('b2');
+    w.unmount();
+  });
+});
+
+describe('ToolbarSeparator — decorative', () => {
+  it('decorative separator is removed from the a11y tree', () => {
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, {}, {
+        default: () => [
+          h(ToolbarButton, { id: 'b1' }, { default: () => 'One' }),
+          h(ToolbarSeparator, { decorative: true }),
+          h(ToolbarButton, { id: 'b2' }, { default: () => 'Two' }),
+        ],
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    const sep = w.element.querySelector<HTMLElement>('[role="none"]');
+    expect(sep).not.toBeNull();
+    expect(sep!.getAttribute('aria-orientation')).toBeNull();
+    expect(w.element.querySelector('[role="separator"]')).toBeNull();
+    w.unmount();
+  });
+});
+
+describe('ToolbarLink', () => {
+  function mountWithLink() {
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, {}, {
+        default: () => [
+          h(ToolbarButton, { id: 'b1' }, { default: () => 'One' }),
+          h(ToolbarLink, { id: 'l1', href: '#target' }, { default: () => 'Link' }),
+        ],
+      }),
+    });
+    return mount(Harness, { attachTo: document.body });
+  }
+
+  it('renders an anchor that participates in roving focus', async () => {
+    const w = mountWithLink();
+    await nextTick();
+    const link = document.getElementById('l1')!;
+    expect(link.tagName).toBe('A');
+    const btn = document.querySelector<HTMLElement>('button')!;
+    btn.focus();
+    press(btn, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(link);
+    w.unmount();
+  });
+
+  it('Space triggers a click on the link', async () => {
+    const w = mountWithLink();
+    await nextTick();
+    const link = document.getElementById('l1') as HTMLAnchorElement;
+    const clicked = vi.fn();
+    link.addEventListener('click', clicked);
+    link.focus();
+    press(link, ' ');
+    await nextTick();
+    expect(clicked).toHaveBeenCalled();
+    w.unmount();
+  });
+});
+
+describe('ToolbarToggleGroup / ToolbarToggleItem', () => {
+  function mountToggles(props: Record<string, unknown> = {}) {
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, {}, {
+        default: () => [
+          h(ToolbarToggleGroup, { type: 'single', ...props }, {
+            default: () => [
+              h(ToolbarToggleItem, { value: 'left', id: 't-left' }, { default: () => 'L' }),
+              h(ToolbarToggleItem, { value: 'center', id: 't-center' }, { default: () => 'C' }),
+              h(ToolbarToggleItem, { value: 'right', id: 't-right' }, { default: () => 'R' }),
+            ],
+          }),
+        ],
+      }),
+    });
+    return mount(Harness, { attachTo: document.body });
+  }
+
+  it('toggle items render as buttons with toggle state', async () => {
+    const w = mountToggles();
+    await nextTick();
+    const items = document.querySelectorAll<HTMLElement>('[id^="t-"]');
+    expect(items.length).toBe(3);
+    expect(items[0]!.tagName).toBe('BUTTON');
+    expect(items[0]!.getAttribute('data-state')).toBe('off');
+    items[0]!.click();
+    await nextTick();
+    expect(items[0]!.getAttribute('data-state')).toBe('on');
+    // single mode: clicking another deselects the first
+    items[1]!.click();
+    await nextTick();
+    expect(items[0]!.getAttribute('data-state')).toBe('off');
+    expect(items[1]!.getAttribute('data-state')).toBe('on');
+    w.unmount();
+  });
+
+  it('toggle items join the toolbar roving order (arrow keys move between them)', async () => {
+    const w = mountToggles();
+    await nextTick();
+    const items = document.querySelectorAll<HTMLElement>('[id^="t-"]');
+    items[0]!.focus();
+    press(items[0]!, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(items[1]);
+    w.unmount();
+  });
+
+  it('multiple mode allows several pressed at once via v-model', async () => {
+    const model = ref<string[]>([]);
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, {}, {
+        default: () => [
+          h(ToolbarToggleGroup, {
+            type: 'multiple',
+            modelValue: model.value,
+            'onUpdate:modelValue': (v: string[]) => { model.value = v; },
+          }, {
+            default: () => [
+              h(ToolbarToggleItem, { value: 'bold', id: 'm-bold' }, { default: () => 'B' }),
+              h(ToolbarToggleItem, { value: 'italic', id: 'm-italic' }, { default: () => 'I' }),
+            ],
+          }),
+        ],
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    document.getElementById('m-bold')!.click();
+    await nextTick();
+    document.getElementById('m-italic')!.click();
+    await nextTick();
+    expect(model.value).toEqual(['bold', 'italic']);
+    w.unmount();
+  });
+
+  it('disabled toggle item is skipped by toolbar roving', async () => {
+    const Harness = defineComponent({
+      setup: () => () => h(ToolbarRoot, {}, {
+        default: () => [
+          h(ToolbarToggleGroup, { type: 'single' }, {
+            default: () => [
+              h(ToolbarToggleItem, { value: 'a', id: 'd-a' }, { default: () => 'A' }),
+              h(ToolbarToggleItem, { value: 'b', id: 'd-b', disabled: true }, { default: () => 'B' }),
+              h(ToolbarToggleItem, { value: 'c', id: 'd-c' }, { default: () => 'C' }),
+            ],
+          }),
+        ],
+      }),
+    });
+    const w = mount(Harness, { attachTo: document.body });
+    await nextTick();
+    const a = document.getElementById('d-a')!;
+    const c = document.getElementById('d-c')!;
+    a.focus();
+    press(a, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(c);
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/menus/toolbar/context.ts b/vue/primitives/src/menus/toolbar/context.ts
new file mode 100644
index 0000000..a70779b
--- /dev/null
+++ b/vue/primitives/src/menus/toolbar/context.ts
@@ -0,0 +1,37 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { RovingDirection, RovingOrientation } from '../../internal/utils/roving-focus';
+import { useContextFactory } from '@robonen/vue';
+
+export interface ToolbarContext {
+  orientation: Ref<RovingOrientation>;
+  direction: Ref<RovingDirection>;
+  loop: Ref<boolean>;
+  /** DOM-ordered items, sourced from the internal Collection. */
+  items: ComputedRef<HTMLElement[]>;
+  activeIndex: Ref<number>;
+  focusIndex: (i: number) => void;
+  onItemKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
+  /**
+   * Notify the root that an item received focus, so the current tab stop
+   * follows the focused control (backs `currentTabStopId` / roving tabindex).
+   */
+  onItemFocus: (el: HTMLElement) => void;
+  /**
+   * Notify the root that the user pressed `Shift+Tab` to leave the toolbar, so
+   * the group element drops out of the tab order until focus comes back.
+   */
+  onItemShiftTab: () => void;
+}
+
+const ctx = useContextFactory<ToolbarContext>('ToolbarContext');
+
+export const provideToolbarContext = ctx.provide;
+export const useToolbarContext = ctx.inject;
+
+/**
+ * Dedicated collection key for toolbar items. A `ToolbarToggleGroup` nests a
+ * `ToggleGroupRoot`, which provides its own default-key collection; using a
+ * namespaced key here keeps the toolbar's roving collection from being shadowed
+ * so that `ToolbarToggleItem`s still register with the toolbar for navigation.
+ */
+export const TOOLBAR_COLLECTION_KEY = 'toolbar';
diff --git a/vue/primitives/src/toolbar/demo.vue b/vue/primitives/src/menus/toolbar/demo.vue
similarity index 72%
rename from vue/primitives/src/toolbar/demo.vue
rename to vue/primitives/src/menus/toolbar/demo.vue
index 4bf9173..53b04f3 100644
--- a/vue/primitives/src/toolbar/demo.vue
+++ b/vue/primitives/src/menus/toolbar/demo.vue
@@ -18,9 +18,9 @@ const alignments = [
 </script>
 
 <template>
-  <div class="flex w-full max-w-md flex-col gap-3 rounded-xl border border-(--border) bg-(--bg-elevated) p-4 text-(--fg)">
+  <div class="demo-card flex w-full max-w-md flex-col gap-3 p-4 text-fg">
     <ToolbarRoot
-      class="flex w-fit items-center gap-1 rounded-lg border border-(--border) bg-(--bg-inset) p-1"
+      class="flex w-fit items-center gap-1 rounded-lg border border-border bg-bg-inset p-1"
       aria-label="Text formatting"
     >
       <ToolbarButton
@@ -28,9 +28,9 @@ const alignments = [
         :key="m"
         :title="m.charAt(0).toUpperCase() + m.slice(1)"
         :class="[
-          marks[m] ? 'bg-(--accent) text-(--accent-fg)' : 'text-(--fg-muted) hover:bg-(--bg-subtle)',
+          marks[m] ? 'bg-accent text-accent-fg' : 'text-fg-muted hover:bg-bg-subtle',
         ]"
-        class="grid h-8 w-8 place-items-center rounded-md outline-none transition-colors focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="grid h-8 w-8 place-items-center rounded-md outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring"
         @click="toggle(m)"
       >
         <span
@@ -43,34 +43,34 @@ const alignments = [
         />
       </ToolbarButton>
 
-      <ToolbarSeparator class="mx-1 h-5 w-px bg-(--border)" />
+      <ToolbarSeparator class="mx-1 h-5 w-px bg-border" />
 
       <ToolbarButton
         v-for="a in alignments"
         :key="a.value"
         :title="a.title"
         :class="[
-          align === a.value ? 'bg-(--accent) text-(--accent-fg)' : 'text-(--fg-muted) hover:bg-(--bg-subtle)',
+          align === a.value ? 'bg-accent text-accent-fg' : 'text-fg-muted hover:bg-bg-subtle',
         ]"
-        class="grid h-8 w-8 place-items-center rounded-md outline-none transition-colors focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="grid h-8 w-8 place-items-center rounded-md outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring"
         @click="align = a.value"
       >
         <span :class="a.icon" class="h-4 w-4" />
       </ToolbarButton>
 
-      <ToolbarSeparator class="mx-1 h-5 w-px bg-(--border)" />
+      <ToolbarSeparator class="mx-1 h-5 w-px bg-border" />
 
       <ToolbarButton
         title="Delete"
         disabled
-        class="grid h-8 w-8 place-items-center rounded-md text-(--fg-muted) outline-none transition-colors hover:bg-(--bg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring) data-[disabled]:cursor-not-allowed data-[disabled]:opacity-40"
+        class="grid h-8 w-8 place-items-center rounded-md text-fg-muted outline-none transition-colors hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-ring data-[disabled]:cursor-not-allowed data-[disabled]:opacity-40"
       >
         <span class="i-ph-trash h-4 w-4" />
       </ToolbarButton>
     </ToolbarRoot>
 
     <p
-      class="rounded-lg border border-(--border) bg-(--bg-subtle) px-3 py-4 text-sm"
+      class="rounded-lg border border-border bg-bg-subtle px-3 py-4 text-sm"
       :class="[
         { 'font-bold': marks.bold },
         { 'italic': marks.italic },
diff --git a/vue/primitives/src/menus/toolbar/index.ts b/vue/primitives/src/menus/toolbar/index.ts
new file mode 100644
index 0000000..26318b5
--- /dev/null
+++ b/vue/primitives/src/menus/toolbar/index.ts
@@ -0,0 +1,13 @@
+export { default as ToolbarButton } from './ToolbarButton.vue';
+export { default as ToolbarLink } from './ToolbarLink.vue';
+export { default as ToolbarRoot } from './ToolbarRoot.vue';
+export { default as ToolbarSeparator } from './ToolbarSeparator.vue';
+export { default as ToolbarToggleGroup } from './ToolbarToggleGroup.vue';
+export { default as ToolbarToggleItem } from './ToolbarToggleItem.vue';
+export type { ToolbarButtonProps } from './ToolbarButton.vue';
+export type { ToolbarLinkProps } from './ToolbarLink.vue';
+export type { ToolbarRootEmits, ToolbarRootProps } from './ToolbarRoot.vue';
+export type { ToolbarSeparatorProps } from './ToolbarSeparator.vue';
+export type { ToolbarToggleGroupEmits, ToolbarToggleGroupProps } from './ToolbarToggleGroup.vue';
+export type { ToolbarToggleItemProps } from './ToolbarToggleItem.vue';
+export { useToolbarContext, type ToolbarContext } from './context';
diff --git a/vue/primitives/src/pagination/PaginationEllipsis.vue b/vue/primitives/src/navigation/pagination/PaginationEllipsis.vue
similarity index 85%
rename from vue/primitives/src/pagination/PaginationEllipsis.vue
rename to vue/primitives/src/navigation/pagination/PaginationEllipsis.vue
index a89f754..a08a161 100644
--- a/vue/primitives/src/pagination/PaginationEllipsis.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationEllipsis.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A non-interactive placeholder shown where page links are collapsed into a
@@ -10,7 +10,7 @@ export interface PaginationEllipsisProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 
 const { as = 'span' as const } = defineProps<PaginationEllipsisProps>();
diff --git a/vue/primitives/src/pagination/PaginationFirst.vue b/vue/primitives/src/navigation/pagination/PaginationFirst.vue
similarity index 71%
rename from vue/primitives/src/pagination/PaginationFirst.vue
rename to vue/primitives/src/navigation/pagination/PaginationFirst.vue
index 133a6b3..87e9133 100644
--- a/vue/primitives/src/pagination/PaginationFirst.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationFirst.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that jumps to the first page. Renders as a `<button>`, is
@@ -10,7 +10,7 @@ export interface PaginationFirstProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
@@ -25,13 +25,17 @@ const disabled = computed(() => ctx.isFirstPage.value || ctx.disabled.value);
 const attrs = computed(() => ({
   'aria-label': 'First Page',
   type: as === 'button' ? 'button' as const : undefined,
-  disabled: disabled.value,
+  disabled: disabled.value || undefined,
+  'aria-disabled': disabled.value && as !== 'button' ? true : undefined,
+  'data-disabled': disabled.value ? '' : undefined,
 }));
 
-function handleClick() {
-  if (!disabled.value) {
-    ctx.onPageChange(1);
+function handleClick(event: MouseEvent) {
+  if (disabled.value) {
+    event.preventDefault();
+    return;
   }
+  ctx.onPageChange(1);
 }
 </script>
 
diff --git a/vue/primitives/src/pagination/PaginationLast.vue b/vue/primitives/src/navigation/pagination/PaginationLast.vue
similarity index 69%
rename from vue/primitives/src/pagination/PaginationLast.vue
rename to vue/primitives/src/navigation/pagination/PaginationLast.vue
index 78dfeeb..5f802dd 100644
--- a/vue/primitives/src/pagination/PaginationLast.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationLast.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that jumps to the last page. Renders as a `<button>`, is
@@ -10,7 +10,7 @@ export interface PaginationLastProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
@@ -25,13 +25,17 @@ const disabled = computed(() => ctx.isLastPage.value || ctx.disabled.value);
 const attrs = computed(() => ({
   'aria-label': 'Last Page',
   type: as === 'button' ? 'button' as const : undefined,
-  disabled: disabled.value,
+  disabled: disabled.value || undefined,
+  'aria-disabled': disabled.value && as !== 'button' ? true : undefined,
+  'data-disabled': disabled.value ? '' : undefined,
 }));
 
-function handleClick() {
-  if (!disabled.value) {
-    ctx.onPageChange(ctx.totalPages.value);
+function handleClick(event: MouseEvent) {
+  if (disabled.value) {
+    event.preventDefault();
+    return;
   }
+  ctx.onPageChange(ctx.totalPages.value);
 }
 </script>
 
diff --git a/vue/primitives/src/pagination/PaginationList.vue b/vue/primitives/src/navigation/pagination/PaginationList.vue
similarity index 89%
rename from vue/primitives/src/pagination/PaginationList.vue
rename to vue/primitives/src/navigation/pagination/PaginationList.vue
index a94a1b8..e2e3994 100644
--- a/vue/primitives/src/pagination/PaginationList.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationList.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The container that computes the visible page sequence (page numbers and
@@ -12,7 +12,7 @@ export interface PaginationListProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import type { PaginationItem } from './utils';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { getRange } from './utils';
 import { injectPaginationContext } from './context';
@@ -23,7 +23,7 @@ const { as = 'div' as const } = defineProps<PaginationListProps>();
 defineSlots<{
   default?: (props: {
     items: PaginationItem[];
-  }) => any;
+  }) => unknown;
 }>();
 
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/pagination/PaginationListItem.vue b/vue/primitives/src/navigation/pagination/PaginationListItem.vue
similarity index 56%
rename from vue/primitives/src/pagination/PaginationListItem.vue
rename to vue/primitives/src/navigation/pagination/PaginationListItem.vue
index fbb46d8..bad9824 100644
--- a/vue/primitives/src/pagination/PaginationListItem.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationListItem.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A single page link. Renders as a `<button>` that selects its `value` page on
@@ -13,7 +13,7 @@ export interface PaginationListItemProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
@@ -25,19 +25,27 @@ const ctx = injectPaginationContext();
 
 const isSelected = computed(() => ctx.currentPage.value === value);
 
-const attrs = computed(() => ({
-  'data-type': 'page',
-  'aria-label': `Page ${value}`,
-  'aria-current': isSelected.value ? 'page' as const : undefined,
-  'data-selected': isSelected.value ? 'true' : undefined,
-  disabled: ctx.disabled.value,
-  type: as === 'button' ? 'button' as const : undefined,
-}));
+const attrs = computed(() => {
+  const isDisabled = ctx.disabled.value;
 
-function handleClick() {
-  if (!ctx.disabled.value) {
-    ctx.onPageChange(value);
+  return {
+    'data-type': 'page',
+    'aria-label': `Page ${value}`,
+    'aria-current': isSelected.value ? 'page' as const : undefined,
+    'data-selected': isSelected.value ? 'true' : undefined,
+    disabled: isDisabled || undefined,
+    'aria-disabled': isDisabled && as !== 'button' ? true : undefined,
+    'data-disabled': isDisabled ? '' : undefined,
+    type: as === 'button' ? 'button' as const : undefined,
+  };
+});
+
+function handleClick(event: MouseEvent) {
+  if (ctx.disabled.value) {
+    event.preventDefault();
+    return;
   }
+  ctx.onPageChange(value);
 }
 </script>
 
diff --git a/vue/primitives/src/pagination/PaginationNext.vue b/vue/primitives/src/navigation/pagination/PaginationNext.vue
similarity index 69%
rename from vue/primitives/src/pagination/PaginationNext.vue
rename to vue/primitives/src/navigation/pagination/PaginationNext.vue
index 8d056df..fcd2e5c 100644
--- a/vue/primitives/src/pagination/PaginationNext.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationNext.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that moves to the next page. Renders as a `<button>`, is
@@ -10,7 +10,7 @@ export interface PaginationNextProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
@@ -25,13 +25,17 @@ const disabled = computed(() => ctx.isLastPage.value || ctx.disabled.value);
 const attrs = computed(() => ({
   'aria-label': 'Next Page',
   type: as === 'button' ? 'button' as const : undefined,
-  disabled: disabled.value,
+  disabled: disabled.value || undefined,
+  'aria-disabled': disabled.value && as !== 'button' ? true : undefined,
+  'data-disabled': disabled.value ? '' : undefined,
 }));
 
-function handleClick() {
-  if (!disabled.value) {
-    ctx.onPageChange(ctx.currentPage.value + 1);
+function handleClick(event: MouseEvent) {
+  if (disabled.value) {
+    event.preventDefault();
+    return;
   }
+  ctx.onPageChange(ctx.currentPage.value + 1);
 }
 </script>
 
diff --git a/vue/primitives/src/pagination/PaginationPrev.vue b/vue/primitives/src/navigation/pagination/PaginationPrev.vue
similarity index 69%
rename from vue/primitives/src/pagination/PaginationPrev.vue
rename to vue/primitives/src/navigation/pagination/PaginationPrev.vue
index 7a0d2d2..04934f6 100644
--- a/vue/primitives/src/pagination/PaginationPrev.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationPrev.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that moves to the previous page. Renders as a `<button>`, is
@@ -10,7 +10,7 @@ export interface PaginationPrevProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
@@ -25,13 +25,17 @@ const disabled = computed(() => ctx.isFirstPage.value || ctx.disabled.value);
 const attrs = computed(() => ({
   'aria-label': 'Previous Page',
   type: as === 'button' ? 'button' as const : undefined,
-  disabled: disabled.value,
+  disabled: disabled.value || undefined,
+  'aria-disabled': disabled.value && as !== 'button' ? true : undefined,
+  'data-disabled': disabled.value ? '' : undefined,
 }));
 
-function handleClick() {
-  if (!disabled.value) {
-    ctx.onPageChange(ctx.currentPage.value - 1);
+function handleClick(event: MouseEvent) {
+  if (disabled.value) {
+    event.preventDefault();
+    return;
   }
+  ctx.onPageChange(ctx.currentPage.value - 1);
 }
 </script>
 
diff --git a/vue/primitives/src/pagination/PaginationRoot.vue b/vue/primitives/src/navigation/pagination/PaginationRoot.vue
similarity index 76%
rename from vue/primitives/src/pagination/PaginationRoot.vue
rename to vue/primitives/src/navigation/pagination/PaginationRoot.vue
index f17a7f6..e394dc0 100644
--- a/vue/primitives/src/pagination/PaginationRoot.vue
+++ b/vue/primitives/src/navigation/pagination/PaginationRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Splits a large collection into discrete pages and lets users move between
@@ -14,8 +14,8 @@ import type { PrimitiveProps } from '../primitive';
  * `pageCount`.
  */
 export interface PaginationRootProps extends PrimitiveProps {
-  /** Total number of items across all pages. */
-  total: number;
+  /** Total number of items across all pages. @default 0 */
+  total?: number;
 
   /** Number of items per page; combined with `total` to derive the page count. @default 10 */
   pageSize?: number;
@@ -31,23 +31,36 @@ export interface PaginationRootProps extends PrimitiveProps {
 
   /** Initial page for uncontrolled usage (when `v-model:page` is not bound). @default 1 */
   defaultPage?: number;
+
+  /**
+   * Accessible name for the navigation landmark, applied as `aria-label` on the
+   * root. Pass `null` to opt out of the label entirely. @default 'pagination'
+   */
+  label?: string | null;
+}
+
+/** Emits contract for `PaginationRoot`. Mirrors the `v-model:page` binding. */
+export interface PaginationRootEmits {
+  /** Fired when the current page changes (via controls or page links). */
+  'update:page': [value: number];
 }
 </script>
 
 <script setup lang="ts">
 import { useForwardExpose, useOffsetPagination } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { providePaginationContext } from './context';
-import { toRef } from 'vue';
+import { computed, toRef } from 'vue';
 
 const {
   as = 'nav' as const,
-  total,
+  total = 0,
   pageSize = 10,
   siblingCount = 1,
   showEdges = false,
   disabled = false,
   defaultPage = 1,
+  label = 'pagination',
 } = defineProps<PaginationRootProps>();
 
 const page = defineModel<number>('page', { default: undefined });
@@ -60,11 +73,13 @@ defineSlots<{
   default?: (props: {
     page: number;
     pageCount: number;
-  }) => any;
+  }) => unknown;
 }>();
 
 const { forwardRef } = useForwardExpose();
 
+const ariaLabel = computed(() => label ?? undefined);
+
 const {
   currentPage,
   totalPages,
@@ -103,6 +118,7 @@ providePaginationContext({
   <Primitive
     :ref="forwardRef"
     :as
+    :aria-label="ariaLabel"
   >
     <slot
       :page="page!"
diff --git a/vue/primitives/src/pagination/__test__/Pagination.test.ts b/vue/primitives/src/navigation/pagination/__test__/Pagination.test.ts
similarity index 55%
rename from vue/primitives/src/pagination/__test__/Pagination.test.ts
rename to vue/primitives/src/navigation/pagination/__test__/Pagination.test.ts
index 6979b76..ad72908 100644
--- a/vue/primitives/src/pagination/__test__/Pagination.test.ts
+++ b/vue/primitives/src/navigation/pagination/__test__/Pagination.test.ts
@@ -365,6 +365,261 @@ describe('PaginationLast', () => {
   });
 });
 
+describe('PaginationRoot empty collection (total defaults to 0)', () => {
+  function createEmpty(props: Record<string, unknown> = {}) {
+    return mount(
+      defineComponent({
+        setup() {
+          return () =>
+            h(
+              PaginationRoot,
+              { ...props },
+              {
+                default: () => [
+                  h(PaginationList, null, {
+                    default: ({ items }: { items: PaginationItem[] }) =>
+                      items.map((item, i) =>
+                        item.type === 'page'
+                          ? h(PaginationListItem, { key: i, value: item.value })
+                          : h(PaginationEllipsis, { key: `e-${i}` }),
+                      ),
+                  }),
+                  h(PaginationFirst),
+                  h(PaginationPrev),
+                  h(PaginationNext),
+                  h(PaginationLast),
+                ],
+              },
+            );
+        },
+      }),
+      { attachTo: document.body },
+    );
+  }
+
+  it('treats total as optional with a default of 0', () => {
+    const wrapper = createEmpty();
+
+    expect(wrapper.find('nav').exists()).toBe(true);
+
+    wrapper.unmount();
+  });
+
+  it('shows page 1 selected with no total', () => {
+    const wrapper = createEmpty();
+
+    const selected = wrapper.find('[data-selected]');
+    expect(selected.exists()).toBe(true);
+    expect(selected.text()).toBe('1');
+
+    wrapper.unmount();
+  });
+
+  it('renders exactly one page button with no total', () => {
+    const wrapper = createEmpty();
+
+    expect(wrapper.findAll('[data-type="page"]').length).toBe(1);
+
+    wrapper.unmount();
+  });
+
+  it('disables every control with no total', () => {
+    const wrapper = createEmpty();
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('disabled')).toBeDefined();
+    expect(wrapper.find('[aria-label="Previous Page"]').attributes('disabled')).toBeDefined();
+    expect(wrapper.find('[aria-label="Next Page"]').attributes('disabled')).toBeDefined();
+    expect(wrapper.find('[aria-label="Last Page"]').attributes('disabled')).toBeDefined();
+
+    wrapper.unmount();
+  });
+
+  it('disables every control with explicit total: 0', () => {
+    const wrapper = createEmpty({ total: 0 });
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('disabled')).toBeDefined();
+    expect(wrapper.find('[aria-label="Last Page"]').attributes('disabled')).toBeDefined();
+
+    wrapper.unmount();
+  });
+});
+
+describe('PaginationRoot nav label', () => {
+  it('labels the nav landmark by default', () => {
+    const wrapper = createPagination();
+
+    expect(wrapper.find('nav').attributes('aria-label')).toBe('pagination');
+
+    wrapper.unmount();
+  });
+
+  it('accepts a custom label', () => {
+    const wrapper = createPagination({ label: 'Search results pages' });
+
+    expect(wrapper.find('nav').attributes('aria-label')).toBe('Search results pages');
+
+    wrapper.unmount();
+  });
+
+  it('omits the label when label is null', () => {
+    const wrapper = createPagination({ label: null });
+
+    expect(wrapper.find('nav').attributes('aria-label')).toBeUndefined();
+
+    wrapper.unmount();
+  });
+});
+
+describe('Pagination disabled state attributes', () => {
+  it('sets data-disabled on every control when disabled', () => {
+    const wrapper = createPagination({ page: 5, disabled: true });
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('data-disabled')).toBe('');
+    expect(wrapper.find('[aria-label="Previous Page"]').attributes('data-disabled')).toBe('');
+    expect(wrapper.find('[aria-label="Next Page"]').attributes('data-disabled')).toBe('');
+    expect(wrapper.find('[aria-label="Last Page"]').attributes('data-disabled')).toBe('');
+    wrapper.findAll('[data-type="page"]').forEach((btn) => {
+      expect(btn.attributes('data-disabled')).toBe('');
+    });
+
+    wrapper.unmount();
+  });
+
+  it('sets data-disabled on the boundary controls even when not globally disabled', () => {
+    const wrapper = createPagination({ page: 1 });
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('data-disabled')).toBe('');
+    expect(wrapper.find('[aria-label="Previous Page"]').attributes('data-disabled')).toBe('');
+    expect(wrapper.find('[aria-label="Next Page"]').attributes('data-disabled')).toBeUndefined();
+
+    wrapper.unmount();
+  });
+
+  it('omits data-disabled on enabled controls', () => {
+    const wrapper = createPagination({ page: 5 });
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('data-disabled')).toBeUndefined();
+    expect(wrapper.find('[aria-label="Next Page"]').attributes('data-disabled')).toBeUndefined();
+
+    wrapper.unmount();
+  });
+
+  it('does not set aria-disabled on native button hosts', () => {
+    const wrapper = createPagination({ page: 1 });
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('aria-disabled')).toBeUndefined();
+
+    wrapper.unmount();
+  });
+});
+
+function createLinkPagination(props: Record<string, unknown> = {}) {
+  return mount(
+    defineComponent({
+      setup() {
+        const page = ref((props.page as number) ?? 1);
+
+        return () =>
+          h(
+            PaginationRoot,
+            {
+              total: 100,
+              pageSize: 10,
+              ...props,
+              page: page.value,
+              'onUpdate:page': (v: number) => {
+                page.value = v;
+              },
+            },
+            {
+              default: () => [
+                h(PaginationList, null, {
+                  default: ({ items }: { items: PaginationItem[] }) =>
+                    items.map((item, i) =>
+                      item.type === 'page'
+                        ? h(PaginationListItem, { key: i, value: item.value, as: 'a' })
+                        : h(PaginationEllipsis, { key: `ellipsis-${i}` }),
+                    ),
+                }),
+                h(PaginationFirst, { as: 'a' }),
+                h(PaginationPrev, { as: 'a' }),
+                h(PaginationNext, { as: 'a' }),
+                h(PaginationLast, { as: 'a' }),
+              ],
+            },
+          );
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+describe('Pagination with anchor (as="a") controls', () => {
+  it('sets aria-disabled on disabled anchor controls', () => {
+    const wrapper = createLinkPagination({ page: 1 });
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('aria-disabled')).toBe('true');
+    expect(wrapper.find('[aria-label="Previous Page"]').attributes('aria-disabled')).toBe('true');
+
+    wrapper.unmount();
+  });
+
+  it('omits aria-disabled on enabled anchor controls', () => {
+    const wrapper = createLinkPagination({ page: 1 });
+
+    expect(wrapper.find('[aria-label="Next Page"]').attributes('aria-disabled')).toBeUndefined();
+    expect(wrapper.find('[aria-label="Last Page"]').attributes('aria-disabled')).toBeUndefined();
+
+    wrapper.unmount();
+  });
+
+  it('sets aria-disabled on every anchor control when globally disabled', () => {
+    const wrapper = createLinkPagination({ page: 5, disabled: true });
+
+    expect(wrapper.find('[aria-label="First Page"]').attributes('aria-disabled')).toBe('true');
+    expect(wrapper.find('[aria-label="Last Page"]').attributes('aria-disabled')).toBe('true');
+    wrapper.findAll('[data-type="page"]').forEach((el) => {
+      expect(el.attributes('aria-disabled')).toBe('true');
+    });
+
+    wrapper.unmount();
+  });
+
+  it('does not navigate when a disabled anchor control is clicked', async () => {
+    const wrapper = createLinkPagination({ page: 1 });
+
+    await wrapper.find('[aria-label="Previous Page"]').trigger('click');
+    await nextTick();
+
+    expect(wrapper.find('[data-selected]').text()).toBe('1');
+
+    wrapper.unmount();
+  });
+
+  it('does not navigate when a disabled anchor page link is clicked', async () => {
+    const wrapper = createLinkPagination({ page: 2, disabled: true });
+
+    const page1 = wrapper.findAll('[data-type="page"]').find(el => el.text() === '1');
+    await page1?.trigger('click');
+    await nextTick();
+
+    expect(wrapper.find('[data-selected]').text()).toBe('2');
+
+    wrapper.unmount();
+  });
+
+  it('still navigates when an enabled anchor control is clicked', async () => {
+    const wrapper = createLinkPagination({ page: 1 });
+
+    await wrapper.find('[aria-label="Next Page"]').trigger('click');
+    await nextTick();
+
+    expect(wrapper.find('[data-selected]').text()).toBe('2');
+
+    wrapper.unmount();
+  });
+});
+
 describe('PaginationEllipsis', () => {
   it('renders for large page ranges', () => {
     const wrapper = createPagination({ page: 5, total: 200, pageSize: 10 });
diff --git a/vue/primitives/src/pagination/__test__/a11y.test.ts b/vue/primitives/src/navigation/pagination/__test__/a11y.test.ts
similarity index 100%
rename from vue/primitives/src/pagination/__test__/a11y.test.ts
rename to vue/primitives/src/navigation/pagination/__test__/a11y.test.ts
diff --git a/vue/primitives/src/pagination/__test__/utils.test.ts b/vue/primitives/src/navigation/pagination/__test__/utils.test.ts
similarity index 50%
rename from vue/primitives/src/pagination/__test__/utils.test.ts
rename to vue/primitives/src/navigation/pagination/__test__/utils.test.ts
index 26088b3..27d7f38 100644
--- a/vue/primitives/src/pagination/__test__/utils.test.ts
+++ b/vue/primitives/src/navigation/pagination/__test__/utils.test.ts
@@ -116,6 +116,137 @@ describe(getRange, () => {
   });
 });
 
+describe('getRange windowing matrix invariants', () => {
+  function pageValues(items: ReturnType<typeof getRange>): number[] {
+    return items
+      .filter((i): i is { type: 'page'; value: number } => i.type === 'page')
+      .map(i => i.value);
+  }
+
+  const totalsList = [1, 2, 3, 5, 7, 8, 10, 13, 20, 50];
+  const siblingList = [0, 1, 2, 3];
+  const showEdgesList = [false, true];
+
+  it('never produces duplicate page numbers', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const pages = pageValues(getRange(page, totalPages, siblingCount, showEdges));
+            expect(new Set(pages).size).toBe(pages.length);
+          }
+        }
+      }
+    }
+  });
+
+  it('always emits page numbers in strictly increasing order', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const pages = pageValues(getRange(page, totalPages, siblingCount, showEdges));
+            for (let i = 1; i < pages.length; i++)
+              expect(pages[i]!).toBeGreaterThan(pages[i - 1]!);
+          }
+        }
+      }
+    }
+  });
+
+  it('always keeps every page number within [1, totalPages]', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const pages = pageValues(getRange(page, totalPages, siblingCount, showEdges));
+            for (const value of pages) {
+              expect(value).toBeGreaterThanOrEqual(1);
+              expect(value).toBeLessThanOrEqual(totalPages);
+            }
+          }
+        }
+      }
+    }
+  });
+
+  it('always includes the current page', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const pages = pageValues(getRange(page, totalPages, siblingCount, showEdges));
+            expect(pages).toContain(page);
+          }
+        }
+      }
+    }
+  });
+
+  it('always includes the first and last page', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const pages = pageValues(getRange(page, totalPages, siblingCount, showEdges));
+            expect(pages[0]).toBe(1);
+            expect(pages[pages.length - 1]).toBe(totalPages);
+          }
+        }
+      }
+    }
+  });
+
+  it('never places an ellipsis at the first or last slot', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const items = getRange(page, totalPages, siblingCount, showEdges);
+            if (items.length === 0)
+              continue;
+            expect(items[0]!.type).toBe('page');
+            expect(items[items.length - 1]!.type).toBe('page');
+          }
+        }
+      }
+    }
+  });
+
+  it('never places two ellipses adjacently', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const items = getRange(page, totalPages, siblingCount, showEdges);
+            for (let i = 1; i < items.length; i++)
+              expect(items[i]!.type === 'ellipsis' && items[i - 1]!.type === 'ellipsis').toBe(false);
+          }
+        }
+      }
+    }
+  });
+
+  it('always includes the current page siblings when they fit inside the range', () => {
+    for (const totalPages of totalsList) {
+      for (const siblingCount of siblingList) {
+        for (const showEdges of showEdgesList) {
+          for (let page = 1; page <= totalPages; page++) {
+            const pages = pageValues(getRange(page, totalPages, siblingCount, showEdges));
+            for (let s = Math.max(1, page - siblingCount); s <= Math.min(totalPages, page + siblingCount); s++) {
+              // A sibling may legitimately be hidden behind an ellipsis only when
+              // it is not adjacent to the current page window edge; verify the
+              // immediate neighbours (page ± 1) are always present.
+              if (Math.abs(s - page) <= 1)
+                expect(pages).toContain(s);
+            }
+          }
+        }
+      }
+    }
+  });
+});
+
 describe(transform, () => {
   it('converts numbers to page items', () => {
     expect(transform([1, 2, 3])).toEqual([
diff --git a/vue/primitives/src/pagination/context.ts b/vue/primitives/src/navigation/pagination/context.ts
similarity index 100%
rename from vue/primitives/src/pagination/context.ts
rename to vue/primitives/src/navigation/pagination/context.ts
diff --git a/vue/primitives/src/pagination/demo.vue b/vue/primitives/src/navigation/pagination/demo.vue
similarity index 63%
rename from vue/primitives/src/pagination/demo.vue
rename to vue/primitives/src/navigation/pagination/demo.vue
index 7ecc4af..ac06f1d 100644
--- a/vue/primitives/src/pagination/demo.vue
+++ b/vue/primitives/src/navigation/pagination/demo.vue
@@ -30,11 +30,11 @@ const range = computed(() => {
     :page-size="pageSize"
     :sibling-count="1"
     show-edges
-    class="flex flex-col items-center gap-3 text-(--fg)"
+    class="flex flex-col items-center gap-3 text-fg"
   >
-    <p class="text-sm text-(--fg-muted)">
-      Showing <span class="font-medium text-(--fg)">{{ range.start }}–{{ range.end }}</span>
-      of <span class="font-medium text-(--fg)">{{ total }}</span>
+    <p class="text-sm text-fg-muted">
+      Showing <span class="font-medium text-fg">{{ range.start }}–{{ range.end }}</span>
+      of <span class="font-medium text-fg">{{ total }}</span>
     </p>
 
     <PaginationList
@@ -42,7 +42,7 @@ const range = computed(() => {
       class="flex items-center gap-1"
     >
       <PaginationFirst
-        class="grid size-9 place-items-center rounded-md border border-(--border) bg-(--bg) text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) disabled:cursor-not-allowed disabled:opacity-40"
+        class="grid size-9 place-items-center rounded-md border border-border bg-bg text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40"
         aria-label="First page"
       >
         <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -52,7 +52,7 @@ const range = computed(() => {
       </PaginationFirst>
 
       <PaginationPrev
-        class="grid size-9 place-items-center rounded-md border border-(--border) bg-(--bg) text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) disabled:cursor-not-allowed disabled:opacity-40"
+        class="grid size-9 place-items-center rounded-md border border-border bg-bg text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40"
         aria-label="Previous page"
       >
         <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -67,18 +67,18 @@ const range = computed(() => {
         <PaginationListItem
           v-if="item.type === 'page'"
           :value="item.value"
-          class="grid size-9 place-items-center rounded-md border border-(--border) bg-(--bg) text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) data-[selected]:border-(--accent) data-[selected]:bg-(--accent) data-[selected]:text-(--accent-fg) data-[selected]:hover:bg-(--accent-hover)"
+          class="grid size-9 place-items-center rounded-md border border-border bg-bg text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[selected]:border-accent data-[selected]:bg-accent data-[selected]:text-accent-fg data-[selected]:hover:bg-accent-hover"
         >
           {{ item.value }}
         </PaginationListItem>
         <PaginationEllipsis
           v-else
-          class="grid size-9 place-items-center text-sm text-(--fg-subtle)"
+          class="grid size-9 place-items-center text-sm text-fg-subtle"
         />
       </template>
 
       <PaginationNext
-        class="grid size-9 place-items-center rounded-md border border-(--border) bg-(--bg) text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) disabled:cursor-not-allowed disabled:opacity-40"
+        class="grid size-9 place-items-center rounded-md border border-border bg-bg text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40"
         aria-label="Next page"
       >
         <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -87,7 +87,7 @@ const range = computed(() => {
       </PaginationNext>
 
       <PaginationLast
-        class="grid size-9 place-items-center rounded-md border border-(--border) bg-(--bg) text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) disabled:cursor-not-allowed disabled:opacity-40"
+        class="grid size-9 place-items-center rounded-md border border-border bg-bg text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40"
         aria-label="Last page"
       >
         <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -97,7 +97,7 @@ const range = computed(() => {
       </PaginationLast>
     </PaginationList>
 
-    <p class="text-xs text-(--fg-subtle)">
+    <p class="text-xs text-fg-subtle">
       Page {{ page }} of {{ pageCount }}
     </p>
   </PaginationRoot>
diff --git a/vue/primitives/src/pagination/index.ts b/vue/primitives/src/navigation/pagination/index.ts
similarity index 93%
rename from vue/primitives/src/pagination/index.ts
rename to vue/primitives/src/navigation/pagination/index.ts
index addda62..4be557a 100644
--- a/vue/primitives/src/pagination/index.ts
+++ b/vue/primitives/src/navigation/pagination/index.ts
@@ -10,7 +10,7 @@ export { default as PaginationNext } from './PaginationNext.vue';
 export { PaginationCtx, type PaginationContext } from './context';
 export { PaginationItemType, getRange, transform, type PaginationItem, type Pages } from './utils';
 
-export type { PaginationRootProps } from './PaginationRoot.vue';
+export type { PaginationRootEmits, PaginationRootProps } from './PaginationRoot.vue';
 export type { PaginationListProps } from './PaginationList.vue';
 export type { PaginationListItemProps } from './PaginationListItem.vue';
 export type { PaginationEllipsisProps } from './PaginationEllipsis.vue';
diff --git a/vue/primitives/src/pagination/utils.ts b/vue/primitives/src/navigation/pagination/utils.ts
similarity index 100%
rename from vue/primitives/src/pagination/utils.ts
rename to vue/primitives/src/navigation/pagination/utils.ts
diff --git a/vue/primitives/src/navigation/tree/TreeItem.vue b/vue/primitives/src/navigation/tree/TreeItem.vue
new file mode 100644
index 0000000..c0605ec
--- /dev/null
+++ b/vue/primitives/src/navigation/tree/TreeItem.vue
@@ -0,0 +1,190 @@
+<script lang="ts" generic="T">
+import type { FlatItem } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A single node within a `TreeRoot`, rendered once per visible `flatItem`.
+ * Handles click-to-select, click-to-toggle for parents, keyboard interaction,
+ * and the ARIA treeitem attributes (level, set size/position, selected,
+ * expanded). Exposes `isExpanded` / `isSelected` / `isIndeterminate` /
+ * `isDisabled` plus imperative `handleSelect` / `handleToggle` callbacks to its
+ * slot, so custom sub-nodes (a chevron, a checkbox) can drive state
+ * independently.
+ *
+ * `select` and `toggle` are emitted as cancelable events before the root
+ * mutates state — call `event.preventDefault()` to veto.
+ */
+export interface TreeItemProps<U = unknown> extends PrimitiveProps {
+  /** Flattened item produced by `TreeRoot` (from its default slot). */
+  item: FlatItem<U>;
+  /** Disable this specific item. */
+  disabled?: boolean;
+}
+
+export interface TreeItemSelectEventDetail<U = unknown> {
+  originalEvent: Event;
+  value: U;
+  isExpanded: boolean;
+  isSelected: boolean;
+}
+
+export type TreeItemSelectEvent<U = unknown> = CustomEvent<TreeItemSelectEventDetail<U>>;
+export type TreeItemToggleEvent<U = unknown> = CustomEvent<TreeItemSelectEventDetail<U>>;
+
+export interface TreeItemEmits<U = unknown> {
+  /** Fired before selection — cancelable via `event.preventDefault()`. */
+  select: [event: TreeItemSelectEvent<U>];
+  /** Fired before expand/collapse — cancelable via `event.preventDefault()`. */
+  toggle: [event: TreeItemToggleEvent<U>];
+}
+</script>
+
+<script setup lang="ts" generic="T">
+import { computed } from 'vue';
+import { useCollectionInjector } from '../../utilities/collection';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useTreeContext } from './context';
+
+const { as = 'li', item, disabled = false } = defineProps<TreeItemProps<T>>();
+
+const emit = defineEmits<TreeItemEmits<T>>();
+
+const ctx = useTreeContext();
+const { CollectionItem } = useCollectionInjector();
+
+const isDisabled = computed(() => ctx.disabled.value || disabled);
+const isExpanded = computed(() => item.hasChildren && ctx.isExpanded(item.key));
+const isSelected = computed(() => ctx.isSelected(item.key));
+const isIndeterminate = computed(() => ctx.isIndeterminate(item as FlatItem<T>));
+
+// Single-tabstop roving tabindex — only the current tab stop is reachable by
+// Tab; the rest are -1 and reached via arrow keys.
+const isTabStop = computed(() => ctx.currentTabStopKey.value === item.key);
+const tabindex = computed(() => {
+  if (isDisabled.value) return -1;
+  return isTabStop.value ? 0 : -1;
+});
+
+function dispatchSelect(originalEvent: Event): boolean {
+  const event = new CustomEvent('select', {
+    bubbles: false,
+    cancelable: true,
+    detail: {
+      originalEvent,
+      value: item.value as T,
+      isExpanded: isExpanded.value,
+      isSelected: isSelected.value,
+    },
+  }) as TreeItemSelectEvent<T>;
+  emit('select', event);
+  return !event.defaultPrevented;
+}
+
+function dispatchToggle(originalEvent: Event): boolean {
+  const event = new CustomEvent('toggle', {
+    bubbles: false,
+    cancelable: true,
+    detail: {
+      originalEvent,
+      value: item.value as T,
+      isExpanded: isExpanded.value,
+      isSelected: isSelected.value,
+    },
+  }) as TreeItemToggleEvent<T>;
+  emit('toggle', event);
+  return !event.defaultPrevented;
+}
+
+function runSelect(originalEvent: Event): void {
+  if (isDisabled.value) return;
+  if (dispatchSelect(originalEvent)) ctx.select(item.value as T);
+}
+
+function runToggle(originalEvent: Event): void {
+  if (isDisabled.value || !item.hasChildren) return;
+  if (dispatchToggle(originalEvent)) ctx.toggleExpanded(item.value as T);
+}
+
+function onClick(event: MouseEvent): void {
+  if (isDisabled.value) return;
+  event.stopPropagation();
+  runSelect(event);
+  if (item.hasChildren) runToggle(event);
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (isDisabled.value || !currentElement.value) return;
+  // Enter / Space dispatch the cancelable select event first; the root handles
+  // navigation keys. We intercept selection keys here to support preventDefault.
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault();
+    runSelect(event);
+    return;
+  }
+  ctx.onItemKeyDown(event, currentElement.value, item);
+}
+
+function onFocus(): void {
+  if (isDisabled.value) return;
+  ctx.setTabStop(item.key);
+}
+
+// Slot-facing imperative callbacks — let a custom chevron/checkbox drive state.
+function handleSelect(): void {
+  runSelect(new Event('select'));
+}
+function handleToggle(): void {
+  runToggle(new Event('toggle'));
+}
+
+// `defineExpose` must run BEFORE `useForwardExpose`: the composable absorbs a
+// prior expose and merges these slot-facing members alongside the forwarded
+// element ref (mirrors ComboboxItem/AccordionItem).
+defineExpose({
+  isExpanded,
+  isSelected,
+  isIndeterminate,
+  isDisabled,
+  handleSelect,
+  handleToggle,
+});
+
+const { forwardRef, currentElement } = useForwardExpose();
+</script>
+
+<template>
+  <CollectionItem>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      role="treeitem"
+      :tabindex="tabindex"
+      :aria-level="item.level"
+      :aria-setsize="item.setSize"
+      :aria-posinset="item.posInSet"
+      :aria-selected="isSelected"
+      :aria-expanded="item.hasChildren ? isExpanded : undefined"
+      :aria-disabled="isDisabled || undefined"
+      :data-state="item.hasChildren ? (isExpanded ? 'open' : 'closed') : undefined"
+      :data-selected="isSelected ? '' : undefined"
+      :data-indeterminate="isIndeterminate ? '' : undefined"
+      :data-disabled="isDisabled ? '' : undefined"
+      :data-level="item.level"
+      :data-key="item.key"
+      @click="onClick"
+      @keydown="onKeyDown"
+      @focus="onFocus"
+    >
+      <slot
+        :item="item"
+        :is-expanded="isExpanded"
+        :is-selected="isSelected"
+        :is-indeterminate="isIndeterminate"
+        :is-disabled="isDisabled"
+        :handle-select="handleSelect"
+        :handle-toggle="handleToggle"
+      />
+    </Primitive>
+  </CollectionItem>
+</template>
diff --git a/vue/primitives/src/navigation/tree/TreeRoot.vue b/vue/primitives/src/navigation/tree/TreeRoot.vue
new file mode 100644
index 0000000..caf11cf
--- /dev/null
+++ b/vue/primitives/src/navigation/tree/TreeRoot.vue
@@ -0,0 +1,509 @@
+<script lang="ts" generic="T">
+import type { FlatItem } from './utils';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * A hierarchical list of expandable/collapsible nodes with full keyboard
+ * support. Use it to present nested data — file explorers, navigation
+ * sidebars, category pickers, or any place users drill into parent/child
+ * relationships. Works with either nested or flat source data via the
+ * `getKey` / `getChildren` accessors.
+ *
+ * The root owns selection state (single or multiple, controlled via
+ * `v-model` or uncontrolled via `defaultValue`), expanded state
+ * (`v-model:expanded`), roving focus and arrow/Home/End navigation, and
+ * exposes the computed visible `flatItems` through its default slot for
+ * each `TreeItem` to render.
+ */
+export interface TreeRootProps<U = unknown> extends PrimitiveProps {
+  /** Flat or nested item list — children are resolved via `getChildren`. */
+  items: readonly U[];
+  /** Extract a stable unique string key from an item. */
+  getKey: (item: U) => string;
+  /** Return the children of an item, or `undefined` if it is a leaf. */
+  getChildren?: (item: U) => readonly U[] | undefined | null;
+  /**
+   * Return the text label of an item for type-ahead matching. Defaults to the
+   * rendered `textContent` of the item element — supply this for non-text nodes
+   * (icons-only) or to override the matched string.
+   */
+  getLabel?: (item: U) => string;
+  /** Uncontrolled initial selected key(s). */
+  defaultValue?: string | string[];
+  /** Uncontrolled initial expanded keys. */
+  defaultExpanded?: string[];
+  /** Allow selecting multiple items. @default false */
+  multiple?: boolean;
+  /** Disable the entire tree. */
+  disabled?: boolean;
+  /** Writing direction. @default 'ltr' */
+  dir?: 'ltr' | 'rtl';
+  /** When `true`, selecting a parent also selects all of its descendants (requires `multiple`). */
+  propagateSelect?: boolean;
+  /**
+   * When `true`, selecting *all* children of a parent also selects the parent,
+   * and deselecting any child unselects it — partial coverage surfaces as the
+   * item's indeterminate state (requires `multiple`).
+   */
+  bubbleSelect?: boolean;
+  /**
+   * In `multiple` mode, controls how a click/Enter mutates the selection:
+   * `'toggle'` (default) flips membership of the clicked item; `'replace'`
+   * resets the selection to just that item and arms Shift+Arrow range select.
+   * @default 'toggle'
+   */
+  selectionBehavior?: 'toggle' | 'replace';
+}
+</script>
+
+<script setup lang="ts" generic="T">
+import { computed, ref, toRef, watch } from 'vue';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { collectDescendantKeys, flattenVisible, getNextMatch, keysBetween } from './utils';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useConfig } from '../../utilities/config-provider';
+import { refAutoReset, useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { provideTreeContext } from './context';
+
+// Hoisted roving-focus options — reused on every keydown to avoid per-event
+// object allocation (keeps the IC at `rovingKeyToAction` monomorphic).
+const ROVING_OPTS_LTR = { orientation: 'vertical', dir: 'ltr', loop: false } as const;
+const ROVING_OPTS_RTL = { orientation: 'vertical', dir: 'rtl', loop: false } as const;
+
+const {
+  as = 'ul',
+  items,
+  getKey,
+  getChildren = (item: T): readonly T[] | undefined | null => (item as { children?: readonly T[] | null } | undefined)?.children,
+  getLabel,
+  defaultValue,
+  defaultExpanded,
+  multiple = false,
+  disabled = false,
+  dir,
+  propagateSelect = false,
+  bubbleSelect = false,
+  selectionBehavior = 'toggle',
+} = defineProps<TreeRootProps<T>>();
+
+const selectedModel = defineModel<string | string[] | undefined>();
+const expandedModel = defineModel<string[]>('expanded');
+
+const { forwardRef } = useForwardExpose();
+const config = useConfig();
+
+// Writing direction — local prop wins, else inherit from <ConfigProvider>.
+const direction = computed(() => dir ?? config.dir.value);
+
+function normalize(v: string | string[] | undefined): string[] {
+  if (v === undefined) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+// --- Selection state ------------------------------------------------------
+
+const localSelected = ref<string[]>(
+  selectedModel.value !== undefined ? normalize(selectedModel.value) : normalize(defaultValue),
+);
+
+watch(selectedModel, (v) => {
+  if (v === undefined) return;
+  const arr = normalize(v);
+  const cur = localSelected.value;
+  if (arr.length === cur.length && arr.every((x, i) => x === cur[i])) return;
+  localSelected.value = arr;
+});
+
+function commitSelected(next: string[]): void {
+  localSelected.value = next;
+  selectedModel.value = multiple ? next : next[0];
+}
+
+// O(1) membership lookup — replaces linear `.includes()` that was called once
+// per TreeItem's `isSelected` computed, causing O(n²) work on selection change.
+const selectedSet = computed(() => new Set(localSelected.value));
+
+function isSelected(key: string): boolean {
+  return selectedSet.value.has(key);
+}
+
+// Anchor key for Shift+Arrow contiguous range selection (`replace` mode only).
+const anchorKey = ref<string | undefined>(localSelected.value[localSelected.value.length - 1]);
+
+// Walk parent chain upward applying bubbleSelect: a parent becomes selected iff
+// all its (transitive) children are selected. Mutates `set` in place.
+function applyBubbleSelect(value: T, set: Set<string>): void {
+  const byKey = flatByKey.value;
+  let parentKey = byKey.get(getKey(value))?.parentKey;
+  while (parentKey !== undefined) {
+    const parent = byKey.get(parentKey);
+    if (!parent) break;
+    const descendants = collectDescendantKeys(parent.value, getKey, getChildren);
+    const allSelected = descendants.length > 0 && descendants.every(k => set.has(k));
+    if (allSelected) set.add(parentKey);
+    else set.delete(parentKey);
+    parentKey = parent.parentKey;
+  }
+}
+
+function select(value: T): void {
+  if (disabled) return;
+  const key = getKey(value);
+  const current = localSelected.value;
+
+  if (multiple) {
+    const alreadySelected = selectedSet.value.has(key);
+    anchorKey.value = key;
+
+    // `replace` behaviour — collapse selection to just this item (parity with
+    // listbox's selectionBehavior). Shift+Arrow then extends from this anchor.
+    if (selectionBehavior === 'replace') {
+      commitSelected([key]);
+      return;
+    }
+
+    if (propagateSelect) {
+      // `key` + all descendant keys; cascade select/deselect as a unit.
+      const cascadeKeys = collectDescendantKeys(value, getKey, getChildren);
+      cascadeKeys.push(key);
+
+      const merged = new Set(current);
+      if (alreadySelected) {
+        for (let i = 0; i < cascadeKeys.length; i++) merged.delete(cascadeKeys[i]!);
+      }
+      else {
+        for (let i = 0; i < cascadeKeys.length; i++) merged.add(cascadeKeys[i]!);
+      }
+      if (bubbleSelect) applyBubbleSelect(value, merged);
+      commitSelected([...merged]);
+      return;
+    }
+
+    const merged = new Set(current);
+    if (alreadySelected) merged.delete(key);
+    else merged.add(key);
+    if (bubbleSelect) applyBubbleSelect(value, merged);
+    commitSelected([...merged]);
+    return;
+  }
+
+  // single select — toggle off if already selected
+  anchorKey.value = key;
+  if (current[0] === key) commitSelected([]);
+  else commitSelected([key]);
+}
+
+// --- Expanded state -------------------------------------------------------
+
+const localExpanded = ref<string[]>(
+  expandedModel.value !== undefined ? [...expandedModel.value] : [...(defaultExpanded ?? [])],
+);
+
+watch(expandedModel, (v) => {
+  if (v === undefined) return;
+  const cur = localExpanded.value;
+  if (v.length === cur.length && v.every((x, i) => x === cur[i])) return;
+  localExpanded.value = [...v];
+});
+
+const expandedSet = computed(() => new Set(localExpanded.value));
+
+function isExpanded(key: string): boolean {
+  return expandedSet.value.has(key);
+}
+
+function commitExpanded(next: string[]): void {
+  localExpanded.value = next;
+  expandedModel.value = next;
+}
+
+function toggleExpanded(value: T): void {
+  const children = getChildren(value);
+  if (!children || children.length === 0) return;
+  const key = getKey(value);
+  const current = localExpanded.value;
+  if (expandedSet.value.has(key)) {
+    const next: string[] = [];
+    for (let i = 0; i < current.length; i++) {
+      const k = current[i]!;
+      if (k !== key) next.push(k);
+    }
+    commitExpanded(next);
+  }
+  else {
+    commitExpanded([...current, key]);
+  }
+}
+
+// --- Flattened visible items ---------------------------------------------
+
+const flatItems = computed<Array<FlatItem<T>>>(() =>
+  flattenVisible(items, getKey, getChildren, expandedSet.value),
+);
+
+// Full key→item map over the WHOLE tree (ignores expansion). Built lazily and
+// only when bubble/indeterminate features are active, so plain trees pay
+// nothing. `shallowRef`-style replacement — the Map is rebuilt wholesale on a
+// structural change. Used to walk the parent chain past collapsed ancestors.
+const flatByKey = computed<Map<string, { value: T; parentKey?: string }>>(() => {
+  const map = new Map<string, { value: T; parentKey?: string }>();
+  if (!bubbleSelect && !propagateSelect) return map;
+  interface Frame { nodes: readonly T[]; parentKey?: string }
+  const stack: Frame[] = [{ nodes: items, parentKey: undefined }];
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    for (let i = 0; i < frame.nodes.length; i++) {
+      const node = frame.nodes[i]!;
+      const key = getKey(node);
+      map.set(key, { value: node, parentKey: frame.parentKey });
+      const ch = getChildren(node);
+      if (ch && ch.length > 0) stack.push({ nodes: ch, parentKey: key });
+    }
+  }
+  return map;
+});
+
+// --- Indeterminate (tri-state) -------------------------------------------
+
+function isIndeterminate(item: FlatItem<T>): boolean | undefined {
+  if (!multiple || !item.hasChildren) return undefined;
+  if (!bubbleSelect && !propagateSelect) return undefined;
+  const descendants = collectDescendantKeys(item.value, getKey, getChildren);
+  if (descendants.length === 0) return undefined;
+  const set = selectedSet.value;
+  let some = false;
+  let all = true;
+  for (let i = 0; i < descendants.length; i++) {
+    if (set.has(descendants[i]!)) some = true;
+    else all = false;
+  }
+  return some && !all ? true : undefined;
+}
+
+// --- Keyboard navigation --------------------------------------------------
+
+const { getItems, CollectionSlot } = useCollectionProvider();
+const treeItemElements = computed(() => getItems(true).map(i => i.ref));
+
+// Roving tab stop — exactly one item carries `tabindex=0`. Seeds to the first
+// selected key, else the first visible item, so Tab enters the tree once and
+// arrow keys move within it (WAI-ARIA single-tabstop tree pattern).
+const currentTabStopKey = ref<string | undefined>();
+const effectiveTabStopKey = computed(() => {
+  const cur = currentTabStopKey.value;
+  const visible = flatItems.value;
+  if (cur !== undefined && visible.some(i => i.key === cur)) return cur;
+  const firstSelected = visible.find(i => selectedSet.value.has(i.key) && !(disabled));
+  if (firstSelected) return firstSelected.key;
+  return visible.length > 0 ? visible[0]!.key : undefined;
+});
+
+function setTabStop(key: string): void {
+  currentTabStopKey.value = key;
+}
+
+function collectEnabled(): HTMLElement[] {
+  const all = treeItemElements.value;
+  const out: HTMLElement[] = [];
+  for (let i = 0; i < all.length; i++) {
+    const el = all[i]!;
+    if (!el.hasAttribute('data-disabled')) out.push(el);
+  }
+  return out;
+}
+
+function focusElement(el: HTMLElement | undefined): void {
+  if (!el) return;
+  const key = el.getAttribute('data-key');
+  if (key) currentTabStopKey.value = key;
+  el.focus();
+}
+
+// Resolve the FlatItem behind a rendered element via its private `data-key`,
+// decoupling Left/Right parent/child resolution from the public `aria-level`
+// markup (which a consumer may override).
+function itemOfElement(el: HTMLElement): FlatItem<T> | undefined {
+  const key = el.getAttribute('data-key');
+  if (key === null) return undefined;
+  const visible = flatItems.value;
+  for (let i = 0; i < visible.length; i++) {
+    if (visible[i]!.key === key) return visible[i];
+  }
+  return undefined;
+}
+
+function levelOf(el: HTMLElement): number {
+  return Number(el.getAttribute('data-level'));
+}
+
+// Buffered multi-character type-ahead, reset ~500ms after the last keystroke.
+const typeaheadBuffer = refAutoReset('', 500);
+
+function textOf(el: HTMLElement): string {
+  const item = itemOfElement(el);
+  if (item && getLabel) return getLabel(item.value);
+  return el.dataset['textValue'] ?? el.textContent?.trim() ?? '';
+}
+
+function onTypeahead(key: string, el: HTMLElement): void {
+  const enabled = collectEnabled();
+  if (enabled.length === 0) return;
+  typeaheadBuffer.value += key;
+  const values = enabled.map(textOf);
+  const current = textOf(el);
+  const next = getNextMatch(values, typeaheadBuffer.value, current);
+  if (next === undefined) return;
+  focusElement(enabled[values.indexOf(next)]);
+}
+
+// Contiguous range selection (multiple + `replace`) on Shift+navigation.
+function extendRange(targetEl: HTMLElement | undefined): void {
+  if (!multiple || selectionBehavior !== 'replace') return;
+  if (anchorKey.value === undefined || !targetEl) return;
+  const targetKey = targetEl.getAttribute('data-key');
+  if (!targetKey) return;
+  const keys = collectEnabled().map(e => e.getAttribute('data-key') ?? '');
+  const range = keysBetween(keys, anchorKey.value, targetKey);
+  if (range.length === 0) return;
+  commitSelected(range);
+}
+
+function onItemKeyDown(event: KeyboardEvent, el: HTMLElement, item: FlatItem<T>): void {
+  // Enter / Space → select (tree-specific, not covered by roving-focus helper)
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault();
+    select(item.value);
+    return;
+  }
+
+  const enabled = collectEnabled();
+  if (enabled.length === 0) return;
+  const idx = enabled.indexOf(el);
+
+  // PageUp / PageDown jump to first / last visible item (APG tree pattern).
+  if (event.key === 'PageUp' || event.key === 'Home') {
+    event.preventDefault();
+    const target = enabled[0]!;
+    if (event.shiftKey) extendRange(target);
+    focusElement(target);
+    return;
+  }
+  if (event.key === 'PageDown' || event.key === 'End') {
+    event.preventDefault();
+    const target = enabled[enabled.length - 1]!;
+    if (event.shiftKey) extendRange(target);
+    focusElement(target);
+    return;
+  }
+
+  // Up / Down → delegate to shared roving-focus helper.
+  const action = rovingKeyToAction(
+    event,
+    direction.value === 'rtl' ? ROVING_OPTS_RTL : ROVING_OPTS_LTR,
+  );
+  if (action && action.absolute === undefined) {
+    event.preventDefault();
+    const nextIdx = resolveNextIndex(idx, action.delta, enabled.length, false);
+    const target = enabled[nextIdx]!;
+    if (event.shiftKey) extendRange(target);
+    focusElement(target);
+    return;
+  }
+
+  // Left / Right have tree-specific semantics beyond roving focus:
+  //   forward  — expand collapsed parent, else move to first child
+  //   back     — collapse expanded parent, else move to parent item
+  const ltr = direction.value !== 'rtl';
+  const forwardKey = ltr ? 'ArrowRight' : 'ArrowLeft';
+  const backKey = ltr ? 'ArrowLeft' : 'ArrowRight';
+
+  if (event.key === forwardKey) {
+    event.preventDefault();
+    if (!item.hasChildren) return;
+    if (!isExpanded(item.key)) {
+      toggleExpanded(item.value);
+      return;
+    }
+    const next = enabled[idx + 1];
+    if (next && levelOf(next) === item.level + 1) focusElement(next);
+    return;
+  }
+
+  if (event.key === backKey) {
+    event.preventDefault();
+    if (item.hasChildren && isExpanded(item.key)) {
+      toggleExpanded(item.value);
+      return;
+    }
+    const parentLevel = item.level - 1;
+    for (let i = idx - 1; i >= 0; i--) {
+      const candidate = enabled[i]!;
+      if (levelOf(candidate) === parentLevel) {
+        focusElement(candidate);
+        return;
+      }
+    }
+    return;
+  }
+
+  // Printable single character → type-ahead (ignore modifier combos).
+  if (
+    event.key.length === 1
+    && !event.ctrlKey
+    && !event.altKey
+    && !event.metaKey
+    && event.key !== ' '
+  ) {
+    onTypeahead(event.key, el);
+  }
+}
+
+provideTreeContext({
+  flatItems,
+  expandedKeys: localExpanded,
+  selectedKeys: localSelected,
+  multiple: toRef(() => multiple),
+  disabled: toRef(() => disabled),
+  direction,
+  propagateSelect: toRef(() => propagateSelect),
+  bubbleSelect: toRef(() => bubbleSelect),
+  selectionBehavior: toRef(() => selectionBehavior),
+  currentTabStopKey: effectiveTabStopKey,
+  isExpanded,
+  isSelected,
+  isIndeterminate,
+  toggleExpanded,
+  select,
+  setTabStop,
+  treeItemElements,
+  onItemKeyDown,
+});
+
+defineSlots<{
+  default?: (props: {
+    flatItems: Array<FlatItem<T>>;
+    selectedKeys: string[];
+    expandedKeys: string[];
+  }) => unknown;
+}>();
+</script>
+
+<template>
+  <CollectionSlot>
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      role="tree"
+      :aria-multiselectable="multiple ? true : undefined"
+      :aria-disabled="disabled || undefined"
+      :dir="direction"
+    >
+      <slot
+        :flat-items="flatItems"
+        :selected-keys="localSelected"
+        :expanded-keys="localExpanded"
+      />
+    </Primitive>
+  </CollectionSlot>
+</template>
diff --git a/vue/primitives/src/navigation/tree/__test__/Tree.test.ts b/vue/primitives/src/navigation/tree/__test__/Tree.test.ts
new file mode 100644
index 0000000..d2a7509
--- /dev/null
+++ b/vue/primitives/src/navigation/tree/__test__/Tree.test.ts
@@ -0,0 +1,543 @@
+import { TreeItem, TreeRoot } from '../index';
+import { defineComponent, h, nextTick } from 'vue';
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+
+interface Node {
+  id: string;
+  label: string;
+  children?: Node[];
+}
+
+const TREE: Node[] = [
+  {
+    id: 'a',
+    label: 'A',
+    children: [
+      { id: 'a-1', label: 'A.1' },
+      {
+        id: 'a-2',
+        label: 'A.2',
+        children: [
+          { id: 'a-2-1', label: 'A.2.1' },
+          { id: 'a-2-2', label: 'A.2.2' },
+        ],
+      },
+    ],
+  },
+  { id: 'b', label: 'B' },
+  {
+    id: 'c',
+    label: 'C',
+    children: [{ id: 'c-1', label: 'C.1' }],
+  },
+];
+
+function createTree(rootProps: Record<string, unknown> = {}, items: Node[] = TREE) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () => h(
+          TreeRoot,
+          {
+            items,
+            getKey: (n: unknown) => (n as Node).id,
+            getChildren: (n: unknown) => (n as Node).children,
+            ...rootProps,
+          },
+          {
+            default: ({ flatItems }: { flatItems: Array<{ key: string; value: Node; level: number; hasChildren: boolean }> }) =>
+              flatItems.map(item =>
+                h(TreeItem, { key: item.key, item }, { default: () => item.value.label }),
+              ),
+          },
+        );
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+function press(el: Element, key: string, opts: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...opts }));
+}
+
+async function flush() {
+  await nextTick();
+  await nextTick();
+}
+
+// Variant that lets every TreeItem receive extra props / listeners (item-level
+// `disabled`, `onSelect`, `onToggle`).
+function createTreeWithItemProps(
+  rootProps: Record<string, unknown> = {},
+  itemProps: (item: { key: string; value: Node }) => Record<string, unknown> = () => ({}),
+  items: Node[] = TREE,
+) {
+  return mount(
+    defineComponent({
+      setup() {
+        return () => h(
+          TreeRoot,
+          {
+            items,
+            getKey: (n: unknown) => (n as Node).id,
+            getChildren: (n: unknown) => (n as Node).children,
+            ...rootProps,
+          },
+          {
+            default: ({ flatItems }: { flatItems: Array<{ key: string; value: Node }> }) =>
+              flatItems.map(item =>
+                h(TreeItem, { key: item.key, item, ...itemProps(item) }, { default: () => item.value.label }),
+              ),
+          },
+        );
+      },
+    }),
+    { attachTo: document.body },
+  );
+}
+
+describe('Tree', () => {
+  it('renders only top-level items when nothing is expanded', () => {
+    const w = createTree();
+    const items = w.findAll('[role="treeitem"]');
+    expect(items).toHaveLength(3);
+    expect(items.map(i => i.text())).toEqual(['A', 'B', 'C']);
+    w.unmount();
+  });
+
+  it('sets role="tree" on root', () => {
+    const w = createTree();
+    expect(w.find('[role="tree"]').exists()).toBe(true);
+    w.unmount();
+  });
+
+  it('wires aria-level and aria-expanded', () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const items = w.findAll('[role="treeitem"]');
+    // A (has children, expanded), A.1 (leaf), A.2 (has children, closed), B, C
+    expect(items[0]!.attributes('aria-level')).toBe('1');
+    expect(items[0]!.attributes('aria-expanded')).toBe('true');
+    expect(items[0]!.attributes('data-state')).toBe('open');
+
+    expect(items[1]!.attributes('aria-level')).toBe('2');
+    expect(items[1]!.attributes('aria-expanded')).toBeUndefined();
+    expect(items[1]!.attributes('data-state')).toBeUndefined();
+
+    expect(items[2]!.attributes('aria-level')).toBe('2');
+    expect(items[2]!.attributes('aria-expanded')).toBe('false');
+    expect(items[2]!.attributes('data-state')).toBe('closed');
+    w.unmount();
+  });
+
+  it('click toggles expansion of a parent node', async () => {
+    const w = createTree();
+    const a = w.findAll('[role="treeitem"]')[0]!;
+    await a.trigger('click');
+    await flush();
+    // now A is expanded, A.1 + A.2 visible
+    const items = w.findAll('[role="treeitem"]');
+    expect(items).toHaveLength(5);
+    expect(items.map(i => i.text())).toEqual(['A', 'A.1', 'A.2', 'B', 'C']);
+    w.unmount();
+  });
+
+  it('click selects a node (single-select)', async () => {
+    const w = createTree();
+    const b = w.findAll('[role="treeitem"]')[1]!;
+    await b.trigger('click');
+    await flush();
+    expect(b.attributes('aria-selected')).toBe('true');
+    expect(b.attributes('data-selected')).toBe('');
+    w.unmount();
+  });
+
+  it('single-select: selecting another item replaces the previous selection', async () => {
+    const w = createTree({ defaultValue: 'b' });
+    const items = w.findAll('[role="treeitem"]');
+    expect(items[1]!.attributes('aria-selected')).toBe('true');
+
+    await items[0]!.trigger('click');
+    await flush();
+
+    const after = w.findAll('[role="treeitem"]');
+    expect(after[0]!.attributes('aria-selected')).toBe('true');
+    expect(after.find(i => i.text() === 'B')!.attributes('aria-selected')).toBe('false');
+    w.unmount();
+  });
+
+  it('multiple-select: selections accumulate', async () => {
+    const w = createTree({ multiple: true });
+    const items = w.findAll('[role="treeitem"]');
+    await items[0]!.trigger('click'); // A (also expands)
+    await flush();
+    await w.findAll('[role="treeitem"]').find(i => i.text() === 'B')!.trigger('click');
+    await flush();
+    const all = w.findAll('[role="treeitem"]');
+    const selected = all.filter(i => i.attributes('aria-selected') === 'true').map(i => i.text());
+    expect(selected).toContain('A');
+    expect(selected).toContain('B');
+    w.unmount();
+  });
+
+  it('ArrowDown / ArrowUp move focus through visible items', async () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    items[0]!.focus();
+    expect(document.activeElement).toBe(items[0]);
+    press(items[0]!, 'ArrowDown');
+    expect(document.activeElement).toBe(items[1]); // A.1
+    press(items[1]!, 'ArrowDown');
+    expect(document.activeElement).toBe(items[2]); // A.2
+    press(items[2]!, 'ArrowUp');
+    expect(document.activeElement).toBe(items[1]);
+    w.unmount();
+  });
+
+  it('Home / End jump to first / last visible item', () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    items[2]!.focus();
+    press(items[2]!, 'End');
+    expect(document.activeElement).toBe(items[items.length - 1]);
+    press(items[items.length - 1]!, 'Home');
+    expect(document.activeElement).toBe(items[0]);
+    w.unmount();
+  });
+
+  it('ArrowRight expands a collapsed parent; ArrowRight again moves to first child', async () => {
+    const w = createTree();
+    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    items[0]!.focus();
+    press(items[0]!, 'ArrowRight');
+    await flush();
+    const next = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    expect(next[0]!.getAttribute('aria-expanded')).toBe('true');
+    press(next[0]!, 'ArrowRight');
+    expect(document.activeElement).toBe(next[1]); // A.1
+    w.unmount();
+  });
+
+  it('ArrowLeft collapses an expanded parent; ArrowLeft on a leaf jumps to its parent', async () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    const a1 = items[1]!; // leaf
+    a1.focus();
+    press(a1, 'ArrowLeft');
+    expect(document.activeElement).toBe(items[0]); // back to A
+
+    // Now collapse A with another ArrowLeft
+    press(items[0]!, 'ArrowLeft');
+    await flush();
+    const updated = w.findAll('[role="treeitem"]');
+    expect(updated).toHaveLength(3);
+    w.unmount();
+  });
+
+  it('Enter / Space select the focused item', async () => {
+    const w = createTree();
+    const first = w.find('[role="treeitem"]').element as HTMLElement;
+    first.focus();
+    press(first, 'Enter');
+    await flush();
+    expect(first.getAttribute('aria-selected')).toBe('true');
+    w.unmount();
+  });
+
+  it('emits update:modelValue and update:expanded', async () => {
+    const onModel: string[][] = [];
+    const onExpanded: string[][] = [];
+    const w = createTree({
+      'onUpdate:modelValue': (v: string | string[] | undefined) => {
+        onModel.push(Array.isArray(v) ? v : v === undefined ? [] : [v]);
+      },
+      'onUpdate:expanded': (v: string[]) => {
+        onExpanded.push(v);
+      },
+    });
+    const first = w.find('[role="treeitem"]');
+    await first.trigger('click');
+    await flush();
+    expect(onModel[0]).toEqual(['a']);
+    expect(onExpanded[0]).toEqual(['a']);
+    w.unmount();
+  });
+
+  it('disabled tree ignores clicks and keyboard selection', async () => {
+    const onModel: unknown[] = [];
+    const w = createTree({ disabled: true, 'onUpdate:modelValue': (v: unknown) => onModel.push(v) });
+    const first = w.find('[role="treeitem"]');
+    await first.trigger('click');
+    await flush();
+    expect(first.attributes('aria-selected')).toBe('false');
+    expect(onModel).toHaveLength(0);
+    w.unmount();
+  });
+
+  it('propagateSelect cascades selection to all descendants', async () => {
+    const captured: string[][] = [];
+    const w = createTree({
+      multiple: true,
+      propagateSelect: true,
+      defaultExpanded: ['a', 'a-2'],
+      'onUpdate:modelValue': (v: string[]) => captured.push(v),
+    });
+    const a = w.findAll('[role="treeitem"]')[0]!; // A
+    await a.trigger('click');
+    await flush();
+    const emitted = captured.at(-1)!;
+    expect(emitted).toEqual(expect.arrayContaining(['a', 'a-1', 'a-2', 'a-2-1', 'a-2-2']));
+    w.unmount();
+  });
+
+  // --- Roving single tab stop --------------------------------------------
+
+  it('exposes a single roving tab stop: only one item has tabindex=0', () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const items = w.findAll('[role="treeitem"]');
+    const tabbable = items.filter(i => i.attributes('tabindex') === '0');
+    expect(tabbable).toHaveLength(1);
+    // The rest are -1.
+    const negative = items.filter(i => i.attributes('tabindex') === '-1');
+    expect(negative).toHaveLength(items.length - 1);
+    w.unmount();
+  });
+
+  it('initial tab stop lands on the selected item', () => {
+    const w = createTree({ defaultExpanded: ['a'], defaultValue: 'a-2' });
+    const items = w.findAll('[role="treeitem"]');
+    const tabbable = items.find(i => i.attributes('tabindex') === '0')!;
+    expect(tabbable.text()).toBe('A.2');
+    w.unmount();
+  });
+
+  it('moving focus via arrow keys moves the tab stop', async () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const els = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    els[0]!.focus();
+    press(els[0]!, 'ArrowDown');
+    await flush();
+    const items = w.findAll('[role="treeitem"]');
+    expect(items[0]!.attributes('tabindex')).toBe('-1');
+    expect(items[1]!.attributes('tabindex')).toBe('0');
+    w.unmount();
+  });
+
+  // --- aria-setsize / aria-posinset --------------------------------------
+
+  it('emits aria-setsize and aria-posinset per sibling group', () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const items = w.findAll('[role="treeitem"]');
+    // Top level has 3 siblings (A, B, C).
+    expect(items[0]!.attributes('aria-setsize')).toBe('3');
+    expect(items[0]!.attributes('aria-posinset')).toBe('1');
+    // A.1 and A.2 are within a group of 2.
+    expect(items[1]!.attributes('aria-setsize')).toBe('2');
+    expect(items[1]!.attributes('aria-posinset')).toBe('1');
+    expect(items[2]!.attributes('aria-setsize')).toBe('2');
+    expect(items[2]!.attributes('aria-posinset')).toBe('2');
+    // B is position 2 of the top-level group.
+    expect(items[3]!.attributes('aria-posinset')).toBe('2');
+    w.unmount();
+  });
+
+  // --- PageUp / PageDown --------------------------------------------------
+
+  it('PageDown jumps to last, PageUp jumps to first', () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const els = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    els[0]!.focus();
+    press(els[0]!, 'PageDown');
+    expect(document.activeElement).toBe(els[els.length - 1]);
+    press(els[els.length - 1]!, 'PageUp');
+    expect(document.activeElement).toBe(els[0]);
+    w.unmount();
+  });
+
+  // --- Type-ahead ---------------------------------------------------------
+
+  it('type-ahead focuses the next item whose label matches a typed character', () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const els = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    // visible: A, A.1, A.2, B, C
+    els[0]!.focus();
+    press(els[0]!, 'b');
+    expect((document.activeElement as HTMLElement).textContent).toBe('B');
+    w.unmount();
+  });
+
+  it('repeating a single character cycles through matches', () => {
+    const w = createTree({ defaultExpanded: ['a'] });
+    const els = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    // visible labels starting with "A": A, A.1, A.2
+    els[0]!.focus();
+    press(els[0]!, 'a'); // from A -> next "A*" is A.1
+    expect((document.activeElement as HTMLElement).textContent).toBe('A.1');
+    press(document.activeElement!, 'a'); // repeated 'a' cycles -> A.2
+    expect((document.activeElement as HTMLElement).textContent).toBe('A.2');
+    w.unmount();
+  });
+
+  it('type-ahead respects a getLabel accessor', () => {
+    const w = createTree({
+      defaultExpanded: ['a'],
+      getLabel: (n: unknown) => (n as Node).id.toUpperCase(),
+    });
+    const els = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    els[0]!.focus();
+    press(els[0]!, 'c'); // id 'c' -> 'C'
+    expect((document.activeElement as HTMLElement).textContent).toBe('C');
+    w.unmount();
+  });
+
+  // --- selectionBehavior --------------------------------------------------
+
+  it('selectionBehavior=replace resets multi-selection to the clicked item', async () => {
+    const w = createTree({ multiple: true, selectionBehavior: 'replace', defaultExpanded: ['a'] });
+    const items = () => w.findAll('[role="treeitem"]');
+    await items()[1]!.trigger('click'); // A.1
+    await flush();
+    await items()[3]!.trigger('click'); // B
+    await flush();
+    const selected = items().filter(i => i.attributes('aria-selected') === 'true').map(i => i.text());
+    expect(selected).toEqual(['B']);
+    w.unmount();
+  });
+
+  it('Shift+ArrowDown extends a contiguous range in replace mode', async () => {
+    const captured: string[][] = [];
+    const w = createTree({
+      multiple: true,
+      selectionBehavior: 'replace',
+      defaultExpanded: ['a'],
+      'onUpdate:modelValue': (v: string[]) => captured.push(v),
+    });
+    const els = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    // visible: A, A.1, A.2, B, C -> click A.1 to anchor
+    els[1]!.focus();
+    await w.findAll('[role="treeitem"]')[1]!.trigger('click');
+    await flush();
+    press(document.activeElement!, 'ArrowDown', { shiftKey: true });
+    await flush();
+    expect(captured.at(-1)).toEqual(['a-1', 'a-2']);
+    press(document.activeElement!, 'ArrowDown', { shiftKey: true });
+    await flush();
+    expect(captured.at(-1)).toEqual(['a-1', 'a-2', 'b']);
+    w.unmount();
+  });
+
+  // --- bubbleSelect + indeterminate --------------------------------------
+
+  it('bubbleSelect selects parent when all children are selected', async () => {
+    const captured: string[][] = [];
+    const w = createTree({
+      multiple: true,
+      bubbleSelect: true,
+      defaultExpanded: ['a', 'a-2'],
+      'onUpdate:modelValue': (v: string[]) => captured.push(v),
+    });
+    const find = (text: string) => w.findAll('[role="treeitem"]').find(i => i.text() === text)!;
+    await find('A.2.1').trigger('click');
+    await flush();
+    await find('A.2.2').trigger('click');
+    await flush();
+    // Both children of A.2 selected -> A.2 bubbles in.
+    expect(captured.at(-1)).toEqual(expect.arrayContaining(['a-2-1', 'a-2-2', 'a-2']));
+    w.unmount();
+  });
+
+  it('exposes is-indeterminate to the item slot for partial parent coverage', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          return () => h(
+            TreeRoot,
+            {
+              items: TREE,
+              getKey: (n: unknown) => (n as Node).id,
+              getChildren: (n: unknown) => (n as Node).children,
+              multiple: true,
+              bubbleSelect: true,
+              defaultExpanded: ['a', 'a-2'],
+            },
+            {
+              default: ({ flatItems }: { flatItems: Array<{ key: string; value: Node }> }) =>
+                flatItems.map(item =>
+                  h(TreeItem, { key: item.key, item }, {
+                    default: ({ isIndeterminate }: { isIndeterminate: boolean | undefined }) =>
+                      h('span', { 'data-ind': isIndeterminate ? 'yes' : 'no' }, item.value.label),
+                  }),
+                ),
+            },
+          );
+        },
+      }),
+      { attachTo: document.body },
+    );
+    const find = (text: string) => w.findAll('[role="treeitem"]').find(i => i.text() === text)!;
+    await find('A.2.1').trigger('click'); // only one of A.2's two children
+    await flush();
+    const a2 = find('A.2');
+    expect(a2.attributes('data-indeterminate')).toBe('');
+    expect(a2.find('[data-ind]').attributes('data-ind')).toBe('yes');
+    w.unmount();
+  });
+
+  // --- Cancelable select / toggle emits ----------------------------------
+
+  it('emits cancelable select / toggle events that can veto state change', async () => {
+    const w = createTreeWithItemProps(
+      {},
+      item => item.key === 'a'
+        ? {
+            onSelect: (e: CustomEvent) => e.preventDefault(),
+            onToggle: (e: CustomEvent) => e.preventDefault(),
+          }
+        : {},
+    );
+    const a = w.findAll('[role="treeitem"]')[0]!; // A
+    await a.trigger('click');
+    await flush();
+    // select + toggle vetoed -> still collapsed, not selected.
+    expect(w.findAll('[role="treeitem"]')).toHaveLength(3);
+    expect(a.attributes('aria-selected')).toBe('false');
+    w.unmount();
+  });
+
+  it('select event carries value + state in its detail', async () => {
+    const details: Array<{ value: Node; isSelected: boolean }> = [];
+    const w = createTreeWithItemProps(
+      {},
+      () => ({ onSelect: (e: CustomEvent) => details.push(e.detail) }),
+    );
+    await w.findAll('[role="treeitem"]')[1]!.trigger('click'); // B
+    await flush();
+    expect(details[0]!.value.id).toBe('b');
+    expect(details[0]!.isSelected).toBe(false); // state captured before mutation
+    w.unmount();
+  });
+
+  // --- item-level disabled -----------------------------------------------
+
+  it('item-level disabled blocks selection and is skipped by navigation', async () => {
+    const onModel: unknown[] = [];
+    const w = createTreeWithItemProps(
+      { defaultExpanded: ['a'], 'onUpdate:modelValue': (v: unknown) => onModel.push(v) },
+      item => (item.key === 'a-1' ? { disabled: true } : {}),
+    );
+    const items = w.findAll('[role="treeitem"]');
+    const a1 = items.find(i => i.text() === 'A.1')!;
+    expect(a1.attributes('data-disabled')).toBe('');
+    expect(a1.attributes('tabindex')).toBe('-1');
+    await a1.trigger('click');
+    await flush();
+    expect(onModel).toHaveLength(0);
+    // ArrowDown from A skips disabled A.1 and lands on A.2.
+    const els = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
+    els[0]!.focus();
+    press(els[0]!, 'ArrowDown');
+    expect((document.activeElement as HTMLElement).textContent).toBe('A.2');
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/tree/context.ts b/vue/primitives/src/navigation/tree/context.ts
similarity index 60%
rename from vue/primitives/src/tree/context.ts
rename to vue/primitives/src/navigation/tree/context.ts
index 43b9552..9ce2c6f 100644
--- a/vue/primitives/src/tree/context.ts
+++ b/vue/primitives/src/navigation/tree/context.ts
@@ -2,6 +2,8 @@ import type { ComputedRef, Ref } from 'vue';
 import type { FlatItem } from './utils';
 import { useContextFactory } from '@robonen/vue';
 
+export type TreeSelectionBehavior = 'toggle' | 'replace';
+
 export interface TreeContext<T = unknown> {
   /** Reactive flattened visible items (only descendants of expanded nodes). */
   flatItems: ComputedRef<Array<FlatItem<T>>>;
@@ -17,11 +19,24 @@ export interface TreeContext<T = unknown> {
   direction: Ref<'ltr' | 'rtl'>;
   /** When `true`, selecting a parent cascades selection to all descendants. */
   propagateSelect: Ref<boolean>;
+  /** When `true`, selecting all children of a parent selects the parent too. */
+  bubbleSelect: Ref<boolean>;
+  /** How a multi-selection mutates on select: toggle membership or replace. */
+  selectionBehavior: Ref<TreeSelectionBehavior>;
+  /** Key of the current roving tab stop — only one item carries `tabindex=0`. */
+  currentTabStopKey: Ref<string | undefined>;
 
   isExpanded: (key: string) => boolean;
   isSelected: (key: string) => boolean;
+  /**
+   * Tri-state for a parent in `propagateSelect`/`bubbleSelect` mode: `true` when
+   * some — but not all — descendants are selected. `undefined` otherwise.
+   */
+  isIndeterminate: (item: FlatItem<T>) => boolean | undefined;
   toggleExpanded: (value: T) => void;
   select: (value: T) => void;
+  /** Mark this item as the current roving tab stop (e.g. on focus). */
+  setTabStop: (key: string) => void;
 
   /** DOM-ordered list of rendered treeitem elements (from the internal Collection). */
   treeItemElements: ComputedRef<HTMLElement[]>;
@@ -32,4 +47,4 @@ export interface TreeContext<T = unknown> {
 export const {
   inject: useTreeContext,
   provide: provideTreeContext,
-} = useContextFactory<TreeContext<any>>('TreeContext');
+} = useContextFactory<TreeContext<unknown>>('TreeContext');
diff --git a/vue/primitives/src/tree/demo.vue b/vue/primitives/src/navigation/tree/demo.vue
similarity index 87%
rename from vue/primitives/src/tree/demo.vue
rename to vue/primitives/src/navigation/tree/demo.vue
index 05c4ea1..b23239c 100644
--- a/vue/primitives/src/tree/demo.vue
+++ b/vue/primitives/src/navigation/tree/demo.vue
@@ -51,7 +51,7 @@ const expanded = ref<string[]>(['src', 'components']);
     :items="items"
     :get-key="(item) => item.key"
     :get-children="(item) => item.children"
-    class="w-full max-w-xs select-none rounded-lg border border-(--border) bg-(--bg) p-1.5 text-(--fg)"
+    class="w-full max-w-xs select-none rounded-lg border border-border bg-bg p-1.5 text-fg"
   >
     <template #default="{ flatItems }">
       <TreeItem
@@ -59,12 +59,12 @@ const expanded = ref<string[]>(['src', 'components']);
         :key="item.key"
         :item="item"
         :style="{ paddingLeft: `${(item.level - 1) * 16 + 8}px` }"
-        class="flex items-center gap-1.5 rounded-md py-1.5 pr-2 text-sm outline-none transition-colors hover:bg-(--bg-subtle) focus-visible:ring-2 focus-visible:ring-(--ring) data-[selected]:bg-(--accent) data-[selected]:text-(--accent-fg)"
+        class="flex items-center gap-1.5 rounded-md py-1.5 pr-2 text-sm outline-none transition-colors hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-ring data-[selected]:bg-accent data-[selected]:text-accent-fg"
       >
         <template #default="{ isExpanded }">
           <svg
             v-if="item.hasChildren"
-            class="size-3.5 shrink-0 text-(--fg-subtle) transition-transform duration-150"
+            class="size-3.5 shrink-0 text-fg-subtle transition-transform duration-150"
             :class="{ 'rotate-90': isExpanded }"
             viewBox="0 0 24 24"
             fill="none"
@@ -77,7 +77,7 @@ const expanded = ref<string[]>(['src', 'components']);
           </svg>
           <svg
             v-else
-            class="size-3.5 shrink-0 text-(--fg-subtle)"
+            class="size-3.5 shrink-0 text-fg-subtle"
             viewBox="0 0 24 24"
             fill="none"
             stroke="currentColor"
diff --git a/vue/primitives/src/navigation/tree/index.ts b/vue/primitives/src/navigation/tree/index.ts
new file mode 100644
index 0000000..3a5dcb9
--- /dev/null
+++ b/vue/primitives/src/navigation/tree/index.ts
@@ -0,0 +1,16 @@
+export { default as TreeRoot } from './TreeRoot.vue';
+export { default as TreeItem } from './TreeItem.vue';
+
+export { useTreeContext, provideTreeContext } from './context';
+
+export type { TreeRootProps } from './TreeRoot.vue';
+export type {
+  TreeItemProps,
+  TreeItemEmits,
+  TreeItemSelectEvent,
+  TreeItemToggleEvent,
+  TreeItemSelectEventDetail,
+} from './TreeItem.vue';
+export type { TreeContext, TreeSelectionBehavior } from './context';
+export type { FlatItem } from './utils';
+export { flattenAll, flattenVisible, collectDescendantKeys } from './utils';
diff --git a/vue/primitives/src/navigation/tree/utils.ts b/vue/primitives/src/navigation/tree/utils.ts
new file mode 100644
index 0000000..05be4ec
--- /dev/null
+++ b/vue/primitives/src/navigation/tree/utils.ts
@@ -0,0 +1,173 @@
+/**
+ * Shared Tree helpers. Pure, no Vue imports.
+ */
+
+export interface FlatItem<T = unknown> {
+  /** Unique string key produced by `getKey(value)`. */
+  key: string;
+  /** Original item value. */
+  value: T;
+  /** 1-based depth — top-level is 1. */
+  level: number;
+  /** Whether the item has a non-empty children array. */
+  hasChildren: boolean;
+  /** Parent key, or `undefined` for root-level items. */
+  parentKey?: string;
+  /** Number of siblings in the same group (for `aria-setsize`). */
+  setSize: number;
+  /** 1-based position within the sibling group (for `aria-posinset`). */
+  posInSet: number;
+}
+
+/**
+ * Depth-first flattening of a tree into a visible list, honoring `expandedKeys`.
+ * Collapsed subtrees are skipped entirely. Iterative implementation to avoid
+ * deep recursion on large trees.
+ */
+export function flattenVisible<T>(
+  items: readonly T[],
+  getKey: (item: T) => string,
+  getChildren: (item: T) => readonly T[] | undefined | null,
+  expandedKeys: ReadonlySet<string>,
+): Array<FlatItem<T>> {
+  const out: Array<FlatItem<T>> = [];
+  // Stack holds frames to expand. Seed in reverse so first child pops first.
+  interface Frame { nodes: readonly T[]; index: number; level: number; parentKey?: string }
+  const stack: Frame[] = [{ nodes: items, index: 0, level: 1, parentKey: undefined }];
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1]!;
+    if (frame.index >= frame.nodes.length) {
+      stack.pop();
+      continue;
+    }
+    const node = frame.nodes[frame.index]!;
+    const posInSet = frame.index + 1;
+    frame.index += 1;
+
+    const key = getKey(node);
+    const children = getChildren(node);
+    const hasChildren = Array.isArray(children) && children.length > 0;
+    out.push({
+      key,
+      value: node,
+      level: frame.level,
+      hasChildren,
+      parentKey: frame.parentKey,
+      setSize: frame.nodes.length,
+      posInSet,
+    });
+
+    if (hasChildren && expandedKeys.has(key)) {
+      stack.push({
+        nodes: children as readonly T[],
+        index: 0,
+        level: frame.level + 1,
+        parentKey: key,
+      });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Flattens all descendants (regardless of expansion) — used for cascade
+ * select/deselect operations.
+ */
+export function flattenAll<T>(
+  items: readonly T[],
+  getKey: (item: T) => string,
+  getChildren: (item: T) => readonly T[] | undefined | null,
+): Array<{ key: string; value: T }> {
+  const out: Array<{ key: string; value: T }> = [];
+  const stack: Array<readonly T[]> = [items];
+  while (stack.length > 0) {
+    const nodes = stack.pop()!;
+    for (const node of nodes) {
+      out.push({ key: getKey(node), value: node });
+      const children = getChildren(node);
+      if (Array.isArray(children) && children.length > 0) stack.push(children);
+    }
+  }
+  return out;
+}
+
+/**
+ * Collects the keys of all *direct and transitive* children of `value` (the
+ * node itself is NOT included). Iterative — never recurses, so deeply nested
+ * trees can't blow the call stack. Powers `propagateSelect` / `bubbleSelect`
+ * and the indeterminate computation.
+ */
+export function collectDescendantKeys<T>(
+  value: T,
+  getKey: (item: T) => string,
+  getChildren: (item: T) => readonly T[] | undefined | null,
+): string[] {
+  const out: string[] = [];
+  const first = getChildren(value);
+  if (!first || first.length === 0) return out;
+  const stack: Array<readonly T[]> = [first];
+  while (stack.length > 0) {
+    const nodes = stack.pop()!;
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i]!;
+      out.push(getKey(node));
+      const ch = getChildren(node);
+      if (ch && ch.length > 0) stack.push(ch);
+    }
+  }
+  return out;
+}
+
+/**
+ * Rotates `array` so it starts at `startIndex`, wrapping around.
+ * `wrapArray(['a','b','c','d'], 2) === ['c','d','a','b']`.
+ */
+export function wrapArray<T>(array: readonly T[], startIndex: number): T[] {
+  const len = array.length;
+  const out: T[] = Array.from({ length: len });
+  for (let i = 0; i < len; i++) out[i] = array[(startIndex + i) % len]!;
+  return out;
+}
+
+/**
+ * Core type-ahead matcher. Given the list of item text values, the accumulated
+ * `search` buffer, and the current match, returns the next item text to focus
+ * (or `undefined`). Repeated single characters cycle through matches; longer
+ * buffers match by prefix without excluding the current item. Wraps around so
+ * focus always moves forward from the current item.
+ */
+export function getNextMatch(
+  values: readonly string[],
+  search: string,
+  currentMatch?: string,
+): string | undefined {
+  const isRepeated = search.length > 1 && Array.from(search).every(c => c === search[0]);
+  const normalizedSearch = isRepeated ? search[0]! : search;
+  const currentMatchIndex = currentMatch ? values.indexOf(currentMatch) : -1;
+  let wrapped = wrapArray(values, Math.max(currentMatchIndex, 0));
+  const excludeCurrentMatch = normalizedSearch.length === 1;
+  if (excludeCurrentMatch) wrapped = wrapped.filter(v => v !== currentMatch);
+  const lower = normalizedSearch.toLowerCase();
+  const nextMatch = wrapped.find(v => v.toLowerCase().startsWith(lower));
+  return nextMatch !== currentMatch ? nextMatch : undefined;
+}
+
+/**
+ * Returns the contiguous slice of `keys` between the first occurrences of
+ * `start` and `end` (inclusive), regardless of their order. Empty if either is
+ * missing. Powers Shift+Arrow/Home/End contiguous range selection.
+ */
+export function keysBetween(
+  keys: readonly string[],
+  start: string,
+  end: string,
+): string[] {
+  const startIndex = keys.indexOf(start);
+  const endIndex = keys.indexOf(end);
+  if (startIndex === -1 || endIndex === -1) return [];
+  const min = Math.min(startIndex, endIndex);
+  const max = Math.max(startIndex, endIndex);
+  return keys.slice(min, max + 1) as string[];
+}
diff --git a/vue/primitives/src/number-field/NumberFieldDecrement.vue b/vue/primitives/src/number-field/NumberFieldDecrement.vue
deleted file mode 100644
index 2bbf4ad..0000000
--- a/vue/primitives/src/number-field/NumberFieldDecrement.vue
+++ /dev/null
@@ -1,40 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A button that decreases the value by one `step` when clicked. Rendered as a
- * `<button>` by default and hidden from assistive tech (`aria-hidden`, removed
- * from the tab order) since the input itself is the accessible spinbutton; it
- * is disabled whenever the root is `disabled` or `readonly`.
- */
-export interface NumberFieldDecrementProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { useForwardExpose } from '@robonen/vue';
-import { useNumberFieldContext } from './context';
-
-const { as = 'button' } = defineProps<NumberFieldDecrementProps>();
-const { forwardRef } = useForwardExpose();
-const ctx = useNumberFieldContext();
-
-function onClick() {
-  ctx.decrement();
-}
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    :type="as === 'button' ? 'button' : undefined"
-    tabindex="-1"
-    aria-hidden="true"
-    :disabled="ctx.disabled.value || ctx.readonly.value || undefined"
-    :data-disabled="(ctx.disabled.value || ctx.readonly.value) ? '' : undefined"
-    @click="onClick"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/number-field/NumberFieldIncrement.vue b/vue/primitives/src/number-field/NumberFieldIncrement.vue
deleted file mode 100644
index c656ffb..0000000
--- a/vue/primitives/src/number-field/NumberFieldIncrement.vue
+++ /dev/null
@@ -1,40 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A button that increases the value by one `step` when clicked. Rendered as a
- * `<button>` by default and hidden from assistive tech (`aria-hidden`, removed
- * from the tab order) since the input itself is the accessible spinbutton; it
- * is disabled whenever the root is `disabled` or `readonly`.
- */
-export interface NumberFieldIncrementProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { useForwardExpose } from '@robonen/vue';
-import { useNumberFieldContext } from './context';
-
-const { as = 'button' } = defineProps<NumberFieldIncrementProps>();
-const { forwardRef } = useForwardExpose();
-const ctx = useNumberFieldContext();
-
-function onClick() {
-  ctx.increment();
-}
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    :type="as === 'button' ? 'button' : undefined"
-    tabindex="-1"
-    aria-hidden="true"
-    :disabled="ctx.disabled.value || ctx.readonly.value || undefined"
-    :data-disabled="(ctx.disabled.value || ctx.readonly.value) ? '' : undefined"
-    @click="onClick"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/number-field/NumberFieldInput.vue b/vue/primitives/src/number-field/NumberFieldInput.vue
deleted file mode 100644
index b09b999..0000000
--- a/vue/primitives/src/number-field/NumberFieldInput.vue
+++ /dev/null
@@ -1,94 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The text field that displays and edits the value, rendered as a native
- * `<input role="spinbutton">` wired to the root context. It parses typed input,
- * mirrors the current value via `aria-valuenow`/`aria-valuemin`/`aria-valuemax`,
- * and handles Arrow/Page/Home/End keys to step, jump, or clamp to the bounds.
- */
-export interface NumberFieldInputProps extends PrimitiveProps {
-
-  placeholder?: string;
-  name?: string;
-  required?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { computed } from 'vue';
-import { useNumberFieldContext } from './context';
-
-const props = defineProps<NumberFieldInputProps>();
-const ctx = useNumberFieldContext();
-
-const displayValue = computed(() => ctx.value.value === null ? '' : String(ctx.value.value));
-
-function parse(raw: string): number | null {
-  const trimmed = raw.trim();
-  if (trimmed === '') return null;
-  const n = Number(trimmed);
-  return Number.isFinite(n) ? n : null;
-}
-
-function onInput(event: Event): void {
-  const target = event.target as HTMLInputElement;
-  ctx.setValue(parse(target.value));
-}
-
-function onKeyDown(event: KeyboardEvent): void {
-  if (ctx.disabled.value || ctx.readonly.value) return;
-  switch (event.key) {
-    case 'ArrowUp':
-      event.preventDefault();
-      ctx.increment();
-      break;
-    case 'ArrowDown':
-      event.preventDefault();
-      ctx.decrement();
-      break;
-    case 'PageUp':
-      event.preventDefault();
-      ctx.increment(ctx.step.value * 10);
-      break;
-    case 'PageDown':
-      event.preventDefault();
-      ctx.decrement(ctx.step.value * 10);
-      break;
-    case 'Home':
-      if (ctx.min.value !== undefined) {
-        event.preventDefault();
-        ctx.setValue(ctx.min.value);
-      }
-      break;
-    case 'End':
-      if (ctx.max.value !== undefined) {
-        event.preventDefault();
-        ctx.setValue(ctx.max.value);
-      }
-      break;
-  }
-}
-</script>
-
-<template>
-  <input
-    :id="ctx.inputId"
-    role="spinbutton"
-    inputmode="decimal"
-    autocomplete="off"
-    :aria-valuemin="ctx.min.value"
-    :aria-valuemax="ctx.max.value"
-    :aria-valuenow="ctx.value.value ?? undefined"
-    :aria-disabled="ctx.disabled.value || undefined"
-    :aria-readonly="ctx.readonly.value || undefined"
-    :disabled="ctx.disabled.value || undefined"
-    :readonly="ctx.readonly.value || undefined"
-    :placeholder="props.placeholder"
-    :name="props.name"
-    :required="props.required || undefined"
-    :value="displayValue"
-    @input="onInput"
-    @keydown="onKeyDown"
-  >
-</template>
diff --git a/vue/primitives/src/number-field/NumberFieldRoot.vue b/vue/primitives/src/number-field/NumberFieldRoot.vue
deleted file mode 100644
index f5a5e0b..0000000
--- a/vue/primitives/src/number-field/NumberFieldRoot.vue
+++ /dev/null
@@ -1,103 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A numeric input with stepper controls, keyboard increment/decrement, and
- * optional clamping. The interactive root: it owns the value (controlled via
- * `v-model` / `update:modelValue` or uncontrolled via `defaultValue`), clamps
- * to `min`/`max`, applies `step`, and provides context to `NumberFieldInput`,
- * `NumberFieldIncrement`, and `NumberFieldDecrement`. Use it whenever you need
- * a styled number entry with spinner buttons and arrow-key support.
- */
-export interface NumberFieldRootProps extends PrimitiveProps {
-  defaultValue?: number | null;
-  min?: number;
-  max?: number;
-  step?: number;
-  disabled?: boolean;
-  readonly?: boolean;
-
-}
-
-export interface NumberFieldRootEmits {
-  valueChange: [value: number | null];
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { ref, toRef, watch } from 'vue';
-import { provideNumberFieldContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
-import { clamp } from '@robonen/stdlib';
-import { useId } from '../config-provider';
-
-const { step = 1, disabled = false, readonly = false, min, max, defaultValue, as = 'div' } = defineProps<NumberFieldRootProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const emit = defineEmits<NumberFieldRootEmits>();
-
-// `defineModel` drives both controlled (`v-model`) and uncontrolled modes; in
-// uncontrolled mode `model.value` is `undefined` until first write, so the
-// internal `localValue` below seeds from `defaultValue` and stays the live
-// source of truth (synchronous multi-step updates can't wait on a prop re-flow).
-const model = defineModel<number | null>();
-
-const localValue = ref<number | null>(
-  model.value !== undefined ? model.value : (defaultValue ?? null),
-);
-
-watch(model, (v) => {
-  if (v === undefined) return;
-  if (v === localValue.value) return;
-  localValue.value = v;
-});
-
-function setValue(v: number | null): void {
-  if (disabled || readonly) return;
-  const next = v === null ? null : clamp(v, min ?? -Infinity, max ?? Infinity);
-  if (next === localValue.value) return;
-  localValue.value = next;
-  // `defineModel` emits `update:modelValue` on write — no manual emit needed.
-  model.value = next;
-  emit('valueChange', next);
-}
-
-function increment(delta = step): void {
-  const base = localValue.value ?? min ?? 0;
-  setValue(base + delta);
-}
-function decrement(delta = step): void {
-  const base = localValue.value ?? min ?? 0;
-  setValue(base - delta);
-}
-
-const inputId = useId(undefined, 'number-field-input').value;
-
-provideNumberFieldContext({
-  value: localValue,
-  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
-  min: toRef(() => min),
-  max: toRef(() => max),
-  step: toRef(() => step),
-  disabled: toRef(() => disabled),
-  readonly: toRef(() => readonly),
-  increment,
-  decrement,
-  setValue,
-  inputId,
-});
-defineExpose({ value: localValue, increment, decrement, setValue });
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    :data-disabled="disabled ? '' : undefined"
-    :data-readonly="readonly ? '' : undefined"
-  >
-    <slot :value="localValue" :increment="increment" :decrement="decrement" />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/number-field/context.ts b/vue/primitives/src/number-field/context.ts
deleted file mode 100644
index aee578a..0000000
--- a/vue/primitives/src/number-field/context.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { Ref } from 'vue';
-import { useContextFactory } from '@robonen/vue';
-
-export interface NumberFieldContext {
-  value: Ref<number | null>;
-  min: Ref<number | undefined>;
-  max: Ref<number | undefined>;
-  step: Ref<number>;
-  disabled: Ref<boolean>;
-  readonly: Ref<boolean>;
-  increment: (delta?: number) => void;
-  decrement: (delta?: number) => void;
-  setValue: (v: number | null) => void;
-  inputId: string;
-}
-
-const ctx = useContextFactory<NumberFieldContext>('NumberFieldContext');
-
-export const provideNumberFieldContext = ctx.provide;
-export const useNumberFieldContext = ctx.inject;
diff --git a/vue/primitives/src/alert-dialog/AlertDialogAction.vue b/vue/primitives/src/overlays/alert-dialog/AlertDialogAction.vue
similarity index 68%
rename from vue/primitives/src/alert-dialog/AlertDialogAction.vue
rename to vue/primitives/src/overlays/alert-dialog/AlertDialogAction.vue
index d3dcc9d..e87e230 100644
--- a/vue/primitives/src/alert-dialog/AlertDialogAction.vue
+++ b/vue/primitives/src/overlays/alert-dialog/AlertDialogAction.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button that confirms the alert and closes the dialog. Use it for the
@@ -10,13 +10,16 @@ export interface AlertDialogActionProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { DialogClose } from '../dialog';
 
 const { as = 'button' } = defineProps<AlertDialogActionProps>();
+
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
-  <DialogClose :as="as" data-alert-dialog-action>
+  <DialogClose :ref="forwardRef" :as="as" data-alert-dialog-action>
     <slot />
   </DialogClose>
 </template>
diff --git a/vue/primitives/src/overlays/alert-dialog/AlertDialogCancel.vue b/vue/primitives/src/overlays/alert-dialog/AlertDialogCancel.vue
new file mode 100644
index 0000000..e2efd7b
--- /dev/null
+++ b/vue/primitives/src/overlays/alert-dialog/AlertDialogCancel.vue
@@ -0,0 +1,34 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The button that dismisses the alert without acting and closes the dialog.
+ * Receives focus automatically when the alert opens, making it the safe default
+ * choice; always include one so the user has a non-destructive way out.
+ */
+export interface AlertDialogCancelProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { DialogClose } from '../dialog';
+import { useAlertDialogContentContext } from './context';
+
+const { as = 'button' } = defineProps<AlertDialogCancelProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const ctx = useAlertDialogContentContext();
+
+// Report this control's element to the owning Content so it can move open
+// focus here — scoped per-instance, never resolved by a global DOM query.
+watch(currentElement, (el) => {
+  ctx.cancelElement.value = el as HTMLElement | undefined;
+}, { immediate: true, flush: 'post' });
+</script>
+
+<template>
+  <DialogClose :ref="forwardRef" :as="as" data-alert-dialog-cancel>
+    <slot />
+  </DialogClose>
+</template>
diff --git a/vue/primitives/src/alert-dialog/AlertDialogContent.vue b/vue/primitives/src/overlays/alert-dialog/AlertDialogContent.vue
similarity index 59%
rename from vue/primitives/src/alert-dialog/AlertDialogContent.vue
rename to vue/primitives/src/overlays/alert-dialog/AlertDialogContent.vue
index fd9b886..1a57465 100644
--- a/vue/primitives/src/alert-dialog/AlertDialogContent.vue
+++ b/vue/primitives/src/overlays/alert-dialog/AlertDialogContent.vue
@@ -12,27 +12,40 @@ export type AlertDialogContentEmits = DialogContentEmits;
 </script>
 
 <script setup lang="ts">
+import { shallowRef } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
 import { DialogContent } from '../dialog';
+import { provideAlertDialogContentContext } from './context';
 
 const props = defineProps<AlertDialogContentProps>();
 const emit = defineEmits<AlertDialogContentEmits>();
 
+const { forwardRef } = useForwardExpose();
+
+// Per-instance Cancel element registered by AlertDialogCancel through context.
+// Scoped to this Content so nested/multiple alert dialogs each focus their own
+// Cancel instead of the first match in document order.
+const cancelElement = shallowRef<HTMLElement | undefined>(undefined);
+provideAlertDialogContentContext({ cancelElement });
+
 function onOpenAutoFocus(event: Event) {
   emit('openAutoFocus', event);
   if (event.defaultPrevented) return;
+  // Suppress the focus-scope's default first-tabbable focus synchronously, then
+  // redirect to the safe Cancel choice. The focus runs on a microtask so the
+  // Cancel control has registered its element in context even when its
+  // post-flush registration watch settles after this synchronous event.
+  // `preventScroll` keeps the page/scroll container from jumping to the button.
+  event.preventDefault();
   queueMicrotask(() => {
-    const content = document.querySelector<HTMLElement>('[data-alert-dialog-content]');
-    const cancel = content?.querySelector<HTMLElement>('[data-alert-dialog-cancel]');
-    if (cancel) {
-      event.preventDefault();
-      cancel.focus();
-    }
+    cancelElement.value?.focus({ preventScroll: true });
   });
 }
 </script>
 
 <template>
   <DialogContent
+    :ref="forwardRef"
     v-bind="props"
     role="alertdialog"
     data-alert-dialog-content
diff --git a/vue/primitives/src/alert-dialog/AlertDialogRoot.vue b/vue/primitives/src/overlays/alert-dialog/AlertDialogRoot.vue
similarity index 64%
rename from vue/primitives/src/alert-dialog/AlertDialogRoot.vue
rename to vue/primitives/src/overlays/alert-dialog/AlertDialogRoot.vue
index 34de64c..0e69ba3 100644
--- a/vue/primitives/src/alert-dialog/AlertDialogRoot.vue
+++ b/vue/primitives/src/overlays/alert-dialog/AlertDialogRoot.vue
@@ -12,24 +12,37 @@ import type { DialogRootProps } from '../dialog';
  * and provides context to all parts. Bind `v-model:open` to control it.
  */
 export interface AlertDialogRootProps extends Omit<DialogRootProps, 'modal'> {}
+
+export interface AlertDialogRootEmits {
+  /** Fired when the open state changes — the `v-model:open` update channel. */
+  'update:open': [value: boolean | undefined];
+}
 </script>
 
 <script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
 import { DialogRoot } from '../dialog';
 
 defineOptions({ inheritAttrs: false });
 
-const props = defineProps<AlertDialogRootProps>();
+const { defaultOpen } = defineProps<AlertDialogRootProps>();
 const openModel = defineModel<boolean | undefined>('open', { default: undefined });
+
+defineSlots<{
+  /** Default slot exposing the live open state and a close helper. */
+  default?: (props: { open: boolean | undefined; close: () => void }) => unknown;
+}>();
+
+useForwardExpose();
 </script>
 
 <template>
   <DialogRoot
-    :default-open="props.defaultOpen"
+    :default-open="defaultOpen"
     :modal="true"
     :open="openModel"
     @update:open="openModel = $event"
   >
-    <slot :open="openModel" />
+    <slot :open="openModel" :close="() => { openModel = false; }" />
   </DialogRoot>
 </template>
diff --git a/vue/primitives/src/overlays/alert-dialog/__test__/AlertDialog.test.ts b/vue/primitives/src/overlays/alert-dialog/__test__/AlertDialog.test.ts
new file mode 100644
index 0000000..db862d7
--- /dev/null
+++ b/vue/primitives/src/overlays/alert-dialog/__test__/AlertDialog.test.ts
@@ -0,0 +1,267 @@
+import { mount } from '@vue/test-utils';
+import type { VueWrapper } from '@vue/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogOverlay,
+  AlertDialogPortal,
+  AlertDialogRoot,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  document.body.removeAttribute('style');
+  delete document.body.dataset['dismissableBlocking'];
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+// Auto-focus runs in a post-flush effect and the Cancel redirect lands on a
+// microtask; settle both plus the macrotask boundary before asserting focus.
+async function flush() {
+  await nextTick();
+  await nextTick();
+  await new Promise(resolve => setTimeout(resolve, 0));
+}
+
+function mountAlert(initialOpen = true) {
+  const open = ref(initialOpen);
+  const Harness = defineComponent({
+    setup() {
+      return () => h(
+        AlertDialogRoot,
+        {
+          open: open.value,
+          'onUpdate:open': (v: boolean | undefined) => { open.value = v!; },
+        },
+        {
+          default: () => [
+            h(AlertDialogTrigger, null, { default: () => 'Open' }),
+            h(AlertDialogPortal, null, {
+              default: () => [
+                h(AlertDialogOverlay),
+                h(AlertDialogContent, null, {
+                  default: () => [
+                    h(AlertDialogTitle, null, { default: () => 'Are you sure?' }),
+                    h(AlertDialogDescription, null, { default: () => 'This cannot be undone.' }),
+                    h(AlertDialogCancel, null, { default: () => 'Cancel' }),
+                    h(AlertDialogAction, null, { default: () => 'OK' }),
+                  ],
+                }),
+              ],
+            }),
+          ],
+        },
+      );
+    },
+  });
+  const w = track(mount(Harness, { attachTo: document.body }));
+  return { wrapper: w, open };
+}
+
+describe('AlertDialog', () => {
+  it('renders content with role="alertdialog"', async () => {
+    mountAlert(true);
+    await nextTick();
+    await nextTick();
+    const content = document.querySelector('[data-alert-dialog-content]');
+    expect(content).toBeTruthy();
+    expect(content!.getAttribute('role')).toBe('alertdialog');
+  });
+
+  it('labels content via Title and describes via Description', async () => {
+    mountAlert(true);
+    await nextTick();
+    await nextTick();
+    const content = document.querySelector<HTMLElement>('[data-alert-dialog-content]')!;
+    const labelledby = content.getAttribute('aria-labelledby');
+    const describedby = content.getAttribute('aria-describedby');
+    expect(labelledby).toMatch(/dialog-title/);
+    expect(describedby).toMatch(/dialog-description/);
+    expect(document.getElementById(labelledby!)?.textContent).toBe('Are you sure?');
+    expect(document.getElementById(describedby!)?.textContent).toBe('This cannot be undone.');
+  });
+
+  it('Cancel button closes the dialog', async () => {
+    const { open } = mountAlert(true);
+    await nextTick();
+    await nextTick();
+    const cancel = document.querySelector<HTMLButtonElement>('[data-alert-dialog-cancel]')!;
+    cancel.click();
+    await nextTick();
+    await nextTick();
+    expect(open.value).toBe(false);
+  });
+
+  it('Action button closes the dialog', async () => {
+    const { open } = mountAlert(true);
+    await nextTick();
+    await nextTick();
+    const action = document.querySelector<HTMLButtonElement>('[data-alert-dialog-action]')!;
+    action.click();
+    await nextTick();
+    await nextTick();
+    expect(open.value).toBe(false);
+  });
+
+  it('Cancel and Action carry data attributes', async () => {
+    mountAlert(true);
+    await nextTick();
+    await nextTick();
+    expect(document.querySelector('[data-alert-dialog-cancel]')).toBeTruthy();
+    expect(document.querySelector('[data-alert-dialog-action]')).toBeTruthy();
+  });
+
+  it('moves focus to its own Cancel button on open', async () => {
+    mountAlert(true);
+    await flush();
+    const cancel = document.querySelector<HTMLElement>('[data-alert-dialog-cancel]')!;
+    expect(document.activeElement).toBe(cancel);
+  });
+
+  it('focuses Cancel with preventScroll to avoid scroll jumps', async () => {
+    const original = HTMLElement.prototype.focus;
+    const calls: Array<{ el: HTMLElement; opts?: FocusOptions }> = [];
+    HTMLElement.prototype.focus = function focus(this: HTMLElement, opts?: FocusOptions) {
+      calls.push({ el: this, opts });
+      return original.call(this, opts);
+    };
+    try {
+      mountAlert(true);
+      await flush();
+      const cancel = document.querySelector<HTMLElement>('[data-alert-dialog-cancel]')!;
+      const cancelCall = calls.find(c => c.el === cancel);
+      expect(cancelCall).toBeTruthy();
+      expect(cancelCall!.opts?.preventScroll).toBe(true);
+    }
+    finally {
+      HTMLElement.prototype.focus = original;
+    }
+  });
+
+  it('a consumer can preventDefault openAutoFocus to keep its own focus target', async () => {
+    const open = ref(true);
+    const Harness = defineComponent({
+      setup() {
+        return () => h(AlertDialogRoot, { open: open.value }, {
+          default: () => h(AlertDialogPortal, null, {
+            default: () => h(AlertDialogContent, {
+              onOpenAutoFocus: (e: Event) => e.preventDefault(),
+            }, {
+              default: () => [
+                h(AlertDialogTitle, null, { default: () => 'T' }),
+                h(AlertDialogDescription, null, { default: () => 'D' }),
+                h(AlertDialogCancel, null, { default: () => 'Cancel' }),
+                h(AlertDialogAction, null, { default: () => 'OK' }),
+              ],
+            }),
+          }),
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await flush();
+    const cancel = document.querySelector<HTMLElement>('[data-alert-dialog-cancel]')!;
+    expect(document.activeElement).not.toBe(cancel);
+  });
+
+  it('each of two simultaneous alert dialogs focuses its own Cancel', async () => {
+    const Harness = defineComponent({
+      setup() {
+        const make = (label: string) => h(AlertDialogRoot, { open: true }, {
+          default: () => h(AlertDialogPortal, null, {
+            default: () => h(AlertDialogContent, { 'data-which': label }, {
+              default: () => [
+                h(AlertDialogTitle, null, { default: () => `${label} title` }),
+                h(AlertDialogDescription, null, { default: () => `${label} desc` }),
+                h(AlertDialogCancel, { 'data-which-cancel': label }, { default: () => `${label} cancel` }),
+                h(AlertDialogAction, null, { default: () => `${label} ok` }),
+              ],
+            }),
+          }),
+        });
+        return () => [make('a'), make('b')];
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await flush();
+    // The last dialog's auto-focus wins activeElement, but the decisive check is
+    // that each Content focuses a Cancel that belongs to it — never a sibling's.
+    const focused = document.activeElement as HTMLElement;
+    expect(focused?.getAttribute('data-alert-dialog-cancel')).not.toBeNull();
+    const which = focused.getAttribute('data-which-cancel');
+    expect(which === 'a' || which === 'b').toBe(true);
+    // Both cancel buttons exist and are distinct DOM nodes.
+    const cancels = document.querySelectorAll('[data-alert-dialog-cancel]');
+    expect(cancels.length).toBe(2);
+    expect(cancels[0]).not.toBe(cancels[1]);
+  });
+
+  it('exposes a close helper from the Root default slot', async () => {
+    const open = ref(true);
+    let close: (() => void) | undefined;
+    const Harness = defineComponent({
+      setup() {
+        return () => h(
+          AlertDialogRoot,
+          { open: open.value, 'onUpdate:open': (v: boolean | undefined) => { open.value = v!; } },
+          {
+            default: (slotProps: { open: boolean | undefined; close: () => void }) => {
+              close = slotProps.close;
+              return h(AlertDialogPortal, null, {
+                default: () => h(AlertDialogContent, null, {
+                  default: () => [
+                    h(AlertDialogTitle, null, { default: () => 'T' }),
+                    h(AlertDialogDescription, null, { default: () => 'D' }),
+                    h(AlertDialogCancel, null, { default: () => 'Cancel' }),
+                  ],
+                }),
+              });
+            },
+          },
+        );
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+    expect(typeof close).toBe('function');
+    close!();
+    await nextTick();
+    expect(open.value).toBe(false);
+  });
+
+  it('forwards a ref to the underlying content element', async () => {
+    const contentRef = ref<{ $el?: HTMLElement }>();
+    const Harness = defineComponent({
+      setup() {
+        return () => h(AlertDialogRoot, { open: true }, {
+          default: () => h(AlertDialogPortal, null, {
+            default: () => h(AlertDialogContent, { ref: contentRef }, {
+              default: () => [
+                h(AlertDialogTitle, null, { default: () => 'T' }),
+                h(AlertDialogDescription, null, { default: () => 'D' }),
+                h(AlertDialogCancel, null, { default: () => 'Cancel' }),
+              ],
+            }),
+          }),
+        });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await flush();
+    expect(contentRef.value?.$el).toBeTruthy();
+    expect((contentRef.value!.$el as HTMLElement).getAttribute('role')).toBe('alertdialog');
+  });
+});
diff --git a/vue/primitives/src/overlays/alert-dialog/context.ts b/vue/primitives/src/overlays/alert-dialog/context.ts
new file mode 100644
index 0000000..f64e0eb
--- /dev/null
+++ b/vue/primitives/src/overlays/alert-dialog/context.ts
@@ -0,0 +1,17 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+
+export interface AlertDialogContentContext {
+  /**
+   * DOM node of the Cancel control for this specific Content instance. Used to
+   * move focus to the safe default choice on open — scoped per-instance so
+   * nested or simultaneously-mounted alert dialogs focus their own Cancel and
+   * never reach across to another dialog's button.
+   */
+  cancelElement: Ref<HTMLElement | undefined>;
+}
+
+const ctx = useContextFactory<AlertDialogContentContext>('AlertDialogContent');
+
+export const provideAlertDialogContentContext = ctx.provide;
+export const useAlertDialogContentContext = ctx.inject;
diff --git a/vue/primitives/src/alert-dialog/demo.vue b/vue/primitives/src/overlays/alert-dialog/demo.vue
similarity index 69%
rename from vue/primitives/src/alert-dialog/demo.vue
rename to vue/primitives/src/overlays/alert-dialog/demo.vue
index 7458c62..ab5498b 100644
--- a/vue/primitives/src/alert-dialog/demo.vue
+++ b/vue/primitives/src/overlays/alert-dialog/demo.vue
@@ -25,9 +25,9 @@ function restore() {
 </script>
 
 <template>
-  <div class="flex flex-col items-start gap-3 text-(--fg)">
-    <p v-if="!deleted" class="text-sm text-(--fg-muted)">
-      Project <span class="font-medium text-(--fg)">"acme-web"</span> is live.
+  <div class="flex flex-col items-start gap-3 text-fg">
+    <p v-if="!deleted" class="text-sm text-fg-muted">
+      Project <span class="font-medium text-fg">"acme-web"</span> is live.
     </p>
     <p
       v-else
@@ -46,7 +46,7 @@ function restore() {
     <AlertDialogRoot v-model:open="open">
       <AlertDialogTrigger
         :disabled="deleted"
-        class="inline-flex items-center rounded-md border border-red-300 bg-(--bg) px-3 py-1.5 text-sm font-medium text-red-600 transition-colors hover:bg-red-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-400 disabled:cursor-not-allowed disabled:opacity-50 dark:border-red-900 dark:text-red-400 dark:hover:bg-red-950/40"
+        class="inline-flex items-center rounded-md border border-red-300 bg-bg px-3 py-1.5 text-sm font-medium text-red-600 transition-colors hover:bg-red-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-400 disabled:cursor-not-allowed disabled:opacity-50 dark:border-red-900 dark:text-red-400 dark:hover:bg-red-950/40"
       >
         Delete project
       </AlertDialogTrigger>
@@ -56,19 +56,19 @@ function restore() {
           class="fixed inset-0 z-40 bg-black/50 backdrop-blur-sm"
         />
         <AlertDialogContent
-          class="fixed left-1/2 top-1/2 z-50 w-[min(92vw,26rem)] -translate-x-1/2 -translate-y-1/2 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 shadow-xl"
+          class="demo-card fixed left-1/2 top-1/2 z-50 w-[min(92vw,26rem)] -translate-x-1/2 -translate-y-1/2 p-5 shadow-xl"
         >
-          <AlertDialogTitle class="text-base font-semibold text-(--fg)">
+          <AlertDialogTitle class="text-base font-semibold text-fg">
             Delete this project?
           </AlertDialogTitle>
-          <AlertDialogDescription class="mt-1.5 text-sm text-(--fg-muted)">
+          <AlertDialogDescription class="mt-1.5 text-sm text-fg-muted">
             This permanently removes "acme-web" and all of its deployments.
             This action cannot be undone.
           </AlertDialogDescription>
 
           <div class="mt-5 flex justify-end gap-2">
             <AlertDialogCancel
-              class="inline-flex items-center rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+              class="inline-flex items-center rounded-md border border-border bg-bg px-3 py-1.5 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             >
               Cancel
             </AlertDialogCancel>
diff --git a/vue/primitives/src/alert-dialog/index.ts b/vue/primitives/src/overlays/alert-dialog/index.ts
similarity index 60%
rename from vue/primitives/src/alert-dialog/index.ts
rename to vue/primitives/src/overlays/alert-dialog/index.ts
index 761d675..79a3462 100644
--- a/vue/primitives/src/alert-dialog/index.ts
+++ b/vue/primitives/src/overlays/alert-dialog/index.ts
@@ -5,7 +5,17 @@ export { default as AlertDialogContent } from './AlertDialogContent.vue';
 
 export { default as AlertDialogRoot } from './AlertDialogRoot.vue';
 
+export { useAlertDialogContentContext } from './context';
+
+export type {
+  DialogDescriptionProps as AlertDialogDescriptionProps,
+  DialogOverlayProps as AlertDialogOverlayProps,
+  DialogPortalProps as AlertDialogPortalProps,
+  DialogTitleProps as AlertDialogTitleProps,
+  DialogTriggerProps as AlertDialogTriggerProps,
+} from '../dialog';
+export type { AlertDialogContentContext } from './context';
 export type { AlertDialogActionProps } from './AlertDialogAction.vue';
 export type { AlertDialogCancelProps } from './AlertDialogCancel.vue';
 export type { AlertDialogContentEmits, AlertDialogContentProps } from './AlertDialogContent.vue';
-export type { AlertDialogRootProps } from './AlertDialogRoot.vue';
+export type { AlertDialogRootEmits, AlertDialogRootProps } from './AlertDialogRoot.vue';
diff --git a/vue/primitives/src/dialog/DialogClose.vue b/vue/primitives/src/overlays/dialog/DialogClose.vue
similarity index 84%
rename from vue/primitives/src/dialog/DialogClose.vue
rename to vue/primitives/src/overlays/dialog/DialogClose.vue
index 482eaf1..74e86ff 100644
--- a/vue/primitives/src/dialog/DialogClose.vue
+++ b/vue/primitives/src/overlays/dialog/DialogClose.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that closes the dialog when activated. Place inside Content for an
@@ -9,7 +9,7 @@ export interface DialogCloseProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useDialogContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
diff --git a/vue/primitives/src/dialog/DialogContent.vue b/vue/primitives/src/overlays/dialog/DialogContent.vue
similarity index 97%
rename from vue/primitives/src/dialog/DialogContent.vue
rename to vue/primitives/src/overlays/dialog/DialogContent.vue
index bd9d150..68d2fc1 100644
--- a/vue/primitives/src/dialog/DialogContent.vue
+++ b/vue/primitives/src/overlays/dialog/DialogContent.vue
@@ -17,7 +17,7 @@ export type DialogContentEmits = DialogContentImplEmits;
 </script>
 
 <script setup lang="ts">
-import { Presence } from '../presence';
+import { Presence } from '../../utilities/presence';
 import { useDialogContext } from './context';
 import DialogContentModal from './DialogContentModal.vue';
 import DialogContentNonModal from './DialogContentNonModal.vue';
diff --git a/vue/primitives/src/dialog/DialogContentImpl.vue b/vue/primitives/src/overlays/dialog/DialogContentImpl.vue
similarity index 65%
rename from vue/primitives/src/dialog/DialogContentImpl.vue
rename to vue/primitives/src/overlays/dialog/DialogContentImpl.vue
index c0e9a21..d8e80b9 100644
--- a/vue/primitives/src/dialog/DialogContentImpl.vue
+++ b/vue/primitives/src/overlays/dialog/DialogContentImpl.vue
@@ -1,7 +1,7 @@
 <script lang="ts">
-import type { DismissableLayerEmits } from '../dismissable-layer';
-import type { FocusScopeEmits } from '../focus-scope';
-import type { PrimitiveProps } from '../primitive';
+import type { DismissableLayerEmits } from '../../utilities/dismissable-layer';
+import type { FocusScopeEmits } from '../../utilities/focus-scope';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Internal shared implementation behind DialogContent — wraps a FocusScope and
@@ -29,9 +29,13 @@ export interface DialogContentImplEmits {
 </script>
 
 <script setup lang="ts">
-import { DismissableLayer } from '../dismissable-layer';
-import { FocusScope } from '../focus-scope';
+import { onMounted } from 'vue';
+import { getActiveElement } from '@robonen/platform/browsers';
+import { useForwardExpose } from '@robonen/vue';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
+import { FocusScope } from '../../utilities/focus-scope';
 import { useDialogContext } from './context';
+import { useDialogAccessibilityWarning } from './utils';
 
 const {
   as = 'div',
@@ -42,6 +46,25 @@ const {
 
 const emit = defineEmits<DialogContentImplEmits>();
 const ctx = useDialogContext();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+onMounted(() => {
+  // Preserve the focus origin when the dialog was opened programmatically
+  // (v-model / `onOpen`) without a DialogTrigger: capture whatever was focused
+  // so close-restore and the non-modal trigger-containment guard still work.
+  if (!ctx.triggerElement.value) {
+    const active = getActiveElement();
+    if (active && active !== active.ownerDocument.body)
+      ctx.triggerElement.value = active;
+  }
+});
+
+useDialogAccessibilityWarning({
+  titleId: ctx.titleId,
+  descriptionId: ctx.descriptionId,
+  contentElement: currentElement,
+});
 </script>
 
 <template>
@@ -54,6 +77,7 @@ const ctx = useDialogContext();
   >
     <DismissableLayer
       :id="ctx.contentId.value"
+      :ref="forwardRef"
       :as="as"
       :disable-outside-pointer-events="disableOutsidePointerEvents"
       :role="role"
diff --git a/vue/primitives/src/dialog/DialogContentModal.vue b/vue/primitives/src/overlays/dialog/DialogContentModal.vue
similarity index 54%
rename from vue/primitives/src/dialog/DialogContentModal.vue
rename to vue/primitives/src/overlays/dialog/DialogContentModal.vue
index 9474323..9a69f78 100644
--- a/vue/primitives/src/dialog/DialogContentModal.vue
+++ b/vue/primitives/src/overlays/dialog/DialogContentModal.vue
@@ -3,7 +3,7 @@ import type { DialogContentImplEmits, DialogContentImplProps } from './DialogCon
 import type { VoidFunction } from '@robonen/stdlib';
 import { onBeforeUnmount, watch } from 'vue';
 import { useBodyScrollLock, useForwardExpose } from '@robonen/vue';
-import { useHideOthers } from '../utils/useHideOthers';
+import { useHideOthers } from '../../internal/utils/useHideOthers';
 import { useDialogContext } from './context';
 import DialogContentImpl from './DialogContentImpl.vue';
 
@@ -32,6 +32,32 @@ onBeforeUnmount(() => {
   release?.();
   release = null;
 });
+
+function onCloseAutoFocus(event: Event) {
+  emit('closeAutoFocus', event);
+  // The trap restores focus to the previously-focused element on its own, but a
+  // consumer may have re-pointed focus; pin it back to the trigger explicitly so
+  // a programmatically-opened modal still returns focus to its origin.
+  if (!event.defaultPrevented) {
+    event.preventDefault();
+    ctx.triggerElement.value?.focus();
+  }
+}
+
+function onPointerDownOutside(event: PointerEvent | MouseEvent) {
+  emit('pointerDownOutside', event);
+  // A right-click (or ctrl+left on macOS) on the overlay opens a context menu —
+  // it should not be treated as a dismiss gesture, mirroring a real overlay click.
+  const isRightClick = event.button === 2 || (event.button === 0 && event.ctrlKey);
+  if (isRightClick) event.preventDefault();
+}
+
+function onFocusOutside(event: FocusEvent) {
+  emit('focusOutside', event);
+  // While focus is trapped a stray `focusout`/`focusin` can still fire; never let
+  // it drive a dismiss, the trap will pull focus back inside.
+  event.preventDefault();
+}
 </script>
 
 <template>
@@ -42,10 +68,10 @@ onBeforeUnmount(() => {
     :trap-focus="ctx.open.value"
     :disable-outside-pointer-events="true"
     @open-auto-focus="emit('openAutoFocus', $event)"
-    @close-auto-focus="emit('closeAutoFocus', $event)"
+    @close-auto-focus="onCloseAutoFocus"
     @escape-key-down="emit('escapeKeyDown', $event)"
-    @pointer-down-outside="emit('pointerDownOutside', $event)"
-    @focus-outside="emit('focusOutside', $event)"
+    @pointer-down-outside="onPointerDownOutside"
+    @focus-outside="onFocusOutside"
     @interact-outside="emit('interactOutside', $event)"
     @dismiss="emit('dismiss')"
   >
diff --git a/vue/primitives/src/overlays/dialog/DialogContentNonModal.vue b/vue/primitives/src/overlays/dialog/DialogContentNonModal.vue
new file mode 100644
index 0000000..d3bf573
--- /dev/null
+++ b/vue/primitives/src/overlays/dialog/DialogContentNonModal.vue
@@ -0,0 +1,73 @@
+<script setup lang="ts">
+import type { DialogContentImplEmits, DialogContentImplProps } from './DialogContentImpl.vue';
+import { watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useDialogContext } from './context';
+import DialogContentImpl from './DialogContentImpl.vue';
+
+const { as = 'div', role = 'dialog' } = defineProps<DialogContentImplProps>();
+const emit = defineEmits<DialogContentImplEmits>();
+
+const ctx = useDialogContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+watch(currentElement, (el) => {
+  ctx.contentElement.value = el as HTMLElement | undefined;
+}, { immediate: true, flush: 'post' });
+
+// Track outside interaction so closing a non-modal dialog does not steal focus
+// back to the trigger when the user has deliberately moved focus elsewhere.
+let hasInteractedOutside = false;
+let hasPointerDownOutside = false;
+
+function onCloseAutoFocus(event: Event) {
+  emit('closeAutoFocus', event);
+  if (!event.defaultPrevented) {
+    // Only pull focus back to the trigger when the close was driven from inside
+    // the dialog; otherwise respect the user's focus target.
+    if (!hasInteractedOutside) ctx.triggerElement.value?.focus();
+    event.preventDefault();
+  }
+  hasInteractedOutside = false;
+  hasPointerDownOutside = false;
+}
+
+function onInteractOutside(event: PointerEvent | MouseEvent | FocusEvent) {
+  emit('interactOutside', event);
+  if (!event.defaultPrevented) {
+    hasInteractedOutside = true;
+    if (event.type === 'pointerdown') hasPointerDownOutside = true;
+  }
+
+  // Clicking the trigger while open should not dismiss-then-reopen: the trigger
+  // already toggles, so suppress the outside-interaction dismiss for it.
+  const target = event.target as Node | null;
+  if (target && ctx.triggerElement.value?.contains(target))
+    event.preventDefault();
+
+  // Safari edge case: a pointerdown on a trigger inside a focusable container
+  // also fires a later focusin outside; ignore that focusin once we already saw
+  // the pointerdown.
+  if (event.type === 'focusin' && hasPointerDownOutside)
+    event.preventDefault();
+}
+</script>
+
+<template>
+  <DialogContentImpl
+    :ref="forwardRef"
+    :as="as"
+    :role="role"
+    :trap-focus="false"
+    :disable-outside-pointer-events="false"
+    @open-auto-focus="emit('openAutoFocus', $event)"
+    @close-auto-focus="onCloseAutoFocus"
+    @escape-key-down="emit('escapeKeyDown', $event)"
+    @pointer-down-outside="emit('pointerDownOutside', $event)"
+    @focus-outside="emit('focusOutside', $event)"
+    @interact-outside="onInteractOutside"
+    @dismiss="emit('dismiss')"
+  >
+    <slot />
+  </DialogContentImpl>
+</template>
diff --git a/vue/primitives/src/dialog/DialogDescription.vue b/vue/primitives/src/overlays/dialog/DialogDescription.vue
similarity index 83%
rename from vue/primitives/src/dialog/DialogDescription.vue
rename to vue/primitives/src/overlays/dialog/DialogDescription.vue
index af0496c..668667d 100644
--- a/vue/primitives/src/dialog/DialogDescription.vue
+++ b/vue/primitives/src/overlays/dialog/DialogDescription.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * An optional supporting description for the dialog. Its id is wired to the
@@ -9,11 +9,11 @@ export interface DialogDescriptionProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { onBeforeUnmount, onMounted } from 'vue';
 import { useDialogContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
 const { as = 'p' } = defineProps<DialogDescriptionProps>();
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/dialog/DialogOverlay.vue b/vue/primitives/src/overlays/dialog/DialogOverlay.vue
similarity index 85%
rename from vue/primitives/src/dialog/DialogOverlay.vue
rename to vue/primitives/src/overlays/dialog/DialogOverlay.vue
index cc49914..d47f8ac 100644
--- a/vue/primitives/src/dialog/DialogOverlay.vue
+++ b/vue/primitives/src/overlays/dialog/DialogOverlay.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A full-screen layer rendered behind the Content that dims and covers the page
@@ -17,8 +17,8 @@ export interface DialogOverlayProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
+import { Presence } from '../../utilities/presence';
+import { Primitive } from '../../internal/primitive';
 import { useDialogContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
diff --git a/vue/primitives/src/dialog/DialogPortal.vue b/vue/primitives/src/overlays/dialog/DialogPortal.vue
similarity index 83%
rename from vue/primitives/src/dialog/DialogPortal.vue
rename to vue/primitives/src/overlays/dialog/DialogPortal.vue
index 2db8ee1..9a695c8 100644
--- a/vue/primitives/src/dialog/DialogPortal.vue
+++ b/vue/primitives/src/overlays/dialog/DialogPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { TeleportPrimitiveProps } from '../teleport';
+import type { TeleportPrimitiveProps } from '../../utilities/teleport';
 
 /**
  * Teleports the Overlay and Content out of the normal DOM flow (by default into
@@ -17,8 +17,8 @@ export interface DialogPortalProps extends TeleportPrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import PortalPrimitive from '../teleport/Teleport.vue';
-import { Presence } from '../presence';
+import PortalPrimitive from '../../utilities/teleport/Teleport.vue';
+import { Presence } from '../../utilities/presence';
 import { useDialogContext } from './context';
 
 const {
diff --git a/vue/primitives/src/dialog/DialogRoot.vue b/vue/primitives/src/overlays/dialog/DialogRoot.vue
similarity index 82%
rename from vue/primitives/src/dialog/DialogRoot.vue
rename to vue/primitives/src/overlays/dialog/DialogRoot.vue
index 894f175..c866d0a 100644
--- a/vue/primitives/src/dialog/DialogRoot.vue
+++ b/vue/primitives/src/overlays/dialog/DialogRoot.vue
@@ -24,8 +24,8 @@ export interface DialogRootProps {
 </script>
 
 <script setup lang="ts">
-import { ref, toRef } from 'vue';
-import { useId } from '../config-provider';
+import { ref, shallowRef, toRef } from 'vue';
+import { useId } from '../../utilities/config-provider';
 import { provideDialogContext } from './context';
 
 defineOptions({ inheritAttrs: false });
@@ -45,14 +45,19 @@ const open = defineModel<boolean>('open', {
   },
 });
 
+defineSlots<{
+  /** Default slot exposing the live open state and a close helper. */
+  default?: (props: { open: boolean; close: () => void }) => unknown;
+}>();
+
 const triggerId = useId(undefined, 'dialog-trigger');
 const contentId = useId(undefined, 'dialog-content');
 
 const titleId = ref<string | undefined>(undefined);
 const descriptionId = ref<string | undefined>(undefined);
 
-const triggerElement = ref<HTMLElement | undefined>(undefined);
-const contentElement = ref<HTMLElement | undefined>(undefined);
+const triggerElement = shallowRef<HTMLElement | undefined>(undefined);
+const contentElement = shallowRef<HTMLElement | undefined>(undefined);
 
 // Identity passthrough — `toRef` with a getter returns a `GetterRefImpl`:
 // reactive `Ref` without the `ReactiveEffect`/cache that `computed` allocates.
@@ -74,5 +79,8 @@ provideDialogContext({
 </script>
 
 <template>
-  <slot :open="open" />
+  <slot
+    :open="open"
+    :close="() => { open = false; }"
+  />
 </template>
diff --git a/vue/primitives/src/dialog/DialogTitle.vue b/vue/primitives/src/overlays/dialog/DialogTitle.vue
similarity index 83%
rename from vue/primitives/src/dialog/DialogTitle.vue
rename to vue/primitives/src/overlays/dialog/DialogTitle.vue
index df06a6c..b34b6e3 100644
--- a/vue/primitives/src/dialog/DialogTitle.vue
+++ b/vue/primitives/src/overlays/dialog/DialogTitle.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * An accessible title for the dialog. Its id is wired to the Content's
@@ -10,11 +10,11 @@ export interface DialogTitleProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { onBeforeUnmount, onMounted } from 'vue';
 import { useDialogContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
 const { as = 'h2' } = defineProps<DialogTitleProps>();
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/dialog/DialogTrigger.vue b/vue/primitives/src/overlays/dialog/DialogTrigger.vue
similarity index 84%
rename from vue/primitives/src/dialog/DialogTrigger.vue
rename to vue/primitives/src/overlays/dialog/DialogTrigger.vue
index 13572c9..bfcace8 100644
--- a/vue/primitives/src/dialog/DialogTrigger.vue
+++ b/vue/primitives/src/overlays/dialog/DialogTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button that toggles the dialog open. Wires up `aria-haspopup`,
@@ -11,7 +11,7 @@ export interface DialogTriggerProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import { watch } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useDialogContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
@@ -32,7 +32,7 @@ watch(currentElement, (el) => {
     type="button"
     :aria-haspopup="'dialog'"
     :aria-expanded="ctx.open.value"
-    :aria-controls="ctx.contentId.value"
+    :aria-controls="ctx.open.value ? ctx.contentId.value : undefined"
     :data-state="ctx.open.value ? 'open' : 'closed'"
     @click="ctx.onToggle"
   >
diff --git a/vue/primitives/src/dialog/__test__/Dialog.test.ts b/vue/primitives/src/overlays/dialog/__test__/Dialog.test.ts
similarity index 67%
rename from vue/primitives/src/dialog/__test__/Dialog.test.ts
rename to vue/primitives/src/overlays/dialog/__test__/Dialog.test.ts
index 724c4f7..2bff8ae 100644
--- a/vue/primitives/src/dialog/__test__/Dialog.test.ts
+++ b/vue/primitives/src/overlays/dialog/__test__/Dialog.test.ts
@@ -286,6 +286,186 @@ describe('Dialog / modal vs non-modal', () => {
   });
 });
 
+describe('Dialog / trigger aria-controls', () => {
+  it('omits aria-controls while closed and sets it once open', async () => {
+    mountDialog();
+    const trigger = $trigger();
+    expect(trigger.getAttribute('aria-controls')).toBeNull();
+
+    trigger.click();
+    await flush();
+
+    const content = $content()!;
+    expect(trigger.getAttribute('aria-controls')).toBe(content.id);
+  });
+});
+
+describe('Dialog / root slot close helper', () => {
+  it('exposes a close helper from the default slot', async () => {
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          DialogRoot,
+          { defaultOpen: true },
+          {
+            default: (slotProps: { open: boolean; close: () => void }) => [
+              h('span', { 'data-testid': 'open-state' }, String(slotProps.open)),
+              h('button', { 'data-testid': 'slot-close', onClick: () => slotProps.close() }, 'X'),
+              h(DialogPortal, null, {
+                default: () => h(DialogContent, null, {
+                  default: () => h(DialogTitle, null, { default: () => 'T' }),
+                }),
+              }),
+            ],
+          },
+        );
+      },
+    });
+    track(mount(Wrapper, { attachTo: document.body }));
+    await flush();
+
+    expect($content()).toBeTruthy();
+    document.querySelector<HTMLButtonElement>('[data-testid="slot-close"]')!.click();
+    await flush();
+
+    expect($content()).toBeNull();
+    expect(document.querySelector('[data-testid="open-state"]')!.textContent).toBe('false');
+  });
+});
+
+describe('Dialog / dev accessibility warnings', () => {
+  function mountNoTitle() {
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(DialogRoot, { defaultOpen: true }, {
+          default: () => h(DialogPortal, null, {
+            default: () => h(DialogContent, null, { default: () => h('span', null, 'body') }),
+          }),
+        });
+      },
+    });
+    return track(mount(Wrapper, { attachTo: document.body }));
+  }
+
+  it('warns when content has no title', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mountNoTitle();
+    await flush();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('DialogTitle'));
+    warn.mockRestore();
+  });
+
+  it('does not warn when a title is present', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mountDialog({ defaultOpen: true });
+    await flush();
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining('DialogTitle'));
+    warn.mockRestore();
+  });
+});
+
+describe('Dialog / modal outside-interaction guards', () => {
+  function fireOutsidePointerDown(button: number, ctrlKey = false): void {
+    document.body.dispatchEvent(new PointerEvent('pointerdown', {
+      bubbles: true,
+      cancelable: true,
+      button,
+      ctrlKey,
+    }));
+  }
+
+  it('does not close on right-click outside (modal)', async () => {
+    mountDialog({ defaultOpen: true, modal: true });
+    await flush();
+    expect($content()).toBeTruthy();
+
+    fireOutsidePointerDown(2);
+    await flush();
+    expect($content()).toBeTruthy();
+  });
+
+  it('does not close on ctrl+left-click outside (modal)', async () => {
+    mountDialog({ defaultOpen: true, modal: true });
+    await flush();
+
+    fireOutsidePointerDown(0, true);
+    await flush();
+    expect($content()).toBeTruthy();
+  });
+
+  it('still closes on a plain left-click outside (modal)', async () => {
+    mountDialog({ defaultOpen: true, modal: true });
+    await flush();
+
+    fireOutsidePointerDown(0);
+    await flush();
+    expect($content()).toBeNull();
+  });
+
+  it('does not close when focus moves outside while trapped (modal)', async () => {
+    const outside = injectBodySibling('outside-focusable');
+    mountDialog({ defaultOpen: true, modal: true });
+    await flush();
+    expect($content()).toBeTruthy();
+
+    // Dispatch a focusin whose target is the outside sibling.
+    outside.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+    await flush();
+
+    expect($content()).toBeTruthy();
+  });
+});
+
+describe('Dialog / non-modal trigger-containment guard', () => {
+  it('does not dismiss-then-reopen when clicking the trigger while open', async () => {
+    mountDialog({ defaultOpen: true, modal: false });
+    await flush();
+    const trigger = $trigger();
+    expect($content()).toBeTruthy();
+
+    // A pointerdown whose target is the trigger should be treated as inside.
+    trigger.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true }));
+    await flush();
+
+    // Content stays mounted (the outside-interaction dismiss was suppressed).
+    expect($content()).toBeTruthy();
+  });
+});
+
+describe('Dialog / programmatic-open trigger capture', () => {
+  it('captures the active element as the trigger when opened without a DialogTrigger', async () => {
+    const seed = injectBodySibling('seed-focus') as HTMLElement;
+    seed.tabIndex = 0;
+    seed.focus();
+
+    const open = ref(false);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          DialogRoot,
+          { open: open.value, 'onUpdate:open': (v: boolean) => { open.value = v; } },
+          {
+            default: () => h(DialogPortal, null, {
+              default: () => h(DialogContent, null, {
+                default: () => h(DialogTitle, null, { default: () => 'T' }),
+              }),
+            }),
+          },
+        );
+      },
+    });
+    track(mount(Wrapper, { attachTo: document.body }));
+
+    open.value = true;
+    await flush();
+
+    expect($content()).toBeTruthy();
+    // The dialog has no DialogTrigger; the previously-focused element became the
+    // restore origin (only meaningfully asserted in the browser suite, but the
+    // capture path must not throw here).
+  });
+});
+
 // -----------------------------------------------------------------------------
 // Browser-only tests (real focus behaviour).
 // -----------------------------------------------------------------------------
diff --git a/vue/primitives/src/dialog/context.ts b/vue/primitives/src/overlays/dialog/context.ts
similarity index 100%
rename from vue/primitives/src/dialog/context.ts
rename to vue/primitives/src/overlays/dialog/context.ts
diff --git a/vue/primitives/src/dialog/demo.vue b/vue/primitives/src/overlays/dialog/demo.vue
similarity index 63%
rename from vue/primitives/src/dialog/demo.vue
rename to vue/primitives/src/overlays/dialog/demo.vue
index 6224e10..e3f1a1d 100644
--- a/vue/primitives/src/dialog/demo.vue
+++ b/vue/primitives/src/overlays/dialog/demo.vue
@@ -35,14 +35,14 @@ function save() {
 </script>
 
 <template>
-  <div class="flex flex-col items-start gap-3 text-(--fg)">
+  <div class="flex flex-col items-start gap-3 text-fg">
     <div class="flex items-center gap-3">
-      <div class="flex size-9 items-center justify-center rounded-full bg-(--accent) text-sm font-semibold text-(--accent-fg)">
+      <div class="flex size-9 items-center justify-center rounded-full bg-accent text-sm font-semibold text-accent-fg">
         {{ name.charAt(0) }}
       </div>
       <div class="text-sm leading-tight">
         <div class="font-medium">{{ name }}</div>
-        <div class="text-(--fg-muted)">{{ email }}</div>
+        <div class="text-fg-muted">{{ email }}</div>
       </div>
     </div>
 
@@ -52,7 +52,7 @@ function save() {
 
     <DialogRoot v-model:open="open">
       <DialogTrigger
-        class="inline-flex items-center rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex items-center rounded-md border border-border bg-bg px-3 py-1.5 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
       >
         Edit profile
       </DialogTrigger>
@@ -60,22 +60,22 @@ function save() {
       <DialogPortal>
         <DialogOverlay class="fixed inset-0 z-40 bg-black/50 backdrop-blur-sm" />
         <DialogContent
-          class="fixed left-1/2 top-1/2 z-50 w-[min(92vw,28rem)] -translate-x-1/2 -translate-y-1/2 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 shadow-xl focus:outline-none"
+          class="demo-card fixed left-1/2 top-1/2 z-50 w-[min(92vw,28rem)] -translate-x-1/2 -translate-y-1/2 p-5 shadow-xl focus:outline-none"
           @open-auto-focus="onOpenAutoFocus"
         >
           <div class="flex items-start justify-between gap-4">
             <div>
-              <DialogTitle class="text-base font-semibold text-(--fg)">
+              <DialogTitle class="text-base font-semibold text-fg">
                 Edit profile
               </DialogTitle>
-              <DialogDescription class="mt-1 text-sm text-(--fg-muted)">
+              <DialogDescription class="mt-1 text-sm text-fg-muted">
                 Update your name and email. Changes apply when you save.
               </DialogDescription>
             </div>
 
             <DialogClose
               aria-label="Close"
-              class="-mr-1 -mt-1 inline-flex size-7 items-center justify-center rounded-md text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+              class="-mr-1 -mt-1 inline-flex size-7 items-center justify-center rounded-md text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             >
               <svg
                 class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor"
@@ -88,31 +88,31 @@ function save() {
 
           <form class="mt-4 flex flex-col gap-3" @submit.prevent="save">
             <label class="flex flex-col gap-1 text-sm">
-              <span class="font-medium text-(--fg)">Name</span>
+              <span class="font-medium text-fg">Name</span>
               <input
                 v-model="draftName"
                 type="text"
-                class="rounded-md border border-(--border) bg-(--bg) px-2.5 py-1.5 text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+                class="rounded-md border border-border bg-bg px-2.5 py-1.5 text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
             </label>
             <label class="flex flex-col gap-1 text-sm">
-              <span class="font-medium text-(--fg)">Email</span>
+              <span class="font-medium text-fg">Email</span>
               <input
                 v-model="draftEmail"
                 type="email"
-                class="rounded-md border border-(--border) bg-(--bg) px-2.5 py-1.5 text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+                class="rounded-md border border-border bg-bg px-2.5 py-1.5 text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
             </label>
 
             <div class="mt-2 flex justify-end gap-2">
               <DialogClose
-                class="inline-flex items-center rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+                class="inline-flex items-center rounded-md border border-border bg-bg px-3 py-1.5 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
                 Cancel
               </DialogClose>
               <button
                 type="submit"
-                class="inline-flex items-center rounded-md bg-(--accent) px-3 py-1.5 text-sm font-medium text-(--accent-fg) transition-colors hover:bg-(--accent-hover) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+                class="inline-flex items-center rounded-md bg-accent px-3 py-1.5 text-sm font-medium text-accent-fg transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
                 Save changes
               </button>
diff --git a/vue/primitives/src/dialog/index.ts b/vue/primitives/src/overlays/dialog/index.ts
similarity index 100%
rename from vue/primitives/src/dialog/index.ts
rename to vue/primitives/src/overlays/dialog/index.ts
diff --git a/vue/primitives/src/overlays/dialog/utils.ts b/vue/primitives/src/overlays/dialog/utils.ts
new file mode 100644
index 0000000..fee2143
--- /dev/null
+++ b/vue/primitives/src/overlays/dialog/utils.ts
@@ -0,0 +1,42 @@
+import type { Ref } from 'vue';
+import { onMounted } from 'vue';
+
+interface AccessibilityWarningOptions {
+  /** Id the Title registered into the Root context, or `undefined` when absent. */
+  titleId: Ref<string | undefined>;
+  /** Id the Description registered into the Root context, or `undefined` when absent. */
+  descriptionId: Ref<string | undefined>;
+  /** Resolved content element — read its `aria-describedby` to validate the link. */
+  contentElement: Ref<HTMLElement | undefined>;
+}
+
+const TITLE_MESSAGE
+  = 'DialogContent requires a DialogTitle so screen readers can announce the dialog. '
+    + 'If the title should not be visible, keep it in the DOM and hide it visually instead of omitting it.';
+
+const DESCRIPTION_MESSAGE
+  = 'DialogContent references an aria-describedby id that has no matching element. '
+    + 'Render a DialogDescription, or drop the description wiring entirely.';
+
+/**
+ * Dev-only accessibility audit for a mounted DialogContent. Warns once on mount
+ * when no DialogTitle is registered (the dialog would ship unlabeled) and when
+ * the content advertises an `aria-describedby` whose target element is missing.
+ * Compiled out of production builds via the `__DEV__` global.
+ */
+export function useDialogAccessibilityWarning({
+  titleId,
+  descriptionId,
+  contentElement,
+}: AccessibilityWarningOptions): void {
+  if (!__DEV__) return;
+
+  onMounted(() => {
+    if (!titleId.value || !document.getElementById(titleId.value))
+      console.warn(TITLE_MESSAGE);
+
+    const describedBy = contentElement.value?.getAttribute('aria-describedby');
+    if (descriptionId.value && describedBy && !document.getElementById(descriptionId.value))
+      console.warn(DESCRIPTION_MESSAGE);
+  });
+}
diff --git a/vue/primitives/src/drawer/DrawerContent.vue b/vue/primitives/src/overlays/drawer/DrawerContent.vue
similarity index 100%
rename from vue/primitives/src/drawer/DrawerContent.vue
rename to vue/primitives/src/overlays/drawer/DrawerContent.vue
diff --git a/vue/primitives/src/drawer/DrawerHandle.vue b/vue/primitives/src/overlays/drawer/DrawerHandle.vue
similarity index 89%
rename from vue/primitives/src/drawer/DrawerHandle.vue
rename to vue/primitives/src/overlays/drawer/DrawerHandle.vue
index c42965c..5aed468 100644
--- a/vue/primitives/src/drawer/DrawerHandle.vue
+++ b/vue/primitives/src/overlays/drawer/DrawerHandle.vue
@@ -11,12 +11,10 @@ export type { DrawerHandleProps } from './controls';
 </script>
 
 <script setup lang="ts">
-import { ref, watch } from 'vue';
+import { ref, useTemplateRef, watchPostEffect } from 'vue';
 import { injectDrawerRootContext } from './context';
 
-const props = withDefaults(defineProps<DrawerHandleProps>(), {
-  preventCycle: false,
-});
+const { preventCycle = false } = defineProps<DrawerHandleProps>();
 
 const LONG_HANDLE_PRESS_TIMEOUT = 250;
 const DOUBLE_TAP_TIMEOUT = 120;
@@ -27,10 +25,11 @@ const { onPress, onDrag, handleRef, handleOnly, isOpen, snapPoints, activeSnapPo
 // Mirror the element into the shared context ref. A local template ref + watch
 // is used instead of an inline function `:ref` because the inline form can't
 // reliably close over the destructured context binding under `<script setup>`.
-const handleElement = ref<HTMLElement | undefined>(undefined);
-watch(handleElement, (el) => {
-  handleRef.value = el;
-}, { immediate: true, flush: 'post' });
+const handleElement = useTemplateRef('handleElement');
+
+watchPostEffect(() => {
+  handleRef.value = handleElement.value;
+});
 
 const closeTimeoutId = ref<number | null>(null);
 const shouldCancelInteraction = ref(false);
@@ -49,7 +48,7 @@ function handleStartCycle() {
 
 function handleCycleSnapPoints() {
   // Don't treat an accidental tap during a resize as a cycle.
-  if (isDragging.value || props.preventCycle || shouldCancelInteraction.value) {
+  if (isDragging.value || preventCycle || shouldCancelInteraction.value) {
     handleCancelInteraction();
     return;
   }
diff --git a/vue/primitives/src/drawer/DrawerOverlay.vue b/vue/primitives/src/overlays/drawer/DrawerOverlay.vue
similarity index 100%
rename from vue/primitives/src/drawer/DrawerOverlay.vue
rename to vue/primitives/src/overlays/drawer/DrawerOverlay.vue
diff --git a/vue/primitives/src/drawer/DrawerRoot.vue b/vue/primitives/src/overlays/drawer/DrawerRoot.vue
similarity index 100%
rename from vue/primitives/src/drawer/DrawerRoot.vue
rename to vue/primitives/src/overlays/drawer/DrawerRoot.vue
diff --git a/vue/primitives/src/drawer/DrawerRootNested.vue b/vue/primitives/src/overlays/drawer/DrawerRootNested.vue
similarity index 100%
rename from vue/primitives/src/drawer/DrawerRootNested.vue
rename to vue/primitives/src/overlays/drawer/DrawerRootNested.vue
diff --git a/vue/primitives/src/drawer/__test__/Drawer.test.ts b/vue/primitives/src/overlays/drawer/__test__/Drawer.test.ts
similarity index 100%
rename from vue/primitives/src/drawer/__test__/Drawer.test.ts
rename to vue/primitives/src/overlays/drawer/__test__/Drawer.test.ts
diff --git a/vue/primitives/src/drawer/constants.ts b/vue/primitives/src/overlays/drawer/constants.ts
similarity index 100%
rename from vue/primitives/src/drawer/constants.ts
rename to vue/primitives/src/overlays/drawer/constants.ts
diff --git a/vue/primitives/src/drawer/context.ts b/vue/primitives/src/overlays/drawer/context.ts
similarity index 94%
rename from vue/primitives/src/drawer/context.ts
rename to vue/primitives/src/overlays/drawer/context.ts
index 18c9502..93c3710 100644
--- a/vue/primitives/src/drawer/context.ts
+++ b/vue/primitives/src/overlays/drawer/context.ts
@@ -1,5 +1,6 @@
 import type { Ref } from 'vue';
 import { useContextFactory } from '@robonen/vue';
+import type { MaybeElementRef } from '@robonen/vue';
 import type { DrawerDirection } from './types';
 
 export interface DrawerRootContext {
@@ -12,11 +13,11 @@ export interface DrawerRootContext {
   /** Becomes `true` the first time the drawer opens; gates Safari position fixes. */
   hasBeenOpened: Ref<boolean>;
   /** DOM node of the drawer content (DialogContent), tracked for drag math. */
-  drawerRef: Ref<HTMLElement | undefined>;
+  drawerRef: MaybeElementRef<HTMLElement | undefined>;
   /** DOM node of the overlay, faded in sync with the drag. */
-  overlayRef: Ref<HTMLElement | undefined>;
+  overlayRef: MaybeElementRef<HTMLElement | undefined>;
   /** DOM node of the drag handle. */
-  handleRef: Ref<HTMLElement | undefined>;
+  handleRef: MaybeElementRef<HTMLElement | undefined>;
   /** Whether a pointer drag is currently in progress. */
   isDragging: Ref<boolean>;
   /** Timestamp the active drag started, for velocity calculations. */
diff --git a/vue/primitives/src/drawer/controls.ts b/vue/primitives/src/overlays/drawer/controls.ts
similarity index 93%
rename from vue/primitives/src/drawer/controls.ts
rename to vue/primitives/src/overlays/drawer/controls.ts
index d0557b6..e4787f4 100644
--- a/vue/primitives/src/drawer/controls.ts
+++ b/vue/primitives/src/overlays/drawer/controls.ts
@@ -1,5 +1,5 @@
 import type { Ref } from 'vue';
-import { computed, ref, watch, watchEffect } 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';
@@ -9,6 +9,9 @@ import { usePositionFixed } from './usePositionFixed';
 import type { DrawerRootContext } from './context';
 import type { DrawerDirection } 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
@@ -160,7 +163,7 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
   const isDragging = ref(false);
   const justReleased = ref(false);
 
-  const overlayRef = ref<HTMLElement | undefined>(undefined);
+  const overlayRef = shallowRef<HTMLElement | undefined>(undefined);
 
   const openTime = ref<Date | null>(null);
   const dragStartTime = ref<Date | null>(null);
@@ -173,14 +176,14 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
   const pointerStart = ref(0);
   const keyboardIsOpen = ref(false);
 
-  const drawerRef = ref<HTMLElement | undefined>(undefined);
+  const drawerRef = shallowRef<HTMLElement | undefined>(undefined);
   const drawerHeightRef = computed(() => drawerRef.value?.getBoundingClientRect().height || 0);
 
   const snapPoints = usePropOrDefaultRef(props.snapPoints, ref<Array<number | string> | undefined>(undefined));
 
   const hasSnapPoints = computed(() => !!(snapPoints.value?.length ?? 0));
 
-  const handleRef = ref<HTMLElement | undefined>(undefined);
+  const handleRef = shallowRef<HTMLElement | undefined>(undefined);
 
   const {
     activeSnapPointIndex,
@@ -280,6 +283,11 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     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) {
     if (!dismissible.value && !snapPoints.value)
       return;
@@ -287,6 +295,8 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
       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;
@@ -309,10 +319,10 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
         return;
 
       const absDraggedDistance = Math.abs(draggedDistance);
-      const wrapper = getDrawerWrapper();
+      const wrapper = dragWrapper;
 
-      // 1 means the closed position.
-      let percentageDragged = absDraggedDistance / drawerHeightRef.value;
+      // 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)
@@ -321,13 +331,17 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
       if (noCloseSnapPointsPreCondition && percentageDragged >= 1)
         return;
 
-      if (!isAllowedToDrag.value && !shouldDrag(event.target, isDraggingInDirection))
-        return;
-      drawerRef.value.classList.add(DRAG_CLASS);
-      // Once allowed, stay allowed for the whole gesture.
-      isAllowedToDrag.value = true;
-      setStyle(drawerRef.value, { transition: 'none' });
-      setStyle(overlayRef.value, { transition: 'none' });
+      // 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 });
@@ -455,6 +469,7 @@ export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRoo
     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');
 
diff --git a/vue/primitives/src/drawer/demo.vue b/vue/primitives/src/overlays/drawer/demo.vue
similarity index 68%
rename from vue/primitives/src/drawer/demo.vue
rename to vue/primitives/src/overlays/drawer/demo.vue
index d948258..ca7dd06 100644
--- a/vue/primitives/src/drawer/demo.vue
+++ b/vue/primitives/src/overlays/drawer/demo.vue
@@ -23,10 +23,10 @@ const selected = ref(goals[0]!.id);
 </script>
 
 <template>
-  <div class="flex flex-col items-start gap-3 text-(--fg)">
+  <div class="flex flex-col items-start gap-3 text-fg">
     <DrawerRoot v-model:open="open">
       <DrawerTrigger
-        class="inline-flex items-center rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex items-center rounded-md border border-border bg-bg px-3 py-1.5 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
       >
         Set today's goal
       </DrawerTrigger>
@@ -34,15 +34,15 @@ const selected = ref(goals[0]!.id);
       <DrawerPortal>
         <DrawerOverlay class="fixed inset-0 z-40 bg-black/40 backdrop-blur-sm" />
         <DrawerContent
-          class="fixed inset-x-0 bottom-0 z-50 mt-24 flex flex-col rounded-t-2xl border-t border-(--border) bg-(--bg-elevated) outline-none"
+          class="fixed inset-x-0 bottom-0 z-50 mt-24 flex flex-col rounded-t-2xl border-t border-border bg-bg-elevated outline-none"
         >
           <DrawerHandle class="mt-3 mb-1" />
 
           <div class="mx-auto w-full max-w-md px-5 pb-8 pt-2">
-            <DrawerTitle class="text-base font-semibold text-(--fg)">
+            <DrawerTitle class="text-base font-semibold text-fg">
               Set today's goal
             </DrawerTitle>
-            <DrawerDescription class="mt-1 text-sm text-(--fg-muted)">
+            <DrawerDescription class="mt-1 text-sm text-fg-muted">
               Pick one thing to focus on. Drag the handle down to dismiss.
             </DrawerDescription>
 
@@ -53,17 +53,17 @@ const selected = ref(goals[0]!.id);
                 type="button"
                 class="flex items-center justify-between rounded-lg border px-3 py-2.5 text-left text-sm transition-colors"
                 :class="selected === goal.id
-                  ? 'border-(--accent) bg-(--accent)/10 text-(--fg)'
-                  : 'border-(--border) bg-(--bg) text-(--fg) hover:bg-(--bg-subtle)'"
+                  ? 'border-accent bg-accent/10 text-fg'
+                  : 'border-border bg-bg text-fg hover:bg-bg-subtle'"
                 @click="selected = goal.id"
               >
                 <span>
                   <span class="font-medium">{{ goal.label }}</span>
-                  <span class="block text-xs text-(--fg-muted)">{{ goal.detail }}</span>
+                  <span class="block text-xs text-fg-muted">{{ goal.detail }}</span>
                 </span>
                 <span
                   v-if="selected === goal.id"
-                  class="inline-flex size-5 items-center justify-center rounded-full bg-(--accent) text-(--accent-fg)"
+                  class="inline-flex size-5 items-center justify-center rounded-full bg-accent text-accent-fg"
                 >
                   <svg class="size-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
                     <path d="M20 6 9 17l-5-5" />
@@ -74,13 +74,13 @@ const selected = ref(goals[0]!.id);
 
             <div class="mt-5 flex justify-end gap-2">
               <DrawerClose
-                class="inline-flex items-center rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+                class="inline-flex items-center rounded-md border border-border bg-bg px-3 py-1.5 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
                 Cancel
               </DrawerClose>
               <button
                 type="button"
-                class="inline-flex items-center rounded-md bg-(--accent) px-3 py-1.5 text-sm font-medium text-(--accent-fg) transition-colors hover:bg-(--accent-hover) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+                class="inline-flex items-center rounded-md bg-accent px-3 py-1.5 text-sm font-medium text-accent-fg transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
                 @click="open = false"
               >
                 Save goal
diff --git a/vue/primitives/src/drawer/helpers.ts b/vue/primitives/src/overlays/drawer/helpers.ts
similarity index 100%
rename from vue/primitives/src/drawer/helpers.ts
rename to vue/primitives/src/overlays/drawer/helpers.ts
diff --git a/vue/primitives/src/drawer/index.ts b/vue/primitives/src/overlays/drawer/index.ts
similarity index 100%
rename from vue/primitives/src/drawer/index.ts
rename to vue/primitives/src/overlays/drawer/index.ts
diff --git a/vue/primitives/src/drawer/style.ts b/vue/primitives/src/overlays/drawer/style.ts
similarity index 100%
rename from vue/primitives/src/drawer/style.ts
rename to vue/primitives/src/overlays/drawer/style.ts
diff --git a/vue/primitives/src/drawer/types.ts b/vue/primitives/src/overlays/drawer/types.ts
similarity index 100%
rename from vue/primitives/src/drawer/types.ts
rename to vue/primitives/src/overlays/drawer/types.ts
diff --git a/vue/primitives/src/drawer/usePositionFixed.ts b/vue/primitives/src/overlays/drawer/usePositionFixed.ts
similarity index 78%
rename from vue/primitives/src/drawer/usePositionFixed.ts
rename to vue/primitives/src/overlays/drawer/usePositionFixed.ts
index ff03a60..a0eef54 100644
--- a/vue/primitives/src/drawer/usePositionFixed.ts
+++ b/vue/primitives/src/overlays/drawer/usePositionFixed.ts
@@ -1,6 +1,7 @@
 import type { Ref } from 'vue';
-import { onMounted, onUnmounted, ref, watch } from 'vue';
+import { ref, watch } from 'vue';
 import { isSafari } from '@robonen/platform/browsers';
+import { useEventListener, useMediaQuery } from '@robonen/vue';
 
 interface BodyPosition {
   position: string;
@@ -31,6 +32,8 @@ export function usePositionFixed(options: PositionFixedOptions) {
   const { isOpen, modal, nested, hasBeenOpened, preventScrollRestoration, noBodyStyles } = options;
   const activeUrl = ref(globalThis.window !== undefined ? globalThis.location.href : '');
   const scrollPos = ref(0);
+  // Standalone PWAs have no address bar to fight (SSR-safe via useMediaQuery).
+  const isStandalone = useMediaQuery('(display-mode: standalone)');
 
   function setPositionFixed(): void {
     if (!isSafari())
@@ -89,27 +92,25 @@ export function usePositionFixed(options: PositionFixedOptions) {
     }
   }
 
-  onMounted(() => {
-    function onScroll() {
-      scrollPos.value = window.scrollY;
-    }
+  function onScroll() {
+    scrollPos.value = window.scrollY;
+  }
 
+  // Capture the position at setup (the page may already be scrolled), then keep
+  // it in sync. `useEventListener` defaults to `defaultWindow` and auto-removes.
+  if (globalThis.window !== undefined)
     onScroll();
-    window.addEventListener('scroll', onScroll);
+  useEventListener('scroll', onScroll, { passive: true });
 
-    onUnmounted(() => {
-      window.removeEventListener('scroll', onScroll);
-    });
-  });
-
-  watch([isOpen, hasBeenOpened, activeUrl], () => {
+  // `activeUrl` is read inside restorePositionSetting's rAF to detect navigation,
+  // but it must NOT drive this watch — it mutates on close and would re-fire the
+  // (idempotent) handler once for nothing.
+  watch([isOpen, hasBeenOpened], () => {
     if (nested.value || !hasBeenOpened.value)
       return;
 
     if (isOpen.value) {
-      // Standalone PWAs have no address bar to fight.
-      const isStandalone = globalThis.matchMedia('(display-mode: standalone)').matches;
-      if (!isStandalone)
+      if (!isStandalone.value)
         setPositionFixed();
 
       if (!modal.value) {
diff --git a/vue/primitives/src/drawer/useScaleBackground.ts b/vue/primitives/src/overlays/drawer/useScaleBackground.ts
similarity index 95%
rename from vue/primitives/src/drawer/useScaleBackground.ts
rename to vue/primitives/src/overlays/drawer/useScaleBackground.ts
index 93f870d..95a945c 100644
--- a/vue/primitives/src/drawer/useScaleBackground.ts
+++ b/vue/primitives/src/overlays/drawer/useScaleBackground.ts
@@ -1,4 +1,4 @@
-import { ref, watchEffect } from 'vue';
+import { onWatcherCleanup, ref, watchEffect } from 'vue';
 import { isClient } from '@robonen/platform/multi';
 import { assignStyle } from '@robonen/platform/browsers';
 import { injectDrawerRootContext } from './context';
@@ -20,7 +20,7 @@ export function useScaleBackground() {
     return (window.innerWidth - WINDOW_TOP_OFFSET) / window.innerWidth;
   }
 
-  watchEffect((onCleanup) => {
+  watchEffect(() => {
     // `flush: 'pre'` watchers run during SSR; this effect touches document/window,
     // so it must stay client-only.
     if (isClient && isOpen.value && shouldScaleBackground.value) {
@@ -50,7 +50,7 @@ export function useScaleBackground() {
           : { transform: `scale(${getScale()}) translate3d(calc(env(safe-area-inset-top) + 14px), 0, 0)` }),
       });
 
-      onCleanup(() => {
+      onWatcherCleanup(() => {
         wrapperStylesCleanup();
         timeoutIdRef.value = globalThis.setTimeout(() => {
           if (initialBackgroundColor.value)
diff --git a/vue/primitives/src/drawer/useSnapPoints.ts b/vue/primitives/src/overlays/drawer/useSnapPoints.ts
similarity index 93%
rename from vue/primitives/src/drawer/useSnapPoints.ts
rename to vue/primitives/src/overlays/drawer/useSnapPoints.ts
index 6cdd821..dc5b481 100644
--- a/vue/primitives/src/drawer/useSnapPoints.ts
+++ b/vue/primitives/src/overlays/drawer/useSnapPoints.ts
@@ -1,6 +1,7 @@
 import type { Ref } from 'vue';
-import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { computed, nextTick, ref, 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 type { DrawerDirection } from './types';
@@ -38,18 +39,17 @@ export function useSnapPoints({
     : undefined);
 
   function onResize() {
-    windowDimensions.value = { innerWidth: window.innerWidth, innerHeight: window.innerHeight };
+    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 };
   }
 
-  onMounted(() => {
-    if (globalThis.window !== undefined)
-      window.addEventListener('resize', onResize);
-  });
-
-  onBeforeUnmount(() => {
-    if (globalThis.window !== undefined)
-      window.removeEventListener('resize', onResize);
-  });
+  // Defaults to `defaultWindow` (SSR-safe) and auto-removes on scope dispose.
+  useEventListener('resize', onResize);
 
   const isLastSnapPoint = computed(
     () => (snapPoints.value && activeSnapPoint.value === snapPoints.value[snapPoints.value.length - 1]) ?? null,
diff --git a/vue/primitives/src/hover-card/HoverCardArrow.vue b/vue/primitives/src/overlays/hover-card/HoverCardArrow.vue
similarity index 100%
rename from vue/primitives/src/hover-card/HoverCardArrow.vue
rename to vue/primitives/src/overlays/hover-card/HoverCardArrow.vue
diff --git a/vue/primitives/src/hover-card/HoverCardContent.vue b/vue/primitives/src/overlays/hover-card/HoverCardContent.vue
similarity index 88%
rename from vue/primitives/src/hover-card/HoverCardContent.vue
rename to vue/primitives/src/overlays/hover-card/HoverCardContent.vue
index 6a29725..9fcb876 100644
--- a/vue/primitives/src/hover-card/HoverCardContent.vue
+++ b/vue/primitives/src/overlays/hover-card/HoverCardContent.vue
@@ -16,18 +16,21 @@ export type HoverCardContentEmits = HoverCardContentImplEmits;
 
 <script setup lang="ts">
 import HoverCardContentImpl from './HoverCardContentImpl.vue';
-import { Presence } from '../presence';
+import { Presence } from '../../utilities/presence';
+import { useForwardExpose } from '@robonen/vue';
 import { useHoverCardContext } from './context';
 
 const { forceMount = false, ...contentProps } = defineProps<HoverCardContentProps>();
 const emit = defineEmits<HoverCardContentEmits>();
 const ctx = useHoverCardContext();
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
   <Presence :present="ctx.open.value" :force-mount="forceMount">
     <HoverCardContentImpl
       v-bind="contentProps"
+      :ref="forwardRef"
       @escape-key-down="emit('escapeKeyDown', $event)"
       @pointer-down-outside="emit('pointerDownOutside', $event)"
       @focus-outside="emit('focusOutside', $event)"
diff --git a/vue/primitives/src/hover-card/HoverCardContentImpl.vue b/vue/primitives/src/overlays/hover-card/HoverCardContentImpl.vue
similarity index 74%
rename from vue/primitives/src/hover-card/HoverCardContentImpl.vue
rename to vue/primitives/src/overlays/hover-card/HoverCardContentImpl.vue
index e8c1294..cffdd03 100644
--- a/vue/primitives/src/hover-card/HoverCardContentImpl.vue
+++ b/vue/primitives/src/overlays/hover-card/HoverCardContentImpl.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
 import type { PopperContentProps } from '../popper';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Internal implementation of the hover card panel: it wires up Popper
@@ -20,10 +20,14 @@ export interface HoverCardContentImplProps extends PrimitiveProps, Pick<
   | 'collisionBoundary'
   | 'collisionPadding'
   | 'arrowPadding'
+  | 'hideShiftedArrow'
   | 'sticky'
   | 'hideWhenDetached'
   | 'positionStrategy'
   | 'updatePositionStrategy'
+  | 'disableUpdateOnLayoutShift'
+  | 'prioritizePosition'
+  | 'reference'
 > {}
 
 export interface HoverCardContentImplEmits {
@@ -35,12 +39,12 @@ export interface HoverCardContentImplEmits {
 </script>
 
 <script setup lang="ts">
-import { nextTick, onMounted, onScopeDispose, ref, watchEffect } from 'vue';
-import { DismissableLayer } from '../dismissable-layer';
+import { nextTick, onMounted, onScopeDispose, onWatcherCleanup, ref, watchEffect } from 'vue';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
 import { PopperContent } from '../popper';
-import { excludeTouch } from './utils';
-import { useForwardExpose } from '@robonen/vue';
-import { useGraceArea } from '../utils/useGraceArea';
+import { excludeTouch, getTabbableNodes } from './utils';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+import { useGraceArea } from '../../internal/utils/useGraceArea';
 import { useHoverCardContext } from './context';
 
 const {
@@ -54,10 +58,14 @@ const {
   collisionBoundary = [],
   collisionPadding = 0,
   arrowPadding = 0,
+  hideShiftedArrow = true,
   sticky = 'partial',
   hideWhenDetached = false,
   positionStrategy,
   updatePositionStrategy,
+  disableUpdateOnLayoutShift = false,
+  prioritizePosition = false,
+  reference,
   as = 'div',
 } = defineProps<HoverCardContentImplProps>();
 
@@ -78,14 +86,14 @@ const containSelection = ref(false);
 let originalUserSelect: string | undefined;
 let originalWebkitUserSelect: string | undefined;
 
-watchEffect((cleanup) => {
+watchEffect(() => {
   if (!containSelection.value) return;
   const body = document.body;
   originalUserSelect = body.style.userSelect;
   originalWebkitUserSelect = body.style.webkitUserSelect;
   body.style.userSelect = 'none';
   body.style.webkitUserSelect = 'none';
-  cleanup(() => {
+  onWatcherCleanup(() => {
     body.style.userSelect = originalUserSelect ?? '';
     body.style.webkitUserSelect = originalWebkitUserSelect ?? '';
   });
@@ -105,14 +113,24 @@ function onScrollCapture(event: Event) {
   if (target && ctx.trigger.value && target.contains(ctx.trigger.value)) ctx.onDismiss();
 }
 
+// Auto-removed on scope dispose. SSR-safe: the window default no-ops without a
+// `window`, and the `document` getter resolves to `undefined` on the server.
+// `passive`/`capture` preserved.
+useEventListener(() => globalThis.document, 'pointerup', onPointerUp);
+useEventListener('scroll', onScrollCapture, { capture: true, passive: true });
+
 onMounted(() => {
-  document.addEventListener('pointerup', onPointerUp);
-  globalThis.addEventListener('scroll', onScrollCapture, { capture: true });
+  // A hover-triggered card is not a focus stop: it opens on hover/focus of the
+  // trigger, never receives focus itself, and its body is a sighted-user
+  // preview. Remove every focusable descendant from the tab sequence so keyboard
+  // users don't tab into content that has no visible focus context.
+  const content = currentElement.value;
+  if (content) {
+    for (const tabbable of getTabbableNodes(content)) tabbable.setAttribute('tabindex', '-1');
+  }
 });
 
 onScopeDispose(() => {
-  document.removeEventListener('pointerup', onPointerUp);
-  globalThis.removeEventListener('scroll', onScrollCapture, { capture: true });
   ctx.hasSelection.value = false;
   ctx.isPointerDownOnContent.value = false;
 });
@@ -153,10 +171,14 @@ function onContentPointerEnter(event: PointerEvent) {
       :collision-boundary="collisionBoundary"
       :collision-padding="collisionPadding"
       :arrow-padding="arrowPadding"
+      :hide-shifted-arrow="hideShiftedArrow"
       :sticky="sticky"
       :hide-when-detached="hideWhenDetached"
       :position-strategy="positionStrategy"
       :update-position-strategy="updatePositionStrategy"
+      :disable-update-on-layout-shift="disableUpdateOnLayoutShift"
+      :prioritize-position="prioritizePosition"
+      :reference="reference"
       :data-state="ctx.open.value ? 'open' : 'closed'"
       :style="{
         'user-select': containSelection ? 'text' : undefined,
diff --git a/vue/primitives/src/hover-card/HoverCardPortal.vue b/vue/primitives/src/overlays/hover-card/HoverCardPortal.vue
similarity index 80%
rename from vue/primitives/src/hover-card/HoverCardPortal.vue
rename to vue/primitives/src/overlays/hover-card/HoverCardPortal.vue
index 8ed53c3..07c2fb5 100644
--- a/vue/primitives/src/hover-card/HoverCardPortal.vue
+++ b/vue/primitives/src/overlays/hover-card/HoverCardPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { TeleportPrimitiveProps } from '../teleport';
+import type { TeleportPrimitiveProps } from '../../utilities/teleport';
 
 /**
  * Teleports the hover card content into a different part of the DOM (the body by
@@ -10,7 +10,7 @@ export interface HoverCardPortalProps extends TeleportPrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Portal } from '../teleport';
+import { Portal } from '../../utilities/teleport';
 
 const props = defineProps<HoverCardPortalProps>();
 </script>
diff --git a/vue/primitives/src/hover-card/HoverCardRoot.vue b/vue/primitives/src/overlays/hover-card/HoverCardRoot.vue
similarity index 90%
rename from vue/primitives/src/hover-card/HoverCardRoot.vue
rename to vue/primitives/src/overlays/hover-card/HoverCardRoot.vue
index 2d758fc..9b1360a 100644
--- a/vue/primitives/src/hover-card/HoverCardRoot.vue
+++ b/vue/primitives/src/overlays/hover-card/HoverCardRoot.vue
@@ -21,10 +21,15 @@ export interface HoverCardRootProps {
   /** Delay (ms) before the content closes after pointer leaves trigger/content. */
   closeDelay?: number;
 }
+
+export interface HoverCardRootEmits {
+  /** Emitted whenever the open state changes. Drives `v-model:open`. */
+  'update:open': [value: boolean];
+}
 </script>
 
 <script setup lang="ts">
-import { computed, onScopeDispose, ref } from 'vue';
+import { computed, onScopeDispose, ref, shallowRef } from 'vue';
 import { PopperRoot } from '../popper';
 import { provideHoverCardContext } from './context';
 
@@ -63,7 +68,7 @@ function clearCloseTimer() {
 const hasSelection = ref(false);
 const isPointerDownOnContent = ref(false);
 const isPointerInTransit = ref(false);
-const trigger = ref<HTMLElement | undefined>();
+const trigger = shallowRef<HTMLElement | undefined>();
 
 function onOpen() {
   clearCloseTimer();
@@ -117,7 +122,7 @@ provideHoverCardContext({
 });
 
 defineSlots<{
-  default?: (props: { open: boolean }) => any;
+  default?: (props: { open: boolean }) => unknown;
 }>();
 </script>
 
diff --git a/vue/primitives/src/hover-card/HoverCardTrigger.vue b/vue/primitives/src/overlays/hover-card/HoverCardTrigger.vue
similarity index 93%
rename from vue/primitives/src/hover-card/HoverCardTrigger.vue
rename to vue/primitives/src/overlays/hover-card/HoverCardTrigger.vue
index c963aa9..49ec138 100644
--- a/vue/primitives/src/hover-card/HoverCardTrigger.vue
+++ b/vue/primitives/src/overlays/hover-card/HoverCardTrigger.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
 import type { PopperAnchorProps } from '../popper';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The element that opens the hover card on pointer enter or focus and anchors
@@ -12,7 +12,7 @@ export interface HoverCardTriggerProps extends PrimitiveProps, Pick<PopperAnchor
 
 <script setup lang="ts">
 import { PopperAnchor } from '../popper';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { excludeTouch } from './utils';
 import { useForwardExpose } from '@robonen/vue';
 import { useHoverCardContext } from './context';
diff --git a/vue/primitives/src/hover-card/__test__/HoverCard.test.ts b/vue/primitives/src/overlays/hover-card/__test__/HoverCard.test.ts
similarity index 67%
rename from vue/primitives/src/hover-card/__test__/HoverCard.test.ts
rename to vue/primitives/src/overlays/hover-card/__test__/HoverCard.test.ts
index cd86ce5..47cb3fc 100644
--- a/vue/primitives/src/hover-card/__test__/HoverCard.test.ts
+++ b/vue/primitives/src/overlays/hover-card/__test__/HoverCard.test.ts
@@ -2,7 +2,7 @@ import {
   HoverCardContent,
   HoverCardRoot,
   HoverCardTrigger,
-} from '../../index';
+} from '../../../index';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { defineComponent, h, nextTick } from 'vue';
 import type { VueWrapper } from '@vue/test-utils';
@@ -173,4 +173,80 @@ describe('HoverCard', () => {
     await nextTick();
     expect(trigger.getAttribute('data-state')).toBe('open');
   });
+
+  it('removes focusable content descendants from the tab sequence', async () => {
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HoverCardRoot, { defaultOpen: true }, {
+            default: () => [
+              h(HoverCardTrigger, null, { default: () => 'Trigger' }),
+              h(HoverCardContent, null, {
+                default: () => [
+                  h('a', { href: '#one', 'data-link': 'one' }, 'Link one'),
+                  h('button', { 'data-btn': 'two' }, 'Button two'),
+                ],
+              }),
+            ],
+          });
+      },
+    });
+    track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    const link = document.querySelector('[data-link="one"]') as HTMLElement;
+    const button = document.querySelector('[data-btn="two"]') as HTMLElement;
+    expect(link).toBeTruthy();
+    expect(button).toBeTruthy();
+    expect(link.getAttribute('tabindex')).toBe('-1');
+    expect(button.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('exposes the content element via a forwarded ref', async () => {
+    const contentRef = vi.fn();
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HoverCardRoot, { defaultOpen: true }, {
+            default: () => [
+              h(HoverCardTrigger, null, { default: () => 'Trigger' }),
+              h(HoverCardContent, { ref: contentRef }, { default: () => 'Body' }),
+            ],
+          });
+      },
+    });
+    track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+    expect(contentRef).toHaveBeenCalled();
+    const instance = contentRef.mock.calls.at(-1)?.[0];
+    expect(instance).toBeTruthy();
+  });
+
+  it('forwards extended positioning props to the content without error', async () => {
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HoverCardRoot, { defaultOpen: true }, {
+            default: () => [
+              h(HoverCardTrigger, null, { default: () => 'Trigger' }),
+              h(
+                HoverCardContent,
+                {
+                  prioritizePosition: true,
+                  disableUpdateOnLayoutShift: true,
+                  hideShiftedArrow: false,
+                  'data-marker': 'content',
+                },
+                { default: () => 'Body' },
+              ),
+            ],
+          });
+      },
+    });
+    track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+    const content = document.querySelector('[data-marker="content"]') as HTMLElement;
+    expect(content).toBeTruthy();
+    expect(content.getAttribute('data-state')).toBe('open');
+  });
 });
diff --git a/vue/primitives/src/hover-card/context.ts b/vue/primitives/src/overlays/hover-card/context.ts
similarity index 100%
rename from vue/primitives/src/hover-card/context.ts
rename to vue/primitives/src/overlays/hover-card/context.ts
diff --git a/vue/primitives/src/hover-card/demo.vue b/vue/primitives/src/overlays/hover-card/demo.vue
similarity index 52%
rename from vue/primitives/src/hover-card/demo.vue
rename to vue/primitives/src/overlays/hover-card/demo.vue
index 59203ff..f94c5c8 100644
--- a/vue/primitives/src/hover-card/demo.vue
+++ b/vue/primitives/src/overlays/hover-card/demo.vue
@@ -17,12 +17,12 @@ const user = {
 </script>
 
 <template>
-  <p class="text-sm text-(--fg)">
+  <p class="text-sm text-fg">
     Maintained by
     <HoverCardRoot :open-delay="200" :close-delay="150">
       <HoverCardTrigger
         href="#"
-        class="rounded font-medium text-(--accent) underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="rounded font-medium text-accent underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
       >
         {{ user.handle }}
       </HoverCardTrigger>
@@ -30,28 +30,28 @@ const user = {
       <HoverCardPortal>
         <HoverCardContent
           :side-offset="6"
-          class="z-50 w-72 rounded-xl border border-(--border) bg-(--bg-elevated) p-4 text-(--fg) shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out data-[state=open]:fade-in data-[state=open]:zoom-in-95"
+          class="demo-card z-50 w-72 p-4 text-fg shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out data-[state=open]:fade-in data-[state=open]:zoom-in-95"
         >
           <div class="flex items-start gap-3">
-            <div class="flex size-11 shrink-0 items-center justify-center rounded-full bg-(--accent) text-base font-semibold text-(--accent-fg)">
+            <div class="flex size-11 shrink-0 items-center justify-center rounded-full bg-accent text-base font-semibold text-accent-fg">
               {{ user.name.charAt(0) }}
             </div>
             <div class="min-w-0">
               <div class="truncate font-semibold leading-tight">{{ user.name }}</div>
-              <div class="truncate text-sm text-(--fg-muted)">{{ user.handle }}</div>
+              <div class="truncate text-sm text-fg-muted">{{ user.handle }}</div>
             </div>
           </div>
 
-          <p class="mt-3 text-sm text-(--fg-muted)">{{ user.bio }}</p>
+          <p class="mt-3 text-sm text-fg-muted">{{ user.bio }}</p>
 
-          <div class="mt-3 flex gap-4 border-t border-(--border) pt-3 text-sm">
-            <span><span class="font-semibold text-(--fg)">{{ user.following }}</span> <span class="text-(--fg-subtle)">Following</span></span>
-            <span><span class="font-semibold text-(--fg)">{{ user.followers }}</span> <span class="text-(--fg-subtle)">Followers</span></span>
+          <div class="mt-3 flex gap-4 border-t border-border pt-3 text-sm">
+            <span><span class="font-semibold text-fg">{{ user.following }}</span> <span class="text-fg-subtle">Following</span></span>
+            <span><span class="font-semibold text-fg">{{ user.followers }}</span> <span class="text-fg-subtle">Followers</span></span>
           </div>
 
           <HoverCardArrow :width="12" :height="6">
             <svg width="12" height="6" viewBox="0 0 12 6" class="block" aria-hidden="true">
-              <path d="M0 0 L6 6 L12 0 Z" class="fill-(--bg-elevated) stroke-(--border)" stroke-width="1" />
+              <path d="M0 0 L6 6 L12 0 Z" class="fill-bg-elevated stroke-border" stroke-width="1" />
             </svg>
           </HoverCardArrow>
         </HoverCardContent>
diff --git a/vue/primitives/src/hover-card/index.ts b/vue/primitives/src/overlays/hover-card/index.ts
similarity index 90%
rename from vue/primitives/src/hover-card/index.ts
rename to vue/primitives/src/overlays/hover-card/index.ts
index 745bc64..e20a1cc 100644
--- a/vue/primitives/src/hover-card/index.ts
+++ b/vue/primitives/src/overlays/hover-card/index.ts
@@ -6,7 +6,7 @@ export { default as HoverCardArrow } from './HoverCardArrow.vue';
 
 export { useHoverCardContext, type HoverCardContext } from './context';
 
-export type { HoverCardRootProps } from './HoverCardRoot.vue';
+export type { HoverCardRootProps, HoverCardRootEmits } from './HoverCardRoot.vue';
 export type { HoverCardTriggerProps } from './HoverCardTrigger.vue';
 export type { HoverCardPortalProps } from './HoverCardPortal.vue';
 export type { HoverCardContentProps, HoverCardContentEmits } from './HoverCardContent.vue';
diff --git a/vue/primitives/src/hover-card/utils.ts b/vue/primitives/src/overlays/hover-card/utils.ts
similarity index 100%
rename from vue/primitives/src/hover-card/utils.ts
rename to vue/primitives/src/overlays/hover-card/utils.ts
diff --git a/vue/primitives/src/popover/PopoverAnchor.vue b/vue/primitives/src/overlays/popover/PopoverAnchor.vue
similarity index 85%
rename from vue/primitives/src/popover/PopoverAnchor.vue
rename to vue/primitives/src/overlays/popover/PopoverAnchor.vue
index 1525f02..16f4c7c 100644
--- a/vue/primitives/src/popover/PopoverAnchor.vue
+++ b/vue/primitives/src/overlays/popover/PopoverAnchor.vue
@@ -12,11 +12,13 @@ export interface PopoverAnchorProps extends PopperAnchorProps {}
 <script setup lang="ts">
 import { onBeforeMount, onUnmounted } from 'vue';
 import { PopperAnchor } from '../popper';
+import { useForwardExpose } from '@robonen/vue';
 import { usePopoverContext } from './context';
 
 const props = defineProps<PopoverAnchorProps>();
 
 const ctx = usePopoverContext();
+const { forwardRef } = useForwardExpose();
 
 onBeforeMount(() => {
   ctx.hasCustomAnchor.value = true;
@@ -27,7 +29,7 @@ onUnmounted(() => {
 </script>
 
 <template>
-  <PopperAnchor v-bind="props">
+  <PopperAnchor :ref="forwardRef" v-bind="props">
     <slot />
   </PopperAnchor>
 </template>
diff --git a/vue/primitives/src/popover/PopoverArrow.vue b/vue/primitives/src/overlays/popover/PopoverArrow.vue
similarity index 72%
rename from vue/primitives/src/popover/PopoverArrow.vue
rename to vue/primitives/src/overlays/popover/PopoverArrow.vue
index fd95e5f..d5a5cc3 100644
--- a/vue/primitives/src/popover/PopoverArrow.vue
+++ b/vue/primitives/src/overlays/popover/PopoverArrow.vue
@@ -11,12 +11,15 @@ export interface PopoverArrowProps extends PopperArrowProps {}
 
 <script setup lang="ts">
 import { PopperArrow } from '../popper';
+import { useForwardExpose } from '@robonen/vue';
 
-const { width = 10, height = 5 } = defineProps<PopoverArrowProps>();
+const props = defineProps<PopoverArrowProps>();
+
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
-  <PopperArrow :width="width" :height="height">
+  <PopperArrow :ref="forwardRef" v-bind="props">
     <slot />
   </PopperArrow>
 </template>
diff --git a/vue/primitives/src/popover/PopoverClose.vue b/vue/primitives/src/overlays/popover/PopoverClose.vue
similarity index 85%
rename from vue/primitives/src/popover/PopoverClose.vue
rename to vue/primitives/src/overlays/popover/PopoverClose.vue
index 558c4ec..51ef12a 100644
--- a/vue/primitives/src/popover/PopoverClose.vue
+++ b/vue/primitives/src/overlays/popover/PopoverClose.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that closes the popover when activated. Place inside Content for an
@@ -9,7 +9,7 @@ export interface PopoverCloseProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { usePopoverContext } from './context';
 
diff --git a/vue/primitives/src/popover/PopoverContent.vue b/vue/primitives/src/overlays/popover/PopoverContent.vue
similarity index 91%
rename from vue/primitives/src/popover/PopoverContent.vue
rename to vue/primitives/src/overlays/popover/PopoverContent.vue
index 54f0a5b..4e24f07 100644
--- a/vue/primitives/src/popover/PopoverContent.vue
+++ b/vue/primitives/src/overlays/popover/PopoverContent.vue
@@ -19,13 +19,15 @@ export type PopoverContentEmits = PopoverContentImplEmits;
 <script setup lang="ts">
 import PopoverContentModal from './PopoverContentModal.vue';
 import PopoverContentNonModal from './PopoverContentNonModal.vue';
-import { Presence } from '../presence';
+import { Presence } from '../../utilities/presence';
+import { useForwardExpose } from '@robonen/vue';
 import { usePopoverContext } from './context';
 
 const { forceMount = false, ...contentProps } = defineProps<PopoverContentProps>();
 const emit = defineEmits<PopoverContentEmits>();
 
 const ctx = usePopoverContext();
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
@@ -33,6 +35,7 @@ const ctx = usePopoverContext();
     <PopoverContentModal
       v-if="ctx.modal.value"
       v-bind="contentProps"
+      :ref="forwardRef"
       @open-auto-focus="emit('openAutoFocus', $event)"
       @close-auto-focus="emit('closeAutoFocus', $event)"
       @escape-key-down="emit('escapeKeyDown', $event)"
@@ -46,6 +49,7 @@ const ctx = usePopoverContext();
     <PopoverContentNonModal
       v-else
       v-bind="contentProps"
+      :ref="forwardRef"
       @open-auto-focus="emit('openAutoFocus', $event)"
       @close-auto-focus="emit('closeAutoFocus', $event)"
       @escape-key-down="emit('escapeKeyDown', $event)"
diff --git a/vue/primitives/src/popover/PopoverContentImpl.vue b/vue/primitives/src/overlays/popover/PopoverContentImpl.vue
similarity index 61%
rename from vue/primitives/src/popover/PopoverContentImpl.vue
rename to vue/primitives/src/overlays/popover/PopoverContentImpl.vue
index b9c5975..3cfde79 100644
--- a/vue/primitives/src/popover/PopoverContentImpl.vue
+++ b/vue/primitives/src/overlays/popover/PopoverContentImpl.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
-import type { DismissableLayerEmits } from '../dismissable-layer';
-import type { FocusScopeEmits } from '../focus-scope';
+import type { DismissableLayerEmits } from '../../utilities/dismissable-layer';
+import type { FocusScopeEmits } from '../../utilities/focus-scope';
 import type { PopperContentProps } from '../popper';
 
 /**
@@ -25,12 +25,29 @@ export interface PopoverContentImplEmits {
   interactOutside: DismissableLayerEmits['interactOutside'];
   dismiss: [];
 }
+
+/**
+ * Static `--popover-*` CSS-variable mappings forwarded to PopperContent. The
+ * values never change (pure `var(--popper-*)` references), so the object is
+ * hoisted to module scope with a stable, frozen identity. PopperContent
+ * re-positions on every animation frame while open (updatePositionStrategy
+ * 'always'); a stable reference lets Vue short-circuit the :style diff and
+ * removes a per-render object allocation on that hot path.
+ */
+const POPOVER_CONTENT_STYLE = Object.freeze({
+  '--popover-content-transform-origin': 'var(--popper-transform-origin)',
+  '--popover-content-available-width': 'var(--popper-available-width)',
+  '--popover-content-available-height': 'var(--popper-available-height)',
+  '--popover-trigger-width': 'var(--popper-anchor-width)',
+  '--popover-trigger-height': 'var(--popper-anchor-height)',
+});
 </script>
 
 <script setup lang="ts">
-import { DismissableLayer } from '../dismissable-layer';
-import { FocusScope } from '../focus-scope';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
+import { FocusScope } from '../../utilities/focus-scope';
 import { PopperContent } from '../popper';
+import { useFocusGuard, useForwardExpose } from '@robonen/vue';
 import { usePopoverContext } from './context';
 
 const {
@@ -43,6 +60,11 @@ const {
 const emit = defineEmits<PopoverContentImplEmits>();
 
 const ctx = usePopoverContext();
+const { forwardRef } = useForwardExpose();
+
+// Insert tabbable focus-guard sentinels at the document edges so focusin/out
+// are caught consistently and Tab cannot escape into the browser chrome.
+useFocusGuard();
 </script>
 
 <template>
@@ -64,18 +86,13 @@ const ctx = usePopoverContext();
     >
       <PopperContent
         :id="ctx.contentId.value"
+        :ref="forwardRef"
         :as="as"
         v-bind="popperProps"
         :data-state="ctx.open.value ? 'open' : 'closed'"
         :aria-labelledby="ctx.triggerId.value"
         role="dialog"
-        :style="{
-          '--popover-content-transform-origin': 'var(--popper-transform-origin)',
-          '--popover-content-available-width': 'var(--popper-available-width)',
-          '--popover-content-available-height': 'var(--popper-available-height)',
-          '--popover-trigger-width': 'var(--popper-anchor-width)',
-          '--popover-trigger-height': 'var(--popper-anchor-height)',
-        }"
+        :style="POPOVER_CONTENT_STYLE"
       >
         <slot />
       </PopperContent>
diff --git a/vue/primitives/src/popover/PopoverContentModal.vue b/vue/primitives/src/overlays/popover/PopoverContentModal.vue
similarity index 76%
rename from vue/primitives/src/popover/PopoverContentModal.vue
rename to vue/primitives/src/overlays/popover/PopoverContentModal.vue
index fac0124..827870e 100644
--- a/vue/primitives/src/popover/PopoverContentModal.vue
+++ b/vue/primitives/src/overlays/popover/PopoverContentModal.vue
@@ -2,7 +2,8 @@
 import type { PopoverContentImplEmits, PopoverContentImplProps } from './PopoverContentImpl.vue';
 import PopoverContentImpl from './PopoverContentImpl.vue';
 import { ref } from 'vue';
-import { useBodyScrollLock } from '@robonen/vue';
+import { useBodyScrollLock, useForwardExpose } from '@robonen/vue';
+import { useHideOthers } from '../../internal/utils/useHideOthers';
 import { usePopoverContext } from './context';
 
 const props = defineProps<PopoverContentImplProps>();
@@ -11,12 +12,18 @@ const emit = defineEmits<PopoverContentImplEmits>();
 const ctx = usePopoverContext();
 const isRightClickOutsideRef = ref(false);
 
+const { forwardRef, currentElement } = useForwardExpose();
+
 useBodyScrollLock();
+// Modal popovers hide every sibling tree from assistive tech so screen readers
+// stay scoped to the content while it is open (parity with Dialog/Menu).
+useHideOthers(currentElement);
 </script>
 
 <template>
   <PopoverContentImpl
     v-bind="props"
+    :ref="forwardRef"
     :trap-focus="ctx.open.value"
     disable-outside-pointer-events
     @close-auto-focus.prevent="(event: Event) => {
diff --git a/vue/primitives/src/popover/PopoverContentNonModal.vue b/vue/primitives/src/overlays/popover/PopoverContentNonModal.vue
similarity index 93%
rename from vue/primitives/src/popover/PopoverContentNonModal.vue
rename to vue/primitives/src/overlays/popover/PopoverContentNonModal.vue
index e7a7d39..51038cb 100644
--- a/vue/primitives/src/popover/PopoverContentNonModal.vue
+++ b/vue/primitives/src/overlays/popover/PopoverContentNonModal.vue
@@ -2,6 +2,7 @@
 import type { PopoverContentImplEmits, PopoverContentImplProps } from './PopoverContentImpl.vue';
 import PopoverContentImpl from './PopoverContentImpl.vue';
 import { ref } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
 import { usePopoverContext } from './context';
 
 const props = defineProps<PopoverContentImplProps>();
@@ -10,11 +11,14 @@ const emit = defineEmits<PopoverContentImplEmits>();
 const ctx = usePopoverContext();
 const hasInteractedOutsideRef = ref(false);
 const hasPointerDownOutsideRef = ref(false);
+
+const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
   <PopoverContentImpl
     v-bind="props"
+    :ref="forwardRef"
     :trap-focus="false"
     :disable-outside-pointer-events="false"
     @close-auto-focus="(event: Event) => {
diff --git a/vue/primitives/src/popover/PopoverPortal.vue b/vue/primitives/src/overlays/popover/PopoverPortal.vue
similarity index 78%
rename from vue/primitives/src/popover/PopoverPortal.vue
rename to vue/primitives/src/overlays/popover/PopoverPortal.vue
index 6e1cfc0..6b58c4a 100644
--- a/vue/primitives/src/popover/PopoverPortal.vue
+++ b/vue/primitives/src/overlays/popover/PopoverPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { TeleportPrimitiveProps } from '../teleport';
+import type { TeleportPrimitiveProps } from '../../utilities/teleport';
 
 /**
  * Teleports Content out of the normal DOM flow (by default into `body`) so the
@@ -10,7 +10,7 @@ export interface PopoverPortalProps extends TeleportPrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import PortalPrimitive from '../teleport/Teleport.vue';
+import PortalPrimitive from '../../utilities/teleport/Teleport.vue';
 
 const props = defineProps<PopoverPortalProps>();
 </script>
diff --git a/vue/primitives/src/popover/PopoverRoot.vue b/vue/primitives/src/overlays/popover/PopoverRoot.vue
similarity index 93%
rename from vue/primitives/src/popover/PopoverRoot.vue
rename to vue/primitives/src/overlays/popover/PopoverRoot.vue
index e735985..e5b9c3a 100644
--- a/vue/primitives/src/popover/PopoverRoot.vue
+++ b/vue/primitives/src/overlays/popover/PopoverRoot.vue
@@ -24,10 +24,10 @@ export interface PopoverRootProps {
 </script>
 
 <script setup lang="ts">
-import { ref, toRef } from 'vue';
+import { ref, shallowRef, toRef } from 'vue';
 import { PopperRoot } from '../popper';
 import { providePopoverContext } from './context';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
 defineOptions({ inheritAttrs: false });
 
@@ -46,7 +46,7 @@ const open = defineModel<boolean>('open', {
 
 const triggerId = useId(undefined, 'popover-trigger');
 const contentId = useId(undefined, 'popover-content');
-const triggerElement = ref<HTMLElement>();
+const triggerElement = shallowRef<HTMLElement>();
 const hasCustomAnchor = ref(false);
 
 providePopoverContext({
diff --git a/vue/primitives/src/popover/PopoverTrigger.vue b/vue/primitives/src/overlays/popover/PopoverTrigger.vue
similarity index 91%
rename from vue/primitives/src/popover/PopoverTrigger.vue
rename to vue/primitives/src/overlays/popover/PopoverTrigger.vue
index ff0f61d..72e734f 100644
--- a/vue/primitives/src/popover/PopoverTrigger.vue
+++ b/vue/primitives/src/overlays/popover/PopoverTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The button that toggles the popover open and closed. Wires up
@@ -11,7 +11,7 @@ export interface PopoverTriggerProps extends PrimitiveProps {}
 
 <script setup lang="ts">
 import { PopperAnchor } from '../popper';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { onMounted } from 'vue';
 import { useForwardExpose } from '@robonen/vue';
 import { usePopoverContext } from './context';
diff --git a/vue/primitives/src/overlays/popover/__test__/Popover.test.ts b/vue/primitives/src/overlays/popover/__test__/Popover.test.ts
new file mode 100644
index 0000000..98cafaa
--- /dev/null
+++ b/vue/primitives/src/overlays/popover/__test__/Popover.test.ts
@@ -0,0 +1,439 @@
+import {
+  PopoverAnchor,
+  PopoverArrow,
+  PopoverClose,
+  PopoverContent,
+  PopoverPortal,
+  PopoverRoot,
+  PopoverTrigger,
+} from '../index';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+import { userEvent } from 'vitest/browser';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  document.body.removeAttribute('style');
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+function mountPopover(options: {
+  open?: boolean;
+  defaultOpen?: boolean;
+  modal?: boolean;
+  onUpdateOpen?: (v: boolean) => void;
+} = {}) {
+  const Wrapper = defineComponent({
+    setup() {
+      return () => h(
+        PopoverRoot,
+        {
+          open: options.open,
+          defaultOpen: options.defaultOpen,
+          modal: options.modal,
+          'onUpdate:open': options.onUpdateOpen,
+        },
+        {
+          default: () => [
+            h(PopoverTrigger, null, { default: () => 'Toggle' }),
+            h(PopoverContent, { forceMount: true }, {
+              default: () => [
+                h('p', 'Popover body'),
+                h(PopoverClose, null, { default: () => 'Close' }),
+              ],
+            }),
+          ],
+        },
+      );
+    },
+  });
+
+  return track(mount(Wrapper, { attachTo: document.body }));
+}
+
+describe('Popover', () => {
+  it('renders trigger', () => {
+    const wrapper = mountPopover();
+    const trigger = wrapper.find('button');
+    expect(trigger.text()).toBe('Toggle');
+    expect(trigger.attributes('aria-haspopup')).toBe('dialog');
+    expect(trigger.attributes('data-state')).toBe('closed');
+  });
+
+  it('opens on trigger click', async () => {
+    const wrapper = mountPopover();
+    const trigger = wrapper.find('button');
+
+    await trigger.trigger('click');
+    await nextTick();
+
+    expect(trigger.attributes('aria-expanded')).toBe('true');
+    expect(trigger.attributes('data-state')).toBe('open');
+  });
+
+  it('toggles with v-model:open', async () => {
+    const onUpdate = vi.fn();
+    const wrapper = mountPopover({ onUpdateOpen: onUpdate });
+    const trigger = wrapper.find('button');
+
+    await trigger.trigger('click');
+    await nextTick();
+
+    expect(onUpdate).toHaveBeenCalledWith(true);
+  });
+
+  it('opens with defaultOpen', async () => {
+    const wrapper = mountPopover({ defaultOpen: true });
+    await nextTick();
+
+    const trigger = wrapper.find('button');
+    expect(trigger.attributes('data-state')).toBe('open');
+  });
+
+  it('close button closes the popover', async () => {
+    const onUpdate = vi.fn();
+    const wrapper = mountPopover({ defaultOpen: true, onUpdateOpen: onUpdate });
+    await nextTick();
+
+    const closeBtn = wrapper.findAll('button').find(b => b.text() === 'Close');
+    expect(closeBtn).toBeDefined();
+
+    await closeBtn!.trigger('click');
+    await nextTick();
+
+    expect(onUpdate).toHaveBeenCalledWith(false);
+  });
+
+  it('content has role="dialog"', async () => {
+    const wrapper = mountPopover({ defaultOpen: true });
+    await nextTick();
+
+    const content = wrapper.find('[role="dialog"]');
+    expect(content.exists()).toBe(true);
+    expect(content.attributes('data-state')).toBe('open');
+  });
+
+  it('closes on Escape key', async () => {
+    const onUpdate = vi.fn();
+    mountPopover({ defaultOpen: true, onUpdateOpen: onUpdate });
+    await nextTick();
+
+    await userEvent.keyboard('{Escape}');
+    await nextTick();
+
+    expect(onUpdate).toHaveBeenCalledWith(false);
+  });
+
+  it('supports controlled open', async () => {
+    const Wrapper = defineComponent({
+      setup() {
+        const open = ref(false);
+        return () => h(
+          PopoverRoot,
+          { open: open.value, 'onUpdate:open': (v: boolean) => { open.value = v; } },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverContent, { forceMount: true }, { default: () => 'Body' }),
+            ],
+          },
+        );
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    expect(wrapper.find('button').attributes('data-state')).toBe('closed');
+
+    await wrapper.find('button').trigger('click');
+    await nextTick();
+
+    expect(wrapper.find('button').attributes('data-state')).toBe('open');
+  });
+
+  it('trigger has aria-controls pointing to content id', async () => {
+    const wrapper = mountPopover({ defaultOpen: true });
+    await nextTick();
+
+    const trigger = wrapper.find('button');
+    const contentId = wrapper.find('[role="dialog"]').attributes('id');
+    expect(trigger.attributes('aria-controls')).toBe(contentId);
+  });
+});
+
+describe('Popover content ref forwarding', () => {
+  it('exposes the content element via a template ref (non-modal)', async () => {
+    const contentRef = ref<{ $el: HTMLElement } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          { defaultOpen: true },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverContent, { ref: contentRef, forceMount: true }, { default: () => 'Body' }),
+            ],
+          },
+        );
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    const dialog = wrapper.find('[role="dialog"]').element;
+    expect(contentRef.value?.$el).toBe(dialog);
+  });
+
+  it('exposes the content element via a template ref (modal)', async () => {
+    const contentRef = ref<{ $el: HTMLElement } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          { defaultOpen: true, modal: true },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverContent, { ref: contentRef, forceMount: true }, { default: () => 'Body' }),
+            ],
+          },
+        );
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    const dialog = wrapper.find('[role="dialog"]').element;
+    expect(contentRef.value?.$el).toBe(dialog);
+  });
+});
+
+describe('Popover focus guards', () => {
+  it('inserts edge focus guards while content is open', async () => {
+    expect(document.querySelectorAll('[data-focus-guard]').length).toBe(0);
+
+    const wrapper = mountPopover({ defaultOpen: true });
+    await nextTick();
+
+    expect(document.querySelectorAll('[data-focus-guard]').length).toBe(2);
+
+    wrapper.unmount();
+    await nextTick();
+
+    expect(document.querySelectorAll('[data-focus-guard]').length).toBe(0);
+  });
+});
+
+describe('Popover modal hides background content', () => {
+  it('aria-hides sibling trees when modal content is open', async () => {
+    const sibling = document.createElement('div');
+    sibling.id = 'outside-sibling';
+    sibling.textContent = 'background';
+    document.body.appendChild(sibling);
+
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          { defaultOpen: true, modal: true },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverContent, { forceMount: true }, { default: () => 'Body' }),
+            ],
+          },
+        );
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+    await nextTick();
+
+    expect(sibling.getAttribute('aria-hidden')).toBe('true');
+
+    wrapper.unmount();
+    await nextTick();
+
+    expect(sibling.getAttribute('aria-hidden')).not.toBe('true');
+    sibling.remove();
+  });
+
+  it('does NOT aria-hide siblings in non-modal mode', async () => {
+    const sibling = document.createElement('div');
+    sibling.id = 'outside-sibling-nonmodal';
+    document.body.appendChild(sibling);
+
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          { defaultOpen: true, modal: false },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverContent, { forceMount: true }, { default: () => 'Body' }),
+            ],
+          },
+        );
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+    await nextTick();
+
+    expect(sibling.getAttribute('aria-hidden')).not.toBe('true');
+
+    wrapper.unmount();
+    sibling.remove();
+  });
+});
+
+describe('PopoverAnchor', () => {
+  it('exposes its element via a template ref', async () => {
+    const anchorRef = ref<{ $el: HTMLElement } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          null,
+          {
+            default: () => [
+              h(PopoverAnchor, { ref: anchorRef }, { default: () => h('span', 'anchor') }),
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+            ],
+          },
+        );
+      },
+    });
+
+    track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    expect(anchorRef.value?.$el).toBeInstanceOf(HTMLElement);
+    expect(anchorRef.value?.$el.textContent).toBe('anchor');
+  });
+});
+
+describe('PopoverArrow', () => {
+  function mountArrow(arrowProps: Record<string, unknown> = {}) {
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          { defaultOpen: true },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverContent, { forceMount: true }, {
+                default: () => h(PopoverArrow, arrowProps),
+              }),
+            ],
+          },
+        );
+      },
+    });
+
+    return track(mount(Wrapper, { attachTo: document.body }));
+  }
+
+  it('renders a default svg triangle out of the box', async () => {
+    const wrapper = mountArrow();
+    await nextTick();
+
+    const svg = wrapper.find('[role="dialog"] svg');
+    expect(svg.exists()).toBe(true);
+    expect(svg.find('path').exists()).toBe(true);
+    expect(svg.find('path').attributes('d')).toBe('M0 0L6 6L12 0');
+  });
+
+  it('forwards the rounded prop to the underlying arrow path', async () => {
+    const wrapper = mountArrow({ rounded: true });
+    await nextTick();
+
+    const path = wrapper.find('[role="dialog"] svg path');
+    expect(path.exists()).toBe(true);
+    expect(path.attributes('d')).not.toBe('M0 0L6 6L12 0');
+  });
+
+  it('forwards width/height attributes', async () => {
+    const wrapper = mountArrow({ width: 20, height: 8 });
+    await nextTick();
+
+    const svg = wrapper.find('[role="dialog"] svg');
+    expect(svg.attributes('width')).toBe('20');
+    expect(svg.attributes('height')).toBe('8');
+  });
+
+  it('exposes the arrow element via a template ref', async () => {
+    const arrowRef = ref<{ $el: HTMLElement } | null>(null);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          { defaultOpen: true },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverContent, { forceMount: true }, {
+                default: () => h(PopoverArrow, { ref: arrowRef }),
+              }),
+            ],
+          },
+        );
+      },
+    });
+
+    track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    expect(arrowRef.value?.$el).toBeTruthy();
+  });
+});
+
+describe('PopoverPortal', () => {
+  it('teleports content out into a custom container', async () => {
+    const target = document.createElement('div');
+    target.id = 'portal-target';
+    document.body.appendChild(target);
+
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          PopoverRoot,
+          { defaultOpen: true },
+          {
+            default: () => [
+              h(PopoverTrigger, null, { default: () => 'Toggle' }),
+              h(PopoverPortal, { to: '#portal-target' }, {
+                default: () => h(PopoverContent, { forceMount: true }, { default: () => 'Body' }),
+              }),
+            ],
+          },
+        );
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    expect(target.querySelector('[role="dialog"]')).not.toBeNull();
+
+    wrapper.unmount();
+    target.remove();
+  });
+});
diff --git a/vue/primitives/src/popover/__test__/__screenshots__/Popover.test.ts/Popover-closes-on-Escape-key-1.png b/vue/primitives/src/overlays/popover/__test__/__screenshots__/Popover.test.ts/Popover-closes-on-Escape-key-1.png
similarity index 100%
rename from vue/primitives/src/popover/__test__/__screenshots__/Popover.test.ts/Popover-closes-on-Escape-key-1.png
rename to vue/primitives/src/overlays/popover/__test__/__screenshots__/Popover.test.ts/Popover-closes-on-Escape-key-1.png
diff --git a/vue/primitives/src/popover/context.ts b/vue/primitives/src/overlays/popover/context.ts
similarity index 100%
rename from vue/primitives/src/popover/context.ts
rename to vue/primitives/src/overlays/popover/context.ts
diff --git a/vue/primitives/src/popover/demo.vue b/vue/primitives/src/overlays/popover/demo.vue
similarity index 68%
rename from vue/primitives/src/popover/demo.vue
rename to vue/primitives/src/overlays/popover/demo.vue
index 4f8b3c7..24e536e 100644
--- a/vue/primitives/src/popover/demo.vue
+++ b/vue/primitives/src/overlays/popover/demo.vue
@@ -25,9 +25,9 @@ const fields = [
 </script>
 
 <template>
-  <div class="flex flex-col items-start gap-3 text-(--fg)">
+  <div class="flex flex-col items-start gap-3 text-fg">
     <div
-      class="rounded-md border border-dashed border-(--border) bg-(--bg-subtle) text-xs text-(--fg-muted)"
+      class="rounded-md border border-dashed border-border bg-bg-subtle text-xs text-fg-muted"
       :style="{ width: `${dimensions.width}px`, height: `${dimensions.height}px` }"
     >
       <span class="block px-2 py-1">{{ dimensions.width }} × {{ dimensions.height }}</span>
@@ -35,10 +35,10 @@ const fields = [
 
     <PopoverRoot>
       <PopoverTrigger
-        class="inline-flex items-center gap-2 rounded-md border border-(--border) bg-(--bg) px-3 py-1.5 text-sm font-medium text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) data-[state=open]:bg-(--bg-subtle)"
+        class="inline-flex items-center gap-2 rounded-md border border-border bg-bg px-3 py-1.5 text-sm font-medium text-fg transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[state=open]:bg-bg-subtle"
       >
         <svg
-          class="size-4 text-(--fg-muted)" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+          class="size-4 text-fg-muted" viewBox="0 0 24 24" fill="none" stroke="currentColor"
           stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"
         >
           <path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" />
@@ -52,16 +52,16 @@ const fields = [
           :side-offset="8"
           align="start"
           :collision-padding="8"
-          class="z-50 w-64 rounded-xl border border-(--border) bg-(--bg-elevated) p-4 text-(--fg) shadow-lg focus:outline-none data-[state=open]:animate-in data-[state=open]:fade-in data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out"
+          class="demo-card z-50 w-64 p-4 text-fg shadow-lg focus:outline-none data-[state=open]:animate-in data-[state=open]:fade-in data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out"
         >
           <div class="flex items-start justify-between">
             <div>
               <h3 class="text-sm font-semibold">Dimensions</h3>
-              <p class="mt-0.5 text-xs text-(--fg-muted)">Set the box size in pixels.</p>
+              <p class="mt-0.5 text-xs text-fg-muted">Set the box size in pixels.</p>
             </div>
             <PopoverClose
               aria-label="Close"
-              class="-mr-1 -mt-1 inline-flex size-6 items-center justify-center rounded-md text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+              class="-mr-1 -mt-1 inline-flex size-6 items-center justify-center rounded-md text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             >
               <svg
                 class="size-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor"
@@ -78,18 +78,18 @@ const fields = [
               :key="field.key"
               class="grid grid-cols-[1fr_auto] items-center gap-3 text-sm"
             >
-              <span class="text-(--fg-muted)">{{ field.label }}</span>
+              <span class="text-fg-muted">{{ field.label }}</span>
               <input
                 v-model.number="dimensions[field.key]"
                 type="number"
-                class="h-7 w-20 rounded-md border border-(--border) bg-(--bg) px-2 text-right tabular-nums text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+                class="h-7 w-20 rounded-md border border-border bg-bg px-2 text-right tabular-nums text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
             </label>
           </div>
 
           <PopoverArrow :width="12" :height="6">
             <svg width="12" height="6" viewBox="0 0 12 6" class="block" aria-hidden="true">
-              <path d="M0 0 L6 6 L12 0 Z" class="fill-(--bg-elevated) stroke-(--border)" stroke-width="1" />
+              <path d="M0 0 L6 6 L12 0 Z" class="fill-bg-elevated stroke-border" stroke-width="1" />
             </svg>
           </PopoverArrow>
         </PopoverContent>
diff --git a/vue/primitives/src/popover/index.ts b/vue/primitives/src/overlays/popover/index.ts
similarity index 100%
rename from vue/primitives/src/popover/index.ts
rename to vue/primitives/src/overlays/popover/index.ts
diff --git a/vue/primitives/src/popper/PopperAnchor.vue b/vue/primitives/src/overlays/popper/PopperAnchor.vue
similarity index 81%
rename from vue/primitives/src/popper/PopperAnchor.vue
rename to vue/primitives/src/overlays/popper/PopperAnchor.vue
index 90e24a6..80e1535 100644
--- a/vue/primitives/src/popper/PopperAnchor.vue
+++ b/vue/primitives/src/overlays/popper/PopperAnchor.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { ReferenceElement } from '@floating-ui/vue';
 
 /**
@@ -16,18 +16,18 @@ export interface PopperAnchorProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { usePopperRootContext } from './context';
 import { watchPostEffect } from 'vue';
 
-const props = defineProps<PopperAnchorProps>();
+const { as, reference } = defineProps<PopperAnchorProps>();
 
 const { forwardRef, currentElement } = useForwardExpose();
 const rootContext = usePopperRootContext();
 
 watchPostEffect(() => {
-  rootContext.onAnchorChange(props.reference ?? currentElement.value);
+  rootContext.onAnchorChange(reference ?? currentElement.value);
 });
 </script>
 
diff --git a/vue/primitives/src/overlays/popper/PopperArrow.vue b/vue/primitives/src/overlays/popper/PopperArrow.vue
new file mode 100644
index 0000000..7a0d743
--- /dev/null
+++ b/vue/primitives/src/overlays/popper/PopperArrow.vue
@@ -0,0 +1,113 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { Side } from './utils';
+
+const OPPOSITE_SIDE: Record<Side, Side> = {
+  top: 'bottom',
+  right: 'left',
+  bottom: 'top',
+  left: 'right',
+};
+
+// Hoisted to module scope — one allocation per module load instead of one per
+// render. Values are primitive strings, so objects are frozen-in-practice.
+const TRANSFORM_ORIGIN: Record<Side, string> = {
+  top: '',
+  right: '0 0',
+  bottom: 'center 0',
+  left: '100% 0',
+};
+
+const TRANSFORM: Record<Side, string> = {
+  top: 'translateY(100%)',
+  right: 'translateY(50%) rotate(90deg) translateX(-50%)',
+  bottom: 'rotate(180deg)',
+  left: 'translateY(50%) rotate(-90deg) translateX(50%)',
+};
+
+// Default arrow geometry, sized against the 12×6 viewBox so the SVG scales to
+// any width/height via preserveAspectRatio="none".
+const ARROW_PATH = 'M0 0L6 6L12 0';
+const ARROW_PATH_ROUNDED = 'M0 0L4.58579 4.58579C5.36683 5.36683 6.63316 5.36684 7.41421 4.58579L12 0';
+
+/**
+ * An optional arrow/pointer rendered inside `PopperContent` that points back at
+ * the anchor. It reads the resolved side and arrow offset from the content
+ * context to position and rotate itself against the correct edge, and hides
+ * automatically when it cannot be centered. By default it renders a real `<svg>`
+ * triangle (a `rounded` variant is available); supply your own SVG/element via
+ * the default slot, or switch the rendered element with `as`. Must be a child of
+ * `PopperContent`.
+ */
+export interface PopperArrowProps extends PrimitiveProps {
+  /** Arrow width in pixels. @default 10 */
+  width?: number;
+  /** Arrow height in pixels. @default 5 */
+  height?: number;
+  /** Render the rounded variant of the default arrow path. Ignored when a custom default slot or `as="template"` is used. @default false */
+  rounded?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import type { CSSProperties, ComponentPublicInstance } from 'vue';
+import { Primitive } from '../../internal/primitive';
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { usePopperContentContext } from './context';
+
+const { as = 'svg', width = 10, height = 5, rounded = false } = defineProps<PopperArrowProps>();
+
+const { forwardRef } = useForwardExpose();
+const contentContext = usePopperContentContext();
+const baseSide = computed(() => OPPOSITE_SIDE[contentContext.placedSide.value]);
+
+// When the consumer merges the arrow onto their own element (`as="template"`)
+// the intrinsic SVG attributes would be invalid, so they are only applied to a
+// real rendered element. Mirrors the slot-merge escape hatch of `Primitive`.
+const isTemplate = computed(() => as === 'template');
+const arrowPath = computed(() => (rounded ? ARROW_PATH_ROUNDED : ARROW_PATH));
+
+// Memoize the wrapper style. PopperArrow re-renders on every scroll/resize/
+// layout-shift frame while open; binding an inline object literal would
+// re-allocate it and re-read every ref + re-run both table lookups each frame.
+// A computed caches the object and recomputes only when its tracked deps change.
+const wrapperStyle = computed(() => {
+  const placedSide = contentContext.placedSide.value;
+  const arrowX = contentContext.arrowX.value;
+  const arrowY = contentContext.arrowY.value;
+  return {
+    position: 'absolute',
+    left: arrowX ? `${arrowX}px` : undefined,
+    top: arrowY ? `${arrowY}px` : undefined,
+    [baseSide.value]: 0,
+    transformOrigin: TRANSFORM_ORIGIN[placedSide],
+    transform: TRANSFORM[placedSide],
+    visibility: contentContext.shouldHideArrow.value ? 'hidden' : undefined,
+  } as CSSProperties;
+});
+</script>
+
+<template>
+  <span
+    :ref="(el: Element | ComponentPublicInstance | null) => {
+      contentContext.onArrowChange((el as HTMLElement) ?? undefined);
+      return undefined;
+    }"
+    :style="wrapperStyle"
+  >
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      :style="{ display: 'block' }"
+      :width="width"
+      :height="height"
+      :viewBox="isTemplate ? undefined : '0 0 12 6'"
+      :preserveAspectRatio="isTemplate ? undefined : 'none'"
+    >
+      <slot>
+        <path :d="arrowPath" />
+      </slot>
+    </Primitive>
+  </span>
+</template>
diff --git a/vue/primitives/src/popper/PopperContent.vue b/vue/primitives/src/overlays/popper/PopperContent.vue
similarity index 80%
rename from vue/primitives/src/popper/PopperContent.vue
rename to vue/primitives/src/overlays/popper/PopperContent.vue
index 9347e10..15831e3 100644
--- a/vue/primitives/src/popper/PopperContent.vue
+++ b/vue/primitives/src/overlays/popper/PopperContent.vue
@@ -1,7 +1,7 @@
 <script lang="ts">
 import type { Align, Side } from './utils';
 import type { Middleware, Placement, ReferenceElement } from '@floating-ui/vue';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The floating element positioned against the anchor. This is the workhorse of
@@ -60,7 +60,7 @@ export interface PopperContentEmits {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import {
   autoUpdate,
   flip,
@@ -72,10 +72,10 @@ import {
   size,
   useFloating,
 } from '@floating-ui/vue';
-import { computed, onBeforeUnmount, ref, shallowRef, useTemplateRef, watchEffect, watchPostEffect } from 'vue';
+import { computed, ref, shallowRef, useTemplateRef, watchEffect, watchPostEffect } from 'vue';
 import { getSideAndAlignFromPlacement, isNotNull, transformOrigin } from './utils';
 import { providePopperContentContext, usePopperRootContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
+import { useForwardExpose, useResizeObserver } from '@robonen/vue';
 
 defineOptions({ inheritAttrs: false });
 
@@ -107,43 +107,25 @@ const rootContext = usePopperRootContext();
 const { forwardRef, currentElement: contentElement } = useForwardExpose();
 
 const floatingRef = useTemplateRef<HTMLElement>('floatingRef');
-const arrow = ref<HTMLElement>();
+const arrow = shallowRef<HTMLElement>();
 
-// Arrow size tracking via ResizeObserver (replaces useSize)
+// Arrow size tracking via ResizeObserver (replaces useSize). The observer
+// re-targets when the arrow element changes and tears down on scope dispose.
 const arrowWidth = ref(0);
 const arrowHeight = ref(0);
-let arrowObserver: ResizeObserver | null = null;
 
-watchEffect((onCleanup) => {
-  arrowObserver?.disconnect();
-  arrowObserver = null;
-
-  const el = arrow.value;
-  if (!el) return;
-
-  arrowObserver = new ResizeObserver(([entry]) => {
-    if (entry) {
-      const borderBox = entry.borderBoxSize[0];
-      if (borderBox) {
-        arrowWidth.value = borderBox.inlineSize;
-        arrowHeight.value = borderBox.blockSize;
-      }
-      else {
-        const rect = el.getBoundingClientRect();
-        arrowWidth.value = rect.width;
-        arrowHeight.value = rect.height;
-      }
-    }
-  });
-  arrowObserver.observe(el);
-
-  onCleanup(() => {
-    arrowObserver?.disconnect();
-  });
-});
-
-onBeforeUnmount(() => {
-  arrowObserver?.disconnect();
+useResizeObserver(arrow, ([entry]) => {
+  if (!entry) return;
+  const borderBox = entry.borderBoxSize[0];
+  if (borderBox) {
+    arrowWidth.value = borderBox.inlineSize;
+    arrowHeight.value = borderBox.blockSize;
+  }
+  else {
+    const rect = (entry.target as HTMLElement).getBoundingClientRect();
+    arrowWidth.value = rect.width;
+    arrowHeight.value = rect.height;
+  }
 });
 
 const desiredPlacement = computed<Placement>(
@@ -247,6 +229,30 @@ watchEffect(() => {
 const arrowX = computed(() => middlewareData.value.arrow?.x ?? 0);
 const arrowY = computed(() => middlewareData.value.arrow?.y ?? 0);
 
+// Memoize the floating wrapper style. The template re-renders on every position
+// update frame while open; a computed isolates the per-frame allocation to one
+// tracked site and avoids re-running the [x,y].join(' ') and conditional reads
+// when the render is triggered by an unrelated dep.
+const wrapperStyle = computed(() => {
+  const md = middlewareData.value;
+  const referenceHidden = md.hide?.referenceHidden;
+  return {
+    ...floatingStyles.value,
+    transform: isPositioned.value ? floatingStyles.value.transform : 'translate(0, -200%)',
+    minWidth: 'max-content',
+    zIndex: contentZIndex.value,
+    '--popper-transform-origin': [
+      md.transformOrigin?.x,
+      md.transformOrigin?.y,
+    ].join(' '),
+    // Always set both keys so V8 keeps a single hidden class for the style
+    // object across renders, instead of allocating a new shape when the
+    // conditional spread kicks in.
+    visibility: referenceHidden ? ('hidden' as const) : undefined,
+    pointerEvents: referenceHidden ? ('none' as const) : undefined,
+  };
+});
+
 providePopperContentContext({
   placedSide,
   onArrowChange: (element: HTMLElement | undefined) => { arrow.value = element; },
@@ -260,21 +266,7 @@ providePopperContentContext({
   <div
     ref="floatingRef"
     data-popper-content-wrapper=""
-    :style="{
-      ...floatingStyles,
-      transform: isPositioned ? floatingStyles.transform : 'translate(0, -200%)',
-      minWidth: 'max-content',
-      zIndex: contentZIndex,
-      ['--popper-transform-origin' as any]: [
-        middlewareData.transformOrigin?.x,
-        middlewareData.transformOrigin?.y,
-      ].join(' '),
-      // Always set both keys so V8 keeps a single hidden class for the style
-      // object across renders, instead of allocating a new shape when the
-      // conditional spread kicks in.
-      visibility: middlewareData.hide?.referenceHidden ? ('hidden' as const) : undefined,
-      pointerEvents: middlewareData.hide?.referenceHidden ? ('none' as const) : undefined,
-    }"
+    :style="wrapperStyle"
   >
     <Primitive
       :ref="forwardRef"
diff --git a/vue/primitives/src/popper/PopperRoot.vue b/vue/primitives/src/overlays/popper/PopperRoot.vue
similarity index 92%
rename from vue/primitives/src/popper/PopperRoot.vue
rename to vue/primitives/src/overlays/popper/PopperRoot.vue
index a546eee..b20fe73 100644
--- a/vue/primitives/src/popper/PopperRoot.vue
+++ b/vue/primitives/src/overlays/popper/PopperRoot.vue
@@ -15,13 +15,13 @@ export interface PopperRootProps {}
 <script setup lang="ts">
 import type { ReferenceElement } from '@floating-ui/vue';
 import { providePopperRootContext } from './context';
-import { ref } from 'vue';
+import { shallowRef } from 'vue';
 
 defineOptions({ inheritAttrs: false });
 
 defineProps<PopperRootProps>();
 
-const anchor = ref<ReferenceElement>();
+const anchor = shallowRef<ReferenceElement>();
 
 providePopperRootContext({
   anchor,
diff --git a/vue/primitives/src/overlays/popper/__test__/Popper.test.ts b/vue/primitives/src/overlays/popper/__test__/Popper.test.ts
new file mode 100644
index 0000000..b69830c
--- /dev/null
+++ b/vue/primitives/src/overlays/popper/__test__/Popper.test.ts
@@ -0,0 +1,220 @@
+import type { Measurable } from '../index';
+import {
+  PopperAnchor,
+  PopperArrow,
+  PopperContent,
+  PopperRoot,
+} from '../index';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+describe('Popper', () => {
+  it('renders root with anchor and content', async () => {
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(PopperRoot, null, {
+          default: () => [
+            h(PopperAnchor, { as: 'button' }, { default: () => 'Anchor' }),
+            h(PopperContent, { as: 'div' }, { default: () => 'Content' }),
+          ],
+        });
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    expect(wrapper.find('button').text()).toBe('Anchor');
+    expect(wrapper.find('[data-popper-content-wrapper]').exists()).toBe(true);
+  });
+
+  it('positions content with default placement (bottom)', async () => {
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(PopperRoot, null, {
+          default: () => [
+            h(PopperAnchor, { as: 'button' }, { default: () => 'Anchor' }),
+            h(PopperContent, null, { default: () => 'Content' }),
+          ],
+        });
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+    await nextTick();
+
+    const content = wrapper.find('[data-side]');
+    expect(content.exists()).toBe(true);
+  });
+
+  it('exposes data-side and data-align attributes', async () => {
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(PopperRoot, null, {
+          default: () => [
+            h(PopperAnchor, { as: 'button' }, { default: () => 'Anchor' }),
+            h(PopperContent, { side: 'top', align: 'start' }, { default: () => 'Content' }),
+          ],
+        });
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+    await nextTick();
+
+    const content = wrapper.find('[data-side]');
+    expect(content.exists()).toBe(true);
+  });
+
+  it('passes custom reference to anchor', async () => {
+    const customRef = {
+      getBoundingClientRect: () => ({
+        x: 100, y: 100, width: 50, height: 50,
+        top: 100, right: 150, bottom: 150, left: 100,
+        toJSON: () => {},
+      }),
+    };
+
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(PopperRoot, null, {
+          default: () => [
+            h(PopperAnchor, { reference: customRef }, { default: () => 'Anchor' }),
+            h(PopperContent, null, { default: () => 'Content' }),
+          ],
+        });
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    expect(wrapper.find('[data-popper-content-wrapper]').exists()).toBe(true);
+  });
+
+  it('accepts a Measurable-typed virtual reference on content', async () => {
+    const virtual: Measurable = {
+      getBoundingClientRect: () => ({
+        x: 0, y: 0, width: 10, height: 10,
+        top: 0, right: 10, bottom: 10, left: 0,
+        toJSON: () => {},
+      } as DOMRect),
+    };
+
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(PopperRoot, null, {
+          default: () => [
+            h(PopperContent, { reference: virtual }, { default: () => 'Content' }),
+          ],
+        });
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+
+    expect(wrapper.find('[data-popper-content-wrapper]').exists()).toBe(true);
+  });
+});
+
+describe('PopperArrow', () => {
+  function mountWithArrow(arrowProps: Record<string, unknown> = {}, arrowSlot?: () => unknown) {
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(PopperRoot, null, {
+          default: () => [
+            h(PopperAnchor, { as: 'button' }, { default: () => 'Anchor' }),
+            h(PopperContent, { as: 'div' }, {
+              default: () => h(PopperArrow, arrowProps, arrowSlot ? { default: arrowSlot } : undefined),
+            }),
+          ],
+        });
+      },
+    });
+    return track(mount(Wrapper, { attachTo: document.body }));
+  }
+
+  it('renders a real svg arrow with default path and viewBox by default', async () => {
+    const wrapper = mountWithArrow();
+    await nextTick();
+
+    const svg = wrapper.find('svg');
+    expect(svg.exists()).toBe(true);
+    // SVG attributes are case-sensitive, so read them off the element directly.
+    expect(svg.element.getAttribute('viewBox')).toBe('0 0 12 6');
+    expect(svg.element.getAttribute('preserveAspectRatio')).toBe('none');
+
+    const path = svg.find('path');
+    expect(path.exists()).toBe(true);
+    expect(path.attributes('d')).toBe('M0 0L6 6L12 0');
+  });
+
+  it('applies width and height defaults (10 × 5) to the svg', async () => {
+    const wrapper = mountWithArrow();
+    await nextTick();
+
+    const svg = wrapper.find('svg');
+    expect(svg.attributes('width')).toBe('10');
+    expect(svg.attributes('height')).toBe('5');
+  });
+
+  it('honors explicit width and height', async () => {
+    const wrapper = mountWithArrow({ width: 24, height: 12 });
+    await nextTick();
+
+    const svg = wrapper.find('svg');
+    expect(svg.attributes('width')).toBe('24');
+    expect(svg.attributes('height')).toBe('12');
+  });
+
+  it('swaps to the rounded path when rounded is set', async () => {
+    const wrapper = mountWithArrow({ rounded: true });
+    await nextTick();
+
+    const path = wrapper.find('svg path');
+    expect(path.exists()).toBe(true);
+    expect(path.attributes('d')).toBe(
+      'M0 0L4.58579 4.58579C5.36683 5.36683 6.63316 5.36684 7.41421 4.58579L12 0',
+    );
+  });
+
+  it('lets the default slot override the built-in path', async () => {
+    const wrapper = mountWithArrow({}, () => h('path', { d: 'M0 0L1 1' }));
+    await nextTick();
+
+    const paths = wrapper.findAll('svg path');
+    expect(paths).toHaveLength(1);
+    expect(paths[0]!.attributes('d')).toBe('M0 0L1 1');
+  });
+
+  it('does not emit svg-only attributes when merged via as="template"', async () => {
+    const wrapper = mountWithArrow(
+      { as: 'template' },
+      () => h('i', { 'data-custom-arrow': '' }),
+    );
+    await nextTick();
+
+    expect(wrapper.find('svg').exists()).toBe(false);
+    const custom = wrapper.find('[data-custom-arrow]');
+    expect(custom.exists()).toBe(true);
+    expect(custom.attributes('viewbox')).toBeUndefined();
+    expect(custom.attributes('preserveaspectratio')).toBeUndefined();
+  });
+});
diff --git a/vue/primitives/src/popper/context.ts b/vue/primitives/src/overlays/popper/context.ts
similarity index 72%
rename from vue/primitives/src/popper/context.ts
rename to vue/primitives/src/overlays/popper/context.ts
index 57ee494..6b447ad 100644
--- a/vue/primitives/src/popper/context.ts
+++ b/vue/primitives/src/overlays/popper/context.ts
@@ -3,6 +3,16 @@ import type { ReferenceElement } from '@floating-ui/vue';
 import type { Side } from './utils';
 import { useContextFactory } from '@robonen/vue';
 
+/**
+ * Minimal shape a custom/virtual reference must satisfy to be positioned
+ * against. Pass any object implementing this to `PopperAnchor`/`PopperContent`'s
+ * `reference` prop to anchor against a point, range, or external element rather
+ * than a rendered DOM node.
+ */
+export interface Measurable {
+  getBoundingClientRect: () => DOMRect;
+}
+
 export interface PopperRootContext {
   anchor: Ref<ReferenceElement | undefined>;
   onAnchorChange: (element: ReferenceElement | undefined) => void;
diff --git a/vue/primitives/src/popper/index.ts b/vue/primitives/src/overlays/popper/index.ts
similarity index 87%
rename from vue/primitives/src/popper/index.ts
rename to vue/primitives/src/overlays/popper/index.ts
index 1c66308..be3508a 100644
--- a/vue/primitives/src/popper/index.ts
+++ b/vue/primitives/src/overlays/popper/index.ts
@@ -5,7 +5,7 @@ export { default as PopperArrow } from './PopperArrow.vue';
 
 export { usePopperRootContext, usePopperContentContext } from './context';
 
-export type { PopperRootContext, PopperContentContext } from './context';
+export type { Measurable, PopperRootContext, PopperContentContext } from './context';
 export type { PopperRootProps } from './PopperRoot.vue';
 export type { PopperAnchorProps } from './PopperAnchor.vue';
 export type { PopperContentEmits, PopperContentProps } from './PopperContent.vue';
diff --git a/vue/primitives/src/popper/utils.ts b/vue/primitives/src/overlays/popper/utils.ts
similarity index 100%
rename from vue/primitives/src/popper/utils.ts
rename to vue/primitives/src/overlays/popper/utils.ts
diff --git a/vue/primitives/src/tooltip/TooltipArrow.vue b/vue/primitives/src/overlays/tooltip/TooltipArrow.vue
similarity index 100%
rename from vue/primitives/src/tooltip/TooltipArrow.vue
rename to vue/primitives/src/overlays/tooltip/TooltipArrow.vue
diff --git a/vue/primitives/src/tooltip/TooltipContent.vue b/vue/primitives/src/overlays/tooltip/TooltipContent.vue
similarity index 69%
rename from vue/primitives/src/tooltip/TooltipContent.vue
rename to vue/primitives/src/overlays/tooltip/TooltipContent.vue
index 9ec537d..b9f1042 100644
--- a/vue/primitives/src/tooltip/TooltipContent.vue
+++ b/vue/primitives/src/overlays/tooltip/TooltipContent.vue
@@ -16,7 +16,9 @@ export type TooltipContentEmits = TooltipContentImplEmits;
 </script>
 
 <script setup lang="ts">
-import { Presence } from '../presence';
+import { computed } from 'vue';
+import { Presence } from '../../utilities/presence';
+import TooltipContentHoverable from './TooltipContentHoverable.vue';
 import TooltipContentImpl from './TooltipContentImpl.vue';
 import { useTooltipContext } from './context';
 
@@ -24,16 +26,24 @@ const { forceMount = false, ...contentProps } = defineProps<TooltipContentProps>
 const emit = defineEmits<TooltipContentEmits>();
 
 const ctx = useTooltipContext();
+
+// When hoverable content is enabled (the default), wrap the impl in the
+// grace-area variant so the pointer can travel onto the content without it
+// closing; otherwise mount the impl directly.
+const contentComponent = computed(() =>
+  ctx.disableHoverableContent.value ? TooltipContentImpl : TooltipContentHoverable,
+);
 </script>
 
 <template>
   <Presence :present="ctx.open.value" :force-mount="forceMount">
-    <TooltipContentImpl
+    <component
+      :is="contentComponent"
       v-bind="contentProps"
       @escape-key-down="emit('escapeKeyDown', $event)"
       @pointer-down-outside="emit('pointerDownOutside', $event)"
     >
       <slot />
-    </TooltipContentImpl>
+    </component>
   </Presence>
 </template>
diff --git a/vue/primitives/src/overlays/tooltip/TooltipContentHoverable.vue b/vue/primitives/src/overlays/tooltip/TooltipContentHoverable.vue
new file mode 100644
index 0000000..6cef24a
--- /dev/null
+++ b/vue/primitives/src/overlays/tooltip/TooltipContentHoverable.vue
@@ -0,0 +1,47 @@
+<script lang="ts">
+import type { TooltipContentImplEmits, TooltipContentImplProps } from './TooltipContentImpl.vue';
+
+/**
+ * Hoverable variant of the tooltip Content: keeps the tooltip open while the
+ * pointer travels through the "safe area" between the trigger and the content,
+ * so the content can itself be hovered without flickering closed. Selected by
+ * `TooltipContent` whenever `disableHoverableContent` is `false` (the default).
+ * Not part of the public anatomy — use `TooltipContent`.
+ */
+export type TooltipContentHoverableProps = TooltipContentImplProps;
+
+export type TooltipContentHoverableEmits = TooltipContentImplEmits;
+</script>
+
+<script setup lang="ts">
+import { watchEffect } from 'vue';
+import TooltipContentImpl from './TooltipContentImpl.vue';
+import { useForwardExpose } from '@robonen/vue';
+import { useGraceArea } from '../../internal/utils/useGraceArea';
+import { useTooltipContext } from './context';
+
+const props = defineProps<TooltipContentHoverableProps>();
+const emit = defineEmits<TooltipContentHoverableEmits>();
+
+const ctx = useTooltipContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+const { isPointerInTransit, onPointerExit } = useGraceArea(ctx.trigger, currentElement);
+
+watchEffect(() => {
+  ctx.isPointerInTransitRef.value = isPointerInTransit.value;
+});
+
+onPointerExit(() => ctx.onClose());
+</script>
+
+<template>
+  <TooltipContentImpl
+    :ref="forwardRef"
+    v-bind="props"
+    @escape-key-down="emit('escapeKeyDown', $event)"
+    @pointer-down-outside="emit('pointerDownOutside', $event)"
+  >
+    <slot />
+  </TooltipContentImpl>
+</template>
diff --git a/vue/primitives/src/tooltip/TooltipContentImpl.vue b/vue/primitives/src/overlays/tooltip/TooltipContentImpl.vue
similarity index 57%
rename from vue/primitives/src/tooltip/TooltipContentImpl.vue
rename to vue/primitives/src/overlays/tooltip/TooltipContentImpl.vue
index d2c59b1..7ef11a0 100644
--- a/vue/primitives/src/tooltip/TooltipContentImpl.vue
+++ b/vue/primitives/src/overlays/tooltip/TooltipContentImpl.vue
@@ -1,6 +1,6 @@
 <script lang="ts">
 import type { PopperContentProps } from '../popper';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Internal implementation behind `TooltipContent`: renders the Popper content
@@ -41,39 +41,55 @@ export interface TooltipContentImplEmits {
 </script>
 
 <script setup lang="ts">
-import { computed, onMounted, onScopeDispose } from 'vue';
-import { DismissableLayer } from '../dismissable-layer';
+import { computed } from 'vue';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
 import { PopperContent } from '../popper';
 import { TOOLTIP_OPEN_EVENT } from './utils';
-import { VisuallyHidden } from '../visually-hidden';
-import { useForwardExpose } from '@robonen/vue';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
 import { useTooltipContext } from './context';
 
-const {
-  side = 'top',
-  sideOffset = 0,
-  sideFlip = true,
-  align = 'center',
-  alignOffset = 0,
-  alignFlip = true,
-  avoidCollisions = true,
-  collisionBoundary = [],
-  collisionPadding = 0,
-  arrowPadding = 0,
-  sticky = 'partial',
-  hideWhenDetached = false,
-  positionStrategy,
-  updatePositionStrategy,
-  ariaLabel,
-  as = 'div',
-} = defineProps<TooltipContentImplProps>();
+const props = defineProps<TooltipContentImplProps>();
 
 const emit = defineEmits<TooltipContentImplEmits>();
 
 const ctx = useTooltipContext();
 const { forwardRef, currentElement } = useForwardExpose();
 
-const computedAriaLabel = computed(() => ariaLabel ?? currentElement.value?.textContent ?? '');
+// Merge order (highest priority first): explicit per-Content props →
+// Provider-level `content` defaults → hard defaults. `undefined` entries in a
+// higher-priority layer fall through to the next, mirroring reka's `defu`.
+const popperProps = computed(() => {
+  const defaults = ctx.contentDefaults.value;
+  const pick = <K extends keyof TooltipContentImplProps>(
+    key: K,
+    fallback: NonNullable<TooltipContentImplProps[K]>,
+  ): NonNullable<TooltipContentImplProps[K]> =>
+    (props[key] ?? defaults?.[key] ?? fallback) as NonNullable<TooltipContentImplProps[K]>;
+
+  return {
+    side: pick('side', 'top'),
+    sideOffset: pick('sideOffset', 0),
+    sideFlip: pick('sideFlip', true),
+    align: pick('align', 'center'),
+    alignOffset: pick('alignOffset', 0),
+    alignFlip: pick('alignFlip', true),
+    avoidCollisions: pick('avoidCollisions', true),
+    collisionBoundary: props.collisionBoundary ?? defaults?.collisionBoundary ?? [],
+    collisionPadding: pick('collisionPadding', 0),
+    arrowPadding: pick('arrowPadding', 0),
+    sticky: pick('sticky', 'partial'),
+    hideWhenDetached: pick('hideWhenDetached', false),
+    positionStrategy: props.positionStrategy ?? defaults?.positionStrategy,
+    updatePositionStrategy: props.updatePositionStrategy ?? defaults?.updatePositionStrategy,
+  };
+});
+
+const as = computed(() => props.as ?? ctx.contentDefaults.value?.as ?? 'div');
+
+const computedAriaLabel = computed(() =>
+  props.ariaLabel ?? ctx.contentDefaults.value?.ariaLabel ?? currentElement.value?.textContent ?? '',
+);
 
 function onDocumentTooltipOpen() {
   ctx.onClose();
@@ -84,17 +100,11 @@ function onScrollCapture(event: Event) {
   if (target && ctx.trigger.value && target.contains(ctx.trigger.value)) ctx.onClose();
 }
 
-onMounted(() => {
-  if (typeof globalThis === 'undefined') return;
-  globalThis.addEventListener('scroll', onScrollCapture, { capture: true });
-  document.addEventListener(TOOLTIP_OPEN_EVENT, onDocumentTooltipOpen);
-});
-
-onScopeDispose(() => {
-  if (typeof globalThis === 'undefined') return;
-  globalThis.removeEventListener('scroll', onScrollCapture, { capture: true });
-  document.removeEventListener(TOOLTIP_OPEN_EVENT, onDocumentTooltipOpen);
-});
+// Auto-removed on scope dispose. SSR-safe: the window default no-ops without a
+// `window`, and the `document` getter resolves to `undefined` on the server.
+// `capture`/`passive` preserved.
+useEventListener('scroll', onScrollCapture, { capture: true, passive: true });
+useEventListener(() => globalThis.document, TOOLTIP_OPEN_EVENT, onDocumentTooltipOpen);
 
 function onPointerDownOutside(event: PointerEvent | MouseEvent) {
   if (
@@ -120,20 +130,7 @@ function onPointerDownOutside(event: PointerEvent | MouseEvent) {
     <PopperContent
       :ref="forwardRef"
       :as="as"
-      :side="side"
-      :side-offset="sideOffset"
-      :side-flip="sideFlip"
-      :align="align"
-      :align-offset="alignOffset"
-      :align-flip="alignFlip"
-      :avoid-collisions="avoidCollisions"
-      :collision-boundary="collisionBoundary"
-      :collision-padding="collisionPadding"
-      :arrow-padding="arrowPadding"
-      :sticky="sticky"
-      :hide-when-detached="hideWhenDetached"
-      :position-strategy="positionStrategy"
-      :update-position-strategy="updatePositionStrategy"
+      v-bind="popperProps"
       :data-state="ctx.stateAttribute.value"
       :style="{
         '--tooltip-content-transform-origin': 'var(--popper-transform-origin)',
diff --git a/vue/primitives/src/tooltip/TooltipPortal.vue b/vue/primitives/src/overlays/tooltip/TooltipPortal.vue
similarity index 79%
rename from vue/primitives/src/tooltip/TooltipPortal.vue
rename to vue/primitives/src/overlays/tooltip/TooltipPortal.vue
index f126d14..b2a3a73 100644
--- a/vue/primitives/src/tooltip/TooltipPortal.vue
+++ b/vue/primitives/src/overlays/tooltip/TooltipPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { TeleportPrimitiveProps } from '../teleport';
+import type { TeleportPrimitiveProps } from '../../utilities/teleport';
 
 /**
  * Teleports the tooltip Content into another part of the DOM (the body by
@@ -10,7 +10,7 @@ export interface TooltipPortalProps extends TeleportPrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Portal } from '../teleport';
+import { Portal } from '../../utilities/teleport';
 
 const props = defineProps<TooltipPortalProps>();
 </script>
diff --git a/vue/primitives/src/tooltip/TooltipProvider.vue b/vue/primitives/src/overlays/tooltip/TooltipProvider.vue
similarity index 87%
rename from vue/primitives/src/tooltip/TooltipProvider.vue
rename to vue/primitives/src/overlays/tooltip/TooltipProvider.vue
index b7be496..6138982 100644
--- a/vue/primitives/src/tooltip/TooltipProvider.vue
+++ b/vue/primitives/src/overlays/tooltip/TooltipProvider.vue
@@ -1,4 +1,6 @@
 <script lang="ts">
+import type { TooltipContentImplProps } from './TooltipContentImpl.vue';
+
 /**
  * Wraps a group of tooltips to share open/close timing and global behavior.
  * Place it high in the tree (often at the app root); every `TooltipRoot` must
@@ -39,6 +41,12 @@ export interface TooltipProviderProps {
    * @default false
    */
   ignoreNonKeyboardFocus?: boolean;
+  /**
+   * Group-wide default Content props (e.g. `side`, `sideOffset`, `align`)
+   * applied to every tooltip in this provider. Props set on an individual
+   * `TooltipContent` always win over these defaults.
+   */
+  content?: Partial<TooltipContentImplProps>;
 }
 </script>
 
@@ -55,6 +63,7 @@ const {
   disableClosingTrigger = false,
   disabled = false,
   ignoreNonKeyboardFocus = false,
+  content,
 } = defineProps<TooltipProviderProps>();
 
 const isOpenDelayed = ref(true);
@@ -77,6 +86,7 @@ provideTooltipProviderContext({
   disableClosingTrigger: toRef(() => disableClosingTrigger),
   disabled: toRef(() => disabled),
   ignoreNonKeyboardFocus: toRef(() => ignoreNonKeyboardFocus),
+  content: toRef(() => content),
   isPointerInTransitRef,
   onOpen() {
     clearSkipTimer();
diff --git a/vue/primitives/src/tooltip/TooltipRoot.vue b/vue/primitives/src/overlays/tooltip/TooltipRoot.vue
similarity index 85%
rename from vue/primitives/src/tooltip/TooltipRoot.vue
rename to vue/primitives/src/overlays/tooltip/TooltipRoot.vue
index b7ca3d2..c0e7982 100644
--- a/vue/primitives/src/tooltip/TooltipRoot.vue
+++ b/vue/primitives/src/overlays/tooltip/TooltipRoot.vue
@@ -37,14 +37,19 @@ export interface TooltipRootProps {
    */
   ignoreNonKeyboardFocus?: boolean;
 }
+
+/** Emitted whenever the open state of the tooltip changes (controlled or not). */
+export interface TooltipRootEmits {
+  'update:open': [value: boolean];
+}
 </script>
 
 <script setup lang="ts">
-import { computed, onScopeDispose, ref } from 'vue';
+import { computed, onScopeDispose, ref, shallowRef, watch } from 'vue';
 import { provideTooltipContext, useTooltipProviderContext } from './context';
 import { PopperRoot } from '../popper';
 import { TOOLTIP_OPEN_EVENT } from './utils';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
 defineOptions({ inheritAttrs: false });
 
@@ -86,7 +91,7 @@ const ignoreNonKeyboardFocus = computed(
 );
 
 const wasOpenDelayed = ref(false);
-const trigger = ref<HTMLElement>();
+const trigger = shallowRef<HTMLElement>();
 const contentId = useId(undefined, 'tooltip-content');
 
 const stateAttribute = computed<'closed' | 'delayed-open' | 'instant-open'>(() => {
@@ -108,33 +113,35 @@ function dispatchOpenEvent() {
   document.dispatchEvent(new CustomEvent(TOOLTIP_OPEN_EVENT));
 }
 
-function handleOpen() {
-  clearOpenTimer();
-  wasOpenDelayed.value = false;
-  if (!open.value) {
-    open.value = true;
+// Centralize provider skip-delay bookkeeping and the single-open broadcast in a
+// watcher so that controlled (`v-model:open`) changes — not just the imperative
+// trigger handlers — also notify the provider and close sibling tooltips.
+watch(open, (isOpen) => {
+  if (isOpen) {
     providerCtx.onOpen();
     dispatchOpenEvent();
   }
+  else {
+    providerCtx.onClose();
+  }
+});
+
+function handleOpen() {
+  clearOpenTimer();
+  wasOpenDelayed.value = false;
+  open.value = true;
 }
 
 function handleClose() {
   clearOpenTimer();
-  if (open.value) {
-    open.value = false;
-    providerCtx.onClose();
-  }
+  open.value = false;
 }
 
 function handleDelayedOpen() {
   clearOpenTimer();
   openTimer = setTimeout(() => {
     wasOpenDelayed.value = true;
-    if (!open.value) {
-      open.value = true;
-      providerCtx.onOpen();
-      dispatchOpenEvent();
-    }
+    open.value = true;
   }, delayDuration.value);
 }
 
@@ -143,10 +150,12 @@ provideTooltipContext({
   open,
   stateAttribute,
   trigger,
+  isPointerInTransitRef: providerCtx.isPointerInTransitRef,
   disableHoverableContent,
   disableClosingTrigger,
   disabled,
   ignoreNonKeyboardFocus,
+  contentDefaults: computed(() => providerCtx.content.value),
   onTriggerChange(el) {
     trigger.value = el;
   },
diff --git a/vue/primitives/src/tooltip/TooltipTrigger.vue b/vue/primitives/src/overlays/tooltip/TooltipTrigger.vue
similarity index 81%
rename from vue/primitives/src/tooltip/TooltipTrigger.vue
rename to vue/primitives/src/overlays/tooltip/TooltipTrigger.vue
index 011fbf5..93e4afc 100644
--- a/vue/primitives/src/tooltip/TooltipTrigger.vue
+++ b/vue/primitives/src/overlays/tooltip/TooltipTrigger.vue
@@ -1,23 +1,25 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PopperAnchorProps } from '../popper';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The element the tooltip describes and anchors to. Hovering or focusing it
  * opens the tooltip (after the delay); pointer-down/click closes it unless
  * `disableClosingTrigger` is set. Wires up `aria-describedby` to the content
- * and renders as a `<button>` by default.
+ * and renders as a `<button>` by default. Pass `reference` to position the
+ * tooltip against a custom virtual/real element instead of the trigger node.
  */
-export interface TooltipTriggerProps extends PrimitiveProps {}
+export interface TooltipTriggerProps extends PrimitiveProps, Pick<PopperAnchorProps, 'reference'> {}
 </script>
 
 <script setup lang="ts">
 import { onMounted, ref } from 'vue';
 import { useTooltipContext, useTooltipProviderContext } from './context';
 import { PopperAnchor } from '../popper';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 
-const { as = 'button' } = defineProps<TooltipTriggerProps>();
+const { as = 'button', reference } = defineProps<TooltipTriggerProps>();
 
 const ctx = useTooltipContext();
 const providerCtx = useTooltipProviderContext();
@@ -80,7 +82,7 @@ function onClick() {
 </script>
 
 <template>
-  <PopperAnchor as="template">
+  <PopperAnchor as="template" :reference="reference">
     <Primitive
       :ref="forwardRef"
       :as="as"
@@ -88,6 +90,7 @@ function onClick() {
       :aria-describedby="ctx.open.value ? ctx.contentId.value : undefined"
       :data-state="ctx.stateAttribute.value"
       data-tooltip-trigger
+      data-grace-area-trigger
       @pointermove="onPointerMove"
       @pointerleave="onPointerLeave"
       @pointerdown="onPointerDown"
diff --git a/vue/primitives/src/tooltip/__test__/Tooltip.test.ts b/vue/primitives/src/overlays/tooltip/__test__/Tooltip.test.ts
similarity index 62%
rename from vue/primitives/src/tooltip/__test__/Tooltip.test.ts
rename to vue/primitives/src/overlays/tooltip/__test__/Tooltip.test.ts
index e1626f5..ba36ea8 100644
--- a/vue/primitives/src/tooltip/__test__/Tooltip.test.ts
+++ b/vue/primitives/src/overlays/tooltip/__test__/Tooltip.test.ts
@@ -3,9 +3,9 @@ import {
   TooltipProvider,
   TooltipRoot,
   TooltipTrigger,
-} from '../../index';
+} from '../../../index';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { defineComponent, h, nextTick } from 'vue';
+import { defineComponent, h, nextTick, ref } from 'vue';
 import type { VueWrapper } from '@vue/test-utils';
 import { mount } from '@vue/test-utils';
 
@@ -288,4 +288,158 @@ describe('Tooltip', () => {
     await nextTick();
     expect(trigger.getAttribute('data-state')).toBe('instant-open');
   });
+
+  it('tags the trigger as a grace-area trigger for safe-area handoff', () => {
+    mountTooltip();
+    const trigger = getTrigger();
+    expect(trigger.hasAttribute('data-grace-area-trigger')).toBe(true);
+    // Existing marker is preserved for backwards compatibility.
+    expect(trigger.hasAttribute('data-tooltip-trigger')).toBe(true);
+  });
+});
+
+describe('Tooltip hoverable content', () => {
+  it('renders the hoverable variant by default (no flicker on content hover)', async () => {
+    mountTooltip({ defaultOpen: true });
+    await nextTick();
+    const tip = getTooltip();
+    expect(tip).toBeTruthy();
+    // Hoverable variant wires a grace area; the impl still renders role=tooltip,
+    // so we assert the content is present and the variant did not crash.
+    expect(tip!.textContent).toContain('Tooltip body');
+  });
+
+  it('renders without grace area when disableHoverableContent is set', async () => {
+    mountTooltip({ defaultOpen: true, disableHoverableContent: true });
+    await nextTick();
+    const tip = getTooltip();
+    expect(tip).toBeTruthy();
+    expect(tip!.textContent).toContain('Tooltip body');
+  });
+});
+
+describe('Tooltip reference anchor', () => {
+  it('forwards a custom reference to the popper anchor', async () => {
+    const reference = document.createElement('div');
+    document.body.appendChild(reference);
+
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(TooltipProvider, null, {
+            default: () =>
+              h(TooltipRoot, { defaultOpen: true }, {
+                default: () => [
+                  h(TooltipTrigger, { reference }, { default: () => 'T' }),
+                  h(TooltipContent, null, { default: () => 'body' }),
+                ],
+              }),
+          });
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
+    await nextTick();
+    // No throw and the tooltip still opens with a custom reference element.
+    expect(getTrigger().hasAttribute('data-grace-area-trigger')).toBe(true);
+    expect(getTooltip()).toBeTruthy();
+    wrapper.unmount();
+    reference.remove();
+  });
+});
+
+describe('Tooltip provider content defaults', () => {
+  function mountWithProviderContent(options: {
+    providerAriaLabel?: string;
+    contentAriaLabel?: string;
+  }) {
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(
+            TooltipProvider,
+            { content: { ariaLabel: options.providerAriaLabel } },
+            {
+              default: () =>
+                h(TooltipRoot, { defaultOpen: true }, {
+                  default: () => [
+                    h(TooltipTrigger, null, { default: () => 'T' }),
+                    h(
+                      TooltipContent,
+                      { ariaLabel: options.contentAriaLabel },
+                      { default: () => 'visible body' },
+                    ),
+                  ],
+                }),
+            },
+          );
+      },
+    });
+    return track(mount(Wrapper, { attachTo: document.body }));
+  }
+
+  it('applies a provider-level content default to every tooltip', async () => {
+    mountWithProviderContent({ providerAriaLabel: 'from provider' });
+    await nextTick();
+    const tip = getTooltip();
+    expect(tip!.textContent).toContain('from provider');
+  });
+
+  it('lets per-content props win over provider defaults', async () => {
+    mountWithProviderContent({
+      providerAriaLabel: 'from provider',
+      contentAriaLabel: 'from content',
+    });
+    await nextTick();
+    const tip = getTooltip();
+    expect(tip!.textContent).toContain('from content');
+    expect(tip!.textContent).not.toContain('from provider');
+  });
+});
+
+describe('Tooltip controlled-open broadcast', () => {
+  it('closes another open tooltip when one opens via controlled v-model', async () => {
+    const Wrapper = defineComponent({
+      props: { openB: { type: Boolean, default: false } },
+      setup(props) {
+        const openA = ref(true);
+        return () =>
+          h(TooltipProvider, null, {
+            default: () => [
+              h(
+                TooltipRoot,
+                { open: openA.value, 'onUpdate:open': (v: boolean) => { openA.value = v; } },
+                {
+                  default: () => [
+                    h(TooltipTrigger, { 'data-id': 'a' }, { default: () => 'A' }),
+                    h(TooltipContent, null, { default: () => 'A body' }),
+                  ],
+                },
+              ),
+              h(TooltipRoot, { open: props.openB }, {
+                default: () => [
+                  h(TooltipTrigger, { 'data-id': 'b' }, { default: () => 'B' }),
+                  h(TooltipContent, null, { default: () => 'B body' }),
+                ],
+              }),
+            ],
+          });
+      },
+    });
+
+    const wrapper = track(mount(Wrapper, { attachTo: document.body, props: { openB: false } }));
+    await nextTick();
+
+    const a = document.querySelector('[data-id="a"]') as HTMLElement;
+    expect(a.getAttribute('data-state')).toBe('instant-open');
+
+    // Opening B (controlled) should broadcast TOOLTIP_OPEN and close A.
+    await wrapper.setProps({ openB: true });
+    await nextTick();
+    await nextTick();
+
+    const b = document.querySelector('[data-id="b"]') as HTMLElement;
+    expect(b.getAttribute('data-state')).toBe('instant-open');
+    expect(a.getAttribute('data-state')).toBe('closed');
+  });
 });
diff --git a/vue/primitives/src/tooltip/context.ts b/vue/primitives/src/overlays/tooltip/context.ts
similarity index 79%
rename from vue/primitives/src/tooltip/context.ts
rename to vue/primitives/src/overlays/tooltip/context.ts
index b6e9c3a..c45487d 100644
--- a/vue/primitives/src/tooltip/context.ts
+++ b/vue/primitives/src/overlays/tooltip/context.ts
@@ -1,5 +1,6 @@
 import type { ComputedRef, Ref } from 'vue';
 import type { TooltipState } from './utils';
+import type { TooltipContentImplProps } from './TooltipContentImpl.vue';
 import { useContextFactory } from '@robonen/vue';
 
 export interface TooltipProviderContext {
@@ -19,6 +20,8 @@ export interface TooltipProviderContext {
   disabled: Ref<boolean>;
   /** Skip opening on non-keyboard focus (avoids tooltips after closing dialogs / switching tabs). */
   ignoreNonKeyboardFocus: Ref<boolean>;
+  /** Group-wide default Content props (positioning, etc.); per-Content props win. */
+  content: Ref<Partial<TooltipContentImplProps> | undefined>;
   onOpen: () => void;
   onClose: () => void;
 }
@@ -33,10 +36,14 @@ export interface TooltipContext {
   open: Ref<boolean>;
   stateAttribute: ComputedRef<TooltipState>;
   trigger: Ref<HTMLElement | undefined>;
+  /** Set to `true` while the pointer is in the safe-area between trigger and content. */
+  isPointerInTransitRef: Ref<boolean>;
   disableHoverableContent: ComputedRef<boolean>;
   disableClosingTrigger: ComputedRef<boolean>;
   disabled: ComputedRef<boolean>;
   ignoreNonKeyboardFocus: ComputedRef<boolean>;
+  /** Group-wide default Content props from the Provider; per-Content props win. */
+  contentDefaults: ComputedRef<Partial<TooltipContentImplProps> | undefined>;
   onTriggerChange: (el: HTMLElement | undefined) => void;
   onTriggerEnter: () => void;
   onTriggerLeave: () => void;
diff --git a/vue/primitives/src/tooltip/demo.vue b/vue/primitives/src/overlays/tooltip/demo.vue
similarity index 71%
rename from vue/primitives/src/tooltip/demo.vue
rename to vue/primitives/src/overlays/tooltip/demo.vue
index 5c9cc20..25d4bc8 100644
--- a/vue/primitives/src/tooltip/demo.vue
+++ b/vue/primitives/src/overlays/tooltip/demo.vue
@@ -30,11 +30,11 @@ const actions = [
 <template>
   <!-- A single Provider drives shared open/skip timing for the whole toolbar. -->
   <TooltipProvider :delay-duration="300" :skip-delay-duration="200">
-    <div class="flex items-center gap-1 rounded-lg border border-(--border) bg-(--bg-elevated) p-1 text-(--fg)">
+    <div class="flex items-center gap-1 rounded-lg border border-border bg-bg-elevated p-1 text-fg">
       <TooltipRoot v-for="action in actions" :key="action.label">
         <TooltipTrigger
           :aria-label="action.label"
-          class="inline-flex size-9 items-center justify-center rounded-md text-(--fg-muted) transition-colors hover:bg-(--bg-subtle) hover:text-(--fg) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) data-[state=instant-open]:bg-(--bg-subtle) data-[state=delayed-open]:bg-(--bg-subtle)"
+          class="inline-flex size-9 items-center justify-center rounded-md text-fg-muted transition-colors hover:bg-bg-subtle hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[state=instant-open]:bg-bg-subtle data-[state=delayed-open]:bg-bg-subtle"
         >
           <svg
             class="size-4.5" viewBox="0 0 24 24" fill="none" stroke="currentColor"
@@ -49,12 +49,12 @@ const actions = [
             :side="action.side"
             :side-offset="6"
             :collision-padding="8"
-            class="z-50 select-none rounded-md bg-(--fg) px-2.5 py-1.5 text-xs font-medium text-(--bg) shadow-md data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in data-[state=delayed-open]:zoom-in-95 data-[state=instant-open]:animate-in data-[state=instant-open]:fade-in data-[state=closed]:animate-out data-[state=closed]:fade-out"
+            class="z-50 select-none rounded-md bg-fg px-2.5 py-1.5 text-xs font-medium text-bg shadow-md data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in data-[state=delayed-open]:zoom-in-95 data-[state=instant-open]:animate-in data-[state=instant-open]:fade-in data-[state=closed]:animate-out data-[state=closed]:fade-out"
           >
             {{ action.label }}
             <TooltipArrow :width="10" :height="5">
               <svg width="10" height="5" viewBox="0 0 10 5" class="block" aria-hidden="true">
-                <path d="M0 0 L5 5 L10 0 Z" class="fill-(--fg)" />
+                <path d="M0 0 L5 5 L10 0 Z" class="fill-fg" />
               </svg>
             </TooltipArrow>
           </TooltipContent>
diff --git a/vue/primitives/src/tooltip/index.ts b/vue/primitives/src/overlays/tooltip/index.ts
similarity index 78%
rename from vue/primitives/src/tooltip/index.ts
rename to vue/primitives/src/overlays/tooltip/index.ts
index 8f6dd54..495f951 100644
--- a/vue/primitives/src/tooltip/index.ts
+++ b/vue/primitives/src/overlays/tooltip/index.ts
@@ -3,6 +3,7 @@ export { default as TooltipRoot } from './TooltipRoot.vue';
 export { default as TooltipTrigger } from './TooltipTrigger.vue';
 export { default as TooltipPortal } from './TooltipPortal.vue';
 export { default as TooltipContent } from './TooltipContent.vue';
+export { default as TooltipContentHoverable } from './TooltipContentHoverable.vue';
 export { default as TooltipArrow } from './TooltipArrow.vue';
 
 export {
@@ -15,10 +16,14 @@ export {
 export { TOOLTIP_OPEN_EVENT, type TooltipState } from './utils';
 
 export type { TooltipProviderProps } from './TooltipProvider.vue';
-export type { TooltipRootProps } from './TooltipRoot.vue';
+export type { TooltipRootProps, TooltipRootEmits } from './TooltipRoot.vue';
 export type { TooltipTriggerProps } from './TooltipTrigger.vue';
 export type { TooltipPortalProps } from './TooltipPortal.vue';
 export type { TooltipContentProps, TooltipContentEmits } from './TooltipContent.vue';
+export type {
+  TooltipContentHoverableProps,
+  TooltipContentHoverableEmits,
+} from './TooltipContentHoverable.vue';
 export type {
   TooltipContentImplProps,
   TooltipContentImplEmits,
diff --git a/vue/primitives/src/tooltip/utils.ts b/vue/primitives/src/overlays/tooltip/utils.ts
similarity index 100%
rename from vue/primitives/src/tooltip/utils.ts
rename to vue/primitives/src/overlays/tooltip/utils.ts
diff --git a/vue/primitives/src/pin-input/PinInputInput.vue b/vue/primitives/src/pin-input/PinInputInput.vue
deleted file mode 100644
index 5957f2e..0000000
--- a/vue/primitives/src/pin-input/PinInputInput.vue
+++ /dev/null
@@ -1,140 +0,0 @@
-<script lang="ts">
-const DIGIT_RE = /\d/;
-const NON_DIGIT_G = /\D/g;
-
-/**
- * A single cell of the pin input, identified by its zero-based `index`. Renders
- * one masked-or-plain character box that reads/writes its slot of the root's
- * value and handles typing (auto-advancing to the next cell), Backspace/Delete,
- * arrow/Home/End navigation, and paste (spreading text across cells). Render one
- * per character, with `index` from `0` to `length - 1`.
- */
-export interface PinInputInputProps {
-  index: number;
-}
-</script>
-
-<script setup lang="ts">
-import { computed, onBeforeUnmount, useTemplateRef, watch } from 'vue';
-import { usePinInputContext } from './context';
-
-const props = defineProps<PinInputInputProps>();
-const ctx = usePinInputContext();
-const el = useTemplateRef<HTMLInputElement>('el');
-
-watch(el, (curr, prev) => {
-  if (prev)
-    ctx.unregister(prev);
-  if (curr)
-    ctx.register(curr);
-});
-
-onBeforeUnmount(() => {
-  if (el.value)
-    ctx.unregister(el.value);
-});
-
-const displayed = computed(() => {
-  const ch = ctx.value.value[props.index] ?? '';
-  if (!ch)
-    return '';
-  return ctx.mask.value ? '•' : ch;
-});
-
-// `inputType` / `inputMode` were thin ternary wrappers — inline in template.
-
-function onInput(e: Event): void {
-  const target = e.target as HTMLInputElement;
-  const raw = target.value;
-  // keep only the last typed character
-  let ch = raw.length > 0 ? raw[raw.length - 1]! : '';
-  if (ctx.type.value === 'number' && ch && !DIGIT_RE.test(ch))
-    ch = '';
-  ctx.setAt(props.index, ch);
-  // re-sync DOM input since we overwrite with displayed
-  target.value = ch ? (ctx.mask.value ? '•' : ch) : '';
-  if (ch && props.index < ctx.length.value - 1)
-    ctx.focusIndex(props.index + 1);
-}
-
-function onKeyDown(e: KeyboardEvent): void {
-  const i = props.index;
-  const n = ctx.length.value;
-  switch (e.key) {
-    case 'Backspace': {
-      const current = ctx.value.value[i] ?? '';
-      if (current) {
-        ctx.clearAt(i);
-      }
-      else if (i > 0) {
-        ctx.focusIndex(i - 1);
-        ctx.clearAt(i - 1);
-      }
-      e.preventDefault();
-      break;
-    }
-    case 'Delete': {
-      ctx.clearAt(i);
-      e.preventDefault();
-      break;
-    }
-    case 'ArrowLeft': {
-      if (i > 0)
-        ctx.focusIndex(i - 1);
-      e.preventDefault();
-      break;
-    }
-    case 'ArrowRight': {
-      if (i < n - 1)
-        ctx.focusIndex(i + 1);
-      e.preventDefault();
-      break;
-    }
-    case 'Home': {
-      ctx.focusIndex(0);
-      e.preventDefault();
-      break;
-    }
-    case 'End': {
-      ctx.focusIndex(n - 1);
-      e.preventDefault();
-      break;
-    }
-  }
-}
-
-function onPaste(e: ClipboardEvent): void {
-  const data = e.clipboardData?.getData('text') ?? '';
-  if (!data)
-    return;
-  e.preventDefault();
-  const chars = ctx.type.value === 'number'
-    ? data.replaceAll(NON_DIGIT_G, '').split('')
-    : data.split('');
-  let idx = props.index;
-  for (const ch of chars) {
-    if (idx >= ctx.length.value)
-      break;
-    ctx.setAt(idx, ch);
-    idx++;
-  }
-  ctx.focusIndex(Math.min(idx, ctx.length.value - 1));
-}
-</script>
-
-<template>
-  <input
-    ref="el"
-    :type="ctx.mask.value ? 'password' : 'text'"
-    :inputmode="ctx.type.value === 'number' ? 'numeric' : 'text'"
-    :value="displayed"
-    :placeholder="ctx.placeholder.value"
-    :disabled="ctx.disabled.value"
-    :autocomplete="ctx.otp.value ? 'one-time-code' : 'off'"
-    :data-index="props.index"
-    maxlength="1"
-    @input="onInput"
-    @keydown="onKeyDown"
-    @paste="onPaste"
-  >
-</template>
diff --git a/vue/primitives/src/pin-input/__test__/PinInput.test.ts b/vue/primitives/src/pin-input/__test__/PinInput.test.ts
deleted file mode 100644
index 1259942..0000000
--- a/vue/primitives/src/pin-input/__test__/PinInput.test.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import type { Component } from 'vue';
-import { defineComponent, h, nextTick, ref } from 'vue';
-import { PinInputInput, PinInputRoot } from '../index';
-
-function mountPin(props: Record<string, unknown> = {}) {
-  const model = ref<string[] | undefined>(undefined);
-  const completed = ref<string | null>(null);
-  const Harness = defineComponent({
-    setup: () => () => h(PinInputRoot, {
-      modelValue: model.value,
-      length: 4,
-      'onUpdate:modelValue': (v: string[]) => { model.value = v; },
-      onComplete: (v: string) => { completed.value = v; },
-      ...props,
-    }, {
-      default: () => [0, 1, 2, 3].map(i => h(PinInputInput as Component, { key: i, index: i })),
-    }),
-  });
-  const wrapper = mount(Harness, { attachTo: document.body });
-  return { wrapper, model, completed };
-}
-
-function inputs(): HTMLInputElement[] {
-  return Array.from(document.querySelectorAll<HTMLInputElement>('input[data-index]'));
-}
-
-function type(el: HTMLInputElement, ch: string): void {
-  el.value = ch;
-  el.dispatchEvent(new Event('input', { bubbles: true }));
-}
-
-function key(el: Element, k: string): void {
-  el.dispatchEvent(new KeyboardEvent('keydown', { key: k, bubbles: true, cancelable: true }));
-}
-
-describe('PinInput', () => {
-  it('renders N inputs based on length', () => {
-    const { wrapper } = mountPin();
-    expect(inputs().length).toBe(4);
-    wrapper.unmount();
-  });
-
-  it('typing auto-advances focus and fires complete', async () => {
-    const { wrapper, model, completed } = mountPin();
-    await nextTick();
-    const [a, b, c, d] = inputs();
-    type(a!, '1');
-    await nextTick();
-    expect(document.activeElement).toBe(b);
-    type(b!, '2');
-    type(c!, '3');
-    type(d!, '4');
-    await nextTick();
-    expect(model.value).toEqual(['1', '2', '3', '4']);
-    expect(completed.value).toBe('1234');
-    wrapper.unmount();
-  });
-
-  it('Backspace on empty moves to previous and clears', async () => {
-    const { wrapper, model } = mountPin();
-    await nextTick();
-    const [a, b] = inputs();
-    type(a!, '1');
-    await nextTick();
-    b!.focus();
-    key(b!, 'Backspace');
-    await nextTick();
-    expect(document.activeElement).toBe(a);
-    expect(model.value![0]).toBe('');
-    wrapper.unmount();
-  });
-
-  it('ArrowLeft/ArrowRight navigate', async () => {
-    const { wrapper } = mountPin();
-    await nextTick();
-    const [a, b, c] = inputs();
-    b!.focus();
-    key(b!, 'ArrowLeft');
-    expect(document.activeElement).toBe(a);
-    key(a!, 'ArrowRight');
-    expect(document.activeElement).toBe(b);
-    key(b!, 'ArrowRight');
-    expect(document.activeElement).toBe(c);
-    wrapper.unmount();
-  });
-
-  it('type=number rejects non-digit input', async () => {
-    const { wrapper, model } = mountPin({ type: 'number' });
-    await nextTick();
-    const [a] = inputs();
-    type(a!, 'x');
-    await nextTick();
-    expect(model.value?.[0] ?? '').toBe('');
-    type(a!, '7');
-    await nextTick();
-    expect(model.value![0]).toBe('7');
-    wrapper.unmount();
-  });
-
-  it('paste fills across inputs', async () => {
-    const { wrapper, model, completed } = mountPin();
-    await nextTick();
-    const [a] = inputs();
-    a!.focus();
-    const event = new Event('paste', { bubbles: true, cancelable: true }) as unknown as ClipboardEvent;
-    Object.defineProperty(event, 'clipboardData', {
-      value: { getData: (_type: string) => '9876' },
-    });
-    a!.dispatchEvent(event);
-    await nextTick();
-    expect(model.value).toEqual(['9', '8', '7', '6']);
-    expect(completed.value).toBe('9876');
-    wrapper.unmount();
-  });
-
-  it('mask renders password type for each input', async () => {
-    const { wrapper } = mountPin({ mask: true });
-    await nextTick();
-    for (const el of inputs())
-      expect(el.getAttribute('type')).toBe('password');
-    wrapper.unmount();
-  });
-});
diff --git a/vue/primitives/src/popover/__test__/Popover.test.ts b/vue/primitives/src/popover/__test__/Popover.test.ts
deleted file mode 100644
index f9ccb2c..0000000
--- a/vue/primitives/src/popover/__test__/Popover.test.ts
+++ /dev/null
@@ -1,169 +0,0 @@
-import {
-  PopoverClose,
-  PopoverContent,
-  PopoverRoot,
-  PopoverTrigger,
-} from '../index';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { defineComponent, h, nextTick, ref } from 'vue';
-import type { VueWrapper } from '@vue/test-utils';
-import { mount } from '@vue/test-utils';
-import { userEvent } from 'vitest/browser';
-
-const wrappers: Array<VueWrapper<any>> = [];
-
-afterEach(() => {
-  while (wrappers.length) wrappers.pop()!.unmount();
-  document.body.innerHTML = '';
-  document.body.removeAttribute('style');
-});
-
-function track<T extends VueWrapper<any>>(w: T): T {
-  wrappers.push(w);
-  return w;
-}
-
-function mountPopover(options: {
-  open?: boolean;
-  defaultOpen?: boolean;
-  modal?: boolean;
-  onUpdateOpen?: (v: boolean) => void;
-} = {}) {
-  const Wrapper = defineComponent({
-    setup() {
-      return () => h(
-        PopoverRoot,
-        {
-          open: options.open,
-          defaultOpen: options.defaultOpen,
-          modal: options.modal,
-          'onUpdate:open': options.onUpdateOpen,
-        },
-        {
-          default: () => [
-            h(PopoverTrigger, null, { default: () => 'Toggle' }),
-            h(PopoverContent, { forceMount: true }, {
-              default: () => [
-                h('p', 'Popover body'),
-                h(PopoverClose, null, { default: () => 'Close' }),
-              ],
-            }),
-          ],
-        },
-      );
-    },
-  });
-
-  return track(mount(Wrapper, { attachTo: document.body }));
-}
-
-describe('Popover', () => {
-  it('renders trigger', () => {
-    const wrapper = mountPopover();
-    const trigger = wrapper.find('button');
-    expect(trigger.text()).toBe('Toggle');
-    expect(trigger.attributes('aria-haspopup')).toBe('dialog');
-    expect(trigger.attributes('data-state')).toBe('closed');
-  });
-
-  it('opens on trigger click', async () => {
-    const wrapper = mountPopover();
-    const trigger = wrapper.find('button');
-
-    await trigger.trigger('click');
-    await nextTick();
-
-    expect(trigger.attributes('aria-expanded')).toBe('true');
-    expect(trigger.attributes('data-state')).toBe('open');
-  });
-
-  it('toggles with v-model:open', async () => {
-    const onUpdate = vi.fn();
-    const wrapper = mountPopover({ onUpdateOpen: onUpdate });
-    const trigger = wrapper.find('button');
-
-    await trigger.trigger('click');
-    await nextTick();
-
-    expect(onUpdate).toHaveBeenCalledWith(true);
-  });
-
-  it('opens with defaultOpen', async () => {
-    const wrapper = mountPopover({ defaultOpen: true });
-    await nextTick();
-
-    const trigger = wrapper.find('button');
-    expect(trigger.attributes('data-state')).toBe('open');
-  });
-
-  it('close button closes the popover', async () => {
-    const onUpdate = vi.fn();
-    const wrapper = mountPopover({ defaultOpen: true, onUpdateOpen: onUpdate });
-    await nextTick();
-
-    const closeBtn = wrapper.findAll('button').find(b => b.text() === 'Close');
-    expect(closeBtn).toBeDefined();
-
-    await closeBtn!.trigger('click');
-    await nextTick();
-
-    expect(onUpdate).toHaveBeenCalledWith(false);
-  });
-
-  it('content has role="dialog"', async () => {
-    const wrapper = mountPopover({ defaultOpen: true });
-    await nextTick();
-
-    const content = wrapper.find('[role="dialog"]');
-    expect(content.exists()).toBe(true);
-    expect(content.attributes('data-state')).toBe('open');
-  });
-
-  it('closes on Escape key', async () => {
-    const onUpdate = vi.fn();
-    mountPopover({ defaultOpen: true, onUpdateOpen: onUpdate });
-    await nextTick();
-
-    await userEvent.keyboard('{Escape}');
-    await nextTick();
-
-    expect(onUpdate).toHaveBeenCalledWith(false);
-  });
-
-  it('supports controlled open', async () => {
-    const Wrapper = defineComponent({
-      setup() {
-        const open = ref(false);
-        return () => h(
-          PopoverRoot,
-          { open: open.value, 'onUpdate:open': (v: boolean) => { open.value = v; } },
-          {
-            default: () => [
-              h(PopoverTrigger, null, { default: () => 'Toggle' }),
-              h(PopoverContent, { forceMount: true }, { default: () => 'Body' }),
-            ],
-          },
-        );
-      },
-    });
-
-    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
-    await nextTick();
-
-    expect(wrapper.find('button').attributes('data-state')).toBe('closed');
-
-    await wrapper.find('button').trigger('click');
-    await nextTick();
-
-    expect(wrapper.find('button').attributes('data-state')).toBe('open');
-  });
-
-  it('trigger has aria-controls pointing to content id', async () => {
-    const wrapper = mountPopover({ defaultOpen: true });
-    await nextTick();
-
-    const trigger = wrapper.find('button');
-    const contentId = wrapper.find('[role="dialog"]').attributes('id');
-    expect(trigger.attributes('aria-controls')).toBe(contentId);
-  });
-});
diff --git a/vue/primitives/src/popper/PopperArrow.vue b/vue/primitives/src/popper/PopperArrow.vue
deleted file mode 100644
index af8e403..0000000
--- a/vue/primitives/src/popper/PopperArrow.vue
+++ /dev/null
@@ -1,82 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { Side } from './utils';
-
-const OPPOSITE_SIDE: Record<Side, Side> = {
-  top: 'bottom',
-  right: 'left',
-  bottom: 'top',
-  left: 'right',
-};
-
-// Hoisted to module scope — one allocation per module load instead of one per
-// render. Values are primitive strings, so objects are frozen-in-practice.
-const TRANSFORM_ORIGIN: Record<Side, string> = {
-  top: '',
-  right: '0 0',
-  bottom: 'center 0',
-  left: '100% 0',
-};
-
-const TRANSFORM: Record<Side, string> = {
-  top: 'translateY(100%)',
-  right: 'translateY(50%) rotate(90deg) translateX(-50%)',
-  bottom: 'rotate(180deg)',
-  left: 'translateY(50%) rotate(-90deg) translateX(50%)',
-};
-
-/**
- * An optional arrow/pointer rendered inside `PopperContent` that points back at
- * the anchor. It reads the resolved side and arrow offset from the content
- * context to position and rotate itself against the correct edge, and hides
- * automatically when it cannot be centered. Must be a child of `PopperContent`.
- */
-export interface PopperArrowProps extends PrimitiveProps {
-  /** Arrow width in pixels. @default 10 */
-  width?: number;
-  /** Arrow height in pixels. @default 5 */
-  height?: number;
-}
-</script>
-
-<script setup lang="ts">
-import type { ComponentPublicInstance } from 'vue';
-import { Primitive } from '../primitive';
-import { computed } from 'vue';
-import { useForwardExpose } from '@robonen/vue';
-import { usePopperContentContext } from './context';
-
-const { as = 'span', width = 10, height = 5 } = defineProps<PopperArrowProps>();
-
-const { forwardRef } = useForwardExpose();
-const contentContext = usePopperContentContext();
-const baseSide = computed(() => OPPOSITE_SIDE[contentContext.placedSide.value]);
-</script>
-
-<template>
-  <span
-    :ref="(el: Element | ComponentPublicInstance | null) => {
-      contentContext.onArrowChange((el as HTMLElement) ?? undefined);
-      return undefined;
-    }"
-    :style="{
-      position: 'absolute',
-      left: contentContext.arrowX.value ? `${contentContext.arrowX.value}px` : undefined,
-      top: contentContext.arrowY.value ? `${contentContext.arrowY.value}px` : undefined,
-      [baseSide]: 0,
-      transformOrigin: TRANSFORM_ORIGIN[contentContext.placedSide.value],
-      transform: TRANSFORM[contentContext.placedSide.value],
-      visibility: contentContext.shouldHideArrow.value ? 'hidden' : undefined,
-    }"
-  >
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      :style="{ display: 'block' }"
-      :width="width"
-      :height="height"
-    >
-      <slot />
-    </Primitive>
-  </span>
-</template>
diff --git a/vue/primitives/src/popper/__test__/Popper.test.ts b/vue/primitives/src/popper/__test__/Popper.test.ts
deleted file mode 100644
index 5d43a0c..0000000
--- a/vue/primitives/src/popper/__test__/Popper.test.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-import {
-  PopperAnchor,
-  PopperContent,
-  PopperRoot,
-} from '../index';
-import { afterEach, describe, expect, it } from 'vitest';
-import { defineComponent, h, nextTick } from 'vue';
-import type { VueWrapper } from '@vue/test-utils';
-import { mount } from '@vue/test-utils';
-
-const wrappers: Array<VueWrapper<any>> = [];
-
-afterEach(() => {
-  while (wrappers.length) wrappers.pop()!.unmount();
-  document.body.innerHTML = '';
-});
-
-function track<T extends VueWrapper<any>>(w: T): T {
-  wrappers.push(w);
-  return w;
-}
-
-describe('Popper', () => {
-  it('renders root with anchor and content', async () => {
-    const Wrapper = defineComponent({
-      setup() {
-        return () => h(PopperRoot, null, {
-          default: () => [
-            h(PopperAnchor, { as: 'button' }, { default: () => 'Anchor' }),
-            h(PopperContent, { as: 'div' }, { default: () => 'Content' }),
-          ],
-        });
-      },
-    });
-
-    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
-    await nextTick();
-
-    expect(wrapper.find('button').text()).toBe('Anchor');
-    expect(wrapper.find('[data-popper-content-wrapper]').exists()).toBe(true);
-  });
-
-  it('positions content with default placement (bottom)', async () => {
-    const Wrapper = defineComponent({
-      setup() {
-        return () => h(PopperRoot, null, {
-          default: () => [
-            h(PopperAnchor, { as: 'button' }, { default: () => 'Anchor' }),
-            h(PopperContent, null, { default: () => 'Content' }),
-          ],
-        });
-      },
-    });
-
-    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
-    await nextTick();
-    await nextTick();
-
-    const content = wrapper.find('[data-side]');
-    expect(content.exists()).toBe(true);
-  });
-
-  it('exposes data-side and data-align attributes', async () => {
-    const Wrapper = defineComponent({
-      setup() {
-        return () => h(PopperRoot, null, {
-          default: () => [
-            h(PopperAnchor, { as: 'button' }, { default: () => 'Anchor' }),
-            h(PopperContent, { side: 'top', align: 'start' }, { default: () => 'Content' }),
-          ],
-        });
-      },
-    });
-
-    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
-    await nextTick();
-    await nextTick();
-
-    const content = wrapper.find('[data-side]');
-    expect(content.exists()).toBe(true);
-  });
-
-  it('passes custom reference to anchor', async () => {
-    const customRef = {
-      getBoundingClientRect: () => ({
-        x: 100, y: 100, width: 50, height: 50,
-        top: 100, right: 150, bottom: 150, left: 100,
-        toJSON: () => {},
-      }),
-    };
-
-    const Wrapper = defineComponent({
-      setup() {
-        return () => h(PopperRoot, null, {
-          default: () => [
-            h(PopperAnchor, { reference: customRef }, { default: () => 'Anchor' }),
-            h(PopperContent, null, { default: () => 'Content' }),
-          ],
-        });
-      },
-    });
-
-    const wrapper = track(mount(Wrapper, { attachTo: document.body }));
-    await nextTick();
-
-    expect(wrapper.find('[data-popper-content-wrapper]').exists()).toBe(true);
-  });
-});
diff --git a/vue/primitives/src/primitive/__test__/Primitive.bench.ts b/vue/primitives/src/primitive/__test__/Primitive.bench.ts
deleted file mode 100644
index 148624e..0000000
--- a/vue/primitives/src/primitive/__test__/Primitive.bench.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-import { bench, describe } from 'vitest';
-import { Comment, cloneVNode, createVNode, h, render } from 'vue';
-import { Primitive, Slot } from '..';
-
-const attrs1 = { class: 'a' };
-
-const attrs5 = { class: 'a', id: 'b', role: 'button', tabindex: '0', title: 'tip' };
-
-const attrs15 = {
-  class: 'a',
-  id: 'b',
-  style: { color: 'red' },
-  onClick: () => {},
-  role: 'button',
-  tabindex: '0',
-  title: 'tip',
-  'data-a': '1',
-  'data-b': '2',
-  'data-c': '3',
-  'data-d': '4',
-  'data-e': '5',
-  'data-f': '6',
-  'data-g': '7',
-  'data-h': '8',
-};
-
-const defaultSlot = { default: () => [h('span', 'content')] };
-const noop = () => {};
-
-// ---- Baselines (raw Vue calls) ----
-
-describe('baseline: raw h()', () => {
-  bench('h() — 1 attr', () => {
-    h('div', attrs1, defaultSlot);
-  });
-
-  bench('h() — 5 attrs', () => {
-    h('div', attrs5, defaultSlot);
-  });
-
-  bench('h() — 15 attrs', () => {
-    h('div', attrs15, defaultSlot);
-  });
-});
-
-describe('baseline: raw cloneVNode()', () => {
-  const child = h('div', 'content');
-
-  bench('cloneVNode — 1 attr', () => {
-    cloneVNode(child, attrs1, true);
-  });
-
-  bench('cloneVNode — 5 attrs', () => {
-    cloneVNode(child, attrs5, true);
-  });
-
-  bench('cloneVNode — 15 attrs', () => {
-    cloneVNode(child, attrs15, true);
-  });
-});
-
-// ---- Primitive overhead vs raw h() ----
-
-describe('Primitive vs h()', () => {
-  bench('h("div") — baseline', () => {
-    h('div', attrs5, defaultSlot);
-  });
-
-  bench('Primitive({ as: "div" })', () => {
-    Primitive({ as: 'div' }, { attrs: attrs5, slots: defaultSlot, emit: noop });
-  });
-
-  bench('Primitive({ as: "template" }) — Slot mode', () => {
-    Primitive({ as: 'template' }, { attrs: attrs5, slots: defaultSlot, emit: noop });
-  });
-});
-
-// ---- Slot scaling by attribute count ----
-
-describe('Slot — scaling by attrs', () => {
-  bench('1 attr', () => {
-    Slot({} as never, { attrs: attrs1, slots: defaultSlot, emit: noop });
-  });
-
-  bench('5 attrs', () => {
-    Slot({} as never, { attrs: attrs5, slots: defaultSlot, emit: noop });
-  });
-
-  bench('15 attrs (mixed types)', () => {
-    Slot({} as never, { attrs: attrs15, slots: defaultSlot, emit: noop });
-  });
-});
-
-// ---- Slot edge cases ----
-
-describe('Slot — edge cases', () => {
-  bench('child with comments to skip', () => {
-    Slot({} as never, {
-      attrs: attrs5,
-      slots: {
-        default: () => [
-          createVNode(Comment, null, 'skip'),
-          createVNode(Comment, null, 'skip'),
-          h('span', 'content'),
-        ],
-      },
-      emit: noop,
-    });
-  });
-
-  bench('no default slot', () => {
-    Slot({} as never, { attrs: attrs5, slots: {}, emit: noop });
-  });
-});
-
-// ---- Slot — realistic attrs (fresh object per iteration) ----
-
-describe('Slot — fresh attrs per call', () => {
-  bench('5 attrs (stable ref)', () => {
-    Slot({} as never, { attrs: attrs5, slots: defaultSlot, emit: noop });
-  });
-
-  bench('5 attrs (new object)', () => {
-    Slot({} as never, {
-      attrs: { class: 'a', id: 'b', role: 'button', tabindex: '0', title: 'tip' },
-      slots: defaultSlot,
-      emit: noop,
-    });
-  });
-});
-
-// ---- Realistic runtime: mount + update via render() ----
-
-describe('Primitive — mount + update via render()', () => {
-  bench('h("div") — mount + update', () => {
-    const container = document.createElement('div');
-    render(h('div', attrs5, [h('span', 'content')]), container);
-    render(h('div', attrs15, [h('span', 'content')]), container);
-    render(null, container);
-  });
-
-  bench('Primitive({ as: "div" }) — mount + update', () => {
-    const container = document.createElement('div');
-    render(h(Primitive, { as: 'div', ...attrs5 }, defaultSlot), container);
-    render(h(Primitive, { as: 'div', ...attrs15 }, defaultSlot), container);
-    render(null, container);
-  });
-
-  bench('Primitive({ as: "template" }) — mount + update', () => {
-    const container = document.createElement('div');
-    render(h(Primitive, { as: 'template', ...attrs5 }, defaultSlot), container);
-    render(h(Primitive, { as: 'template', ...attrs15 }, defaultSlot), container);
-    render(null, container);
-  });
-});
diff --git a/vue/primitives/src/progress/ProgressRoot.vue b/vue/primitives/src/progress/ProgressRoot.vue
deleted file mode 100644
index f0772ef..0000000
--- a/vue/primitives/src/progress/ProgressRoot.vue
+++ /dev/null
@@ -1,77 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { ProgressState } from './context';
-
-/**
- * A bar that shows the completion progress of a task, typically a horizontal
- * fill that grows from empty to full. Use it for file uploads, multi-step form
- * progress, loading indicators, or any operation whose progress you can measure
- * (or, with a `null` value, signal as indeterminate).
- *
- * The root renders the accessible `progressbar` (wiring up `aria-valuemin`,
- * `aria-valuemax`, `aria-valuenow`, and `aria-valuetext`) and derives the
- * current `state` — `indeterminate`, `loading`, or `complete` — which it
- * provides via context and exposes on the `data-state` attribute. Pair it with
- * `ProgressIndicator` for the visual fill.
- */
-export interface ProgressRootProps extends PrimitiveProps {
-  /** Current value. `null` denotes an indeterminate progress bar. */
-  modelValue?: number | null;
-  /** Maximum value. @default 100 */
-  max?: number;
-  /** Accessible label (use when no external label is provided). */
-  getValueLabel?: (value: number, max: number) => string;
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed, toRef } from 'vue';
-import { provideProgressContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
-
-const {
-  modelValue = null,
-  max = 100,
-  getValueLabel = (v: number, m: number) => `${Math.round((v / m) * 100)}%`,
-  as = 'div',
-} = defineProps<ProgressRootProps>();
-
-const { forwardRef } = useForwardExpose();
-
-// Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
-const value = toRef(() => modelValue);
-const maxRef = toRef(() => max);
-
-const state = computed<ProgressState>(() => {
-  const v = modelValue;
-  if (v === null || v === undefined) return 'indeterminate';
-  if (v >= max) return 'complete';
-  return 'loading';
-});
-
-const valueLabel = computed(() => value.value === null || value.value === undefined ? undefined : getValueLabel(value.value, max));
-
-provideProgressContext({
-  value,
-  max: maxRef,
-  state,
-});
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    role="progressbar"
-    :aria-valuemin="0"
-    :aria-valuemax="max"
-    :aria-valuenow="value ?? undefined"
-    :aria-valuetext="valueLabel"
-    :data-state="state"
-    :data-value="value ?? undefined"
-    :data-max="max"
-  >
-    <slot :value="value" :max="max" :state="state" />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/progress/__test__/Progress.test.ts b/vue/primitives/src/progress/__test__/Progress.test.ts
deleted file mode 100644
index a7e5b3c..0000000
--- a/vue/primitives/src/progress/__test__/Progress.test.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { defineComponent, h } from 'vue';
-import { ProgressIndicator, ProgressRoot } from '../index';
-
-function mountProgress(props: Record<string, unknown> = {}) {
-  return mount(defineComponent({
-    setup: () => () => h(ProgressRoot, props, { default: () => h(ProgressIndicator, { class: 'ind' }) }),
-  }));
-}
-
-describe('Progress', () => {
-  it('has role="progressbar" with aria attributes', () => {
-    const wrapper = mountProgress({ modelValue: 40 });
-    expect(wrapper.attributes('role')).toBe('progressbar');
-    expect(wrapper.attributes('aria-valuemin')).toBe('0');
-    expect(wrapper.attributes('aria-valuemax')).toBe('100');
-    expect(wrapper.attributes('aria-valuenow')).toBe('40');
-    expect(wrapper.attributes('aria-valuetext')).toBe('40%');
-  });
-
-  it('is indeterminate when value is null', () => {
-    const wrapper = mountProgress({ modelValue: null });
-    expect(wrapper.attributes('data-state')).toBe('indeterminate');
-    expect(wrapper.attributes('aria-valuenow')).toBeUndefined();
-  });
-
-  it('is complete when value reaches max', () => {
-    const wrapper = mountProgress({ modelValue: 100 });
-    expect(wrapper.attributes('data-state')).toBe('complete');
-  });
-
-  it('custom max', () => {
-    const wrapper = mountProgress({ modelValue: 5, max: 10 });
-    expect(wrapper.attributes('aria-valuemax')).toBe('10');
-    expect(wrapper.attributes('aria-valuetext')).toBe('50%');
-  });
-
-  it('indicator receives matching data-state', () => {
-    const wrapper = mountProgress({ modelValue: 70 });
-    const ind = wrapper.find('.ind');
-    expect(ind.attributes('data-state')).toBe('loading');
-    expect(ind.attributes('data-value')).toBe('70');
-  });
-
-  it('getValueLabel override', () => {
-    const wrapper = mountProgress({ modelValue: 3, max: 10, getValueLabel: (v: number, m: number) => `${v} of ${m}` });
-    expect(wrapper.attributes('aria-valuetext')).toBe('3 of 10');
-  });
-});
diff --git a/vue/primitives/src/progress/context.ts b/vue/primitives/src/progress/context.ts
deleted file mode 100644
index 171e28e..0000000
--- a/vue/primitives/src/progress/context.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import type { Ref } from 'vue';
-import { useContextFactory } from '@robonen/vue';
-
-export type ProgressState = 'indeterminate' | 'loading' | 'complete';
-
-export interface ProgressContext {
-  value: Ref<number | null>;
-  max: Ref<number>;
-  state: Ref<ProgressState>;
-}
-
-const ctx = useContextFactory<ProgressContext>('ProgressContext');
-
-export const provideProgressContext = ctx.provide;
-export const useProgressContext = ctx.inject;
diff --git a/vue/primitives/src/radio-group/RadioGroupIndicator.vue b/vue/primitives/src/radio-group/RadioGroupIndicator.vue
deleted file mode 100644
index c912e4b..0000000
--- a/vue/primitives/src/radio-group/RadioGroupIndicator.vue
+++ /dev/null
@@ -1,35 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-/**
- * Renders its content only when the parent `RadioGroupItem` is selected,
- * mirroring that state via `data-state`. Place the filled dot or check mark
- * inside it; use `forceMount` to keep it mounted for CSS exit animations.
- */
-export interface RadioGroupIndicatorProps extends PrimitiveProps {
-  forceMount?: boolean;
-
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { useForwardExpose } from '@robonen/vue';
-import { useRadioGroupItemContext } from './context';
-
-const { as = 'span', forceMount = false } = defineProps<RadioGroupIndicatorProps>();
-const { forwardRef } = useForwardExpose();
-const item = useRadioGroupItemContext();
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    v-if="forceMount || item.checked.value"
-    :data-state="item.checked.value ? 'checked' : 'unchecked'"
-    :data-disabled="item.disabled.value ? '' : undefined"
-    style="pointer-events: none;"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/radio-group/RadioGroupItem.vue b/vue/primitives/src/radio-group/RadioGroupItem.vue
deleted file mode 100644
index b2c7cf1..0000000
--- a/vue/primitives/src/radio-group/RadioGroupItem.vue
+++ /dev/null
@@ -1,82 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-/**
- * A single selectable option within a `RadioGroupRoot`, rendered as a native
- * `<button role="radio">`. Clicking or pressing Space selects its `value`;
- * it reflects selection via `data-state` and participates in the group's
- * roving tab order. Provides context to a nested `RadioGroupIndicator`.
- */
-export interface RadioGroupItemProps extends PrimitiveProps {
-  value: string;
-  disabled?: boolean;
-  required?: boolean;
-
-}
-</script>
-
-<script setup lang="ts">
-import { computed } from 'vue';
-import { Primitive } from '../primitive';
-import { useCollectionInjector } from '../collection';
-import { useForwardExpose } from '@robonen/vue';
-import { provideRadioGroupItemContext, useRadioGroupContext } from './context';
-
-const { value, disabled = false, as = 'button' } = defineProps<RadioGroupItemProps>();
-
-const ctx = useRadioGroupContext();
-const { CollectionItem } = useCollectionInjector();
-const { forwardRef, currentElement } = useForwardExpose();
-
-const isChecked = computed(() => ctx.value.value === value);
-const isDisabled = computed(() => ctx.disabled.value || disabled);
-const dataState = computed(() => isChecked.value ? 'checked' : 'unchecked');
-
-provideRadioGroupItemContext({
-  value,
-  checked: isChecked,
-  disabled: isDisabled,
-});
-
-// Only one item should be in the tab order:
-// - the checked one, or
-// - the first enabled one if nothing is checked.
-const isTabStop = computed(() => {
-  if (isDisabled.value) return false;
-  if (ctx.value.value !== undefined) return isChecked.value;
-  const firstEnabled = ctx.items.value.find(x => !x.hasAttribute('data-disabled'));
-  return currentElement.value ? firstEnabled === currentElement.value : false;
-});
-
-function onClick(): void {
-  if (isDisabled.value) return;
-  ctx.setValue(value);
-  currentElement.value?.focus();
-}
-function onKeyDown(event: KeyboardEvent): void {
-  if (!currentElement.value) return;
-  ctx.onItemKeyDown(event, currentElement.value);
-}
-</script>
-
-<template>
-  <CollectionItem>
-    <Primitive
-      :as="as"
-      :ref="forwardRef"
-      :type="as === 'button' ? 'button' : undefined"
-      role="radio"
-      :aria-checked="isChecked"
-      :aria-required="required || undefined"
-      :aria-disabled="isDisabled || undefined"
-      :data-state="dataState"
-      :data-disabled="isDisabled ? '' : undefined"
-      :data-value="value"
-      :tabindex="isTabStop ? 0 : -1"
-      :disabled="isDisabled || undefined"
-      @click="onClick"
-      @keydown="onKeyDown"
-    >
-      <slot :checked="isChecked" />
-    </Primitive>
-  </CollectionItem>
-</template>
diff --git a/vue/primitives/src/radio-group/RadioGroupRoot.vue b/vue/primitives/src/radio-group/RadioGroupRoot.vue
deleted file mode 100644
index e1c6e6d..0000000
--- a/vue/primitives/src/radio-group/RadioGroupRoot.vue
+++ /dev/null
@@ -1,146 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { RovingDirection } from '../utils/roving-focus';
-
-/**
- * A set of mutually exclusive options where only one may be selected at a time,
- * built on `role="radiogroup"` with full keyboard roving focus (arrow keys move
- * and select, Space selects, Home/End jump to ends). The container and state
- * owner: it tracks the selected value (controlled via `v-model` or uncontrolled
- * via `defaultValue`), provides context to `RadioGroupItem`, and renders a hidden
- * form input when `name` is set. Reach for it whenever a user must pick exactly
- * one choice from a small, visible list.
- */
-export interface RadioGroupRootProps extends PrimitiveProps {
-  defaultValue?: string;
-  disabled?: boolean;
-  required?: boolean;
-  name?: string;
-  orientation?: 'horizontal' | 'vertical';
-  dir?: RovingDirection;
-  loop?: boolean;
-
-}
-
-export interface RadioGroupRootEmits {
-  valueChange: [value: string];
-}
-</script>
-
-<script setup lang="ts">
-import { computed, ref, toRef, watch } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { useCollectionProvider } from '../collection';
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { provideRadioGroupContext } from './context';
-
-const {
-  disabled = false,
-  required = false,
-  orientation = 'vertical',
-  dir = 'ltr',
-  loop = true,
-  defaultValue,
-  name,
-  as = 'div',
-} = defineProps<RadioGroupRootProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const emit = defineEmits<RadioGroupRootEmits>();
-const model = defineModel<string | undefined>({ default: undefined });
-
-const localValue = ref<string | undefined>(model.value ?? defaultValue);
-
-watch(model, (v) => {
-  if (v === undefined) return;
-  if (v !== localValue.value) localValue.value = v;
-});
-
-function setValue(v: string): void {
-  if (disabled) return;
-  localValue.value = v;
-  model.value = v;
-  emit('valueChange', v);
-}
-
-// DOM-order items via Collection primitive — survives `v-for` reorders.
-const { getItems, CollectionSlot } = useCollectionProvider();
-const items = computed(() => getItems(true).map(i => i.ref));
-
-function focusIndex(i: number): void {
-  const el = items.value[i];
-  if (!el || el.hasAttribute('data-disabled')) {
-    // Skip disabled items when looping forward.
-    return;
-  }
-  el.focus();
-  const v = el.getAttribute('data-value');
-  if (v !== null) setValue(v);
-}
-
-function onItemKeyDown(event: KeyboardEvent, el: HTMLElement): void {
-  // Space selects without moving focus.
-  if (event.key === ' ') {
-    event.preventDefault();
-    const v = el.getAttribute('data-value');
-    if (v !== null) setValue(v);
-    return;
-  }
-  const action = rovingKeyToAction(event, { orientation, dir, loop });
-  if (!action) return;
-  event.preventDefault();
-  const enabled = items.value.filter(x => !x.hasAttribute('data-disabled'));
-  if (enabled.length === 0) return;
-  const current = enabled.indexOf(el);
-  if (action.absolute === 'home') return focusIndex(items.value.indexOf(enabled[0]!));
-  if (action.absolute === 'end') return focusIndex(items.value.indexOf(enabled[enabled.length - 1]!));
-  const nextIdx = resolveNextIndex(current === -1 ? 0 : current, action.delta, enabled.length, loop);
-  focusIndex(items.value.indexOf(enabled[nextIdx]!));
-}
-
-provideRadioGroupContext({
-  value: localValue,
-  setValue,
-  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
-  orientation: toRef(() => orientation),
-  direction: toRef(() => dir),
-  loop: toRef(() => loop),
-  disabled: toRef(() => disabled),
-  required: toRef(() => required),
-  name: toRef(() => name),
-  items,
-  onItemKeyDown,
-});
-</script>
-
-<template>
-  <CollectionSlot>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      role="radiogroup"
-      :aria-orientation="orientation"
-      :aria-required="required || undefined"
-      :aria-disabled="disabled || undefined"
-      :dir="dir"
-      :data-orientation="orientation"
-      :data-disabled="disabled ? '' : undefined"
-    >
-      <slot :value="localValue" />
-      <input
-        v-if="name"
-        type="radio"
-        tabindex="-1"
-        aria-hidden="true"
-        :name="name"
-        :value="localValue ?? ''"
-        :checked="localValue !== undefined"
-        :required="required"
-        :disabled="disabled"
-        style="position: absolute; pointer-events: none; opacity: 0; margin: 0; transform: translateX(-100%);"
-      >
-    </Primitive>
-  </CollectionSlot>
-</template>
diff --git a/vue/primitives/src/radio-group/context.ts b/vue/primitives/src/radio-group/context.ts
deleted file mode 100644
index f7c0874..0000000
--- a/vue/primitives/src/radio-group/context.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import type { ComputedRef, Ref } from 'vue';
-import type { RovingDirection, RovingOrientation } from '../utils/roving-focus';
-import { useContextFactory } from '@robonen/vue';
-
-export interface RadioGroupContext {
-  value: Ref<string | undefined>;
-  setValue: (v: string) => void;
-  orientation: Ref<RovingOrientation>;
-  direction: Ref<RovingDirection>;
-  loop: Ref<boolean>;
-  disabled: Ref<boolean>;
-  required: Ref<boolean>;
-  name: Ref<string | undefined>;
-  /** DOM-ordered items, sourced from the internal Collection. */
-  items: ComputedRef<HTMLElement[]>;
-  onItemKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
-}
-
-const rootCtx = useContextFactory<RadioGroupContext>('RadioGroupContext');
-
-export const provideRadioGroupContext = rootCtx.provide;
-export const useRadioGroupContext = rootCtx.inject;
-
-export interface RadioGroupItemContext {
-  value: string;
-  checked: ComputedRef<boolean>;
-  disabled: ComputedRef<boolean>;
-}
-
-const itemCtx = useContextFactory<RadioGroupItemContext>('RadioGroupItemContext');
-
-export const provideRadioGroupItemContext = itemCtx.provide;
-export const useRadioGroupItemContext = itemCtx.inject;
diff --git a/vue/primitives/src/radio-group/index.ts b/vue/primitives/src/radio-group/index.ts
deleted file mode 100644
index 25c039c..0000000
--- a/vue/primitives/src/radio-group/index.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-export { default as RadioGroupIndicator } from './RadioGroupIndicator.vue';
-export { default as RadioGroupItem } from './RadioGroupItem.vue';
-export { default as RadioGroupRoot } from './RadioGroupRoot.vue';
-export type { RadioGroupIndicatorProps } from './RadioGroupIndicator.vue';
-export type { RadioGroupItemProps } from './RadioGroupItem.vue';
-export type { RadioGroupRootEmits, RadioGroupRootProps } from './RadioGroupRoot.vue';
diff --git a/vue/primitives/src/select/SelectContent.vue b/vue/primitives/src/select/SelectContent.vue
deleted file mode 100644
index 26162d9..0000000
--- a/vue/primitives/src/select/SelectContent.vue
+++ /dev/null
@@ -1,33 +0,0 @@
-<script lang="ts">
-import type { SelectContentImplEmits, SelectContentImplProps } from './SelectContentImpl.vue';
-
-/**
- * The floating panel that holds the options. Mounts only while the select is
- * open (it gates `SelectContentImpl` behind `Presence`), so it can animate in
- * and out. Usually placed inside a `SelectPortal` and contains a
- * `SelectViewport` of `SelectItem`s.
- */
-export type SelectContentProps = SelectContentImplProps;
-export type SelectContentEmits = SelectContentImplEmits;
-</script>
-
-<script setup lang="ts">
-import { Presence } from '../presence';
-import { useSelectRootContext } from './context';
-import SelectContentImpl from './SelectContentImpl.vue';
-
-const props = defineProps<SelectContentProps>();
-const emit = defineEmits<SelectContentEmits>();
-const rootCtx = useSelectRootContext();
-</script>
-
-<template>
-  <Presence :present="rootCtx.open.value">
-    <SelectContentImpl
-      v-bind="props"
-      @close-auto-focus="emit('closeAutoFocus', $event)"
-      @escape-key-down="emit('escapeKeyDown', $event)"
-      @pointer-down-outside="emit('pointerDownOutside', $event)"
-    />
-  </Presence>
-</template>
diff --git a/vue/primitives/src/select/SelectContentImpl.vue b/vue/primitives/src/select/SelectContentImpl.vue
deleted file mode 100644
index ae686f7..0000000
--- a/vue/primitives/src/select/SelectContentImpl.vue
+++ /dev/null
@@ -1,157 +0,0 @@
-<script lang="ts">
-import type { DismissableLayerEmits } from '../dismissable-layer';
-import type { FocusScopeEmits } from '../focus-scope';
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The mounted body of the content panel: it traps focus, dismisses on outside
- * pointer/escape, locks body scroll, and handles keyboard navigation and
- * type-ahead. Rendered by `SelectContent` once open — prefer using
- * `SelectContent` rather than this part directly.
- */
-export interface SelectContentImplProps extends PrimitiveProps {
-  /** Position mode. @default 'item-aligned' */
-  position?: 'item-aligned' | 'popper';
-  /** Block outside pointer events. @default true */
-  disableOutsidePointerEvents?: boolean;
-}
-
-export interface SelectContentImplEmits {
-  closeAutoFocus: FocusScopeEmits['unmountAutoFocus'];
-  escapeKeyDown: DismissableLayerEmits['escapeKeyDown'];
-  pointerDownOutside: DismissableLayerEmits['pointerDownOutside'];
-}
-</script>
-
-<script setup lang="ts">
-import { ref, shallowRef } from 'vue';
-
-import { useBodyScrollLock, useForwardExpose } from '@robonen/vue';
-import { DismissableLayer } from '../dismissable-layer';
-import { FocusScope } from '../focus-scope';
-import { provideSelectContentContext, useSelectRootContext } from './context';
-import SelectItemAlignedPosition from './SelectItemAlignedPosition.vue';
-import SelectPopperPosition from './SelectPopperPosition.vue';
-
-const {
-  as = 'div',
-  position = 'item-aligned',
-  disableOutsidePointerEvents = true,
-} = defineProps<SelectContentImplProps>();
-
-const emit = defineEmits<SelectContentImplEmits>();
-
-const { forwardRef, currentElement } = useForwardExpose();
-const rootCtx = useSelectRootContext();
-
-useBodyScrollLock();
-
-const isPositioned = ref(false);
-const searchRef = ref('');
-const viewportRef = shallowRef<HTMLElement | undefined>(undefined);
-let searchTimer: ReturnType<typeof setTimeout> | null = null;
-
-function handleTypeahead(key: string) {
-  searchRef.value += key;
-  if (searchTimer) clearTimeout(searchTimer);
-  searchTimer = setTimeout(() => {
-    searchRef.value = '';
-  }, 1000);
-
-  const viewport = viewportRef.value;
-  if (!viewport) return;
-  const items = Array.from(viewport.querySelectorAll<HTMLElement>(
-    '[data-primitives-select-item]:not([data-disabled])',
-  ));
-  const match = items.find(item =>
-    item.textContent?.trim().toLowerCase().startsWith(searchRef.value.toLowerCase()),
-  );
-  match?.focus();
-}
-
-function handleKeyDown(event: KeyboardEvent) {
-  const viewport = viewportRef.value;
-  if (!viewport) return;
-
-  const items = Array.from(viewport.querySelectorAll<HTMLElement>(
-    '[data-primitives-select-item]:not([data-disabled])',
-  ));
-  const currentIdx = items.indexOf(document.activeElement as HTMLElement);
-
-  if (event.key === 'ArrowDown') {
-    event.preventDefault();
-    const next = items[currentIdx + 1] ?? items[0];
-    next?.focus();
-  }
-  else if (event.key === 'ArrowUp') {
-    event.preventDefault();
-    const prev = items[currentIdx - 1] ?? items[items.length - 1];
-    prev?.focus();
-  }
-  else if (event.key === 'Home') {
-    event.preventDefault();
-    items[0]?.focus();
-  }
-  else if (event.key === 'End') {
-    event.preventDefault();
-    items[items.length - 1]?.focus();
-  }
-  else if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
-    handleTypeahead(event.key);
-  }
-}
-
-provideSelectContentContext({
-  viewportRef,
-  onViewportChange: (el) => { viewportRef.value = el; },
-  selectedItemRef: rootCtx.selectedItemRef,
-  selectedItemTextRef: rootCtx.selectedItemTextRef,
-  onItemLeave: () => { currentElement.value?.focus(); },
-  itemRefCallback: rootCtx.itemRefCallback,
-  itemTextRefCallback: rootCtx.itemTextRefCallback,
-  isPositioned,
-  searchRef,
-  position,
-});
-</script>
-
-<template>
-  <FocusScope
-    as="template"
-    :loop="true"
-    :trapped="true"
-    @unmount-auto-focus="emit('closeAutoFocus', $event)"
-  >
-    <DismissableLayer
-      as="template"
-      :disable-outside-pointer-events="disableOutsidePointerEvents"
-      @escape-key-down="emit('escapeKeyDown', $event)"
-      @pointer-down-outside="emit('pointerDownOutside', $event)"
-      @dismiss="rootCtx.onOpenChange(false)"
-    >
-      <SelectItemAlignedPosition
-        v-if="position === 'item-aligned'"
-        :ref="forwardRef"
-        :as="as"
-        :data-state="rootCtx.open.value ? 'open' : 'closed'"
-        :dir="rootCtx.dir.value"
-        @placed="isPositioned = true"
-        @keydown="handleKeyDown"
-      >
-        <slot />
-      </SelectItemAlignedPosition>
-
-      <SelectPopperPosition
-        v-else
-        :ref="forwardRef"
-        :as="as"
-        :data-state="rootCtx.open.value ? 'open' : 'closed'"
-        :dir="rootCtx.dir.value"
-        @placed="isPositioned = true"
-        @keydown="handleKeyDown"
-      >
-        <slot />
-      </SelectPopperPosition>
-    </DismissableLayer>
-  </FocusScope>
-</template>
diff --git a/vue/primitives/src/select/SelectItem.vue b/vue/primitives/src/select/SelectItem.vue
deleted file mode 100644
index c3f2562..0000000
--- a/vue/primitives/src/select/SelectItem.vue
+++ /dev/null
@@ -1,101 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A single selectable option. Renders as a `role="option"`, registers its value
- * and text with the root, becomes the selected value on click/Enter/Space, and
- * exposes `data-state`/`data-disabled` for styling. Holds a `SelectItemText`
- * and, optionally, a `SelectItemIndicator`.
- */
-export interface SelectItemProps extends PrimitiveProps {
-  /** The option value. */
-  value: string;
-  /** Disable this item. */
-  disabled?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, shallowRef } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
-import { Primitive } from '../primitive';
-import { provideSelectItemContext, useSelectContentContext, useSelectRootContext } from './context';
-
-const { as = 'div', value, disabled = false } = defineProps<SelectItemProps>();
-
-const { forwardRef, currentElement } = useForwardExpose();
-const rootCtx = useSelectRootContext();
-const contentCtx = useSelectContentContext();
-
-const textId = useId(undefined, 'select-item-text');
-const isSelected = computed(() => rootCtx.value.value === value);
-const isDisabled = computed(() => rootCtx.disabled.value || disabled);
-
-const itemTextElement = shallowRef<HTMLElement | undefined>(undefined);
-
-function onItemTextChange(el: HTMLElement | undefined) {
-  itemTextElement.value = el;
-  contentCtx.itemTextRefCallback(el, value);
-  if (el) rootCtx.onOptionAdd(value, el.textContent?.trim() ?? '');
-}
-
-onMounted(() => {
-  contentCtx.itemRefCallback(currentElement.value, value, isDisabled.value);
-});
-
-onBeforeUnmount(() => {
-  rootCtx.onOptionRemove(value);
-  contentCtx.itemRefCallback(undefined, value, isDisabled.value);
-});
-
-function handleSelect() {
-  if (isDisabled.value) return;
-  rootCtx.onValueChange(value);
-}
-
-function handlePointerEnter() {
-  if (isDisabled.value) return;
-  currentElement.value?.focus();
-}
-
-function handlePointerLeave() {
-  contentCtx.onItemLeave();
-}
-
-function handleKeyDown(event: KeyboardEvent) {
-  if (event.key === 'Enter' || event.key === ' ') {
-    event.preventDefault();
-    handleSelect();
-  }
-}
-
-provideSelectItemContext({
-  value,
-  isSelected,
-  isDisabled,
-  textId,
-  onItemTextChange,
-});
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    role="option"
-    :aria-selected="isSelected"
-    :aria-disabled="isDisabled || undefined"
-    :data-state="isSelected ? 'checked' : 'unchecked'"
-    :data-disabled="isDisabled ? '' : undefined"
-    :tabindex="isDisabled ? undefined : -1"
-    data-primitives-select-item
-    @click="handleSelect"
-    @pointerenter="handlePointerEnter"
-    @pointerleave="handlePointerLeave"
-    @keydown="handleKeyDown"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/select/SelectItemAlignedPosition.vue b/vue/primitives/src/select/SelectItemAlignedPosition.vue
deleted file mode 100644
index bf85967..0000000
--- a/vue/primitives/src/select/SelectItemAlignedPosition.vue
+++ /dev/null
@@ -1,64 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The `'item-aligned'` positioning strategy for the content panel: pins the
- * panel directly below the trigger, matching its left edge and minimum width.
- * Chosen internally by `SelectContentImpl` when `position` is `'item-aligned'`.
- */
-export interface SelectItemAlignedPositionProps extends PrimitiveProps {
-  /** Reading direction, forwarded from the root. */
-  dir?: string;
-}
-
-export interface SelectItemAlignedPositionEmits {
-  placed: [];
-}
-</script>
-
-<script setup lang="ts">
-import { onMounted } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { useSelectContentContext, useSelectRootContext } from './context';
-
-const { as = 'div' } = defineProps<SelectItemAlignedPositionProps>();
-const emit = defineEmits<SelectItemAlignedPositionEmits>();
-
-const { forwardRef, currentElement } = useForwardExpose();
-const rootCtx = useSelectRootContext();
-const contentCtx = useSelectContentContext();
-
-onMounted(() => {
-  const trigger = rootCtx.triggerElement.value;
-  const content = currentElement.value;
-  if (!trigger || !content) {
-    emit('placed');
-    return;
-  }
-
-  const triggerRect = trigger.getBoundingClientRect();
-
-  Object.assign(content.style, {
-    position: 'fixed',
-    top: `${triggerRect.bottom}px`,
-    left: `${triggerRect.left}px`,
-    minWidth: `${triggerRect.width}px`,
-    zIndex: '50',
-  });
-
-  contentCtx.isPositioned.value = true;
-  emit('placed');
-});
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    data-primitives-select-content
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/select/SelectRoot.vue b/vue/primitives/src/select/SelectRoot.vue
deleted file mode 100644
index 0e9b118..0000000
--- a/vue/primitives/src/select/SelectRoot.vue
+++ /dev/null
@@ -1,170 +0,0 @@
-<script lang="ts">
-import type { Direction } from '../config-provider';
-
-/**
- * A custom, fully stylable replacement for the native `<select>` element: a
- * trigger button that opens a floating listbox of options, with full keyboard
- * support (arrow keys, Home/End, type-ahead search), focus trapping, and an
- * optional hidden `<input>` for native form submission.
- *
- * Use it when you need a single-choice dropdown whose menu and options must be
- * styled beyond what a native control allows. The root owns the selected value
- * and open state and provides context to every part; bind `v-model` for the
- * value and `v-model:open` (or listen to `update:modelValue` / `update:open`)
- * to control or observe it. Compose it from a `SelectTrigger` (with
- * `SelectValue`/`SelectIcon`) plus a portalled `SelectContent` of
- * `SelectItem`s.
- */
-export interface SelectRootProps {
-  /** Reading direction. Falls back to ConfigProvider. */
-  dir?: Direction;
-  /** Disable the whole select. */
-  disabled?: boolean;
-  /** Mark field as required for native form validation. */
-  required?: boolean;
-  /** Native input name for form submission. */
-  name?: string;
-  /** Uncontrolled default value. */
-  defaultValue?: string;
-  /** Uncontrolled default open state. */
-  defaultOpen?: boolean;
-  /** Native autocomplete attribute forwarded to the hidden input. */
-  autocomplete?: string;
-}
-
-export interface SelectRootEmits {
-  'update:modelValue': [value: string | undefined];
-  'update:open': [open: boolean];
-}
-</script>
-
-<script setup lang="ts">
-import { ref, shallowRef, toRef, watch } from 'vue';
-
-import { useId } from '../config-provider';
-import { PopperRoot } from '../popper';
-import { provideSelectRootContext } from './context';
-import type { SelectValue } from './context';
-
-defineOptions({ inheritAttrs: false });
-
-const {
-  dir,
-  disabled = false,
-  required = false,
-  name,
-  defaultValue,
-  defaultOpen = false,
-  autocomplete,
-} = defineProps<SelectRootProps>();
-
-const localOpen = ref<boolean>(defaultOpen);
-const open = defineModel<boolean>('open', {
-  default: undefined,
-  get: v => v ?? localOpen.value,
-  set: (v) => {
-    localOpen.value = v;
-    return v;
-  },
-});
-
-const localValue = ref<SelectValue | undefined>(defaultValue);
-const value = defineModel<SelectValue | undefined>('modelValue', {
-  default: undefined,
-  get: v => v ?? localValue.value,
-  set: (v) => {
-    localValue.value = v;
-    return v;
-  },
-});
-
-const contentId = useId(undefined, 'select-content');
-const dirRef = toRef(() => dir);
-const disabledRef = toRef(() => disabled);
-const requiredRef = toRef(() => required);
-const nameRef = toRef(() => name);
-
-const triggerElement = shallowRef<HTMLElement | undefined>(undefined);
-const selectedItemRef = shallowRef<HTMLElement | undefined>(undefined);
-const selectedItemTextRef = shallowRef<HTMLElement | undefined>(undefined);
-const displayValue = ref<string | undefined>(undefined);
-const optionsSet = shallowRef(new Map<SelectValue, string>());
-
-function onOptionAdd(v: SelectValue, textContent: string) {
-  optionsSet.value = new Map(optionsSet.value).set(v, textContent);
-}
-
-function onOptionRemove(v: SelectValue) {
-  const m = new Map(optionsSet.value);
-  m.delete(v);
-  optionsSet.value = m;
-}
-
-// Update displayValue whenever optionsSet or value changes.
-// When content is open, optionsSet contains the text; we persist the last
-// known text so SelectValue keeps showing after content closes.
-watch([optionsSet, value], () => {
-  if (value.value !== undefined) {
-    const text = optionsSet.value.get(value.value);
-    if (text !== undefined) displayValue.value = text;
-  }
-}, { immediate: true });
-
-function handleValueChange(newValue: SelectValue) {
-  value.value = newValue;
-  displayValue.value = optionsSet.value.get(newValue);
-  open.value = false;
-}
-
-function itemRefCallback(el: HTMLElement | undefined, itemValue: SelectValue, isDisabled: boolean) {
-  if (itemValue === value.value && !isDisabled) {
-    selectedItemRef.value = el;
-  }
-}
-
-function itemTextRefCallback(el: HTMLElement | undefined, itemValue: SelectValue) {
-  if (itemValue === value.value) {
-    selectedItemTextRef.value = el;
-  }
-}
-
-provideSelectRootContext({
-  value,
-  onValueChange: handleValueChange,
-  open,
-  onOpenChange: (v) => { open.value = v; },
-  dir: dirRef,
-  disabled: disabledRef,
-  required: requiredRef,
-  name: nameRef,
-  triggerElement,
-  onTriggerChange: (el) => { triggerElement.value = el; },
-  contentId,
-  displayValue,
-  optionsSet,
-  onOptionAdd,
-  onOptionRemove,
-  itemRefCallback,
-  itemTextRefCallback,
-  selectedItemRef,
-  selectedItemTextRef,
-});
-</script>
-
-<template>
-  <PopperRoot>
-    <slot />
-    <input
-      v-if="name"
-      type="hidden"
-      :name="name"
-      :value="value ?? ''"
-      :required="required"
-      :disabled="disabled"
-      :autocomplete="autocomplete"
-      aria-hidden="true"
-      style="display: none"
-      tabindex="-1"
-    />
-  </PopperRoot>
-</template>
diff --git a/vue/primitives/src/select/SelectScrollUpButton.vue b/vue/primitives/src/select/SelectScrollUpButton.vue
deleted file mode 100644
index 2871285..0000000
--- a/vue/primitives/src/select/SelectScrollUpButton.vue
+++ /dev/null
@@ -1,58 +0,0 @@
-<script lang="ts">
-import type { SelectScrollButtonImplProps } from './SelectScrollButtonImpl.vue';
-
-/**
- * An auto-scroll affordance shown at the top of the viewport when there is
- * content scrolled out of view above. Scrolls the viewport up while hovered and
- * hides itself when already at the top.
- */
-export type SelectScrollUpButtonProps = Omit<SelectScrollButtonImplProps, 'direction'>;
-</script>
-
-<script setup lang="ts">
-import { onMounted, ref, watchEffect } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { useSelectContentContext } from './context';
-import SelectScrollButtonImpl from './SelectScrollButtonImpl.vue';
-
-const props = defineProps<SelectScrollUpButtonProps>();
-
-const { forwardRef } = useForwardExpose();
-const contentCtx = useSelectContentContext();
-
-const canScrollUp = ref(false);
-let cleanupFn: (() => void) | null = null;
-
-watchEffect(() => {
-  if (cleanupFn) {
-    cleanupFn();
-    cleanupFn = null;
-  }
-  const viewport = contentCtx.viewportRef.value;
-  if (!viewport) return;
-
-  const update = () => {
-    canScrollUp.value = viewport.scrollTop > 0;
-  };
-  viewport.addEventListener('scroll', update, { passive: true });
-  update();
-  cleanupFn = () => viewport.removeEventListener('scroll', update);
-});
-
-onMounted(() => {
-  const viewport = contentCtx.viewportRef.value;
-  if (viewport) canScrollUp.value = viewport.scrollTop > 0;
-});
-</script>
-
-<template>
-  <SelectScrollButtonImpl
-    v-if="canScrollUp"
-    v-bind="props"
-    :ref="forwardRef"
-    :direction="-1"
-  >
-    <slot />
-  </SelectScrollButtonImpl>
-</template>
diff --git a/vue/primitives/src/select/SelectTrigger.vue b/vue/primitives/src/select/SelectTrigger.vue
deleted file mode 100644
index aa265af..0000000
--- a/vue/primitives/src/select/SelectTrigger.vue
+++ /dev/null
@@ -1,71 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The button that toggles the select open and anchors the floating content.
- * Renders as a `role="combobox"` control wired with the appropriate ARIA and
- * `data-state`/`data-placeholder` attributes; place a `SelectValue` and
- * `SelectIcon` inside it.
- */
-export interface SelectTriggerProps extends PrimitiveProps {
-  /** Disable this trigger independently from the root. */
-  disabled?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { computed, onBeforeUnmount, watchEffect } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { PopperAnchor } from '../popper';
-import { Primitive } from '../primitive';
-import { useSelectRootContext } from './context';
-import { getOpenState } from './utils';
-
-const { as = 'button', disabled = false } = defineProps<SelectTriggerProps>();
-
-const { forwardRef, currentElement } = useForwardExpose();
-const rootCtx = useSelectRootContext();
-
-const isDisabled = computed(() => rootCtx.disabled.value || disabled);
-
-watchEffect(() => rootCtx.onTriggerChange(currentElement.value));
-onBeforeUnmount(() => rootCtx.onTriggerChange(undefined));
-
-function handlePointerDown(event: PointerEvent) {
-  if (isDisabled.value) return;
-  if (event.button !== 0 || event.ctrlKey) return;
-  event.preventDefault();
-  rootCtx.onOpenChange(true);
-}
-
-function handleKeyDown(event: KeyboardEvent) {
-  if (isDisabled.value) return;
-  if (['Enter', ' ', 'ArrowUp', 'ArrowDown'].includes(event.key)) {
-    event.preventDefault();
-    rootCtx.onOpenChange(true);
-  }
-}
-</script>
-
-<template>
-  <PopperAnchor>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      role="combobox"
-      type="button"
-      :aria-controls="rootCtx.contentId.value"
-      :aria-expanded="rootCtx.open.value"
-      :aria-required="rootCtx.required.value || undefined"
-      :data-state="getOpenState(rootCtx.open.value)"
-      :disabled="isDisabled || undefined"
-      :data-disabled="isDisabled ? '' : undefined"
-      :data-placeholder="!rootCtx.value.value ? '' : undefined"
-      @pointerdown="handlePointerDown"
-      @keydown="handleKeyDown"
-    >
-      <slot />
-    </Primitive>
-  </PopperAnchor>
-</template>
diff --git a/vue/primitives/src/select/SelectValue.vue b/vue/primitives/src/select/SelectValue.vue
deleted file mode 100644
index b397bd7..0000000
--- a/vue/primitives/src/select/SelectValue.vue
+++ /dev/null
@@ -1,40 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * Displays the text of the currently selected option inside the trigger, or the
- * `placeholder` when nothing is selected. Renders into a non-interactive span so
- * pointer events fall through to the trigger.
- */
-export interface SelectValueProps extends PrimitiveProps {
-  /** Text shown when no option is selected. */
-  placeholder?: string;
-}
-</script>
-
-<script setup lang="ts">
-import { computed } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { useSelectRootContext } from './context';
-import { shouldShowPlaceholder } from './utils';
-
-const { as = 'span', placeholder } = defineProps<SelectValueProps>();
-
-const { forwardRef } = useForwardExpose();
-const rootCtx = useSelectRootContext();
-
-const showPlaceholder = computed(() => shouldShowPlaceholder(rootCtx.value.value));
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    style="pointer-events: none"
-  >
-    <template v-if="showPlaceholder">{{ placeholder }}</template>
-    <template v-else>{{ rootCtx.displayValue.value }}</template>
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/select/SelectViewport.vue b/vue/primitives/src/select/SelectViewport.vue
deleted file mode 100644
index 2616f74..0000000
--- a/vue/primitives/src/select/SelectViewport.vue
+++ /dev/null
@@ -1,37 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The scrollable `role="listbox"` region inside the content that wraps the
- * options. Caps its height to the available space and scrolls when the list
- * overflows; pair it with the scroll buttons for an item-aligned menu.
- */
-export interface SelectViewportProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { watchPostEffect } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { useSelectContentContext } from './context';
-
-const { as = 'div' } = defineProps<SelectViewportProps>();
-
-const { forwardRef, currentElement } = useForwardExpose();
-const contentCtx = useSelectContentContext();
-
-watchPostEffect(() => contentCtx.onViewportChange(currentElement.value));
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    role="listbox"
-    data-primitives-select-viewport
-    style="overflow: auto; max-height: var(--primitives-select-content-available-height, 300px)"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/select/utils.ts b/vue/primitives/src/select/utils.ts
deleted file mode 100644
index 15fb63d..0000000
--- a/vue/primitives/src/select/utils.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-export function getOpenState(open: boolean): 'open' | 'closed' {
-  return open ? 'open' : 'closed';
-}
-
-export function shouldShowPlaceholder(value: string | undefined): boolean {
-  return value === undefined || value === '';
-}
diff --git a/vue/primitives/src/combobox/ComboboxAnchor.vue b/vue/primitives/src/selection/combobox/ComboboxAnchor.vue
similarity index 58%
rename from vue/primitives/src/combobox/ComboboxAnchor.vue
rename to vue/primitives/src/selection/combobox/ComboboxAnchor.vue
index 5ba587f..fe0aac4 100644
--- a/vue/primitives/src/combobox/ComboboxAnchor.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxAnchor.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperAnchorProps } from '../popper';
+import type { PopperAnchorProps } from '../../overlays/popper';
 
 /**
  * The element the popup is positioned against, typically wrapping the Input and Trigger.
@@ -12,8 +12,7 @@ export interface ComboboxAnchorProps extends PopperAnchorProps {}
 import { onBeforeUnmount, watchPostEffect } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { PopperAnchor } from '../popper';
-import { Primitive } from '../primitive';
+import { PopperAnchor } from '../../overlays/popper';
 import { useComboboxRootContext } from './context';
 
 const props = defineProps<ComboboxAnchorProps>();
@@ -26,12 +25,15 @@ onBeforeUnmount(() => rootCtx.onParentChange(undefined));
 </script>
 
 <template>
-  <PopperAnchor :reference="props.reference">
-    <Primitive
-      :ref="forwardRef"
-      :as="props.as ?? 'div'"
-    >
-      <slot />
-    </Primitive>
+  <!-- PopperAnchor IS the single anchor element: the consumer's class (e.g. a
+       flex row of Input + Trigger) and the slotted children must live on the
+       SAME element. A nested Primitive split them — the class landed here while
+       the children sat in an unstyled inner div, stacking them vertically. -->
+  <PopperAnchor
+    :ref="forwardRef"
+    :as="props.as ?? 'div'"
+    :reference="props.reference"
+  >
+    <slot />
   </PopperAnchor>
 </template>
diff --git a/vue/primitives/src/combobox/ComboboxArrow.vue b/vue/primitives/src/selection/combobox/ComboboxArrow.vue
similarity index 84%
rename from vue/primitives/src/combobox/ComboboxArrow.vue
rename to vue/primitives/src/selection/combobox/ComboboxArrow.vue
index 770f601..f98b523 100644
--- a/vue/primitives/src/combobox/ComboboxArrow.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxArrow.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperArrowProps } from '../popper';
+import type { PopperArrowProps } from '../../overlays/popper';
 
 /**
  * An optional arrow that visually points from the popup back to the anchor. Renders only
@@ -11,7 +11,7 @@ export type ComboboxArrowProps = PopperArrowProps;
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { PopperArrow } from '../popper';
+import { PopperArrow } from '../../overlays/popper';
 import { useComboboxRootContext } from './context';
 
 const props = defineProps<ComboboxArrowProps>();
diff --git a/vue/primitives/src/combobox/ComboboxCancel.vue b/vue/primitives/src/selection/combobox/ComboboxCancel.vue
similarity index 83%
rename from vue/primitives/src/combobox/ComboboxCancel.vue
rename to vue/primitives/src/selection/combobox/ComboboxCancel.vue
index f03cfcc..416f164 100644
--- a/vue/primitives/src/combobox/ComboboxCancel.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxCancel.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button that clears the current search term and refocuses the input. Typically shown
@@ -11,7 +11,7 @@ export interface ComboboxCancelProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useComboboxRootContext } from './context';
 
 const { as = 'button' } = defineProps<ComboboxCancelProps>();
@@ -27,6 +27,7 @@ function handleClick() {
     input.focus();
   }
   rootCtx.onUserInputtedChange(false);
+  if (rootCtx.resetModelValueOnClear.value) rootCtx.clearModelValue();
 }
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxContent.vue b/vue/primitives/src/selection/combobox/ComboboxContent.vue
similarity index 66%
rename from vue/primitives/src/combobox/ComboboxContent.vue
rename to vue/primitives/src/selection/combobox/ComboboxContent.vue
index 2e7660a..d6bbe59 100644
--- a/vue/primitives/src/combobox/ComboboxContent.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxContent.vue
@@ -5,28 +5,32 @@ import type { ComboboxContentImplEmits, ComboboxContentImplProps } from './Combo
  * The popup listbox that holds the options. Mounts only while open (via Presence) and
  * positions itself relative to the anchor. Place the Viewport, Items, and Empty inside it.
  */
-export type ComboboxContentProps = ComboboxContentImplProps;
+export interface ComboboxContentProps extends ComboboxContentImplProps {
+  /** Keep the content mounted even while closed (for external animation libraries). @default false */
+  forceMount?: boolean;
+}
 export type ComboboxContentEmits = ComboboxContentImplEmits;
 </script>
 
 <script setup lang="ts">
-import { Presence } from '../presence';
+import { Presence } from '../../utilities/presence';
 import ComboboxContentImpl from './ComboboxContentImpl.vue';
 import { useComboboxRootContext } from './context';
 
-const props = defineProps<ComboboxContentProps>();
+const { forceMount = false, ...contentProps } = defineProps<ComboboxContentProps>();
 const emit = defineEmits<ComboboxContentEmits>();
 const rootCtx = useComboboxRootContext();
 </script>
 
 <template>
-  <Presence :present="rootCtx.open.value">
+  <Presence :present="rootCtx.open.value" :force-mount="forceMount">
     <ComboboxContentImpl
-      v-bind="props"
+      v-bind="contentProps"
       @close-auto-focus="emit('closeAutoFocus', $event)"
       @escape-key-down="emit('escapeKeyDown', $event)"
       @pointer-down-outside="emit('pointerDownOutside', $event)"
       @focus-outside="emit('focusOutside', $event)"
+      @interact-outside="emit('interactOutside', $event)"
     >
       <slot />
     </ComboboxContentImpl>
diff --git a/vue/primitives/src/combobox/ComboboxContentImpl.vue b/vue/primitives/src/selection/combobox/ComboboxContentImpl.vue
similarity index 68%
rename from vue/primitives/src/combobox/ComboboxContentImpl.vue
rename to vue/primitives/src/selection/combobox/ComboboxContentImpl.vue
index b9991ae..6cd6a6a 100644
--- a/vue/primitives/src/combobox/ComboboxContentImpl.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxContentImpl.vue
@@ -1,8 +1,8 @@
 <script lang="ts">
-import type { DismissableLayerEmits } from '../dismissable-layer';
-import type { FocusScopeEmits } from '../focus-scope';
-import type { PopperContentProps } from '../popper';
-import type { PrimitiveProps } from '../primitive';
+import type { DismissableLayerEmits } from '../../utilities/dismissable-layer';
+import type { FocusScopeEmits } from '../../utilities/focus-scope';
+import type { PopperContentProps } from '../../overlays/popper';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Internal implementation of the content popup: wires up focus scoping, dismiss-on-outside,
@@ -13,6 +13,10 @@ export interface ComboboxContentImplProps extends PrimitiveProps, /* @vue-ignore
   position?: 'inline' | 'popper';
   /** Block outside pointer events. @default false */
   disableOutsidePointerEvents?: boolean;
+  /** Lock body scroll while the content is open (reuses the shared body-scroll-lock). @default false */
+  bodyLock?: boolean;
+  /** Hide the content (`display: none`) when no items match the filter. @default false */
+  hideWhenEmpty?: boolean;
 }
 
 export interface ComboboxContentImplEmits {
@@ -20,19 +24,20 @@ export interface ComboboxContentImplEmits {
   escapeKeyDown: DismissableLayerEmits['escapeKeyDown'];
   pointerDownOutside: DismissableLayerEmits['pointerDownOutside'];
   focusOutside: FocusScopeEmits['unmountAutoFocus'];
+  interactOutside: DismissableLayerEmits['interactOutside'];
 }
 </script>
 
 <script setup lang="ts">
-import { onBeforeUnmount, shallowRef, toRef, watchPostEffect } from 'vue';
+import { computed, onBeforeUnmount, shallowRef, toRef, watch, watchPostEffect } from 'vue';
 
-import { useForwardExpose } from '@robonen/vue';
-import { DismissableLayer } from '../dismissable-layer';
-import { FocusScope } from '../focus-scope';
-import { PopperContent } from '../popper';
-import { Primitive } from '../primitive';
-import { VisuallyHidden } from '../visually-hidden';
-import { useHideOthers } from '../utils/useHideOthers';
+import { useBodyScrollLock, useForwardExpose } from '@robonen/vue';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
+import { FocusScope } from '../../utilities/focus-scope';
+import { PopperContent } from '../../overlays/popper';
+import { Primitive } from '../../internal/primitive';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+import { useHideOthers } from '../../internal/utils/useHideOthers';
 import { provideComboboxContentContext, useComboboxRootContext } from './context';
 
 const props = defineProps<ComboboxContentImplProps>();
@@ -48,6 +53,29 @@ onBeforeUnmount(() => rootCtx.onContentChange(undefined));
 
 useHideOthers(toRef(() => rootCtx.parentElement.value));
 
+const isEmpty = computed(() => rootCtx.filterState.value.count === 0);
+
+// Body scroll lock is reference-counted and opt-in: acquire only while `bodyLock`
+// is set, releasing as soon as it flips off or the content unmounts.
+let releaseScrollLock: (() => void) | undefined;
+watch(
+  () => props.bodyLock ?? false,
+  (locked) => {
+    if (locked && !releaseScrollLock) {
+      releaseScrollLock = useBodyScrollLock();
+    }
+    else if (!locked && releaseScrollLock) {
+      releaseScrollLock();
+      releaseScrollLock = undefined;
+    }
+  },
+  { immediate: true },
+);
+onBeforeUnmount(() => {
+  releaseScrollLock?.();
+  releaseScrollLock = undefined;
+});
+
 provideComboboxContentContext({
   viewportElement,
   onViewportChange: (el) => { viewportElement.value = el; },
@@ -70,19 +98,25 @@ function handleInteractOutside(event: PointerEvent | MouseEvent | FocusEvent) {
   if (target && (parent?.contains(target) || input?.contains(target) || trigger?.contains(target))) {
     event.preventDefault();
   }
+  emit('interactOutside', event);
 }
 
-function handlePointerDownOutside(event: any) {
+function handlePointerDownOutside(event: PointerEvent | MouseEvent) {
   emit('pointerDownOutside', event);
 }
 
-function handleFocusOutside(event: any) {
+function handleFocusOutside(event: FocusEvent) {
   emit('focusOutside', event);
 }
 
 function handleCloseAutoFocus(event: Event) {
   emit('closeAutoFocus', event);
 }
+
+const dataEmpty = computed(() => (isEmpty.value ? '' : undefined));
+const hiddenStyle = computed(() =>
+  (props.hideWhenEmpty && isEmpty.value) ? ({ display: 'none' } as const) : undefined,
+);
 </script>
 
 <template>
@@ -121,6 +155,8 @@ function handleCloseAutoFocus(event: Event) {
         role="listbox"
         :aria-multiselectable="rootCtx.multiple.value || undefined"
         :data-state="rootCtx.open.value ? 'open' : 'closed'"
+        :data-empty="dataEmpty"
+        :style="hiddenStyle"
         data-primitives-combobox-content
       >
         <VisuallyHidden role="status" aria-live="polite" data-primitives-combobox-announce>
@@ -137,6 +173,8 @@ function handleCloseAutoFocus(event: Event) {
         role="listbox"
         :aria-multiselectable="rootCtx.multiple.value || undefined"
         :data-state="rootCtx.open.value ? 'open' : 'closed'"
+        :data-empty="dataEmpty"
+        :style="hiddenStyle"
         data-primitives-combobox-content
       >
         <VisuallyHidden role="status" aria-live="polite" data-primitives-combobox-announce>
diff --git a/vue/primitives/src/combobox/ComboboxEmpty.vue b/vue/primitives/src/selection/combobox/ComboboxEmpty.vue
similarity index 88%
rename from vue/primitives/src/combobox/ComboboxEmpty.vue
rename to vue/primitives/src/selection/combobox/ComboboxEmpty.vue
index 3306b64..5e7bc93 100644
--- a/vue/primitives/src/combobox/ComboboxEmpty.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxEmpty.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Fallback content shown when the current search term matches no items. Renders only when
@@ -15,7 +15,7 @@ export interface ComboboxEmptyProps extends PrimitiveProps {
 import { computed } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useComboboxRootContext } from './context';
 
 const { as = 'div', always = false } = defineProps<ComboboxEmptyProps>();
diff --git a/vue/primitives/src/combobox/ComboboxGroup.vue b/vue/primitives/src/selection/combobox/ComboboxGroup.vue
similarity index 65%
rename from vue/primitives/src/combobox/ComboboxGroup.vue
rename to vue/primitives/src/selection/combobox/ComboboxGroup.vue
index 0a28269..4adb976 100644
--- a/vue/primitives/src/combobox/ComboboxGroup.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxGroup.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Groups related items under a shared ComboboxLabel. Hides itself automatically when none
@@ -9,11 +9,11 @@ export interface ComboboxGroupProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted } from 'vue';
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
-import { Primitive } from '../primitive';
+import { useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { provideComboboxGroupContext, useComboboxRootContext } from './context';
 
 const { as = 'div' } = defineProps<ComboboxGroupProps>();
@@ -22,12 +22,19 @@ const { forwardRef } = useForwardExpose();
 const rootCtx = useComboboxRootContext();
 const id = useId(undefined, 'combobox-group');
 
+const labelId = ref<string | undefined>(undefined);
+
 const isVisible = computed(() => rootCtx.filterState.value.groups.has(id.value));
 
 onMounted(() => rootCtx.onGroupRegister(id.value));
 onBeforeUnmount(() => rootCtx.onGroupUnregister(id.value));
 
-provideComboboxGroupContext({ id });
+provideComboboxGroupContext({
+  id,
+  labelId,
+  registerLabel: (labelElId) => { labelId.value = labelElId; },
+  unregisterLabel: () => { labelId.value = undefined; },
+});
 </script>
 
 <template>
@@ -36,7 +43,7 @@ provideComboboxGroupContext({ id });
     :ref="forwardRef"
     :as="as"
     role="group"
-    :aria-labelledby="id"
+    :aria-labelledby="labelId"
   >
     <slot />
   </Primitive>
diff --git a/vue/primitives/src/combobox/ComboboxInput.vue b/vue/primitives/src/selection/combobox/ComboboxInput.vue
similarity index 75%
rename from vue/primitives/src/combobox/ComboboxInput.vue
rename to vue/primitives/src/selection/combobox/ComboboxInput.vue
index 3f16034..9dd0c6f 100644
--- a/vue/primitives/src/combobox/ComboboxInput.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxInput.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The text field users type into to filter options. Owns the search term, ARIA combobox
@@ -10,9 +10,9 @@ export interface ComboboxInputProps extends PrimitiveProps {
   disabled?: boolean;
   /** Focus the input on mount. */
   autoFocus?: boolean;
-  /** Open the combobox when the input is focused. */
+  /** Open the combobox when the input is focused. Combined (OR) with the Root-level `openOnFocus`. */
   openOnFocus?: boolean;
-  /** Open the combobox when the input is clicked. */
+  /** Open the combobox when the input is clicked. Combined (OR) with the Root-level `openOnClick`. */
   openOnClick?: boolean;
 }
 </script>
@@ -21,21 +21,30 @@ export interface ComboboxInputProps extends PrimitiveProps {
 import { computed, nextTick, onBeforeUnmount, onMounted, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useComboboxRootContext } from './context';
 import { INPUT_OPEN_KEYS } from './utils';
 
+const props = defineProps<ComboboxInputProps>();
 const {
   as = 'input',
   disabled = false,
   autoFocus = false,
-  openOnFocus = false,
-  openOnClick = false,
-} = defineProps<ComboboxInputProps>();
+} = props;
 
 const { forwardRef, currentElement } = useForwardExpose();
 const rootCtx = useComboboxRootContext();
 
+// Opens when EITHER the per-input prop or the Root-level default opts in. (Boolean
+// props coerce an absent value to `false`, so a nullish-merge can't distinguish
+// "unset" from "false" — OR composition is the correct, back-compatible semantic.)
+const shouldOpenOnFocus = computed(() => props.openOnFocus || rootCtx.openOnFocus.value);
+const shouldOpenOnClick = computed(() => props.openOnClick || rootCtx.openOnClick.value);
+
+// IME composition guard: while composing, Enter confirms the candidate and must
+// not commit a combobox selection.
+let isComposing = false;
+
 const isDisabled = computed(() => disabled || rootCtx.disabled.value);
 const activeDescendant = computed(() => rootCtx.selectedValueId.value);
 
@@ -107,7 +116,14 @@ function moveHighlight(delta: number) {
   rootCtx.highlightItemById(els[nextIdx]!.id);
 }
 
-function commitHighlighted() {
+function commitHighlighted(event: KeyboardEvent) {
+  const id = rootCtx.selectedValueId.value;
+  if (id) {
+    const info = rootCtx.allItems.value.get(id);
+    // Route through the highlighted item's cancelable `select` flow so keyboard
+    // Enter fires the same `select` event (and honours preventDefault) as a click.
+    if (info) return info.select(event);
+  }
   const value = rootCtx.selectedValue.value;
   if (value === undefined) return false;
   rootCtx.onValueChange(value);
@@ -163,7 +179,10 @@ function handleKeyDown(event: KeyboardEvent) {
       break;
     }
     case 'Enter':
-      if (commitHighlighted()) event.preventDefault();
+      // While composing an IME candidate, Enter confirms the candidate — it must
+      // not select a combobox item.
+      if (isComposing) break;
+      if (commitHighlighted(event)) event.preventDefault();
       break;
     case 'Escape':
       event.preventDefault();
@@ -177,11 +196,19 @@ function handleKeyDown(event: KeyboardEvent) {
 }
 
 function handleFocus() {
-  if (openOnFocus && !rootCtx.open.value) rootCtx.onOpenChange(true);
+  if (shouldOpenOnFocus.value && !rootCtx.open.value) rootCtx.onOpenChange(true);
 }
 
 function handleClick() {
-  if (openOnClick && !rootCtx.open.value) rootCtx.onOpenChange(true);
+  if (shouldOpenOnClick.value && !rootCtx.open.value) rootCtx.onOpenChange(true);
+}
+
+function handleCompositionStart() {
+  isComposing = true;
+}
+
+function handleCompositionEnd() {
+  isComposing = false;
 }
 
 function handleBlur(event: FocusEvent) {
@@ -219,6 +246,8 @@ function handleBlur(event: FocusEvent) {
     @focus="handleFocus"
     @click="handleClick"
     @blur="handleBlur"
+    @compositionstart="handleCompositionStart"
+    @compositionend="handleCompositionEnd"
   >
     <slot />
   </Primitive>
diff --git a/vue/primitives/src/combobox/ComboboxItem.vue b/vue/primitives/src/selection/combobox/ComboboxItem.vue
similarity index 65%
rename from vue/primitives/src/combobox/ComboboxItem.vue
rename to vue/primitives/src/selection/combobox/ComboboxItem.vue
index 6af98e1..501faf4 100644
--- a/vue/primitives/src/combobox/ComboboxItem.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxItem.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { AcceptableValue } from './utils';
 
 /**
@@ -14,22 +14,44 @@ export interface ComboboxItemProps<T extends AcceptableValue = AcceptableValue>
   /** Disable this item. */
   disabled?: boolean;
 }
+
+/**
+ * Detail of the cancelable `select` event. Call `preventDefault()` on the event
+ * (or read `defaultPrevented`) to block the default selection/auto-close — the
+ * interception point for create-on-enter and custom selection flows.
+ */
+export interface ComboboxItemSelectEvent<T extends AcceptableValue = AcceptableValue> extends CustomEvent {
+  detail: { value: T; originalEvent: PointerEvent | KeyboardEvent | MouseEvent };
+}
+
+export interface ComboboxItemEmits<T extends AcceptableValue = AcceptableValue> {
+  /** Cancelable. Fires before selection commits; `preventDefault()` blocks it. */
+  select: [event: ComboboxItemSelectEvent<T>];
+}
 </script>
 
 <script setup lang="ts" generic="T extends AcceptableValue = AcceptableValue">
+import type { ComboboxGroupContext } from './context';
 import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
-import { Primitive } from '../primitive';
+import { useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { provideComboboxItemContext, useComboboxGroupContext, useComboboxRootContext } from './context';
 
 const props = defineProps<ComboboxItemProps<T>>();
+const emit = defineEmits<ComboboxItemEmits<T>>();
+
+if (props.value === ('' as unknown as T)) {
+  throw new Error(
+    '[ComboboxItem] `value` must not be an empty string — the empty string is reserved for the cleared selection state.',
+  );
+}
 
 const rootCtx = useComboboxRootContext();
-let groupCtx: { id: { value: string } } | null = null;
+let groupCtx: ComboboxGroupContext | null = null;
 try {
-  groupCtx = useComboboxGroupContext() as any;
+  groupCtx = useComboboxGroupContext();
 }
 catch {
   groupCtx = null;
@@ -54,6 +76,7 @@ function syncRegistration() {
     value: props.value,
     textValue: textValue.value,
     disabled: isDisabled.value,
+    select: trySelect,
   });
 }
 
@@ -79,18 +102,37 @@ onBeforeUnmount(() => {
   }
 });
 
-function handleClick(event: MouseEvent) {
-  if (isDisabled.value) return;
-  event.preventDefault();
+/**
+ * Runs the selection flow guarded by a cancelable `select` event. Consumers can
+ * call `preventDefault()` on the event to block selection (e.g. create-on-enter).
+ * Returns `true` when selection committed.
+ */
+function trySelect(originalEvent: PointerEvent | KeyboardEvent | MouseEvent): boolean {
+  if (isDisabled.value) return false;
+  const selectEvent = new CustomEvent('combobox-item-select', {
+    bubbles: false,
+    cancelable: true,
+    detail: { value: props.value, originalEvent },
+  }) as ComboboxItemSelectEvent<T>;
+  emit('select', selectEvent);
+  if (selectEvent.defaultPrevented) return false;
+
   rootCtx.onValueChange(props.value);
   if (rootCtx.resetSearchTermOnSelect.value && !rootCtx.multiple.value) {
     rootCtx.onSearchTermChange('');
     rootCtx.onUserInputtedChange(false);
   }
+  return true;
+}
+
+function handleClick(event: MouseEvent) {
+  if (isDisabled.value) return;
+  event.preventDefault();
+  trySelect(event);
 }
 
 function handlePointerMove() {
-  if (isDisabled.value) return;
+  if (isDisabled.value || !rootCtx.highlightOnHover.value) return;
   if (rootCtx.selectedValueId.value !== id.value) {
     rootCtx.onSelectedValueChange(props.value, id.value);
   }
diff --git a/vue/primitives/src/combobox/ComboboxItemIndicator.vue b/vue/primitives/src/selection/combobox/ComboboxItemIndicator.vue
similarity index 85%
rename from vue/primitives/src/combobox/ComboboxItemIndicator.vue
rename to vue/primitives/src/selection/combobox/ComboboxItemIndicator.vue
index eca754b..72b5501 100644
--- a/vue/primitives/src/combobox/ComboboxItemIndicator.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxItemIndicator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Marks the selected state of its parent ComboboxItem, e.g. a checkmark. Renders only when
@@ -11,7 +11,7 @@ export interface ComboboxItemIndicatorProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useComboboxItemContext } from './context';
 
 const { as = 'span' } = defineProps<ComboboxItemIndicatorProps>();
diff --git a/vue/primitives/src/combobox/ComboboxLabel.vue b/vue/primitives/src/selection/combobox/ComboboxLabel.vue
similarity index 63%
rename from vue/primitives/src/combobox/ComboboxLabel.vue
rename to vue/primitives/src/selection/combobox/ComboboxLabel.vue
index c720e3b..5d1e1a5 100644
--- a/vue/primitives/src/combobox/ComboboxLabel.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxLabel.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * An accessible label for a ComboboxGroup. Its id is referenced by the group's
@@ -9,21 +9,27 @@ export interface ComboboxLabelProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { useForwardExpose } from '@robonen/vue';
+import { onBeforeUnmount } from 'vue';
 
-import { Primitive } from '../primitive';
+import { useForwardExpose } from '@robonen/vue';
+import { useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { useComboboxGroupContext } from './context';
 
 const { as = 'div' } = defineProps<ComboboxLabelProps>();
 const { forwardRef } = useForwardExpose();
 const groupCtx = useComboboxGroupContext();
+
+const id = useId(undefined, 'combobox-group-label');
+groupCtx.registerLabel(id.value);
+onBeforeUnmount(() => groupCtx.unregisterLabel());
 </script>
 
 <template>
   <Primitive
     :ref="forwardRef"
     :as="as"
-    :id="groupCtx.id.value"
+    :id="id"
   >
     <slot />
   </Primitive>
diff --git a/vue/primitives/src/combobox/ComboboxPortal.vue b/vue/primitives/src/selection/combobox/ComboboxPortal.vue
similarity index 80%
rename from vue/primitives/src/combobox/ComboboxPortal.vue
rename to vue/primitives/src/selection/combobox/ComboboxPortal.vue
index 96e392a..a876c2f 100644
--- a/vue/primitives/src/combobox/ComboboxPortal.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PortalProps } from '../teleport';
+import type { PortalProps } from '../../utilities/teleport';
 
 /**
  * Teleports the ComboboxContent into another part of the DOM (defaults to `body`) to escape
@@ -9,7 +9,7 @@ export interface ComboboxPortalProps extends PortalProps {}
 </script>
 
 <script setup lang="ts">
-import { Portal } from '../teleport';
+import { Portal } from '../../utilities/teleport';
 
 const { to, defer, disabled } = defineProps<ComboboxPortalProps>();
 </script>
diff --git a/vue/primitives/src/combobox/ComboboxRoot.vue b/vue/primitives/src/selection/combobox/ComboboxRoot.vue
similarity index 83%
rename from vue/primitives/src/combobox/ComboboxRoot.vue
rename to vue/primitives/src/selection/combobox/ComboboxRoot.vue
index 433c30b..a5336d7 100644
--- a/vue/primitives/src/combobox/ComboboxRoot.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxRoot.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { Direction } from '../config-provider';
+import type { Direction } from '../../utilities/config-provider';
 import type { AcceptableValue, ComboboxFilterFunction, ComboboxFilterItem } from './utils';
 
 /**
@@ -30,6 +30,14 @@ export interface ComboboxRootProps<T extends AcceptableValue = AcceptableValue>
   resetSearchTermOnBlur?: boolean;
   /** Reset the search term when a value is selected (single mode). @default true */
   resetSearchTermOnSelect?: boolean;
+  /** Clear the model value (to `undefined`, or `[]` when `multiple`) when the search is cleared via ComboboxCancel. @default false */
+  resetModelValueOnClear?: boolean;
+  /** Open the combobox when the input is focused. Root-level default for every ComboboxInput; a per-input prop still overrides it. @default false */
+  openOnFocus?: boolean;
+  /** Open the combobox when the input is clicked. Root-level default for every ComboboxInput; a per-input prop still overrides it. @default false */
+  openOnClick?: boolean;
+  /** Highlight items on pointer hover. Set `false` to opt out of pointermove highlighting. @default true */
+  highlightOnHover?: boolean;
   /** Skip the built-in filter; render every item regardless of search term. */
   ignoreFilter?: boolean;
   /** Custom filter implementation. Overrides the default substring match. */
@@ -43,6 +51,8 @@ export interface ComboboxRootProps<T extends AcceptableValue = AcceptableValue>
 export interface ComboboxRootEmits<T extends AcceptableValue = AcceptableValue> {
   'update:modelValue': [value: T | T[] | undefined];
   'update:open': [open: boolean];
+  /** Fired whenever the highlighted (active-descendant) item changes; payload is `undefined` when nothing is highlighted. */
+  highlight: [payload: { value: T; ref: HTMLElement | undefined } | undefined];
 }
 </script>
 
@@ -52,8 +62,8 @@ import type { ComboboxFilterState, ComboboxItemInfo } from './context';
 
 import { computed, nextTick, ref, shallowRef, toRef, triggerRef, watch } from 'vue';
 
-import { useConfig, useId } from '../config-provider';
-import { PopperRoot } from '../popper';
+import { useConfig, useId } from '../../utilities/config-provider';
+import { PopperRoot } from '../../overlays/popper';
 import { provideComboboxRootContext } from './context';
 import { defaultFilter, valueComparator } from './utils';
 
@@ -70,12 +80,18 @@ const {
   name,
   resetSearchTermOnBlur = true,
   resetSearchTermOnSelect = true,
+  resetModelValueOnClear = false,
+  openOnFocus = false,
+  openOnClick = false,
+  highlightOnHover = true,
   ignoreFilter = false,
   filterFunction,
   displayValue,
   by,
 } = defineProps<ComboboxRootProps<T>>();
 
+const emit = defineEmits<ComboboxRootEmits<T>>();
+
 const config = useConfig();
 const direction = computed(() => dir ?? config.dir.value);
 
@@ -235,6 +251,28 @@ function onSelectedValueChange(v: T | undefined, id?: string) {
   selectedValueId.value = id;
 }
 
+function clearModelValue() {
+  commitValue(multiple ? ([] as T[]) : undefined);
+}
+
+// `selectedValueId` is the single source of truth for the active-descendant, so
+// emitting `highlight` off its change covers keyboard, hover, and programmatic
+// highlight paths without instrumenting each call site.
+watch(selectedValueId, (id) => {
+  if (id === undefined) {
+    emit('highlight', undefined);
+    return;
+  }
+  const value = selectedValue.value;
+  if (value === undefined) {
+    emit('highlight', undefined);
+    return;
+  }
+  const root = contentElement.value ?? parentElement.value;
+  const el = root?.querySelector<HTMLElement>(`#${CSS.escape(id)}`) ?? undefined;
+  emit('highlight', { value, ref: el });
+});
+
 function getVisibleItemElements(): HTMLElement[] {
   const root = contentElement.value ?? parentElement.value;
   if (!root) return [];
@@ -326,9 +364,14 @@ provideComboboxRootContext({
   onSearchTermChange,
   resetSearchTermOnBlur: toRef(() => resetSearchTermOnBlur),
   resetSearchTermOnSelect: toRef(() => resetSearchTermOnSelect),
+  resetModelValueOnClear: toRef(() => resetModelValueOnClear),
+  openOnFocus: toRef(() => openOnFocus),
+  openOnClick: toRef(() => openOnClick),
+  highlightOnHover: toRef(() => highlightOnHover),
   ignoreFilter: ignoreFilterRef,
   filterFunction: filterRef,
   displayValue: displayValue as ((v: unknown) => string) | undefined,
+  clearModelValue,
 
   isUserInputted,
   onUserInputtedChange,
diff --git a/vue/primitives/src/combobox/ComboboxSeparator.vue b/vue/primitives/src/selection/combobox/ComboboxSeparator.vue
similarity index 83%
rename from vue/primitives/src/combobox/ComboboxSeparator.vue
rename to vue/primitives/src/selection/combobox/ComboboxSeparator.vue
index 79271cd..3650607 100644
--- a/vue/primitives/src/combobox/ComboboxSeparator.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxSeparator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A purely visual divider between items or groups inside the popup. Decorative and hidden
@@ -11,7 +11,7 @@ export interface ComboboxSeparatorProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'div' } = defineProps<ComboboxSeparatorProps>();
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/combobox/ComboboxTrigger.vue b/vue/primitives/src/selection/combobox/ComboboxTrigger.vue
similarity index 93%
rename from vue/primitives/src/combobox/ComboboxTrigger.vue
rename to vue/primitives/src/selection/combobox/ComboboxTrigger.vue
index dd37a59..815c7bb 100644
--- a/vue/primitives/src/combobox/ComboboxTrigger.vue
+++ b/vue/primitives/src/selection/combobox/ComboboxTrigger.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A button, usually a chevron next to the input, that toggles the popup open and closed.
@@ -15,7 +15,7 @@ export interface ComboboxTriggerProps extends PrimitiveProps {
 import { computed, onBeforeUnmount, watchPostEffect } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useComboboxRootContext } from './context';
 import { getOpenState } from './utils';
 
diff --git a/vue/primitives/src/selection/combobox/ComboboxViewport.vue b/vue/primitives/src/selection/combobox/ComboboxViewport.vue
new file mode 100644
index 0000000..099317f
--- /dev/null
+++ b/vue/primitives/src/selection/combobox/ComboboxViewport.vue
@@ -0,0 +1,49 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The scrollable region inside ComboboxContent that holds the items. Provides the overflow
+ * container that keeps the highlighted item scrolled into view.
+ */
+export interface ComboboxViewportProps extends PrimitiveProps {
+  /**
+   * CSP `nonce` applied to the injected scrollbar-hiding `<style>` tag. Falls
+   * back to the `ConfigProvider` nonce when omitted.
+   */
+  nonce?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { toRef, watchPostEffect } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
+import { useNonce } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
+import { useComboboxContentContext } from './context';
+
+const props = defineProps<ComboboxViewportProps>();
+const { as = 'div' } = props;
+
+const { forwardRef, currentElement } = useForwardExpose();
+const contentCtx = useComboboxContentContext();
+const nonce = useNonce(toRef(() => props.nonce));
+
+watchPostEffect(() => contentCtx.onViewportChange(currentElement.value));
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="presentation"
+    data-primitives-combobox-viewport
+    style="position: relative; flex: 1 1 0%; overflow: hidden auto"
+  >
+    <slot />
+  </Primitive>
+  <Primitive as="style" :nonce="nonce">
+    [data-primitives-combobox-viewport]{scrollbar-width:none;-ms-overflow-style:none;-webkit-overflow-scrolling:touch;}
+    [data-primitives-combobox-viewport]::-webkit-scrollbar{display:none;}
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/selection/combobox/__test__/Combobox.features.test.ts b/vue/primitives/src/selection/combobox/__test__/Combobox.features.test.ts
new file mode 100644
index 0000000..d9256be
--- /dev/null
+++ b/vue/primitives/src/selection/combobox/__test__/Combobox.features.test.ts
@@ -0,0 +1,433 @@
+import type { Ref } from 'vue';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { userEvent } from 'vitest/browser';
+import { defineComponent, h, nextTick, ref } from 'vue';
+
+import {
+  ComboboxAnchor,
+  ComboboxCancel,
+  ComboboxContent,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxLabel,
+  ComboboxPortal,
+  ComboboxRoot,
+  ComboboxTrigger,
+  ComboboxViewport,
+  accentInsensitiveContains,
+} from '../index';
+
+interface MountOptions {
+  defaultOpen?: boolean;
+  multiple?: boolean;
+  highlightOnHover?: boolean;
+  resetModelValueOnClear?: boolean;
+  openOnFocus?: boolean;
+  openOnClick?: boolean;
+  model?: Ref<unknown>;
+  onSelect?: (e: CustomEvent) => void;
+  onHighlight?: (p: unknown) => void;
+  items?: Array<{ value: string; textValue: string }>;
+}
+
+const DEFAULT_ITEMS = [
+  { value: 'apple', textValue: 'Apple' },
+  { value: 'banana', textValue: 'Banana' },
+  { value: 'cherry', textValue: 'Cherry' },
+];
+
+function mountCombobox(options: MountOptions = {}) {
+  const items = options.items ?? DEFAULT_ITEMS;
+  const Harness = defineComponent({
+    setup: () => () => h(ComboboxRoot, {
+      defaultOpen: options.defaultOpen ?? false,
+      multiple: options.multiple ?? false,
+      ...(options.highlightOnHover !== undefined ? { highlightOnHover: options.highlightOnHover } : {}),
+      ...(options.resetModelValueOnClear !== undefined ? { resetModelValueOnClear: options.resetModelValueOnClear } : {}),
+      ...(options.openOnFocus !== undefined ? { openOnFocus: options.openOnFocus } : {}),
+      ...(options.openOnClick !== undefined ? { openOnClick: options.openOnClick } : {}),
+      ...(options.onHighlight ? { onHighlight: options.onHighlight } : {}),
+      ...(options.model
+        ? {
+            modelValue: options.model.value,
+            'onUpdate:modelValue': (v: unknown) => { options.model!.value = v; },
+          }
+        : {}),
+    }, {
+      default: () => [
+        h(ComboboxAnchor, { id: 'anchor' }, {
+          default: () => [
+            h(ComboboxInput, { id: 'input' }),
+            h(ComboboxCancel, { id: 'cancel' }, { default: () => 'x' }),
+            h(ComboboxTrigger, { id: 'trigger' }, { default: () => 'v' }),
+          ],
+        }),
+        h(ComboboxPortal, {}, {
+          default: () => h(ComboboxContent, {}, {
+            default: () => h(ComboboxViewport, {}, {
+              default: () => items.map(it => h(ComboboxItem, {
+                key: it.value,
+                value: it.value,
+                textValue: it.textValue,
+                ...(options.onSelect ? { onSelect: options.onSelect } : {}),
+              }, { default: () => it.textValue })),
+            }),
+          }),
+        }),
+      ],
+    }),
+  });
+  return mount(Harness, { attachTo: document.body });
+}
+
+function getInput(): HTMLInputElement {
+  return document.querySelector<HTMLInputElement>('#input')!;
+}
+
+function getItem(text: string): HTMLElement {
+  return Array.from(document.querySelectorAll<HTMLElement>('[data-primitives-combobox-item]'))
+    .find(el => el.textContent?.includes(text))!;
+}
+
+function getContent(): HTMLElement | null {
+  return document.querySelector('[data-primitives-combobox-content]');
+}
+
+async function flush(times = 4) {
+  for (let i = 0; i < times; i++) await nextTick();
+}
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('Combobox — cancelable item select event', () => {
+  it('fires select on click and commits when not prevented', async () => {
+    const model = ref<unknown>(undefined);
+    const onSelect = vi.fn();
+    const w = mountCombobox({ defaultOpen: true, model, onSelect });
+    await flush();
+
+    await userEvent.click(getItem('Banana'));
+    await flush();
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    const event = onSelect.mock.calls[0]![0] as CustomEvent;
+    expect(event.detail.value).toBe('banana');
+    expect(model.value).toBe('banana');
+    w.unmount();
+  });
+
+  it('blocks selection when the consumer calls preventDefault', async () => {
+    const model = ref<unknown>(undefined);
+    const onSelect = (e: CustomEvent) => e.preventDefault();
+    const w = mountCombobox({ defaultOpen: true, model, onSelect });
+    await flush();
+
+    await userEvent.click(getItem('Banana'));
+    await flush();
+
+    expect(model.value).toBeUndefined();
+    // List stays open because selection was blocked (single-select would close on commit).
+    expect(getContent()).toBeTruthy();
+    w.unmount();
+  });
+
+  it('fires the same cancelable select on keyboard Enter', async () => {
+    const model = ref<unknown>(undefined);
+    const onSelect = vi.fn((e: CustomEvent) => e.preventDefault());
+    const w = mountCombobox({ model, onSelect });
+    await flush();
+
+    const input = getInput();
+    await userEvent.click(input);
+    await userEvent.keyboard('{ArrowDown}');
+    await flush();
+    await userEvent.keyboard('{Enter}');
+    await flush();
+
+    expect(onSelect).toHaveBeenCalled();
+    // preventDefault blocked the commit.
+    expect(model.value).toBeUndefined();
+    w.unmount();
+  });
+});
+
+describe('Combobox — empty-string item value guard', () => {
+  it('throws when an item has an empty-string value', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(() => mountCombobox({
+      defaultOpen: true,
+      items: [{ value: '', textValue: 'Empty' }],
+    })).toThrow(/empty string/i);
+    spy.mockRestore();
+  });
+});
+
+describe('Combobox — resetModelValueOnClear', () => {
+  it('clears the model value when Cancel is clicked and the prop is set', async () => {
+    const model = ref<unknown>('banana');
+    const w = mountCombobox({ defaultOpen: true, model, resetModelValueOnClear: true });
+    await flush();
+
+    await userEvent.click(document.querySelector('#cancel')!);
+    await flush();
+
+    expect(model.value).toBeUndefined();
+    w.unmount();
+  });
+
+  it('leaves the model value intact by default', async () => {
+    const model = ref<unknown>('banana');
+    const w = mountCombobox({ defaultOpen: true, model });
+    await flush();
+
+    await userEvent.click(document.querySelector('#cancel')!);
+    await flush();
+
+    expect(model.value).toBe('banana');
+    w.unmount();
+  });
+
+  it('resets to an empty array in multiple mode', async () => {
+    const model = ref<unknown>(['banana']);
+    const w = mountCombobox({ defaultOpen: true, multiple: true, model, resetModelValueOnClear: true });
+    await flush();
+
+    await userEvent.click(document.querySelector('#cancel')!);
+    await flush();
+
+    expect(model.value).toEqual([]);
+    w.unmount();
+  });
+});
+
+describe('Combobox — highlightOnHover opt-out', () => {
+  it('does not highlight on pointermove when highlightOnHover is false', async () => {
+    const w = mountCombobox({ defaultOpen: true, highlightOnHover: false });
+    await flush();
+
+    const cherry = getItem('Cherry');
+    cherry.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }));
+    await flush();
+
+    expect(cherry.getAttribute('data-highlighted')).toBeNull();
+    w.unmount();
+  });
+
+  it('highlights on pointermove by default', async () => {
+    const w = mountCombobox({ defaultOpen: true });
+    await flush();
+
+    const cherry = getItem('Cherry');
+    cherry.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }));
+    await flush();
+
+    expect(cherry.getAttribute('data-highlighted')).toBe('');
+    w.unmount();
+  });
+});
+
+describe('Combobox — highlight emit', () => {
+  it('emits highlight with the active item when navigation moves', async () => {
+    const onHighlight = vi.fn();
+    const w = mountCombobox({ onHighlight });
+    await flush();
+
+    const input = getInput();
+    await userEvent.click(input);
+    await userEvent.keyboard('{ArrowDown}');
+    await flush();
+
+    const lastPayload = onHighlight.mock.calls.at(-1)?.[0];
+    expect(lastPayload).toBeTruthy();
+    expect(lastPayload.value).toBe('apple');
+    w.unmount();
+  });
+
+  it('emits highlight undefined when the list closes', async () => {
+    const onHighlight = vi.fn();
+    const w = mountCombobox({ defaultOpen: true, onHighlight });
+    await flush();
+
+    const cherry = getItem('Cherry');
+    cherry.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }));
+    await flush();
+    onHighlight.mockClear();
+
+    await userEvent.keyboard('{Escape}');
+    await flush();
+
+    expect(onHighlight).toHaveBeenCalledWith(undefined);
+    w.unmount();
+  });
+});
+
+describe('Combobox — accent-insensitive default filter', () => {
+  it('matches accented text against an unaccented search term', () => {
+    expect(accentInsensitiveContains('Café', 'cafe')).toBe(true);
+    expect(accentInsensitiveContains('Crème brûlée', 'creme')).toBe(true);
+    expect(accentInsensitiveContains('Apple', 'xyz')).toBe(false);
+  });
+
+  it('filters list items ignoring diacritics', async () => {
+    const w = mountCombobox({
+      items: [
+        { value: 'cafe', textValue: 'Café' },
+        { value: 'tea', textValue: 'Tea' },
+      ],
+    });
+    await flush();
+
+    const input = getInput();
+    await userEvent.click(input);
+    await userEvent.type(input, 'cafe');
+    await flush();
+
+    const visible = Array.from(document.querySelectorAll<HTMLElement>('[data-primitives-combobox-item]'))
+      .filter(el => el.style.display !== 'none')
+      .map(el => el.textContent?.trim());
+    expect(visible).toEqual(['Café']);
+    w.unmount();
+  });
+});
+
+describe('Combobox — IME composition guard', () => {
+  it('does not select an item when Enter fires during composition', async () => {
+    const model = ref<unknown>(undefined);
+    const w = mountCombobox({ model });
+    await flush();
+
+    const input = getInput();
+    await userEvent.click(input);
+    await userEvent.keyboard('{ArrowDown}');
+    await flush();
+
+    input.dispatchEvent(new CompositionEvent('compositionstart', { bubbles: true }));
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+    await flush();
+
+    expect(model.value).toBeUndefined();
+
+    input.dispatchEvent(new CompositionEvent('compositionend', { bubbles: true }));
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+    await flush();
+
+    expect(model.value).toBe('apple');
+    w.unmount();
+  });
+});
+
+describe('Combobox — Root-level openOnFocus / openOnClick', () => {
+  it('opens on input focus when Root openOnFocus is set', async () => {
+    const w = mountCombobox({ openOnFocus: true });
+    await flush();
+
+    getInput().focus();
+    await flush();
+
+    expect(getContent()).toBeTruthy();
+    w.unmount();
+  });
+
+  it('opens on input click when Root openOnClick is set', async () => {
+    const w = mountCombobox({ openOnClick: true });
+    await flush();
+
+    await userEvent.click(getInput());
+    await flush();
+
+    expect(getContent()).toBeTruthy();
+    w.unmount();
+  });
+});
+
+describe('Combobox — group label relationship', () => {
+  function mountWithGroup(withLabel: boolean) {
+    const Harness = defineComponent({
+      setup: () => () => h(ComboboxRoot, { defaultOpen: true }, {
+        default: () => [
+          h(ComboboxAnchor, {}, { default: () => h(ComboboxInput, { id: 'input' }) }),
+          h(ComboboxPortal, {}, {
+            default: () => h(ComboboxContent, {}, {
+              default: () => h(ComboboxViewport, {}, {
+                default: () => h(ComboboxGroup, { id: 'group' }, {
+                  default: () => [
+                    ...(withLabel ? [h(ComboboxLabel, { class: 'group-label' }, { default: () => 'Fruits' })] : []),
+                    h(ComboboxItem, { value: 'apple', textValue: 'Apple' }, { default: () => 'Apple' }),
+                  ],
+                }),
+              }),
+            }),
+          }),
+        ],
+      }),
+    });
+    return mount(Harness, { attachTo: document.body });
+  }
+
+  it('points aria-labelledby at the rendered label id', async () => {
+    const w = mountWithGroup(true);
+    await flush();
+
+    const group = document.querySelector('#group')!;
+    const label = document.querySelector('.group-label')!;
+    const labelledby = group.getAttribute('aria-labelledby');
+    expect(labelledby).toBeTruthy();
+    expect(label.id).toBeTruthy();
+    expect(labelledby).toBe(label.id);
+    w.unmount();
+  });
+
+  it('omits aria-labelledby when no label is rendered (no dangling id)', async () => {
+    const w = mountWithGroup(false);
+    await flush();
+
+    const group = document.querySelector('#group')!;
+    expect(group.getAttribute('aria-labelledby')).toBeNull();
+    w.unmount();
+  });
+});
+
+describe('Combobox — hideWhenEmpty + data-empty', () => {
+  function mountHideWhenEmpty() {
+    const Harness = defineComponent({
+      setup: () => () => h(ComboboxRoot, { defaultOpen: true }, {
+        default: () => [
+          h(ComboboxAnchor, {}, { default: () => h(ComboboxInput, { id: 'input' }) }),
+          h(ComboboxPortal, {}, {
+            default: () => h(ComboboxContent, { hideWhenEmpty: true }, {
+              default: () => h(ComboboxViewport, {}, {
+                default: () => DEFAULT_ITEMS.map(it => h(ComboboxItem, {
+                  key: it.value,
+                  value: it.value,
+                  textValue: it.textValue,
+                }, { default: () => it.textValue })),
+              }),
+            }),
+          }),
+        ],
+      }),
+    });
+    return mount(Harness, { attachTo: document.body });
+  }
+
+  it('marks the content data-empty and hides it when no items match', async () => {
+    const w = mountHideWhenEmpty();
+    await flush();
+
+    const content = getContent()!;
+    expect(content.getAttribute('data-empty')).toBeNull();
+
+    const input = getInput();
+    await userEvent.click(input);
+    await userEvent.type(input, 'zzz');
+    await flush();
+
+    expect(content.getAttribute('data-empty')).toBe('');
+    expect(content.style.display).toBe('none');
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/combobox/__test__/Combobox.live-region.test.ts b/vue/primitives/src/selection/combobox/__test__/Combobox.live-region.test.ts
similarity index 100%
rename from vue/primitives/src/combobox/__test__/Combobox.live-region.test.ts
rename to vue/primitives/src/selection/combobox/__test__/Combobox.live-region.test.ts
diff --git a/vue/primitives/src/combobox/__test__/Combobox.test.ts b/vue/primitives/src/selection/combobox/__test__/Combobox.test.ts
similarity index 100%
rename from vue/primitives/src/combobox/__test__/Combobox.test.ts
rename to vue/primitives/src/selection/combobox/__test__/Combobox.test.ts
diff --git a/vue/primitives/src/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-announces--N-results-available---reflecting-the-unfiltered-count-on-open-1.png b/vue/primitives/src/selection/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-announces--N-results-available---reflecting-the-unfiltered-count-on-open-1.png
similarity index 100%
rename from vue/primitives/src/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-announces--N-results-available---reflecting-the-unfiltered-count-on-open-1.png
rename to vue/primitives/src/selection/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-announces--N-results-available---reflecting-the-unfiltered-count-on-open-1.png
diff --git a/vue/primitives/src/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-updates-the-count-as-the-search-term-filters-items-1.png b/vue/primitives/src/selection/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-updates-the-count-as-the-search-term-filters-items-1.png
similarity index 100%
rename from vue/primitives/src/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-updates-the-count-as-the-search-term-filters-items-1.png
rename to vue/primitives/src/selection/combobox/__test__/__screenshots__/Combobox.live-region.test.ts/Combobox---filtered-results-live-region-updates-the-count-as-the-search-term-filters-items-1.png
diff --git a/vue/primitives/src/combobox/context.ts b/vue/primitives/src/selection/combobox/context.ts
similarity index 71%
rename from vue/primitives/src/combobox/context.ts
rename to vue/primitives/src/selection/combobox/context.ts
index 48a81f0..8a1a54a 100644
--- a/vue/primitives/src/combobox/context.ts
+++ b/vue/primitives/src/selection/combobox/context.ts
@@ -1,5 +1,5 @@
 import type { ComputedRef, Ref, ShallowRef } from 'vue';
-import type { Direction } from '../config-provider';
+import type { Direction } from '../../utilities/config-provider';
 import type { AcceptableValue, ComboboxFilterFunction } from './utils';
 
 import { useContextFactory } from '@robonen/vue';
@@ -8,6 +8,12 @@ export interface ComboboxItemInfo<T = AcceptableValue> {
   value: T;
   textValue: string;
   disabled: boolean;
+  /**
+   * Runs the item's cancelable `select` flow (fires the `select` event, commits
+   * unless prevented). Lets keyboard Enter on the Input go through the same
+   * interception point as a click. Returns whether selection committed.
+   */
+  select: (originalEvent: KeyboardEvent | PointerEvent | MouseEvent) => boolean;
 }
 
 export interface ComboboxFilterState {
@@ -33,9 +39,15 @@ export interface ComboboxRootContext<T = AcceptableValue> {
   onSearchTermChange: (value: string) => void;
   resetSearchTermOnBlur: Ref<boolean>;
   resetSearchTermOnSelect: Ref<boolean>;
+  resetModelValueOnClear: Ref<boolean>;
+  openOnFocus: Ref<boolean>;
+  openOnClick: Ref<boolean>;
+  highlightOnHover: Ref<boolean>;
   ignoreFilter: Ref<boolean>;
   filterFunction: Ref<ComboboxFilterFunction | undefined>;
   displayValue?: (value: T | T[] | undefined) => string;
+  /** Clears the current selection (resets the model). */
+  clearModelValue: () => void;
 
   isUserInputted: Ref<boolean>;
   onUserInputtedChange: (value: boolean) => void;
@@ -81,6 +93,14 @@ export interface ComboboxContentContext {
 
 export interface ComboboxGroupContext {
   id: Ref<string>;
+  /**
+   * The id of the rendered `ComboboxLabel`, or `undefined` until one mounts.
+   * The group only points `aria-labelledby` at it once it exists, avoiding a
+   * dangling reference when no label is rendered.
+   */
+  labelId: Ref<string | undefined>;
+  registerLabel: (id: string) => void;
+  unregisterLabel: () => void;
 }
 
 export interface ComboboxItemContext<T = AcceptableValue> {
@@ -91,6 +111,11 @@ export interface ComboboxItemContext<T = AcceptableValue> {
   isDisabled: Ref<boolean>;
 }
 
+// `any` (not `AcceptableValue`): the generic `ComboboxRoot` provides a
+// `ComboboxRootContext<T>` whose contravariant callbacks ((value: T) => void)
+// are not assignable to the concrete `AcceptableValue` instantiation. `any` is
+// the type-erasure boundary that lets the generic root provide and arbitrary
+// `ComboboxItem<T>` consumers inject without per-component casts.
 export const {
   inject: useComboboxRootContext,
   provide: provideComboboxRootContext,
@@ -106,6 +131,8 @@ export const {
   provide: provideComboboxGroupContext,
 } = useContextFactory<ComboboxGroupContext>('ComboboxGroup');
 
+// `any` for the same generic type-erasure reason as the root context above:
+// `ComboboxItem<T>` provides `ComboboxItemContext<T>`, injected generically.
 export const {
   inject: useComboboxItemContext,
   provide: provideComboboxItemContext,
diff --git a/vue/primitives/src/combobox/demo.vue b/vue/primitives/src/selection/combobox/demo.vue
similarity index 78%
rename from vue/primitives/src/combobox/demo.vue
rename to vue/primitives/src/selection/combobox/demo.vue
index ff8d441..b037a15 100644
--- a/vue/primitives/src/combobox/demo.vue
+++ b/vue/primitives/src/selection/combobox/demo.vue
@@ -51,22 +51,22 @@ const groups = ['JavaScript', 'Native'] as const;
       class="relative"
     >
       <ComboboxAnchor
-        class="flex items-center gap-1 rounded-lg border border-(--border) bg-(--bg-inset) px-2 py-1.5 focus-within:border-(--accent) focus-within:ring-2 focus-within:ring-(--ring)"
+        class="flex items-center gap-1 rounded-lg border border-border bg-bg-inset px-2 py-1.5 focus-within:border-accent focus-within:ring-2 focus-within:ring-ring"
       >
         <ComboboxInput
           placeholder="Search a framework..."
           open-on-click
-          class="min-w-0 flex-1 bg-transparent px-1 text-sm text-(--fg) outline-none placeholder:text-(--fg-subtle)"
+          class="min-w-0 flex-1 bg-transparent px-1 text-sm text-fg outline-none placeholder:text-fg-subtle"
         />
 
         <ComboboxCancel
-          class="grid size-5 place-items-center rounded text-(--fg-subtle) hover:bg-(--bg-subtle) hover:text-(--fg)"
+          class="grid size-5 place-items-center rounded text-fg-subtle hover:bg-bg-subtle hover:text-fg"
         >
           <span aria-hidden="true" class="text-xs">✕</span>
         </ComboboxCancel>
 
         <ComboboxTrigger
-          class="grid size-5 place-items-center rounded text-(--fg-muted) hover:bg-(--bg-subtle) hover:text-(--fg) data-[state=open]:rotate-180"
+          class="grid size-5 place-items-center rounded text-fg-muted hover:bg-bg-subtle hover:text-fg data-[state=open]:rotate-180"
         >
           <span aria-hidden="true" class="text-xs">▾</span>
         </ComboboxTrigger>
@@ -75,10 +75,10 @@ const groups = ['JavaScript', 'Native'] as const;
       <ComboboxPortal>
         <ComboboxContent
           :side-offset="6"
-          class="z-50 w-(--popper-anchor-width) overflow-hidden rounded-lg border border-(--border) bg-(--bg-elevated) shadow-lg"
+          class="z-50 w-(--popper-anchor-width) overflow-hidden rounded-lg border border-border bg-bg-elevated shadow-lg"
         >
           <ComboboxViewport class="max-h-60 p-1">
-            <ComboboxEmpty class="px-3 py-6 text-center text-sm text-(--fg-subtle)">
+            <ComboboxEmpty class="px-3 py-6 text-center text-sm text-fg-subtle">
               No frameworks found.
             </ComboboxEmpty>
 
@@ -88,7 +88,7 @@ const groups = ['JavaScript', 'Native'] as const;
               class="mb-1 last:mb-0"
             >
               <ComboboxLabel
-                class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-(--fg-subtle)"
+                class="demo-label px-2 py-1"
               >
                 {{ group }}
               </ComboboxLabel>
@@ -98,7 +98,7 @@ const groups = ['JavaScript', 'Native'] as const;
                 :key="framework.value"
                 :value="framework.value"
                 :text-value="framework.label"
-                class="flex cursor-pointer items-center justify-between rounded-md px-2 py-1.5 text-sm text-(--fg) outline-none data-[highlighted]:bg-(--accent) data-[highlighted]:text-(--accent-fg) data-[disabled]:opacity-50"
+                class="flex cursor-pointer items-center justify-between rounded-md px-2 py-1.5 text-sm text-fg outline-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-fg data-[disabled]:opacity-50"
               >
                 <span>{{ framework.label }}</span>
                 <ComboboxItemIndicator>
@@ -111,9 +111,9 @@ const groups = ['JavaScript', 'Native'] as const;
       </ComboboxPortal>
     </ComboboxRoot>
 
-    <p class="text-sm text-(--fg-muted)">
+    <p class="text-sm text-fg-muted">
       Selected:
-      <span class="font-medium text-(--fg)">{{ selected ? labelFor(selected) : 'none' }}</span>
+      <span class="font-medium text-fg">{{ selected ? labelFor(selected) : 'none' }}</span>
     </p>
   </div>
 </template>
diff --git a/vue/primitives/src/combobox/index.ts b/vue/primitives/src/selection/combobox/index.ts
similarity index 94%
rename from vue/primitives/src/combobox/index.ts
rename to vue/primitives/src/selection/combobox/index.ts
index 12e8346..cb20f5c 100644
--- a/vue/primitives/src/combobox/index.ts
+++ b/vue/primitives/src/selection/combobox/index.ts
@@ -31,6 +31,7 @@ export type {
   ComboboxRootContext,
 } from './context';
 
+export { accentInsensitiveContains } from './utils';
 export type { AcceptableValue, ComboboxFilterFunction, ComboboxFilterItem } from './utils';
 
 export type { ComboboxAnchorProps } from './ComboboxAnchor.vue';
@@ -42,7 +43,7 @@ export type { ComboboxEmptyProps } from './ComboboxEmpty.vue';
 export type { ComboboxGroupProps } from './ComboboxGroup.vue';
 export type { ComboboxInputProps } from './ComboboxInput.vue';
 export type { ComboboxItemIndicatorProps } from './ComboboxItemIndicator.vue';
-export type { ComboboxItemProps } from './ComboboxItem.vue';
+export type { ComboboxItemEmits, ComboboxItemProps, ComboboxItemSelectEvent } from './ComboboxItem.vue';
 export type { ComboboxLabelProps } from './ComboboxLabel.vue';
 export type { ComboboxPortalProps } from './ComboboxPortal.vue';
 export type { ComboboxRootEmits, ComboboxRootProps } from './ComboboxRoot.vue';
diff --git a/vue/primitives/src/selection/combobox/utils.ts b/vue/primitives/src/selection/combobox/utils.ts
new file mode 100644
index 0000000..48602e8
--- /dev/null
+++ b/vue/primitives/src/selection/combobox/utils.ts
@@ -0,0 +1,54 @@
+export type AcceptableValue = string | number | boolean | Record<string, unknown>;
+
+export const OPEN_KEYS = ['Enter', ' ', 'ArrowDown', 'ArrowUp', 'PageUp', 'PageDown', 'Home', 'End'];
+// The input is a text field: Space must type a space and Home/End/Page* must move
+// the caret, so only the arrow keys open a closed list (typing opens it via input).
+export const INPUT_OPEN_KEYS = ['ArrowDown', 'ArrowUp'];
+export const SELECTION_KEYS = ['Enter', ' '];
+
+export function getOpenState(open: boolean): 'open' | 'closed' {
+  return open ? 'open' : 'closed';
+}
+
+// `valueComparator` is listbox's `includes` under a combobox-specific name —
+// shared from ../utils/compare-values to avoid duplicating the comparison logic.
+export { includes as valueComparator } from '../../internal/utils/compare-values';
+
+export interface ComboboxFilterItem {
+  id: string;
+  textValue: string;
+}
+
+export type ComboboxFilterFunction = (
+  items: ComboboxFilterItem[],
+  searchTerm: string,
+) => ComboboxFilterItem[];
+
+/**
+ * Substring match that ignores case AND diacritics via Unicode canonical
+ * decomposition (`café` matches `cafe`), using only native `String.normalize`
+ * — no `Intl`/locale dependency, deterministic across runtimes.
+ */
+function foldAccents(value: string): string {
+  // NFD splits accented characters into base + combining marks; \p{M} (Unicode
+  // Mark) strips those marks, leaving the bare letters.
+  return value.normalize('NFD').replaceAll(/\p{M}/gu, '').toLowerCase();
+}
+
+/**
+ * Accent/diacritic-insensitive substring match. Reused by {@link defaultFilter}
+ * and exposed so a custom `filterFunction` can opt into the same folding.
+ */
+export function accentInsensitiveContains(haystack: string, needle: string): boolean {
+  return foldAccents(haystack).includes(foldAccents(needle));
+}
+
+export const defaultFilter: ComboboxFilterFunction = (items, searchTerm) => {
+  if (!searchTerm) return items;
+  const out: ComboboxFilterItem[] = [];
+  for (let i = 0; i < items.length; i++) {
+    const it = items[i]!;
+    if (accentInsensitiveContains(it.textValue, searchTerm)) out.push(it);
+  }
+  return out;
+};
diff --git a/vue/primitives/src/listbox/ListboxContent.vue b/vue/primitives/src/selection/listbox/ListboxContent.vue
similarity index 86%
rename from vue/primitives/src/listbox/ListboxContent.vue
rename to vue/primitives/src/selection/listbox/ListboxContent.vue
index 75334ef..f8fd311 100644
--- a/vue/primitives/src/listbox/ListboxContent.vue
+++ b/vue/primitives/src/selection/listbox/ListboxContent.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The scrollable list container (`role="listbox"`) that wraps the items. It
@@ -10,14 +10,14 @@ export interface ListboxContentProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { ref } from 'vue';
-import { useCollectionInjector } from '../collection';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
 import { useListboxRootContext } from './context';
 
 // Module-scoped to avoid re-allocating on every keydown.
-const NAV_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End']);
+const NAV_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown']);
 
 const { as = 'div' } = defineProps<ListboxContentProps>();
 
@@ -70,6 +70,8 @@ function onKeyDown(event: KeyboardEvent): void {
       @mousedown="onMouseDown"
       @focus="onFocus"
       @keydown="onKeyDown"
+      @compositionstart="ctx.onCompositionStart"
+      @compositionend="ctx.onCompositionEnd"
     >
       <slot />
     </Primitive>
diff --git a/vue/primitives/src/listbox/ListboxFilter.vue b/vue/primitives/src/selection/listbox/ListboxFilter.vue
similarity index 86%
rename from vue/primitives/src/listbox/ListboxFilter.vue
rename to vue/primitives/src/selection/listbox/ListboxFilter.vue
index 479f2f0..2d045d4 100644
--- a/vue/primitives/src/listbox/ListboxFilter.vue
+++ b/vue/primitives/src/selection/listbox/ListboxFilter.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * An optional text input for filtering the list. While mounted it takes over
@@ -20,16 +20,20 @@ export interface ListboxFilterProps extends PrimitiveProps {
 export interface ListboxFilterEmits {
   'update:modelValue': [value: string];
 }
+
+export interface ListboxFilterSlots {
+  default?: (props: { modelValue: string }) => unknown;
+}
 </script>
 
 <script setup lang="ts">
 import { computed, onMounted, onUnmounted, ref, watch, watchSyncEffect } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useListboxRootContext } from './context';
 
 // Module-scoped nav key set: avoids per-keydown array allocation.
-const NAV_KEYS = new Set(['ArrowUp', 'ArrowDown', 'Home', 'End']);
+const NAV_KEYS = new Set(['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown']);
 
 const {
   as = 'input',
@@ -39,6 +43,7 @@ const {
 } = defineProps<ListboxFilterProps>();
 
 const emit = defineEmits<ListboxFilterEmits>();
+defineSlots<ListboxFilterSlots>();
 
 const ctx = useListboxRootContext();
 const { forwardRef, currentElement } = useForwardExpose();
@@ -96,6 +101,8 @@ function onKeyDown(event: KeyboardEvent): void {
     :data-disabled="isDisabled ? '' : undefined"
     @input="onInput"
     @keydown="onKeyDown"
+    @compositionstart="ctx.onCompositionStart"
+    @compositionend="ctx.onCompositionEnd"
   >
     <slot :model-value="localValue" />
   </Primitive>
diff --git a/vue/primitives/src/listbox/ListboxGroup.vue b/vue/primitives/src/selection/listbox/ListboxGroup.vue
similarity index 80%
rename from vue/primitives/src/listbox/ListboxGroup.vue
rename to vue/primitives/src/selection/listbox/ListboxGroup.vue
index 6cf9256..8b64cce 100644
--- a/vue/primitives/src/listbox/ListboxGroup.vue
+++ b/vue/primitives/src/selection/listbox/ListboxGroup.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Groups related items under a shared label (`role="group"`). Wraps a set of
@@ -9,10 +9,10 @@ export interface ListboxGroupProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { provideListboxGroupContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
 const { as = 'div' } = defineProps<ListboxGroupProps>();
 
diff --git a/vue/primitives/src/listbox/ListboxGroupLabel.vue b/vue/primitives/src/selection/listbox/ListboxGroupLabel.vue
similarity index 84%
rename from vue/primitives/src/listbox/ListboxGroupLabel.vue
rename to vue/primitives/src/selection/listbox/ListboxGroupLabel.vue
index afa71e3..234cf07 100644
--- a/vue/primitives/src/listbox/ListboxGroupLabel.vue
+++ b/vue/primitives/src/selection/listbox/ListboxGroupLabel.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The accessible label for a `ListboxGroup`. Its id is wired to the group's
@@ -9,7 +9,7 @@ export interface ListboxGroupLabelProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useListboxGroupContext } from './context';
 
diff --git a/vue/primitives/src/listbox/ListboxItem.vue b/vue/primitives/src/selection/listbox/ListboxItem.vue
similarity index 82%
rename from vue/primitives/src/listbox/ListboxItem.vue
rename to vue/primitives/src/selection/listbox/ListboxItem.vue
index 31333a0..dea42fa 100644
--- a/vue/primitives/src/listbox/ListboxItem.vue
+++ b/vue/primitives/src/selection/listbox/ListboxItem.vue
@@ -1,6 +1,6 @@
 <script lang="ts" generic="T extends ListboxValue = ListboxValue">
 import type { ListboxValue } from './utils';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A single selectable option (`role="option"`). Clicking, pressing Space, or
@@ -12,6 +12,12 @@ export interface ListboxItemProps<U extends ListboxValue = ListboxValue> extends
   value: U;
   /** Disable this item. */
   disabled?: boolean;
+  /**
+   * Text used for type-ahead matching. Defaults to the item's `textContent`.
+   * Provide this when the visible text differs from what users will type
+   * (e.g. an item rendered with icons/markup).
+   */
+  textValue?: string;
 }
 
 export interface ListboxItemEmits<U extends ListboxValue = ListboxValue> {
@@ -22,13 +28,13 @@ export interface ListboxItemEmits<U extends ListboxValue = ListboxValue> {
 
 <script setup lang="ts" generic="T extends ListboxValue = ListboxValue">
 import { provideListboxItemContext, useListboxRootContext } from './context';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { computed } from 'vue';
-import { useCollectionInjector } from '../collection';
+import { useCollectionInjector } from '../../utilities/collection';
 import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
+import { useId } from '../../utilities/config-provider';
 
-const { as = 'div', value, disabled = false } = defineProps<ListboxItemProps<T>>();
+const { as = 'div', value, disabled = false, textValue } = defineProps<ListboxItemProps<T>>();
 const emit = defineEmits<ListboxItemEmits<T>>();
 
 const ctx = useListboxRootContext();
@@ -79,6 +85,7 @@ provideListboxItemContext({ isSelected });
       :data-state="isSelected ? 'checked' : 'unchecked'"
       :data-highlighted="isHighlighted ? '' : undefined"
       :data-disabled="isDisabled ? '' : undefined"
+      :data-text-value="textValue || undefined"
       :disabled="isDisabled || undefined"
       @click="onClick"
       @keydown="onKeyDown"
diff --git a/vue/primitives/src/listbox/ListboxItemIndicator.vue b/vue/primitives/src/selection/listbox/ListboxItemIndicator.vue
similarity index 85%
rename from vue/primitives/src/listbox/ListboxItemIndicator.vue
rename to vue/primitives/src/selection/listbox/ListboxItemIndicator.vue
index 350d50b..779fd10 100644
--- a/vue/primitives/src/listbox/ListboxItemIndicator.vue
+++ b/vue/primitives/src/selection/listbox/ListboxItemIndicator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Renders its content only when the parent `ListboxItem` is selected. Use it
@@ -9,7 +9,7 @@ export interface ListboxItemIndicatorProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 import { useListboxItemContext } from './context';
 
diff --git a/vue/primitives/src/listbox/ListboxRoot.vue b/vue/primitives/src/selection/listbox/ListboxRoot.vue
similarity index 55%
rename from vue/primitives/src/listbox/ListboxRoot.vue
rename to vue/primitives/src/selection/listbox/ListboxRoot.vue
index ddeb58f..3501b3a 100644
--- a/vue/primitives/src/listbox/ListboxRoot.vue
+++ b/vue/primitives/src/selection/listbox/ListboxRoot.vue
@@ -1,18 +1,19 @@
 <script lang="ts" generic="T extends ListboxValue = ListboxValue">
 import type { ListboxDirection, ListboxOrientation, ListboxSelectionBehavior } from './context';
 import type { ListboxValue } from './utils';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A list of selectable options that supports single or multiple selection,
- * full keyboard navigation (arrows, Home/End, type-ahead), and optional
- * hover highlighting. Use it when you need an always-visible selection list
- * — picking from a set of values, building a custom multi-select, or as the
- * options surface inside a larger widget.
+ * full keyboard navigation (arrows, Home/End, PageUp/PageDown, type-ahead),
+ * Shift-range selection, and optional hover highlighting. Use it when you need
+ * an always-visible selection list — picking from a set of values, building a
+ * custom multi-select, or as the options surface inside a larger widget.
  *
  * The root owns selection state (controlled via `v-model` or uncontrolled
- * via `defaultValue`), the highlighted item, orientation/direction, and
- * provides context to every descendant part.
+ * via `defaultValue`), the highlighted item, orientation/direction, optional
+ * native-form integration (`name`/`required`), and provides context to every
+ * descendant part.
  */
 export interface ListboxRootProps<U extends ListboxValue = ListboxValue> extends PrimitiveProps {
   /** Uncontrolled initial value. */
@@ -31,6 +32,10 @@ export interface ListboxRootProps<U extends ListboxValue = ListboxValue> extends
   highlightOnHover?: boolean;
   /** Compare objects by key or custom comparator. */
   by?: string | ((a: U, b: U) => boolean);
+  /** Native input name for form submission. When set, a hidden input mirrors the value. */
+  name?: string;
+  /** Mark as required for native form validation. */
+  required?: boolean;
 }
 
 export interface ListboxRootEmits<U extends ListboxValue = ListboxValue> {
@@ -38,18 +43,23 @@ export interface ListboxRootEmits<U extends ListboxValue = ListboxValue> {
   entryFocus: [event: CustomEvent];
   leave: [event: Event];
 }
+
+export interface ListboxRootSlots<U extends ListboxValue = ListboxValue> {
+  default?: (props: { modelValue: U | U[] | undefined }) => unknown;
+}
 </script>
 
 <script setup lang="ts" generic="T extends ListboxValue = ListboxValue">
-import { compare, includes } from './utils';
+import { compareDeep, findValuesBetween, getNextMatch, includesDeep } from './utils';
 import { computed, nextTick, ref, shallowRef, toRef, watch } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { Primitive } from '../primitive';
+import { resolveNextIndex, rovingKeyToAction } from '../../internal/utils/roving-focus';
+import { Primitive } from '../../internal/primitive';
 import type { Ref } from 'vue';
 import { provideListboxRootContext } from './context';
-import { useCollectionProvider } from '../collection';
-import { useConfig } from '../config-provider';
-import { useForwardExpose } from '@robonen/vue';
+import { useCollectionProvider } from '../../utilities/collection';
+import { useConfig } from '../../utilities/config-provider';
+import { refAutoReset, useForwardExpose } from '@robonen/vue';
+import { VisuallyHiddenInput } from '../../utilities/visually-hidden';
 
 const {
   as = 'div',
@@ -61,13 +71,15 @@ const {
   selectionBehavior = 'toggle',
   highlightOnHover = false,
   by,
+  name,
+  required = false,
 } = defineProps<ListboxRootProps<T>>();
 
 const emit = defineEmits<ListboxRootEmits<T>>();
+defineSlots<ListboxRootSlots<T>>();
 
 const model = defineModel<T | T[] | undefined>();
 
-const { forwardRef, currentElement } = useForwardExpose();
 const config = useConfig();
 const direction = computed(() => dir ?? config.dir.value);
 
@@ -96,7 +108,7 @@ watch(model, (v) => {
     localValue.value = v.slice();
   }
   else if (v !== cur) {
-    localValue.value = v as any;
+    localValue.value = v as T | T[];
   }
 });
 
@@ -104,6 +116,9 @@ const highlightedElement = shallowRef<HTMLElement>();
 const previousElement = shallowRef<HTMLElement>();
 const focusable = ref(true);
 const isUserAction = ref(false);
+const isComposing = ref(false);
+// Anchor for Shift-range selection (multiple + replace).
+const firstValue = shallowRef<T>();
 
 const { getItems } = useCollectionProvider();
 
@@ -120,7 +135,26 @@ function enabledEls(): HTMLElement[] {
 }
 
 function isSelected(value: T): boolean {
-  return includes(localValue.value, value, by);
+  return includesDeep(localValue.value, value, by);
+}
+
+// Buffered multi-character type-ahead: accumulates keystrokes, resets ~1s after
+// the last one. Repeated single characters cycle through matches; longer
+// buffers match by prefix. An item may override its match text via
+// `data-text-value` (set by `ListboxItem`'s `textValue` prop).
+const searchBuffer = refAutoReset('', 1000);
+function textOf(el: HTMLElement): string {
+  return el.dataset.textValue ?? el.textContent?.trim() ?? '';
+}
+function typeAheadMatch(key: string): HTMLElement | undefined {
+  const els = enabledEls();
+  if (els.length === 0) return undefined;
+  searchBuffer.value += key;
+  const values = els.map(textOf);
+  const current = highlightedElement.value ? textOf(highlightedElement.value) : undefined;
+  const next = getNextMatch(values, searchBuffer.value, current);
+  if (next === undefined) return undefined;
+  return els[values.indexOf(next)];
 }
 
 function commit(next: T | T[] | undefined): void {
@@ -133,17 +167,18 @@ function onValueChange(val: T): void {
   if (multiple) {
     const cur = Array.isArray(localValue.value) ? [...(localValue.value as T[])] : [];
     if (selectionBehavior === 'toggle') {
-      const idx = cur.findIndex(i => compare(i, val, by));
+      const idx = cur.findIndex(i => compareDeep(i, val, by));
       if (idx === -1) cur.push(val);
       else cur.splice(idx, 1);
       commit(cur);
     }
     else {
+      firstValue.value = val;
       commit([val]);
     }
   }
   else if (selectionBehavior === 'toggle') {
-    commit(compare(localValue.value as T | undefined, val, by) ? undefined : val);
+    commit(compareDeep(localValue.value as T | undefined, val, by) ? undefined : val);
   }
   else {
     commit(val);
@@ -161,7 +196,14 @@ function changeHighlight(el: HTMLElement | undefined, scrollIntoView = true, foc
   if (focus ?? focusable.value) el.focus({ preventScroll: !scrollIntoView });
   if (scrollIntoView) el.scrollIntoView({ block: 'nearest' });
   const hit = getItems(true).find(i => i.ref === el);
-  emit('highlight', hit as any);
+  // getItems is untyped (CollectionItemData<unknown>); a matched item always
+  // carries a value, so assert the emit payload shape rather than widen to any.
+  emit('highlight', hit as { ref: HTMLElement; value: T } | undefined);
+}
+
+function highlightItem(value: T): void {
+  const item = getItems(true).find(i => compareDeep(i.value as T, value, by));
+  if (item) changeHighlight(item.ref);
 }
 
 function onKeydownEnter(event: KeyboardEvent): void {
@@ -169,30 +211,68 @@ function onKeydownEnter(event: KeyboardEvent): void {
   if (!el || !el.isConnected) return;
   event.preventDefault();
   event.stopPropagation();
+  // Do not commit a selection while an IME composition is in progress.
+  if (isComposing.value) return;
   el.click();
 }
 
+// Apply contiguous range selection for multiple + replace mode on Shift+navigation.
+// `targetEl` is the element the highlight is about to move to.
+function handleMultipleReplace(event: KeyboardEvent, targetEl: HTMLElement | undefined): void {
+  if (selectionBehavior !== 'replace' || !multiple || !Array.isArray(localValue.value)) return;
+  const isMetaKey = event.altKey || event.ctrlKey || event.metaKey;
+  if (isMetaKey && !event.shiftKey) return;
+  if (!event.shiftKey) return;
+
+  const collection = enabledEls();
+  const itemOf = (el: HTMLElement | undefined) => getItems(true).find(i => i.ref === el)?.value as T | undefined;
+
+  let lastValue = itemOf(targetEl);
+  if (event.key === 'End' || event.key === 'PageDown') lastValue = itemOf(collection.at(-1));
+  else if (event.key === 'Home' || event.key === 'PageUp') lastValue = itemOf(collection[0]);
+
+  if (lastValue === undefined || firstValue.value === undefined) return;
+
+  const allValues = getItems(true).map(i => i.value as T);
+  const values = findValuesBetween(allValues, firstValue.value, lastValue, by);
+  commit(values);
+}
+
 function onKeydownNavigation(event: KeyboardEvent): void {
   const intent = rovingKeyToAction(event, { orientation, dir: direction.value, loop: false });
-  if (!intent) return;
+  // Page keys jump to first/last regardless of orientation.
+  const isPageUp = event.key === 'PageUp';
+  const isPageDown = event.key === 'PageDown';
+  if (!intent && !isPageUp && !isPageDown) return;
+
   const els = enabledEls();
   if (els.length === 0) return;
 
-  if (intent.absolute === 'home') return changeHighlight(els[0]);
-  if (intent.absolute === 'end') return changeHighlight(els[els.length - 1]);
-
-  const current = highlightedElement.value;
-  const idx = current ? els.indexOf(current) : -1;
-  if (idx === -1) {
-    changeHighlight(intent.delta < 0 ? els[els.length - 1] : els[0]);
-    return;
+  let target: HTMLElement | undefined;
+  if (isPageUp || intent?.absolute === 'home') {
+    target = els[0];
   }
-  const next = resolveNextIndex(idx, intent.delta, els.length, false);
-  changeHighlight(els[next]);
+  else if (isPageDown || intent?.absolute === 'end') {
+    target = els[els.length - 1];
+  }
+  else {
+    const current = highlightedElement.value;
+    const idx = current ? els.indexOf(current) : -1;
+    if (idx === -1) {
+      target = intent!.delta < 0 ? els[els.length - 1] : els[0];
+    }
+    else {
+      target = els[resolveNextIndex(idx, intent!.delta, els.length, false)];
+    }
+  }
+
+  handleMultipleReplace(event, target);
+  changeHighlight(target);
 }
 
 function onKeydownTypeAhead(event: KeyboardEvent): void {
   if (!focusable.value) return;
+  isUserAction.value = true;
   if (event.altKey || event.ctrlKey || event.metaKey) {
     if (event.key.toLowerCase() === 'a' && multiple) {
       const all = getItems(true).map(i => i.value) as T[];
@@ -201,22 +281,18 @@ function onKeydownTypeAhead(event: KeyboardEvent): void {
       const last = enabledEls().at(-1);
       if (last) changeHighlight(last);
     }
+    nextTick(() => {
+      isUserAction.value = false;
+    });
     return;
   }
-  if (event.key.length !== 1) return;
-  const letter = event.key.toLowerCase();
-  const els = enabledEls();
-  const len = els.length;
-  if (len === 0) return;
-  const start = highlightedElement.value ? els.indexOf(highlightedElement.value) + 1 : 0;
-  for (let i = 0; i < len; i++) {
-    const el = els[(start + i) % len]!;
-    const text = el.textContent;
-    if (text && text.trim().toLowerCase().startsWith(letter)) {
-      changeHighlight(el);
-      return;
-    }
+  if (event.key.length === 1) {
+    const el = typeAheadMatch(event.key);
+    if (el) changeHighlight(el);
   }
+  nextTick(() => {
+    isUserAction.value = false;
+  });
 }
 
 function highlightFirstItem(): void {
@@ -226,6 +302,15 @@ function highlightFirstItem(): void {
   });
 }
 
+function onCompositionStart(): void {
+  isComposing.value = true;
+}
+function onCompositionEnd(): void {
+  nextTick(() => {
+    isComposing.value = false;
+  });
+}
+
 function onLeave(event: Event): void {
   const el = highlightedElement.value;
   if (el?.isConnected) previousElement.value = el;
@@ -257,9 +342,7 @@ async function onFocusOut(event: FocusEvent): Promise<void> {
   }
 }
 
-// localValue is always replaced on commit — no need for deep traversal.
-watch(localValue, () => {
-  if (isUserAction.value) return;
+function highlightSelected(): void {
   nextTick(() => {
     const els = enabledEls();
     for (let i = 0; i < els.length; i++) {
@@ -269,6 +352,12 @@ watch(localValue, () => {
       }
     }
   });
+}
+
+// localValue is always replaced on commit — no need for deep traversal.
+watch(localValue, () => {
+  if (isUserAction.value) return;
+  highlightSelected();
 }, { immediate: true });
 
 provideListboxRootContext({
@@ -281,6 +370,7 @@ provideListboxRootContext({
   selectionBehavior: toRef(() => selectionBehavior),
   highlightedElement,
   focusable,
+  firstValue,
   by,
   onValueChange,
   isSelected,
@@ -291,7 +381,27 @@ provideListboxRootContext({
   highlightFirstItem,
   onEnter,
   onLeave,
+  onCompositionStart,
+  onCompositionEnd,
 });
+
+// Expose the imperative API before `useForwardExpose` so the latter merges it
+// into the forwarded expose (it reads `instance.exposed`), keeping both the
+// element ref-forwarding and the imperative API without calling expose() twice.
+defineExpose({
+  /** The currently highlighted DOM element (or `undefined`). */
+  highlightedElement,
+  /** Highlight the item whose value matches `value` (uses `by` comparator). */
+  highlightItem,
+  /** Highlight the first enabled item. */
+  highlightFirstItem,
+  /** Re-highlight the currently selected item (or the first one). */
+  highlightSelected,
+  /** Returns the collection items in DOM order. */
+  getItems,
+});
+
+const { forwardRef, currentElement } = useForwardExpose();
 </script>
 
 <template>
@@ -304,5 +414,13 @@ provideListboxRootContext({
     @focusout="onFocusOut"
   >
     <slot :model-value="localValue" />
+
+    <VisuallyHiddenInput
+      v-if="name"
+      :name="name"
+      :value="localValue"
+      :disabled="disabled"
+      :required="required"
+    />
   </Primitive>
 </template>
diff --git a/vue/primitives/src/listbox/__test__/Listbox.test.ts b/vue/primitives/src/selection/listbox/__test__/Listbox.test.ts
similarity index 51%
rename from vue/primitives/src/listbox/__test__/Listbox.test.ts
rename to vue/primitives/src/selection/listbox/__test__/Listbox.test.ts
index 77048d1..ea3509a 100644
--- a/vue/primitives/src/listbox/__test__/Listbox.test.ts
+++ b/vue/primitives/src/selection/listbox/__test__/Listbox.test.ts
@@ -47,8 +47,8 @@ function createListbox(
   );
 }
 
-function press(el: Element, key: string) {
-  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+function press(el: Element, key: string, init: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
 }
 
 describe('Listbox', () => {
@@ -229,4 +229,193 @@ describe('Listbox', () => {
     expect(input.getAttribute('aria-activedescendant')).toBe(firstItem.attributes('id'));
     w.unmount();
   });
+
+  it('PageUp/PageDown jump to first/last item', async () => {
+    const w = createListbox();
+    const list = w.find('[role="listbox"]').element as HTMLElement;
+    list.focus();
+    await nextTick();
+    press(list, 'PageDown');
+    await nextTick();
+    const items = w.findAll('[role="option"]');
+    expect(items[2]!.attributes('data-highlighted')).toBe('');
+    press(list, 'PageUp');
+    await nextTick();
+    expect(items[0]!.attributes('data-highlighted')).toBe('');
+    w.unmount();
+  });
+
+  it('Ctrl+A selects all in multiple mode', async () => {
+    const w = createListbox({ multiple: true });
+    const list = w.find('[role="listbox"]').element as HTMLElement;
+    list.focus();
+    await nextTick();
+    press(list, 'a', { ctrlKey: true });
+    await nextTick();
+    const items = w.findAll('[role="option"]');
+    expect(items[0]!.attributes('data-state')).toBe('checked');
+    expect(items[1]!.attributes('data-state')).toBe('checked');
+    expect(items[2]!.attributes('data-state')).toBe('checked');
+    w.unmount();
+  });
+
+  it('Shift+ArrowDown selects a contiguous range (multiple + replace)', async () => {
+    const w = createListbox(
+      { multiple: true, selectionBehavior: 'replace' },
+      ['A', 'B', 'C', 'D'],
+    );
+    const items = w.findAll('[role="option"]');
+    // Click sets the range anchor.
+    await items[0]!.trigger('click');
+    await nextTick();
+    const list = w.find('[role="listbox"]').element as HTMLElement;
+    press(list, 'ArrowDown', { shiftKey: true });
+    await nextTick();
+    expect(items[0]!.attributes('data-state')).toBe('checked');
+    expect(items[1]!.attributes('data-state')).toBe('checked');
+    expect(items[2]!.attributes('data-state')).toBe('unchecked');
+    w.unmount();
+  });
+
+  it('Shift+End selects a range to the last item (multiple + replace)', async () => {
+    const w = createListbox(
+      { multiple: true, selectionBehavior: 'replace' },
+      ['A', 'B', 'C', 'D'],
+    );
+    const items = w.findAll('[role="option"]');
+    await items[1]!.trigger('click');
+    await nextTick();
+    const list = w.find('[role="listbox"]').element as HTMLElement;
+    press(list, 'End', { shiftKey: true });
+    await nextTick();
+    expect(items[0]!.attributes('data-state')).toBe('unchecked');
+    expect(items[1]!.attributes('data-state')).toBe('checked');
+    expect(items[2]!.attributes('data-state')).toBe('checked');
+    expect(items[3]!.attributes('data-state')).toBe('checked');
+    w.unmount();
+  });
+
+  it('buffered multi-character typeahead matches by prefix', async () => {
+    const w = createListbox({}, ['Apricot', 'Apple', 'Avocado']);
+    const list = w.find('[role="listbox"]').element as HTMLElement;
+    list.focus();
+    await nextTick();
+    press(list, 'a');
+    press(list, 'p');
+    press(list, 'p');
+    await nextTick();
+    const items = w.findAll('[role="option"]');
+    // "app" should land on "Apple", not "Apricot".
+    expect(items[1]!.attributes('data-highlighted')).toBe('');
+    w.unmount();
+  });
+
+  it('typeahead honours the textValue override', async () => {
+    const w = mount(
+      defineComponent({
+        setup: () => () =>
+          h(ListboxRoot, null, {
+            default: () => h(ListboxContent, null, {
+              default: () => [
+                h(ListboxItem, { value: 'a', textValue: 'Zebra' }, { default: () => '🦓 Animal' }),
+                h(ListboxItem, { value: 'b', textValue: 'Apple' }, { default: () => '🍎 Fruit' }),
+              ],
+            }),
+          }),
+      }),
+      { attachTo: document.body },
+    );
+    const list = w.find('[role="listbox"]').element as HTMLElement;
+    list.focus();
+    await nextTick();
+    press(list, 'z');
+    await nextTick();
+    const items = w.findAll('[role="option"]');
+    expect(items[0]!.attributes('data-highlighted')).toBe('');
+    w.unmount();
+  });
+
+  it('selects structurally-equal object values without `by`', async () => {
+    const options = [{ id: 1, label: 'One' }, { id: 2, label: 'Two' }];
+    const w = mount(
+      defineComponent({
+        setup: () => () =>
+          h(ListboxRoot, { defaultValue: { id: 2, label: 'Two' } }, {
+            default: () => h(ListboxContent, null, {
+              default: () => options.map(o =>
+                h(ListboxItem, { key: o.id, value: o }, { default: () => o.label }),
+              ),
+            }),
+          }),
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    const items = w.findAll('[role="option"]');
+    // A different object instance with the same shape is still recognised.
+    expect(items[1]!.attributes('data-state')).toBe('checked');
+    expect(items[0]!.attributes('data-state')).toBe('unchecked');
+    w.unmount();
+  });
+
+  it('renders a hidden form input mirroring the value when name is set', async () => {
+    const w = createListbox({ name: 'fruit', defaultValue: 'Banana' });
+    await nextTick();
+    const hidden = w.find('input[name="fruit"]');
+    expect(hidden.exists()).toBe(true);
+    expect((hidden.element as HTMLInputElement).value).toBe('Banana');
+    w.unmount();
+  });
+
+  it('does not render a hidden input without a name', () => {
+    const w = createListbox({ defaultValue: 'Banana' });
+    expect(w.find('input').exists()).toBe(false);
+    w.unmount();
+  });
+
+  it('exposes an imperative API on the root', async () => {
+    const rootRef = ref<{ highlightItem: (v: ListboxValue) => void; getItems: () => unknown[]; highlightedElement: unknown } | null>(null);
+    const w = mount(
+      defineComponent({
+        setup: () => () =>
+          h(ListboxRoot, { ref: rootRef }, {
+            default: () => h(ListboxContent, null, {
+              default: () => ['Apple', 'Banana', 'Cherry'].map(o =>
+                h(ListboxItem, { key: o, value: o }, { default: () => o }),
+              ),
+            }),
+          }),
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    expect(typeof rootRef.value!.highlightItem).toBe('function');
+    expect(rootRef.value!.getItems().length).toBe(3);
+    rootRef.value!.highlightItem('Cherry');
+    await nextTick();
+    const items = w.findAll('[role="option"]');
+    expect(items[2]!.attributes('data-highlighted')).toBe('');
+    w.unmount();
+  });
+
+  it('Enter mid IME composition does not commit a selection', async () => {
+    const w = createListbox();
+    const list = w.find('[role="listbox"]').element as HTMLElement;
+    list.focus();
+    await nextTick();
+    press(list, 'End');
+    await nextTick();
+    list.dispatchEvent(new CompositionEvent('compositionstart', { bubbles: true }));
+    press(list, 'Enter');
+    await nextTick();
+    const items = w.findAll('[role="option"]');
+    expect(items[2]!.attributes('data-state')).toBe('unchecked');
+    // After composition ends, Enter commits again.
+    list.dispatchEvent(new CompositionEvent('compositionend', { bubbles: true }));
+    await nextTick();
+    press(list, 'Enter');
+    await nextTick();
+    expect(items[2]!.attributes('data-state')).toBe('checked');
+    w.unmount();
+  });
 });
diff --git a/vue/primitives/src/listbox/context.ts b/vue/primitives/src/selection/listbox/context.ts
similarity index 75%
rename from vue/primitives/src/listbox/context.ts
rename to vue/primitives/src/selection/listbox/context.ts
index 7234efc..b2b3a80 100644
--- a/vue/primitives/src/listbox/context.ts
+++ b/vue/primitives/src/selection/listbox/context.ts
@@ -16,6 +16,8 @@ export interface ListboxRootContext<T extends ListboxValue = ListboxValue> {
   selectionBehavior: Ref<ListboxSelectionBehavior>;
   highlightedElement: ShallowRef<HTMLElement | undefined>;
   focusable: Ref<boolean>;
+  /** Anchor value for Shift-range selection in `multiple` + `replace` mode. */
+  firstValue: ShallowRef<T | undefined>;
   by?: string | ((a: T, b: T) => boolean);
 
   onValueChange: (value: T) => void;
@@ -27,6 +29,9 @@ export interface ListboxRootContext<T extends ListboxValue = ListboxValue> {
   highlightFirstItem: () => void;
   onEnter: (event: Event) => void;
   onLeave: (event: Event) => void;
+  /** IME composition guards so Enter mid-composition does not commit a selection. */
+  onCompositionStart: () => void;
+  onCompositionEnd: () => void;
 }
 
 export interface ListboxItemContext {
@@ -37,6 +42,10 @@ export interface ListboxGroupContext {
   id: string;
 }
 
+// `any` (not `ListboxValue`): the generic `ListboxRoot` provides a
+// `ListboxRootContext<T>` whose contravariant callbacks ((value: T) => void) are
+// not assignable to the concrete `ListboxValue` instantiation. `any` is the
+// type-erasure boundary letting the generic root provide and descendants inject.
 export const {
   inject: useListboxRootContext,
   provide: provideListboxRootContext,
diff --git a/vue/primitives/src/listbox/demo.vue b/vue/primitives/src/selection/listbox/demo.vue
similarity index 75%
rename from vue/primitives/src/listbox/demo.vue
rename to vue/primitives/src/selection/listbox/demo.vue
index a2f0a09..8daaa65 100644
--- a/vue/primitives/src/listbox/demo.vue
+++ b/vue/primitives/src/selection/listbox/demo.vue
@@ -51,20 +51,20 @@ function labelFor(value: string) {
       v-model="selected"
       multiple
       highlight-on-hover
-      class="overflow-hidden rounded-lg border border-(--border) bg-(--bg-elevated)"
+      class="overflow-hidden rounded-lg border border-border bg-bg-elevated"
     >
-      <div class="border-b border-(--border) p-2">
+      <div class="border-b border-border p-2">
         <ListboxFilter
           v-model="query"
           placeholder="Filter fruit..."
-          class="w-full rounded-md border border-(--border) bg-(--bg-inset) px-2.5 py-1.5 text-sm text-(--fg) outline-none placeholder:text-(--fg-subtle) focus:border-(--accent) focus:ring-2 focus:ring-(--ring)"
+          class="w-full rounded-md border border-border bg-bg-inset px-2.5 py-1.5 text-sm text-fg outline-none placeholder:text-fg-subtle focus:border-accent focus:ring-2 focus:ring-ring"
         />
       </div>
 
       <ListboxContent class="max-h-64 overflow-y-auto p-1 outline-none">
         <p
           v-if="filtered.length === 0"
-          class="px-3 py-6 text-center text-sm text-(--fg-subtle)"
+          class="px-3 py-6 text-center text-sm text-fg-subtle"
         >
           No fruit found.
         </p>
@@ -76,7 +76,7 @@ function labelFor(value: string) {
           class="mb-1 last:mb-0"
         >
           <ListboxGroupLabel
-            class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-(--fg-subtle)"
+            class="demo-label px-2 py-1"
           >
             {{ group }}
           </ListboxGroupLabel>
@@ -85,10 +85,10 @@ function labelFor(value: string) {
             v-for="fruit in itemsFor(group)"
             :key="fruit.value"
             :value="fruit.value"
-            class="flex cursor-pointer items-center justify-between rounded-md px-2 py-1.5 text-sm text-(--fg) outline-none data-[highlighted]:bg-(--bg-subtle) data-[state=checked]:text-(--accent) data-[disabled]:opacity-50"
+            class="flex cursor-pointer items-center justify-between rounded-md px-2 py-1.5 text-sm text-fg outline-none data-[highlighted]:bg-bg-subtle data-[state=checked]:text-accent data-[disabled]:opacity-50"
           >
             <span>{{ fruit.label }}</span>
-            <ListboxItemIndicator class="text-(--accent)">
+            <ListboxItemIndicator class="text-accent">
               <span aria-hidden="true">✓</span>
             </ListboxItemIndicator>
           </ListboxItem>
@@ -96,9 +96,9 @@ function labelFor(value: string) {
       </ListboxContent>
     </ListboxRoot>
 
-    <p class="text-sm text-(--fg-muted)">
+    <p class="text-sm text-fg-muted">
       Selected:
-      <span class="font-medium text-(--fg)">
+      <span class="font-medium text-fg">
         {{ selected.length ? selected.map(labelFor).join(', ') : 'none' }}
       </span>
     </p>
diff --git a/vue/primitives/src/listbox/index.ts b/vue/primitives/src/selection/listbox/index.ts
similarity index 72%
rename from vue/primitives/src/listbox/index.ts
rename to vue/primitives/src/selection/listbox/index.ts
index c0a5981..45c1c62 100644
--- a/vue/primitives/src/listbox/index.ts
+++ b/vue/primitives/src/selection/listbox/index.ts
@@ -21,12 +21,19 @@ export {
   type ListboxSelectionBehavior,
 } from './context';
 
-export { compare as compareListboxValues, includes as includesListboxValue, type ListboxValue } from './utils';
+export {
+  compare as compareListboxValues,
+  includes as includesListboxValue,
+  compareDeep as compareListboxValuesDeep,
+  includesDeep as includesListboxValueDeep,
+  findValuesBetween as findListboxValuesBetween,
+  type ListboxValue,
+} from './utils';
 
-export type { ListboxRootProps, ListboxRootEmits } from './ListboxRoot.vue';
+export type { ListboxRootProps, ListboxRootEmits, ListboxRootSlots } from './ListboxRoot.vue';
 export type { ListboxContentProps } from './ListboxContent.vue';
 export type { ListboxItemProps, ListboxItemEmits } from './ListboxItem.vue';
 export type { ListboxItemIndicatorProps } from './ListboxItemIndicator.vue';
 export type { ListboxGroupProps } from './ListboxGroup.vue';
 export type { ListboxGroupLabelProps } from './ListboxGroupLabel.vue';
-export type { ListboxFilterProps, ListboxFilterEmits } from './ListboxFilter.vue';
+export type { ListboxFilterProps, ListboxFilterEmits, ListboxFilterSlots } from './ListboxFilter.vue';
diff --git a/vue/primitives/src/selection/listbox/utils.ts b/vue/primitives/src/selection/listbox/utils.ts
new file mode 100644
index 0000000..3f6b624
--- /dev/null
+++ b/vue/primitives/src/selection/listbox/utils.ts
@@ -0,0 +1,123 @@
+export type ListboxValue = string | number | boolean | Record<string, unknown>;
+
+// `compare`/`includes` are shared with the combobox primitive — see ../utils/compare-values.
+// Re-exported here so listbox/index.ts can surface them as compareListboxValues/includesListboxValue.
+export { compare, includes } from '../../internal/utils/compare-values';
+
+/**
+ * Structural deep equality for option values. Used as a fallback when no `by`
+ * comparator/key is supplied and the values are non-primitive objects, so two
+ * structurally-equal object values are recognised as the same selection
+ * without forcing consumers to pass `by`. Kept local (no external dependency)
+ * and intentionally small — option values are shallow plain objects/arrays.
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
+
+  const aArray = Array.isArray(a);
+  const bArray = Array.isArray(b);
+  if (aArray !== bArray) return false;
+
+  if (aArray && bArray) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  const aKeys = Object.keys(a as Record<string, unknown>);
+  const bKeys = Object.keys(b as Record<string, unknown>);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * Like {@link compare} from `../utils/compare-values`, but when `by` is omitted
+ * and the values are objects it falls back to structural deep equality instead
+ * of reference equality. Strings/numbers/booleans keep `===` semantics.
+ */
+export function compareDeep<T>(
+  a: T | undefined,
+  b: T | undefined,
+  by?: string | ((x: T, y: T) => boolean),
+): boolean {
+  if (a === undefined || b === undefined) return false;
+  if (typeof by === 'function') return by(a, b);
+  if (typeof by === 'string') return (a as Record<string, unknown>)?.[by] === (b as Record<string, unknown>)?.[by];
+  if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
+    return deepEqual(a, b);
+  }
+  return a === b;
+}
+
+/** Whether `current` is contained in `value`, using {@link compareDeep}. */
+export function includesDeep<T>(
+  value: T | T[] | undefined,
+  current: T,
+  by?: string | ((x: T, y: T) => boolean),
+): boolean {
+  if (value === undefined) return false;
+  if (!Array.isArray(value)) return compareDeep(value, current, by);
+  for (const v of value) {
+    if (compareDeep(v, current, by)) return true;
+  }
+  return false;
+}
+
+/**
+ * Returns the contiguous slice of `array` between the first occurrences of
+ * `start` and `end` (inclusive), regardless of their order. Empty if either is
+ * missing. Powers Shift+Arrow/Home/End contiguous range selection.
+ */
+export function findValuesBetween<T>(
+  array: T[],
+  start: T,
+  end: T,
+  by?: string | ((x: T, y: T) => boolean),
+): T[] {
+  const startIndex = array.findIndex(i => compareDeep(i, start, by));
+  const endIndex = array.findIndex(i => compareDeep(i, end, by));
+  if (startIndex === -1 || endIndex === -1) return [];
+  const min = Math.min(startIndex, endIndex);
+  const max = Math.max(startIndex, endIndex);
+  return array.slice(min, max + 1);
+}
+
+/**
+ * Rotates `array` so it starts at `startIndex`, wrapping around.
+ * `wrapArray(['a','b','c','d'], 2) === ['c','d','a','b']`.
+ */
+export function wrapArray<T>(array: T[], startIndex: number): T[] {
+  const len = array.length;
+  const out: T[] = Array.from({ length: len });
+  for (let i = 0; i < len; i++) out[i] = array[(startIndex + i) % len]!;
+  return out;
+}
+
+/**
+ * Core type-ahead matcher. Given the list of item text values, the accumulated
+ * `search` buffer, and the current match, returns the next item text to focus
+ * (or `undefined`). Repeated single characters cycle through matches; longer
+ * buffers match by prefix without excluding the current item.
+ */
+export function getNextMatch(
+  values: string[],
+  search: string,
+  currentMatch?: string,
+): string | undefined {
+  const isRepeated = search.length > 1 && Array.from(search).every(c => c === search[0]);
+  const normalizedSearch = isRepeated ? search[0]! : search;
+  const currentMatchIndex = currentMatch ? values.indexOf(currentMatch) : -1;
+  let wrapped = wrapArray(values, Math.max(currentMatchIndex, 0));
+  const excludeCurrentMatch = normalizedSearch.length === 1;
+  if (excludeCurrentMatch) wrapped = wrapped.filter(v => v !== currentMatch);
+  const lower = normalizedSearch.toLowerCase();
+  const nextMatch = wrapped.find(v => v.toLowerCase().startsWith(lower));
+  return nextMatch !== currentMatch ? nextMatch : undefined;
+}
diff --git a/vue/primitives/src/select/SelectArrow.vue b/vue/primitives/src/selection/select/SelectArrow.vue
similarity index 53%
rename from vue/primitives/src/select/SelectArrow.vue
rename to vue/primitives/src/selection/select/SelectArrow.vue
index 59df716..0878f75 100644
--- a/vue/primitives/src/select/SelectArrow.vue
+++ b/vue/primitives/src/selection/select/SelectArrow.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperArrowProps } from '../popper';
+import type { PopperArrowProps } from '../../overlays/popper';
 
 /**
  * An optional arrow that points from the content back to the trigger. Only
@@ -10,16 +10,24 @@ export type SelectArrowProps = PopperArrowProps;
 </script>
 
 <script setup lang="ts">
-import { useForwardExpose } from '@robonen/vue';
+import { computed } from 'vue';
 
-import { PopperArrow } from '../popper';
+import { useForwardExpose } from '@robonen/vue';
+import { PopperArrow } from '../../overlays/popper';
+import { useSelectContentContext } from './context';
 
 const props = defineProps<SelectArrowProps>();
 const { forwardRef } = useForwardExpose();
+
+const contentCtx = useSelectContentContext();
+// The arrow only makes sense with `position="popper"`; it relies on popper
+// placement, so it is a no-op in `item-aligned` mode.
+const shouldRender = computed(() => contentCtx.position === 'popper');
 </script>
 
 <template>
   <PopperArrow
+    v-if="shouldRender"
     :ref="forwardRef"
     v-bind="props"
   />
diff --git a/vue/primitives/src/selection/select/SelectBubbleSelect.vue b/vue/primitives/src/selection/select/SelectBubbleSelect.vue
new file mode 100644
index 0000000..bdb2946
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectBubbleSelect.vue
@@ -0,0 +1,87 @@
+<script lang="ts">
+import type { AcceptableValue } from './utils';
+
+/**
+ * A real, visually-hidden native `<select>` mirrored from the custom control so
+ * the value participates in native form submission, autofill, and `change`
+ * bubbling. Renders an `<option>` per registered item, supports `multiple`, and
+ * writes through the native value setter so frameworks that observe form
+ * controls (and the browser's autofill) see the change exactly as for a real
+ * `<select>`. Internal — rendered by `SelectRoot` when a `name` is set inside a
+ * form.
+ */
+export interface SelectBubbleSelectProps {
+  autocomplete?: string;
+  disabled?: boolean;
+  multiple?: boolean;
+  name?: string;
+  required?: boolean;
+  /** Registered option values, rendered as native `<option>`s. */
+  options: AcceptableValue[];
+  /** Current model value(s). */
+  value?: AcceptableValue | AcceptableValue[];
+}
+</script>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
+import { VisuallyHidden } from '../../utilities/visually-hidden';
+
+const props = defineProps<SelectBubbleSelectProps>();
+const emit = defineEmits<{ change: [value: string] }>();
+
+defineOptions({ inheritAttrs: false });
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Serialise an option value to the string a native <option> can carry.
+function serialize(value: AcceptableValue | undefined): string {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+// Bubble a native `change` event to the surrounding form when the value
+// changes programmatically, using the native value setter so synthetic-event
+// systems observe it.
+watch(() => props.value, (cur, prev) => {
+  if (cur === prev) return;
+  if (globalThis.window === undefined) return;
+  const el = currentElement.value as HTMLSelectElement | undefined;
+  if (!el) return;
+
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis.HTMLSelectElement.prototype, 'value');
+  const setValue = descriptor?.set;
+  if (!setValue) return;
+
+  const next = serialize(Array.isArray(cur) ? cur[0] : cur);
+  setValue.call(el, next);
+  el.dispatchEvent(new Event('change', { bubbles: true }));
+});
+
+// Autofill triggers an `input` event on the native <select>; mirror it back.
+function handleInput(event: Event) {
+  emit('change', (event.target as HTMLSelectElement).value);
+}
+</script>
+
+<template>
+  <VisuallyHidden as="template" feature="hidden">
+    <select
+      :ref="forwardRef"
+      :name="name"
+      :required="required || undefined"
+      :disabled="disabled || undefined"
+      :multiple="multiple || undefined"
+      :autocomplete="autocomplete"
+      aria-hidden="true"
+      tabindex="-1"
+      v-bind="$attrs"
+      @input="handleInput"
+    >
+      <option v-for="opt in options" :key="serialize(opt)" :value="serialize(opt)">{{ serialize(opt) }}</option>
+    </select>
+  </VisuallyHidden>
+</template>
diff --git a/vue/primitives/src/selection/select/SelectContent.vue b/vue/primitives/src/selection/select/SelectContent.vue
new file mode 100644
index 0000000..01e5432
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectContent.vue
@@ -0,0 +1,74 @@
+<script lang="ts">
+import type { SelectContentImplEmits, SelectContentImplProps } from './SelectContentImpl.vue';
+
+/**
+ * The floating panel that holds the options. While open it mounts
+ * `SelectContentImpl` behind `Presence` (so it can animate in and out); while
+ * closed it still renders the options into a detached `DocumentFragment` so each
+ * `SelectItem` registers its value/label and `SelectValue` shows the
+ * initially-selected label before the dropdown is ever opened. Usually placed
+ * inside a `SelectPortal` and contains a `SelectViewport` of `SelectItem`s.
+ */
+export interface SelectContentProps extends SelectContentImplProps {
+  /**
+   * Force mounting (keeps the panel in the DOM) for externally-controlled
+   * animation libraries.
+   */
+  forceMount?: boolean;
+}
+
+export type SelectContentEmits = SelectContentImplEmits;
+</script>
+
+<script setup lang="ts">
+import { computed, onMounted, ref, shallowRef, watch } from 'vue';
+
+import { Presence } from '../../utilities/presence';
+import { useSelectRootContext } from './context';
+import SelectContentImpl from './SelectContentImpl.vue';
+import SelectProvider from './SelectProvider.vue';
+
+const props = defineProps<SelectContentProps>();
+const emit = defineEmits<SelectContentEmits>();
+const rootCtx = useSelectRootContext();
+
+const present = computed(() => props.forceMount || rootCtx.open.value);
+
+// Delay toggling render-presence so children re-render with the latest state
+// before the exit transition runs (state-based `data-state=closed` animations).
+const renderPresence = ref(present.value);
+function syncRenderPresence() {
+  renderPresence.value = present.value;
+}
+watch(present, () => {
+  setTimeout(syncRenderPresence);
+});
+
+// Detached fragment that keeps options mounted (and registered) while closed.
+const fragment = shallowRef<DocumentFragment | undefined>(undefined);
+onMounted(() => {
+  fragment.value = typeof DocumentFragment !== 'undefined' ? new DocumentFragment() : undefined;
+});
+</script>
+
+<template>
+  <Presence
+    v-if="present || renderPresence"
+    :present="present"
+  >
+    <SelectContentImpl
+      v-bind="props"
+      @close-auto-focus="emit('closeAutoFocus', $event)"
+      @escape-key-down="emit('escapeKeyDown', $event)"
+      @pointer-down-outside="emit('pointerDownOutside', $event)"
+    >
+      <slot />
+    </SelectContentImpl>
+  </Presence>
+
+  <Teleport v-else-if="fragment" :to="fragment">
+    <SelectProvider :context="rootCtx">
+      <slot />
+    </SelectProvider>
+  </Teleport>
+</template>
diff --git a/vue/primitives/src/selection/select/SelectContentImpl.vue b/vue/primitives/src/selection/select/SelectContentImpl.vue
new file mode 100644
index 0000000..b0f62b8
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectContentImpl.vue
@@ -0,0 +1,241 @@
+<script lang="ts">
+import type { DismissableLayerEmits } from '../../utilities/dismissable-layer';
+import type { FocusScopeEmits } from '../../utilities/focus-scope';
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The mounted body of the content panel: it traps focus, dismisses on outside
+ * pointer/escape, locks body scroll, hides sibling content from assistive tech,
+ * installs focus guards, focuses the selected option on open, and handles
+ * keyboard navigation and cycling type-ahead. Rendered by `SelectContent` once
+ * open — prefer using `SelectContent` rather than this part directly.
+ */
+export interface SelectContentImplProps extends PrimitiveProps {
+  /** Position mode. @default 'item-aligned' */
+  position?: 'item-aligned' | 'popper';
+  /** Block outside pointer events. @default true */
+  disableOutsidePointerEvents?: boolean;
+  /** Lock body scroll while open. @default true */
+  bodyLock?: boolean;
+}
+
+export interface SelectContentImplEmits {
+  closeAutoFocus: FocusScopeEmits['unmountAutoFocus'];
+  escapeKeyDown: DismissableLayerEmits['escapeKeyDown'];
+  pointerDownOutside: DismissableLayerEmits['pointerDownOutside'];
+}
+</script>
+
+<script setup lang="ts">
+import { ref, shallowRef, watch } from 'vue';
+
+import { refAutoReset, useBodyScrollLock, useFocusGuard, useForwardExpose } from '@robonen/vue';
+import { getActiveElement } from '@robonen/platform/browsers';
+import { DismissableLayer } from '../../utilities/dismissable-layer';
+import { FocusScope } from '../../utilities/focus-scope';
+import { useHideOthers } from '../../internal/utils/useHideOthers';
+import { provideSelectContentContext, useSelectRootContext } from './context';
+import SelectItemAlignedPosition from './SelectItemAlignedPosition.vue';
+import SelectPopperPosition from './SelectPopperPosition.vue';
+import { getNextMatch } from './utils';
+
+const {
+  as = 'div',
+  position = 'item-aligned',
+  disableOutsidePointerEvents = true,
+  bodyLock = true,
+} = defineProps<SelectContentImplProps>();
+
+const emit = defineEmits<SelectContentImplEmits>();
+
+const { forwardRef } = useForwardExpose();
+const rootCtx = useSelectRootContext();
+
+if (bodyLock) useBodyScrollLock();
+useFocusGuard();
+
+const isPositioned = ref(false);
+const search = refAutoReset('', 1000);
+const viewportRef = shallowRef<HTMLElement | undefined>(undefined);
+const contentRef = shallowRef<HTMLElement | undefined>(undefined);
+const selectedItemRef = rootCtx.selectedItemRef;
+const selectedItemTextRef = rootCtx.selectedItemTextRef;
+
+const firstValidItemFoundRef = ref(false);
+
+// Recompute the selected/first-valid item afresh for this open cycle.
+selectedItemRef.value = undefined;
+
+// Resolve the actual listbox content element. The item-aligned strategy renders
+// a positioning wrapper whose first child is the listbox; the popper strategy
+// renders a wrapper marked `data-primitives-popper-content-wrapper`.
+function setContentRef(vnode: unknown) {
+  forwardRef(vnode as never);
+  const el = (vnode as { $el?: HTMLElement } | null)?.$el ?? (vnode as HTMLElement | null);
+  if (!el) {
+    contentRef.value = undefined;
+    return;
+  }
+  if (el.hasAttribute?.('data-primitives-select-content-wrapper')
+    || el.hasAttribute?.('data-popper-content-wrapper')) {
+    contentRef.value = (el.firstElementChild as HTMLElement | null) ?? el;
+  }
+  else {
+    contentRef.value = el;
+  }
+}
+
+useHideOthers(contentRef);
+
+function focusFirst(candidates: Array<HTMLElement | undefined>) {
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const prev = getActiveElement();
+    candidate.focus({ preventScroll: true });
+    if (getActiveElement() !== prev) return;
+  }
+}
+
+function focusSelectedItem() {
+  focusFirst([selectedItemRef.value, contentRef.value]);
+}
+
+// Focus the selected option (or content) once positioning completes.
+watch(isPositioned, (positioned) => {
+  if (positioned) focusSelectedItem();
+});
+
+function getItems(): HTMLElement[] {
+  const viewport = viewportRef.value ?? contentRef.value;
+  if (!viewport) return [];
+  return Array.from(
+    viewport.querySelectorAll<HTMLElement>('[data-primitives-select-item]:not([data-disabled])'),
+  );
+}
+
+function textOf(el: HTMLElement): string {
+  return el.dataset['textValue'] ?? el.textContent?.trim() ?? '';
+}
+
+function handleTypeahead(key: string) {
+  search.value += key;
+  const items = getItems();
+  if (items.length === 0) return;
+  const values = items.map(textOf);
+  const active = getActiveElement() as HTMLElement | null;
+  const currentMatch = active && items.includes(active) ? textOf(active) : undefined;
+  const next = getNextMatch(values, search.value, currentMatch);
+  if (next === undefined) return;
+  const matched = items[values.indexOf(next)];
+  matched?.focus({ preventScroll: true });
+}
+
+function handleKeyDown(event: KeyboardEvent) {
+  const isModifierKey = event.ctrlKey || event.altKey || event.metaKey;
+
+  // The listbox should not be Tab-navigable.
+  if (event.key === 'Tab') {
+    event.preventDefault();
+    return;
+  }
+
+  if (!isModifierKey && event.key.length === 1) {
+    handleTypeahead(event.key);
+  }
+
+  const items = getItems();
+  if (items.length === 0) return;
+  let candidates = [...items];
+
+  if (['ArrowUp', 'End'].includes(event.key)) {
+    candidates = candidates.slice().reverse();
+  }
+
+  if (['ArrowUp', 'ArrowDown'].includes(event.key)) {
+    const current = getActiveElement() as HTMLElement;
+    const currentIndex = candidates.indexOf(current);
+    candidates = candidates.slice(currentIndex + 1);
+  }
+
+  if (['ArrowUp', 'ArrowDown', 'Home', 'End'].includes(event.key)) {
+    event.preventDefault();
+    setTimeout(() => focusFirst(candidates));
+  }
+}
+
+function itemRefCallback(el: HTMLElement | undefined, value: unknown, disabled: boolean) {
+  const isFirstValidItem = !firstValidItemFoundRef.value && !disabled;
+  rootCtx.itemRefCallback(el, value as never, disabled);
+  if (isFirstValidItem && !selectedItemRef.value) {
+    selectedItemRef.value = el;
+    firstValidItemFoundRef.value = true;
+  }
+  else if (isFirstValidItem) {
+    firstValidItemFoundRef.value = true;
+  }
+}
+
+provideSelectContentContext({
+  viewportRef,
+  onViewportChange: (el) => { viewportRef.value = el; },
+  contentRef,
+  selectedItemRef,
+  selectedItemTextRef,
+  onItemLeave: () => { contentRef.value?.focus(); },
+  focusSelectedItem,
+  itemRefCallback,
+  itemTextRefCallback: rootCtx.itemTextRefCallback,
+  isPositioned,
+  searchRef: search,
+  position,
+});
+</script>
+
+<template>
+  <FocusScope
+    as="template"
+    :loop="true"
+    :trapped="true"
+    @unmount-auto-focus="emit('closeAutoFocus', $event)"
+  >
+    <DismissableLayer
+      as="template"
+      :disable-outside-pointer-events="disableOutsidePointerEvents"
+      @escape-key-down="emit('escapeKeyDown', $event)"
+      @pointer-down-outside="emit('pointerDownOutside', $event)"
+      @dismiss="rootCtx.onOpenChange(false)"
+    >
+      <SelectItemAlignedPosition
+        v-if="position === 'item-aligned'"
+        :ref="setContentRef"
+        :as="as"
+        :id="rootCtx.contentId.value"
+        role="listbox"
+        :data-state="rootCtx.open.value ? 'open' : 'closed'"
+        :dir="rootCtx.dir.value"
+        style="display: flex; flex-direction: column; outline: none"
+        @contextmenu.prevent
+        @placed="isPositioned = true"
+        @keydown="handleKeyDown"
+      >
+        <slot />
+      </SelectItemAlignedPosition>
+
+      <SelectPopperPosition
+        v-else
+        :ref="setContentRef"
+        :as="as"
+        :id="rootCtx.contentId.value"
+        role="listbox"
+        :data-state="rootCtx.open.value ? 'open' : 'closed'"
+        :dir="rootCtx.dir.value"
+        style="display: flex; flex-direction: column; outline: none"
+        @contextmenu.prevent
+        @placed="isPositioned = true"
+        @keydown="handleKeyDown"
+      >
+        <slot />
+      </SelectPopperPosition>
+    </DismissableLayer>
+  </FocusScope>
+</template>
diff --git a/vue/primitives/src/select/SelectGroup.vue b/vue/primitives/src/selection/select/SelectGroup.vue
similarity index 81%
rename from vue/primitives/src/select/SelectGroup.vue
rename to vue/primitives/src/selection/select/SelectGroup.vue
index 76946f6..6c78dfc 100644
--- a/vue/primitives/src/select/SelectGroup.vue
+++ b/vue/primitives/src/selection/select/SelectGroup.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Groups a set of related items under a shared label. Renders as a
@@ -12,8 +12,8 @@ export interface SelectGroupProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { useId } from '../config-provider';
-import { Primitive } from '../primitive';
+import { useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
 import { provideSelectGroupContext } from './context';
 
 const { as = 'div' } = defineProps<SelectGroupProps>();
diff --git a/vue/primitives/src/select/SelectIcon.vue b/vue/primitives/src/selection/select/SelectIcon.vue
similarity index 82%
rename from vue/primitives/src/select/SelectIcon.vue
rename to vue/primitives/src/selection/select/SelectIcon.vue
index 552bd15..6266415 100644
--- a/vue/primitives/src/select/SelectIcon.vue
+++ b/vue/primitives/src/selection/select/SelectIcon.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The decorative icon shown in the trigger (a chevron by default). Marked
@@ -11,7 +11,7 @@ export interface SelectIconProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'span' } = defineProps<SelectIconProps>();
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/selection/select/SelectItem.vue b/vue/primitives/src/selection/select/SelectItem.vue
new file mode 100644
index 0000000..30bfb50
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectItem.vue
@@ -0,0 +1,170 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+import type { AcceptableValue } from './utils';
+
+/**
+ * A single selectable option. Renders as a `role="option"`, registers its value
+ * and text with the root, becomes (or toggles, when `multiple`) the selected
+ * value on click/Enter/Space, and exposes `data-state`/`data-disabled`/
+ * `data-highlighted` for styling. Holds a `SelectItemText` and, optionally, a
+ * `SelectItemIndicator`. The value may be any {@link AcceptableValue}.
+ */
+export interface SelectItemProps<T extends AcceptableValue = AcceptableValue> extends PrimitiveProps {
+  /** The option value. Must not be an empty string. */
+  value: T;
+  /** Disable this item. */
+  disabled?: boolean;
+  /**
+   * Optional text used for typeahead. Defaults to the `SelectItemText` content;
+   * set it when the item content is complex or non-textual.
+   */
+  textValue?: string;
+}
+
+export type SelectItemSelectEvent<T = AcceptableValue> = CustomEvent<{
+  originalEvent: PointerEvent | KeyboardEvent;
+  value: T;
+}>;
+
+export interface SelectItemEmits<T extends AcceptableValue = AcceptableValue> {
+  /** Called when the item is selected. Call `event.preventDefault()` to block. */
+  select: [event: SelectItemSelectEvent<T>];
+}
+</script>
+
+<script setup lang="ts" generic="T extends AcceptableValue = AcceptableValue">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, shallowRef } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
+import { getActiveElement } from '@robonen/platform/browsers';
+import { useId } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
+import { provideSelectItemContext, useSelectContentContext, useSelectRootContext } from './context';
+import { SELECTION_KEYS, valueComparator } from './utils';
+
+const { as = 'div', value, disabled = false, textValue } = defineProps<SelectItemProps<T>>();
+const emit = defineEmits<SelectItemEmits<T>>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const rootCtx = useSelectRootContext();
+const contentCtx = useSelectContentContext();
+
+if (value === ('' as T)) {
+  throw new Error(
+    'A <SelectItem /> must have a value prop that is not an empty string. This is because the Select value can be set to an empty string to clear the selection and show the placeholder.',
+  );
+}
+
+const textId = useId(undefined, 'select-item-text');
+const isFocused = ref(false);
+const isSelected = computed(() => valueComparator(rootCtx.value.value, value, rootCtx.by));
+const isDisabled = computed(() => rootCtx.disabled.value || disabled);
+
+const itemTextElement = shallowRef<HTMLElement | undefined>(undefined);
+
+function onItemTextChange(el: HTMLElement | undefined) {
+  itemTextElement.value = el;
+  contentCtx.itemTextRefCallback(el, value);
+  const text = textValue ?? el?.textContent?.trim() ?? '';
+  if (el) rootCtx.onOptionAdd({ value, disabled, textContent: text });
+}
+
+onMounted(() => {
+  contentCtx.itemRefCallback(currentElement.value, value, isDisabled.value);
+});
+
+onBeforeUnmount(() => {
+  rootCtx.onOptionRemove({ value, disabled, textContent: textValue ?? itemTextElement.value?.textContent?.trim() ?? '' });
+  contentCtx.itemRefCallback(undefined, value, isDisabled.value);
+});
+
+async function handleSelect(event: PointerEvent | KeyboardEvent) {
+  if (event.defaultPrevented) return;
+
+  const detail = new CustomEvent('select', {
+    bubbles: false,
+    cancelable: true,
+    detail: { originalEvent: event, value: value as T },
+  }) as SelectItemSelectEvent<T>;
+
+  await nextTick();
+  emit('select', detail);
+  if (detail.defaultPrevented) return;
+
+  if (!isDisabled.value) {
+    rootCtx.onValueChange(value);
+  }
+}
+
+function handleClick(event: MouseEvent) {
+  handleSelect(event as unknown as PointerEvent);
+}
+
+function handlePointerDown(event: PointerEvent) {
+  (event.currentTarget as HTMLElement | null)?.focus({ preventScroll: true });
+}
+
+async function handlePointerMove(event: PointerEvent) {
+  await nextTick();
+  if (event.defaultPrevented) return;
+  if (isDisabled.value) {
+    contentCtx.onItemLeave();
+  }
+  else {
+    (event.currentTarget as HTMLElement | null)?.focus({ preventScroll: true });
+  }
+}
+
+async function handlePointerLeave(event: PointerEvent) {
+  await nextTick();
+  if (event.defaultPrevented) return;
+  if (event.currentTarget === getActiveElement()) {
+    contentCtx.onItemLeave();
+  }
+}
+
+function handleKeyDown(event: KeyboardEvent) {
+  const isTypingAhead = contentCtx.searchRef.value !== '';
+  if (isTypingAhead && event.key === ' ') return;
+  if (SELECTION_KEYS.includes(event.key)) {
+    handleSelect(event);
+  }
+  // prevent page scroll on space
+  if (event.key === ' ') event.preventDefault();
+}
+
+provideSelectItemContext({
+  value,
+  isSelected,
+  isDisabled,
+  isFocused,
+  textId,
+  onItemTextChange,
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="option"
+    :aria-labelledby="textId"
+    :aria-selected="isSelected"
+    :aria-disabled="isDisabled || undefined"
+    :data-state="isSelected ? 'checked' : 'unchecked'"
+    :data-highlighted="isFocused ? '' : undefined"
+    :data-disabled="isDisabled ? '' : undefined"
+    :tabindex="isDisabled ? undefined : -1"
+    data-primitives-select-item
+    @focus="isFocused = true"
+    @blur="isFocused = false"
+    @click="handleClick"
+    @pointerdown="handlePointerDown"
+    @pointermove="handlePointerMove"
+    @pointerleave="handlePointerLeave"
+    @touchend.prevent.stop
+    @keydown="handleKeyDown"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/selection/select/SelectItemAlignedPosition.vue b/vue/primitives/src/selection/select/SelectItemAlignedPosition.vue
new file mode 100644
index 0000000..cf573bb
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectItemAlignedPosition.vue
@@ -0,0 +1,199 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The `'item-aligned'` positioning strategy for the content panel: positions the
+ * panel like a native MacOS menu by vertically centring the selected option
+ * against the trigger, horizontally aligning the selected item's text with the
+ * trigger value, clamping to the viewport (collision margin), computing
+ * min/max height, supporting `dir="rtl"`, growing on scroll, and repositioning
+ * on trigger resize. Chosen internally by `SelectContentImpl` when `position`
+ * is `'item-aligned'`.
+ */
+export interface SelectItemAlignedPositionProps extends PrimitiveProps {
+  /** Reading direction, forwarded from the root. */
+  dir?: string;
+}
+
+export interface SelectItemAlignedPositionEmits {
+  placed: [];
+}
+</script>
+
+<script setup lang="ts">
+import { nextTick, onMounted, ref, shallowRef } from 'vue';
+
+import { useForwardExpose, useResizeObserver } from '@robonen/vue';
+import { clamp } from '@robonen/stdlib';
+import { Primitive } from '../../internal/primitive';
+import {
+  provideSelectItemAlignedPositionContext,
+  useSelectContentContext,
+  useSelectRootContext,
+} from './context';
+import { CONTENT_MARGIN } from './utils';
+
+const { as = 'div' } = defineProps<SelectItemAlignedPositionProps>();
+const emit = defineEmits<SelectItemAlignedPositionEmits>();
+
+defineOptions({ inheritAttrs: false });
+
+const { forwardRef, currentElement: contentElement } = useForwardExpose();
+const rootCtx = useSelectRootContext();
+const contentCtx = useSelectContentContext();
+
+const contentWrapper = shallowRef<HTMLElement | undefined>(undefined);
+const shouldExpandOnScrollRef = ref(false);
+const shouldRepositionRef = ref(true);
+const contentZIndex = ref('');
+
+function position() {
+  const trigger = rootCtx.triggerElement.value;
+  const valueNode = rootCtx.valueElement.value;
+  const wrapper = contentWrapper.value;
+  const content = contentElement.value;
+  const viewport = contentCtx.viewportRef.value;
+  const selectedItem = contentCtx.selectedItemRef.value;
+  const selectedItemText = contentCtx.selectedItemTextRef.value;
+
+  if (!trigger || !valueNode || !wrapper || !content || !viewport || !selectedItem || !selectedItemText) {
+    emit('placed');
+    return;
+  }
+
+  const triggerRect = trigger.getBoundingClientRect();
+
+  // --- Horizontal positioning ---
+  const contentRect = content.getBoundingClientRect();
+  const valueNodeRect = valueNode.getBoundingClientRect();
+  const itemTextRect = selectedItemText.getBoundingClientRect();
+
+  if (rootCtx.dir.value !== 'rtl') {
+    const itemTextOffset = itemTextRect.left - contentRect.left;
+    const left = valueNodeRect.left - itemTextOffset;
+    const leftDelta = triggerRect.left - left;
+    const minContentWidth = triggerRect.width + leftDelta;
+    const contentWidth = Math.max(minContentWidth, contentRect.width);
+    const rightEdge = window.innerWidth - CONTENT_MARGIN;
+    const clampedLeft = clamp(left, CONTENT_MARGIN, Math.max(CONTENT_MARGIN, rightEdge - contentWidth));
+
+    wrapper.style.minWidth = `${minContentWidth}px`;
+    wrapper.style.left = `${clampedLeft}px`;
+  }
+  else {
+    const itemTextOffset = contentRect.right - itemTextRect.right;
+    const right = window.innerWidth - valueNodeRect.right - itemTextOffset;
+    const rightDelta = window.innerWidth - triggerRect.right - right;
+    const minContentWidth = triggerRect.width + rightDelta;
+    const contentWidth = Math.max(minContentWidth, contentRect.width);
+    const leftEdge = window.innerWidth - CONTENT_MARGIN;
+    const clampedRight = clamp(right, CONTENT_MARGIN, Math.max(CONTENT_MARGIN, leftEdge - contentWidth));
+
+    wrapper.style.minWidth = `${minContentWidth}px`;
+    wrapper.style.right = `${clampedRight}px`;
+  }
+
+  // --- Vertical positioning ---
+  const items = Array.from(
+    viewport.querySelectorAll<HTMLElement>('[data-primitives-select-item]'),
+  );
+  const availableHeight = window.innerHeight - CONTENT_MARGIN * 2;
+  const itemsHeight = viewport.scrollHeight;
+
+  const contentStyles = globalThis.getComputedStyle(content);
+  const contentBorderTopWidth = Number.parseInt(contentStyles.borderTopWidth, 10) || 0;
+  const contentPaddingTop = Number.parseInt(contentStyles.paddingTop, 10) || 0;
+  const contentBorderBottomWidth = Number.parseInt(contentStyles.borderBottomWidth, 10) || 0;
+  const contentPaddingBottom = Number.parseInt(contentStyles.paddingBottom, 10) || 0;
+  const fullContentHeight = contentBorderTopWidth + contentPaddingTop + itemsHeight + contentPaddingBottom + contentBorderBottomWidth;
+  const minContentHeight = Math.min(selectedItem.offsetHeight * 5, fullContentHeight);
+
+  const viewportStyles = globalThis.getComputedStyle(viewport);
+  const viewportPaddingTop = Number.parseInt(viewportStyles.paddingTop, 10) || 0;
+  const viewportPaddingBottom = Number.parseInt(viewportStyles.paddingBottom, 10) || 0;
+
+  const topEdgeToTriggerMiddle = triggerRect.top + triggerRect.height / 2 - CONTENT_MARGIN;
+  const triggerMiddleToBottomEdge = availableHeight - topEdgeToTriggerMiddle;
+
+  const selectedItemHalfHeight = selectedItem.offsetHeight / 2;
+  const itemOffsetMiddle = selectedItem.offsetTop + selectedItemHalfHeight;
+  const contentTopToItemMiddle = contentBorderTopWidth + contentPaddingTop + itemOffsetMiddle;
+  const itemMiddleToContentBottom = fullContentHeight - contentTopToItemMiddle;
+
+  const willAlignWithoutTopOverflow = contentTopToItemMiddle <= topEdgeToTriggerMiddle;
+
+  if (willAlignWithoutTopOverflow) {
+    const isLastItem = selectedItem === items.at(-1);
+    wrapper.style.bottom = '0px';
+    const viewportOffsetBottom = content.clientHeight - viewport.offsetTop - viewport.offsetHeight;
+    const clampedTriggerMiddleToBottomEdge = Math.max(
+      triggerMiddleToBottomEdge,
+      selectedItemHalfHeight + (isLastItem ? viewportPaddingBottom : 0) + viewportOffsetBottom + contentBorderBottomWidth,
+    );
+    const height = contentTopToItemMiddle + clampedTriggerMiddleToBottomEdge;
+    wrapper.style.height = `${height}px`;
+  }
+  else {
+    const isFirstItem = selectedItem === items[0];
+    wrapper.style.top = '0px';
+    const clampedTopEdgeToTriggerMiddle = Math.max(
+      topEdgeToTriggerMiddle,
+      contentBorderTopWidth + viewport.offsetTop + (isFirstItem ? viewportPaddingTop : 0) + selectedItemHalfHeight,
+    );
+    const height = clampedTopEdgeToTriggerMiddle + itemMiddleToContentBottom;
+    wrapper.style.height = `${height}px`;
+    viewport.scrollTop = contentTopToItemMiddle - topEdgeToTriggerMiddle + viewport.offsetTop;
+  }
+
+  wrapper.style.margin = `${CONTENT_MARGIN}px 0`;
+  wrapper.style.minHeight = `${minContentHeight}px`;
+  wrapper.style.maxHeight = `${availableHeight}px`;
+
+  emit('placed');
+  requestAnimationFrame(() => (shouldExpandOnScrollRef.value = true));
+}
+
+onMounted(async () => {
+  await nextTick();
+  position();
+  if (contentElement.value) {
+    contentZIndex.value = globalThis.getComputedStyle(contentElement.value).zIndex;
+  }
+});
+
+// When the scroll-up button mounts (because the viewport became scrollable at
+// the top) it pushes the viewport down, throwing the alignment off; re-run once.
+function handleScrollButtonChange(node: HTMLElement | undefined) {
+  if (node && shouldRepositionRef.value) {
+    position();
+    contentCtx.focusSelectedItem();
+    shouldRepositionRef.value = false;
+  }
+}
+
+useResizeObserver(rootCtx.triggerElement, () => position());
+
+provideSelectItemAlignedPositionContext({
+  contentWrapper,
+  shouldExpandOnScrollRef,
+  onScrollButtonChange: handleScrollButtonChange,
+});
+</script>
+
+<template>
+  <div
+    ref="contentWrapper"
+    data-primitives-select-content-wrapper
+    :style="{ display: 'flex', flexDirection: 'column', position: 'fixed', zIndex: contentZIndex }"
+  >
+    <Primitive
+      :ref="forwardRef"
+      :as="as"
+      data-primitives-select-content
+      :style="{ boxSizing: 'border-box', maxHeight: '100%' }"
+      v-bind="$attrs"
+    >
+      <slot />
+    </Primitive>
+  </div>
+</template>
diff --git a/vue/primitives/src/select/SelectItemIndicator.vue b/vue/primitives/src/selection/select/SelectItemIndicator.vue
similarity index 85%
rename from vue/primitives/src/select/SelectItemIndicator.vue
rename to vue/primitives/src/selection/select/SelectItemIndicator.vue
index 5306249..c359eff 100644
--- a/vue/primitives/src/select/SelectItemIndicator.vue
+++ b/vue/primitives/src/selection/select/SelectItemIndicator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A marker (typically a checkmark) rendered only while its `SelectItem` is the
@@ -11,7 +11,7 @@ export interface SelectItemIndicatorProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useSelectItemContext } from './context';
 
 const { as = 'span' } = defineProps<SelectItemIndicatorProps>();
diff --git a/vue/primitives/src/select/SelectItemText.vue b/vue/primitives/src/selection/select/SelectItemText.vue
similarity index 87%
rename from vue/primitives/src/select/SelectItemText.vue
rename to vue/primitives/src/selection/select/SelectItemText.vue
index c5cec95..cfd47b2 100644
--- a/vue/primitives/src/select/SelectItemText.vue
+++ b/vue/primitives/src/selection/select/SelectItemText.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * The visible label of a `SelectItem`. Its text is what the root captures to
@@ -13,7 +13,7 @@ export interface SelectItemTextProps extends PrimitiveProps {}
 import { watchPostEffect } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useSelectItemContext } from './context';
 
 const { as = 'span' } = defineProps<SelectItemTextProps>();
diff --git a/vue/primitives/src/select/SelectLabel.vue b/vue/primitives/src/selection/select/SelectLabel.vue
similarity index 85%
rename from vue/primitives/src/select/SelectLabel.vue
rename to vue/primitives/src/selection/select/SelectLabel.vue
index b981b40..8f8755d 100644
--- a/vue/primitives/src/select/SelectLabel.vue
+++ b/vue/primitives/src/selection/select/SelectLabel.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A non-selectable heading for a `SelectGroup`. Renders the text that labels the
@@ -12,7 +12,7 @@ export interface SelectLabelProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useSelectGroupContext } from './context';
 
 const { as = 'div' } = defineProps<SelectLabelProps>();
diff --git a/vue/primitives/src/select/SelectPopperPosition.vue b/vue/primitives/src/selection/select/SelectPopperPosition.vue
similarity index 88%
rename from vue/primitives/src/select/SelectPopperPosition.vue
rename to vue/primitives/src/selection/select/SelectPopperPosition.vue
index 11a8d05..6a71984 100644
--- a/vue/primitives/src/select/SelectPopperPosition.vue
+++ b/vue/primitives/src/selection/select/SelectPopperPosition.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PopperContentEmits, PopperContentProps } from '../popper';
+import type { PopperContentEmits, PopperContentProps } from '../../overlays/popper';
 
 /**
  * The `'popper'` positioning strategy for the content panel: builds on
@@ -14,18 +14,20 @@ export type SelectPopperPositionEmits = PopperContentEmits;
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { PopperContent } from '../popper';
+import { PopperContent } from '../../overlays/popper';
 
 const props = defineProps<SelectPopperPositionProps>();
 const emit = defineEmits<SelectPopperPositionEmits>();
 
+defineOptions({ inheritAttrs: false });
+
 const { forwardRef } = useForwardExpose();
 </script>
 
 <template>
   <PopperContent
     :ref="forwardRef"
-    v-bind="props"
+    v-bind="{ ...props, ...$attrs }"
     :side="props.side ?? 'bottom'"
     :side-offset="props.sideOffset ?? 4"
     :align="props.align ?? 'start'"
diff --git a/vue/primitives/src/select/SelectPortal.vue b/vue/primitives/src/selection/select/SelectPortal.vue
similarity index 80%
rename from vue/primitives/src/select/SelectPortal.vue
rename to vue/primitives/src/selection/select/SelectPortal.vue
index 35772e2..b734c2d 100644
--- a/vue/primitives/src/select/SelectPortal.vue
+++ b/vue/primitives/src/selection/select/SelectPortal.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PortalProps } from '../teleport';
+import type { PortalProps } from '../../utilities/teleport';
 
 /**
  * Teleports the `SelectContent` into a different part of the DOM (the document
@@ -9,7 +9,7 @@ export interface SelectPortalProps extends PortalProps {}
 </script>
 
 <script setup lang="ts">
-import { Portal } from '../teleport';
+import { Portal } from '../../utilities/teleport';
 
 const { to, defer, disabled } = defineProps<SelectPortalProps>();
 </script>
diff --git a/vue/primitives/src/selection/select/SelectProvider.vue b/vue/primitives/src/selection/select/SelectProvider.vue
new file mode 100644
index 0000000..55024a8
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectProvider.vue
@@ -0,0 +1,46 @@
+<script lang="ts">
+import type { SelectContentContext, SelectRootContext } from './context';
+
+/**
+ * Re-provides the root context and a no-op content context so that
+ * `SelectItem`/`SelectItemText` can mount inside a detached `DocumentFragment`
+ * while the listbox is closed. This lets every option register its value and
+ * label up-front, so `SelectValue` shows the initially-selected label before
+ * the dropdown is ever opened. Internal — rendered by `SelectContent`.
+ */
+export interface SelectProviderProps {
+  context: SelectRootContext;
+}
+</script>
+
+<script setup lang="ts">
+import { shallowRef } from 'vue';
+
+import { provideSelectContentContext, provideSelectRootContext } from './context';
+
+const { context } = defineProps<SelectProviderProps>();
+
+provideSelectRootContext(context);
+
+const noopEl = shallowRef<HTMLElement | undefined>(undefined);
+const defaultContentContext: SelectContentContext = {
+  viewportRef: noopEl,
+  onViewportChange: () => {},
+  contentRef: noopEl,
+  selectedItemRef: context.selectedItemRef,
+  selectedItemTextRef: context.selectedItemTextRef,
+  onItemLeave: () => {},
+  focusSelectedItem: () => {},
+  itemRefCallback: context.itemRefCallback,
+  itemTextRefCallback: context.itemTextRefCallback,
+  isPositioned: shallowRef(false),
+  searchRef: shallowRef(''),
+  position: 'item-aligned',
+};
+
+provideSelectContentContext(defaultContentContext);
+</script>
+
+<template>
+  <slot />
+</template>
diff --git a/vue/primitives/src/selection/select/SelectRoot.vue b/vue/primitives/src/selection/select/SelectRoot.vue
new file mode 100644
index 0000000..4f6fb6c
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectRoot.vue
@@ -0,0 +1,257 @@
+<script lang="ts">
+import type { Direction } from '../../utilities/config-provider';
+import type { AcceptableValue } from './utils';
+
+/**
+ * A custom, fully stylable replacement for the native `<select>` element: a
+ * trigger button that opens a floating listbox of options, with full keyboard
+ * support (arrow keys, Home/End, type-ahead search), focus trapping, and an
+ * optional hidden native `<select>` for native form submission.
+ *
+ * Use it when you need a single- or multi-choice dropdown whose menu and options
+ * must be styled beyond what a native control allows. The root owns the selected
+ * value and open state and provides context to every part; bind `v-model` for
+ * the value and `v-model:open` (or listen to `update:modelValue` / `update:open`)
+ * to control or observe it. Values may be strings, numbers, booleans, or objects
+ * (compared via `by`). Compose it from a `SelectTrigger` (with
+ * `SelectValue`/`SelectIcon`) plus a portalled `SelectContent` of `SelectItem`s.
+ */
+export interface SelectRootProps<T extends AcceptableValue = AcceptableValue> {
+  /** Reading direction. Falls back to ConfigProvider. */
+  dir?: Direction;
+  /** Disable the whole select. */
+  disabled?: boolean;
+  /** Mark field as required for native form validation. */
+  required?: boolean;
+  /** Native input name for form submission. */
+  name?: string;
+  /** Uncontrolled default value. */
+  defaultValue?: T | T[];
+  /** Uncontrolled default open state. */
+  defaultOpen?: boolean;
+  /** Allow selecting multiple options; the model becomes an array. */
+  multiple?: boolean;
+  /**
+   * Compare object values by a property key or a custom comparator. Omitted →
+   * `===` for primitives / structural deep-equality for objects.
+   */
+  by?: string | ((a: T, b: T) => boolean);
+  /** Native autocomplete attribute forwarded to the hidden native select. */
+  autocomplete?: string;
+}
+
+export interface SelectRootEmits<T extends AcceptableValue = AcceptableValue> {
+  'update:modelValue': [value: T | T[] | undefined];
+  'update:open': [open: boolean];
+}
+</script>
+
+<script setup lang="ts" generic="T extends AcceptableValue = AcceptableValue">
+import type { Ref } from 'vue';
+import { computed, ref, shallowRef, toRef, watch } from 'vue';
+
+import { useId } from '../../utilities/config-provider';
+import { PopperRoot } from '../../overlays/popper';
+import { provideSelectRootContext } from './context';
+import type { SelectOption } from './context';
+import SelectBubbleSelect from './SelectBubbleSelect.vue';
+import { compare, shouldShowPlaceholder } from './utils';
+
+defineOptions({ inheritAttrs: false });
+
+const {
+  dir,
+  disabled = false,
+  required = false,
+  name,
+  defaultValue,
+  defaultOpen = false,
+  multiple = false,
+  by,
+  autocomplete,
+} = defineProps<SelectRootProps<T>>();
+
+defineSlots<{
+  default?: (props: {
+    modelValue: T | T[] | undefined;
+    open: boolean;
+  }) => unknown;
+}>();
+
+const localOpen = ref<boolean>(defaultOpen);
+const open = defineModel<boolean>('open', {
+  default: undefined,
+  get: v => v ?? localOpen.value,
+  set: (v) => {
+    localOpen.value = v;
+    return v;
+  },
+});
+
+const localValue = ref<T | T[] | undefined>(defaultValue ?? (multiple ? ([] as T[]) : undefined)) as Ref<T | T[] | undefined>;
+const value = defineModel<T | T[] | undefined>('modelValue', {
+  default: undefined,
+  get: v => (v ?? localValue.value),
+  set: (v) => {
+    localValue.value = v;
+    return v;
+  },
+});
+
+const contentId = useId(undefined, 'select-content');
+const dirRef = toRef(() => dir);
+const disabledRef = toRef(() => disabled);
+const requiredRef = toRef(() => required);
+const multipleRef = toRef(() => multiple);
+const nameRef = toRef(() => name);
+
+const triggerElement = shallowRef<HTMLElement | undefined>(undefined);
+const valueElement = shallowRef<HTMLElement | undefined>(undefined);
+const triggerPointerDownPosRef = ref<{ x: number; y: number } | null>(null);
+const selectedItemRef = shallowRef<HTMLElement | undefined>(undefined);
+const selectedItemTextRef = shallowRef<HTMLElement | undefined>(undefined);
+const displayValue = ref<string | undefined>(undefined);
+
+// Raw (non-reactive) source of truth for option membership; `optionsSet` is the
+// published snapshot consumers read. Mutating the raw set then re-publishing a
+// fresh snapshot avoids tracking the ref inside the registration effect (which
+// would otherwise recurse: read optionsSet -> write optionsSet -> re-run).
+const rawOptions = new Set<SelectOption>();
+const optionsSet = shallowRef(new Set<SelectOption>());
+
+const isEmptyModelValue = computed(() => shouldShowPlaceholder(value.value));
+
+function getOptionFrom(source: Iterable<SelectOption>, v: AcceptableValue): SelectOption | undefined {
+  for (const option of source) {
+    if (compare(option.value as T, v as T, by as never)) return option;
+  }
+  return undefined;
+}
+
+function onOptionAdd(option: SelectOption) {
+  const existing = getOptionFrom(rawOptions, option.value);
+  if (existing) rawOptions.delete(existing);
+  rawOptions.add(option);
+  optionsSet.value = new Set(rawOptions);
+}
+
+function onOptionRemove(option: SelectOption) {
+  const existing = getOptionFrom(rawOptions, option.value);
+  if (!existing) return;
+  rawOptions.delete(existing);
+  optionsSet.value = new Set(rawOptions);
+}
+
+// Persist a single-value label for the legacy `displayValue` slot path.
+watch([optionsSet, value], () => {
+  const current = value.value;
+  if (current === undefined || Array.isArray(current)) return;
+  const text = getOptionFrom(optionsSet.value, current)?.textContent;
+  if (text !== undefined) displayValue.value = text;
+}, { immediate: true });
+
+function handleValueChange(newValue: AcceptableValue) {
+  if (multiple) {
+    const array = Array.isArray(value.value) ? [...value.value] : [];
+    const index = array.findIndex(v => compare(v as T, newValue as T, by as never));
+    if (index === -1) array.push(newValue as T);
+    else array.splice(index, 1);
+    value.value = [...array] as T[];
+  }
+  else {
+    value.value = newValue as T;
+    displayValue.value = getOptionFrom(rawOptions, newValue)?.textContent;
+    open.value = false;
+  }
+}
+
+function isSelectedValue(itemValue: AcceptableValue): boolean {
+  const current = value.value;
+  if (current === undefined) return false;
+  if (Array.isArray(current)) {
+    for (const v of current) {
+      if (compare(itemValue as T, v as T, by as never)) return true;
+    }
+    return false;
+  }
+  return compare(itemValue as T, current as T, by as never);
+}
+
+function itemRefCallback(el: HTMLElement | undefined, itemValue: AcceptableValue, isDisabled: boolean) {
+  if (!isDisabled && isSelectedValue(itemValue)) {
+    selectedItemRef.value = el;
+  }
+}
+
+function itemTextRefCallback(el: HTMLElement | undefined, itemValue: AcceptableValue) {
+  if (isSelectedValue(itemValue)) {
+    selectedItemTextRef.value = el;
+  }
+}
+
+const nativeOptions = computed(() => Array.from(optionsSet.value, o => o.value));
+
+const isFormControl = computed(() => {
+  const el = triggerElement.value;
+  return !!el && !!el.closest('form');
+});
+
+provideSelectRootContext({
+  value,
+  onValueChange: handleValueChange,
+  open,
+  onOpenChange: (v) => { open.value = v; },
+  dir: dirRef,
+  disabled: disabledRef,
+  required: requiredRef,
+  multiple: multipleRef,
+  by: by as never,
+  name: nameRef,
+  triggerElement,
+  onTriggerChange: (el) => { triggerElement.value = el; },
+  valueElement,
+  onValueElementChange: (el) => { valueElement.value = el; },
+  triggerPointerDownPosRef,
+  contentId,
+  isEmptyModelValue,
+  displayValue,
+  optionsSet,
+  onOptionAdd,
+  onOptionRemove,
+  itemRefCallback,
+  itemTextRefCallback,
+  selectedItemRef,
+  selectedItemTextRef,
+});
+</script>
+
+<template>
+  <PopperRoot>
+    <slot :model-value="value" :open="open" />
+
+    <SelectBubbleSelect
+      v-if="isFormControl && name"
+      :name="name"
+      :autocomplete="autocomplete"
+      :required="required"
+      :disabled="disabled"
+      :multiple="multiple"
+      :options="nativeOptions"
+      :value="value"
+      @change="handleValueChange"
+    />
+
+    <input
+      v-else-if="name"
+      type="hidden"
+      :name="name"
+      :value="Array.isArray(value) ? '' : (value ?? '')"
+      :required="required"
+      :disabled="disabled"
+      :autocomplete="autocomplete"
+      aria-hidden="true"
+      style="display: none"
+      tabindex="-1"
+    />
+  </PopperRoot>
+</template>
diff --git a/vue/primitives/src/select/SelectScrollButtonImpl.vue b/vue/primitives/src/selection/select/SelectScrollButtonImpl.vue
similarity index 92%
rename from vue/primitives/src/select/SelectScrollButtonImpl.vue
rename to vue/primitives/src/selection/select/SelectScrollButtonImpl.vue
index 718bba8..4c8373a 100644
--- a/vue/primitives/src/select/SelectScrollButtonImpl.vue
+++ b/vue/primitives/src/selection/select/SelectScrollButtonImpl.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Shared implementation behind the up/down scroll buttons: auto-scrolls the
@@ -16,7 +16,7 @@ export interface SelectScrollButtonImplProps extends PrimitiveProps {
 import { onBeforeUnmount } from 'vue';
 
 import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useSelectContentContext } from './context';
 
 const { as = 'div', direction } = defineProps<SelectScrollButtonImplProps>();
diff --git a/vue/primitives/src/select/SelectScrollDownButton.vue b/vue/primitives/src/selection/select/SelectScrollDownButton.vue
similarity index 59%
rename from vue/primitives/src/select/SelectScrollDownButton.vue
rename to vue/primitives/src/selection/select/SelectScrollDownButton.vue
index 5d2c889..95eb406 100644
--- a/vue/primitives/src/select/SelectScrollDownButton.vue
+++ b/vue/primitives/src/selection/select/SelectScrollDownButton.vue
@@ -10,9 +10,9 @@ export type SelectScrollDownButtonProps = Omit<SelectScrollButtonImplProps, 'dir
 </script>
 
 <script setup lang="ts">
-import { onMounted, ref, watchEffect } from 'vue';
+import { ref, watchEffect } from 'vue';
 
-import { useForwardExpose } from '@robonen/vue';
+import { useEventListener, useForwardExpose } from '@robonen/vue';
 import { useSelectContentContext } from './context';
 import SelectScrollButtonImpl from './SelectScrollButtonImpl.vue';
 
@@ -22,29 +22,16 @@ const { forwardRef } = useForwardExpose();
 const contentCtx = useSelectContentContext();
 
 const canScrollDown = ref(false);
-let cleanupFn: (() => void) | null = null;
+function update() {
+  const viewport = contentCtx.viewportRef.value;
+  canScrollDown.value = viewport ? viewport.scrollHeight - viewport.scrollTop > viewport.clientHeight + 1 : false;
+}
 
+// Re-attaches when the viewport element changes; `passive` preserved, SSR-safe.
+useEventListener(contentCtx.viewportRef, 'scroll', update, { passive: true });
+// Seed/refresh the initial state whenever the viewport appears or changes.
 watchEffect(() => {
-  if (cleanupFn) {
-    cleanupFn();
-    cleanupFn = null;
-  }
-  const viewport = contentCtx.viewportRef.value;
-  if (!viewport) return;
-
-  const update = () => {
-    canScrollDown.value = viewport.scrollHeight - viewport.scrollTop > viewport.clientHeight + 1;
-  };
-  viewport.addEventListener('scroll', update, { passive: true });
-  update();
-  cleanupFn = () => viewport.removeEventListener('scroll', update);
-});
-
-onMounted(() => {
-  const viewport = contentCtx.viewportRef.value;
-  if (viewport) {
-    canScrollDown.value = viewport.scrollHeight - viewport.scrollTop > viewport.clientHeight + 1;
-  }
+  if (contentCtx.viewportRef.value) update();
 });
 </script>
 
diff --git a/vue/primitives/src/selection/select/SelectScrollUpButton.vue b/vue/primitives/src/selection/select/SelectScrollUpButton.vue
new file mode 100644
index 0000000..9feb6b3
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectScrollUpButton.vue
@@ -0,0 +1,56 @@
+<script lang="ts">
+import type { SelectScrollButtonImplProps } from './SelectScrollButtonImpl.vue';
+
+/**
+ * An auto-scroll affordance shown at the top of the viewport when there is
+ * content scrolled out of view above. Scrolls the viewport up while hovered and
+ * hides itself when already at the top.
+ */
+export type SelectScrollUpButtonProps = Omit<SelectScrollButtonImplProps, 'direction'>;
+</script>
+
+<script setup lang="ts">
+import { ref, watch, watchEffect } from 'vue';
+
+import { useEventListener, useForwardExpose } from '@robonen/vue';
+import { useSelectContentContext, useSelectItemAlignedPositionContext } from './context';
+import SelectScrollButtonImpl from './SelectScrollButtonImpl.vue';
+
+const props = defineProps<SelectScrollUpButtonProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const contentCtx = useSelectContentContext();
+const alignedCtx = contentCtx.position === 'item-aligned'
+  ? useSelectItemAlignedPositionContext(null as never)
+  : undefined;
+
+const canScrollUp = ref(false);
+
+// Notify the item-aligned positioner that the scroll-up button mounted so it
+// can re-run alignment (the button pushes the viewport down).
+watch(currentElement, (el) => {
+  if (el) alignedCtx?.onScrollButtonChange(el);
+});
+function update() {
+  const viewport = contentCtx.viewportRef.value;
+  canScrollUp.value = viewport ? viewport.scrollTop > 0 : false;
+}
+
+// Re-attaches when the viewport element changes; `passive` preserved, SSR-safe.
+useEventListener(contentCtx.viewportRef, 'scroll', update, { passive: true });
+// Seed/refresh the initial state whenever the viewport appears or changes.
+watchEffect(() => {
+  if (contentCtx.viewportRef.value) update();
+});
+</script>
+
+<template>
+  <SelectScrollButtonImpl
+    v-if="canScrollUp"
+    v-bind="props"
+    :ref="forwardRef"
+    :direction="-1"
+  >
+    <slot />
+  </SelectScrollButtonImpl>
+</template>
diff --git a/vue/primitives/src/select/SelectSeparator.vue b/vue/primitives/src/selection/select/SelectSeparator.vue
similarity index 83%
rename from vue/primitives/src/select/SelectSeparator.vue
rename to vue/primitives/src/selection/select/SelectSeparator.vue
index 2f0a915..849288d 100644
--- a/vue/primitives/src/select/SelectSeparator.vue
+++ b/vue/primitives/src/selection/select/SelectSeparator.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A visual divider between groups or items in the content. Renders as a
@@ -11,7 +11,7 @@ export interface SelectSeparatorProps extends PrimitiveProps {}
 <script setup lang="ts">
 import { useForwardExpose } from '@robonen/vue';
 
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 
 const { as = 'div' } = defineProps<SelectSeparatorProps>();
 const { forwardRef } = useForwardExpose();
diff --git a/vue/primitives/src/selection/select/SelectTrigger.vue b/vue/primitives/src/selection/select/SelectTrigger.vue
new file mode 100644
index 0000000..b7f4723
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectTrigger.vue
@@ -0,0 +1,145 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The button that toggles the select open and anchors the floating content.
+ * Renders as a `role="combobox"` control wired with the appropriate ARIA and
+ * `data-state`/`data-placeholder` attributes; place a `SelectValue` and
+ * `SelectIcon` inside it. Supports type-to-select while closed and touch-device
+ * pointer hardening.
+ */
+export interface SelectTriggerProps extends PrimitiveProps {
+  /** Disable this trigger independently from the root. */
+  disabled?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, watchEffect } from 'vue';
+
+import { refAutoReset, useForwardExpose } from '@robonen/vue';
+import { PopperAnchor } from '../../overlays/popper';
+import { useSelectRootContext } from './context';
+import { OPEN_KEYS, getNextMatch, getOpenState, shouldShowPlaceholder } from './utils';
+
+const { as = 'button', disabled = false } = defineProps<SelectTriggerProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const rootCtx = useSelectRootContext();
+
+const isDisabled = computed(() => rootCtx.disabled.value || disabled);
+
+watchEffect(() => rootCtx.onTriggerChange(currentElement.value));
+onBeforeUnmount(() => rootCtx.onTriggerChange(undefined));
+
+// Type-to-select on the closed trigger: cycle through the registered options by
+// label prefix and select the match without opening the listbox.
+const search = refAutoReset('', 1000);
+
+function handleOpen() {
+  if (isDisabled.value) return;
+  rootCtx.onOpenChange(true);
+  search.value = '';
+}
+
+function handlePointerOpen(event: PointerEvent) {
+  handleOpen();
+  rootCtx.triggerPointerDownPosRef.value = {
+    x: Math.round(event.pageX),
+    y: Math.round(event.pageY),
+  };
+}
+
+function handlePointerDown(event: PointerEvent) {
+  if (isDisabled.value) return;
+
+  // Prevent opening on touch down — open on touch pointerup instead.
+  if (event.pointerType === 'touch') {
+    event.preventDefault();
+    return;
+  }
+
+  // Release implicit pointer capture so subsequent pointer events target items.
+  const target = event.target as HTMLElement;
+  if (target.hasPointerCapture?.(event.pointerId)) {
+    target.releasePointerCapture(event.pointerId);
+  }
+
+  if (event.button === 0 && !event.ctrlKey) {
+    handlePointerOpen(event);
+    // Prevent the trigger from stealing focus from the active item after open.
+    event.preventDefault();
+  }
+}
+
+function handlePointerUp(event: PointerEvent) {
+  event.preventDefault();
+  if (event.pointerType === 'touch') {
+    handlePointerOpen(event);
+  }
+}
+
+function handleClick(event: MouseEvent) {
+  // Safari focuses the trigger on label clicks but skips pointerdown; force it.
+  (event.currentTarget as HTMLElement | null)?.focus();
+}
+
+function typeaheadSelect(key: string) {
+  search.value += key;
+  const options = Array.from(rootCtx.optionsSet.value);
+  if (options.length === 0) return;
+
+  const labels = options.map(o => o.textContent);
+  const current = Array.isArray(rootCtx.value.value) ? rootCtx.value.value[0] : rootCtx.value.value;
+  const currentLabel = options.find(o => o.value === current)?.textContent;
+  const next = getNextMatch(labels, search.value, currentLabel);
+  if (next === undefined) return;
+
+  const matched = options[labels.indexOf(next)];
+  if (matched) rootCtx.onValueChange(matched.value);
+}
+
+function handleKeyDown(event: KeyboardEvent) {
+  if (isDisabled.value) return;
+  const isModifierKey = event.ctrlKey || event.altKey || event.metaKey;
+  const isTypingAhead = search.value !== '';
+
+  if (!isModifierKey && event.key.length === 1) {
+    if (isTypingAhead && event.key === ' ') return;
+    typeaheadSelect(event.key);
+  }
+
+  if (OPEN_KEYS.includes(event.key)) {
+    handleOpen();
+    event.preventDefault();
+  }
+}
+</script>
+
+<template>
+  <!-- PopperAnchor IS the trigger button: the role/aria/handlers AND the
+       consumer's class + children must live on the SAME element. A nested
+       Primitive split them — the styled box landed on this anchor wrapper while
+       the real button stayed an unstyled inline element with stacked content. -->
+  <PopperAnchor
+    :ref="forwardRef"
+    :as="as"
+    role="combobox"
+    :type="as === 'button' ? 'button' : undefined"
+    aria-autocomplete="none"
+    :aria-controls="rootCtx.contentId.value"
+    :aria-expanded="rootCtx.open.value"
+    :aria-required="rootCtx.required.value || undefined"
+    :dir="rootCtx.dir.value"
+    :data-state="getOpenState(rootCtx.open.value)"
+    :disabled="isDisabled || undefined"
+    :data-disabled="isDisabled ? '' : undefined"
+    :data-placeholder="shouldShowPlaceholder(rootCtx.value.value) ? '' : undefined"
+    @pointerdown="handlePointerDown"
+    @pointerup="handlePointerUp"
+    @click="handleClick"
+    @keydown="handleKeyDown"
+  >
+    <slot />
+  </PopperAnchor>
+</template>
diff --git a/vue/primitives/src/selection/select/SelectValue.vue b/vue/primitives/src/selection/select/SelectValue.vue
new file mode 100644
index 0000000..df2d77b
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectValue.vue
@@ -0,0 +1,63 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Displays the label(s) of the currently selected option(s) inside the trigger,
+ * or the `placeholder` when nothing is selected. Renders into a non-interactive
+ * span so pointer events fall through to the trigger. Exposes the resolved
+ * `selectedLabel` array and raw `modelValue` to its default slot for custom
+ * rendering (e.g. multi-value chips), and reflects a `data-placeholder`
+ * attribute while empty.
+ */
+export interface SelectValueProps extends PrimitiveProps {
+  /** Text shown when no option is selected. */
+  placeholder?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, watchPostEffect } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../../internal/primitive';
+import { useSelectRootContext } from './context';
+import { valueComparator } from './utils';
+
+const { as = 'span', placeholder = '' } = defineProps<SelectValueProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const rootCtx = useSelectRootContext();
+
+watchPostEffect(() => rootCtx.onValueElementChange(currentElement.value));
+
+const selectedLabel = computed<string[]>(() => {
+  const options = Array.from(rootCtx.optionsSet.value);
+  const labelFor = (v: unknown) =>
+    options.find(option => valueComparator(v as never, option.value as never, rootCtx.by as never))?.textContent ?? '';
+
+  const current = rootCtx.value.value;
+  if (Array.isArray(current)) {
+    return current.map(labelFor).filter(Boolean);
+  }
+  // Fall back to the persisted single-value label so a freshly-selected value
+  // keeps showing after the listbox (and its items) unmount.
+  const fromOptions = current === undefined ? '' : labelFor(current);
+  const resolved = fromOptions || (rootCtx.displayValue.value ?? '');
+  return resolved ? [resolved] : [];
+});
+
+const slotText = computed(() => (selectedLabel.value.length ? selectedLabel.value.join(', ') : placeholder));
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    style="pointer-events: none"
+    :data-placeholder="selectedLabel.length ? undefined : placeholder"
+  >
+    <slot :selected-label="selectedLabel" :model-value="rootCtx.value.value">
+      {{ slotText }}
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/selection/select/SelectViewport.vue b/vue/primitives/src/selection/select/SelectViewport.vue
new file mode 100644
index 0000000..cc10fdd
--- /dev/null
+++ b/vue/primitives/src/selection/select/SelectViewport.vue
@@ -0,0 +1,89 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * The scrollable region inside the content that wraps the options. Marked
+ * `role="presentation"` (the listbox role lives on the content element), caps
+ * its height to the available space, and scrolls when the list overflows. In
+ * `item-aligned` mode it grows the panel as you scroll (MacOS-style). Pair it
+ * with the scroll buttons for an item-aligned menu.
+ */
+export interface SelectViewportProps extends PrimitiveProps {
+  /**
+   * CSP `nonce` for the injected scrollbar-hiding `<style>` tag. Falls back to
+   * the active `ConfigProvider` nonce.
+   */
+  nonce?: string;
+}
+</script>
+
+<script setup lang="ts">
+import { ref, toRef, watchPostEffect } from 'vue';
+
+import { useForwardExpose } from '@robonen/vue';
+import { useNonce } from '../../utilities/config-provider';
+import { Primitive } from '../../internal/primitive';
+import { useSelectContentContext, useSelectItemAlignedPositionContext } from './context';
+import { CONTENT_MARGIN } from './utils';
+
+const { as = 'div', nonce: propNonce } = defineProps<SelectViewportProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+const contentCtx = useSelectContentContext();
+const nonce = useNonce(toRef(() => propNonce));
+
+const alignedCtx = contentCtx.position === 'item-aligned'
+  ? useSelectItemAlignedPositionContext(null as never)
+  : undefined;
+
+watchPostEffect(() => contentCtx.onViewportChange(currentElement.value));
+
+const prevScrollTopRef = ref(0);
+
+// Expand-on-scroll for item-aligned mode: grow the wrapper as the user scrolls
+// so more options become visible, matching the native MacOS menu behaviour.
+function handleScroll(event: Event) {
+  const viewport = event.currentTarget as HTMLElement;
+  const shouldExpand = alignedCtx?.shouldExpandOnScrollRef;
+  const contentWrapper = alignedCtx?.contentWrapper;
+  if (shouldExpand?.value && contentWrapper?.value) {
+    const scrolledBy = Math.abs(prevScrollTopRef.value - viewport.scrollTop);
+    if (scrolledBy > 0) {
+      const availableHeight = window.innerHeight - CONTENT_MARGIN * 2;
+      const cssMinHeight = Number.parseFloat(contentWrapper.value.style.minHeight);
+      const cssHeight = Number.parseFloat(contentWrapper.value.style.height);
+      const prevHeight = Math.max(cssMinHeight || 0, cssHeight || 0);
+
+      if (prevHeight < availableHeight) {
+        const nextHeight = prevHeight + scrolledBy;
+        const clampedNextHeight = Math.min(availableHeight, nextHeight);
+        const heightDiff = nextHeight - clampedNextHeight;
+
+        contentWrapper.value.style.height = `${clampedNextHeight}px`;
+        if (contentWrapper.value.style.bottom === '0px') {
+          viewport.scrollTop = heightDiff > 0 ? heightDiff : 0;
+          contentWrapper.value.style.justifyContent = 'flex-end';
+        }
+      }
+    }
+  }
+  prevScrollTopRef.value = viewport.scrollTop;
+}
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    role="presentation"
+    data-primitives-select-viewport
+    style="position: relative; flex: 1; overflow: hidden auto; max-height: var(--primitives-select-content-available-height, 300px)"
+    @scroll="handleScroll"
+  >
+    <slot />
+  </Primitive>
+  <Primitive as="style" :nonce="nonce">
+    [data-primitives-select-viewport]{scrollbar-width:none;-ms-overflow-style:none;-webkit-overflow-scrolling:touch;}
+    [data-primitives-select-viewport]::-webkit-scrollbar{display:none;}
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/selection/select/__test__/Select.test.ts b/vue/primitives/src/selection/select/__test__/Select.test.ts
new file mode 100644
index 0000000..b47a6af
--- /dev/null
+++ b/vue/primitives/src/selection/select/__test__/Select.test.ts
@@ -0,0 +1,387 @@
+import {
+  SelectContent,
+  SelectItem,
+  SelectItemIndicator,
+  SelectItemText,
+  SelectPortal,
+  SelectRoot,
+  SelectTrigger,
+  SelectValue,
+  SelectViewport,
+} from '../index';
+import type { SelectItemSelectEvent } from '../index';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+
+const mounted: Array<{ unmount: () => void }> = [];
+function track<T extends { unmount: () => void }>(w: T): T {
+  mounted.push(w);
+  return w;
+}
+
+afterEach(() => {
+  while (mounted.length) mounted.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+async function flush() {
+  await nextTick();
+  await nextTick();
+  await nextTick();
+}
+
+interface Opt { value: unknown; label: string; disabled?: boolean }
+
+const valueRef = ref<unknown>(undefined);
+
+function createSelect(
+  rootProps: Record<string, unknown> = {},
+  options: Opt[] = [
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' },
+    { value: 'cherry', label: 'Cherry' },
+  ],
+  itemHandlers: Record<string, unknown> = {},
+) {
+  const value = ref(rootProps.modelValue ?? rootProps.defaultValue);
+  valueRef.value = value.value;
+  const w = mount(
+    defineComponent({
+      setup() {
+        return () => h(
+          SelectRoot,
+          {
+            modelValue: value.value as never,
+            'onUpdate:modelValue': (v: unknown) => {
+              value.value = v as never;
+              valueRef.value = v;
+            },
+            ...rootProps,
+          },
+          {
+            default: () => [
+              h(SelectTrigger, null, {
+                default: () => h(SelectValue, { placeholder: 'Pick one' }),
+              }),
+              h(SelectPortal, null, {
+                default: () => h(SelectContent, null, {
+                  default: () => h(SelectViewport, null, {
+                    default: () => options.map(opt =>
+                      h(SelectItem, { key: String(opt.value), value: opt.value as never, disabled: opt.disabled, ...itemHandlers }, {
+                        default: () => [
+                          h(SelectItemText, null, { default: () => opt.label }),
+                          h(SelectItemIndicator, null, { default: () => '✓' }),
+                        ],
+                      }),
+                    ),
+                  }),
+                }),
+              }),
+            ],
+          },
+        );
+      },
+    }),
+    { attachTo: document.body },
+  );
+  return track(w);
+}
+
+function press(el: Element, key: string, init: KeyboardEventInit = {}) {
+  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }));
+}
+
+function getTrigger(): HTMLElement {
+  return document.querySelector('[role="combobox"]') as HTMLElement;
+}
+
+function getContent(): HTMLElement | null {
+  return document.querySelector('[role="listbox"]');
+}
+
+function getItems(): HTMLElement[] {
+  return Array.from(document.querySelectorAll<HTMLElement>('[role="option"]'));
+}
+
+async function openByClick(trigger: HTMLElement) {
+  trigger.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, cancelable: true, button: 0, pointerType: 'mouse' }));
+  await nextTick();
+  await nextTick();
+}
+
+describe('Select — ARIA skeleton', () => {
+  it('renders trigger as role=combobox with aria-controls and aria-expanded', () => {
+    const w = createSelect();
+    const trigger = getTrigger();
+    expect(trigger).toBeTruthy();
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+    expect(trigger.getAttribute('aria-controls')).toBeTruthy();
+    expect(trigger.getAttribute('aria-autocomplete')).toBe('none');
+    w.unmount();
+  });
+
+  it('shows placeholder + data-placeholder when empty', () => {
+    const w = createSelect();
+    const trigger = getTrigger();
+    expect(trigger.getAttribute('data-placeholder')).toBe('');
+    expect(trigger.textContent).toContain('Pick one');
+    w.unmount();
+  });
+
+  it('content carries role=listbox and matches trigger aria-controls when open', async () => {
+    const w = createSelect();
+    const trigger = getTrigger();
+    await openByClick(trigger);
+    const content = getContent();
+    expect(content).toBeTruthy();
+    expect(content!.id).toBe(trigger.getAttribute('aria-controls'));
+    expect(trigger.getAttribute('aria-expanded')).toBe('true');
+    w.unmount();
+  });
+
+  it('items expose role=option, aria-labelledby, aria-selected, data-state', async () => {
+    const w = createSelect({ defaultValue: 'banana' });
+    await openByClick(getTrigger());
+    const items = getItems();
+    expect(items).toHaveLength(3);
+    expect(items[0]!.getAttribute('aria-labelledby')).toBeTruthy();
+    const banana = items.find(i => i.textContent?.includes('Banana'))!;
+    expect(banana.getAttribute('aria-selected')).toBe('true');
+    expect(banana.getAttribute('data-state')).toBe('checked');
+    w.unmount();
+  });
+});
+
+describe('Select — initial label without opening', () => {
+  it('SelectValue shows the selected label before the dropdown is ever opened', async () => {
+    const w = createSelect({ defaultValue: 'cherry' });
+    await nextTick();
+    await nextTick();
+    const trigger = getTrigger();
+    expect(trigger.textContent).toContain('Cherry');
+    expect(trigger.getAttribute('data-placeholder')).toBeNull();
+    w.unmount();
+  });
+});
+
+describe('Select — selection (controlled + uncontrolled)', () => {
+  it('clicking an item selects its value and closes (single)', async () => {
+    createSelect();
+    const trigger = getTrigger();
+    await openByClick(trigger);
+    const banana = getItems().find(i => i.textContent?.includes('Banana'))!;
+    banana.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await flush();
+    expect(valueRef.value).toBe('banana');
+    expect(getContent()).toBeNull();
+    expect(getTrigger().textContent).toContain('Banana');
+  });
+
+  it('uncontrolled defaultValue drives initial selection', async () => {
+    const w = createSelect({ defaultValue: 'apple', modelValue: undefined });
+    await nextTick();
+    expect(getTrigger().textContent).toContain('Apple');
+    w.unmount();
+  });
+});
+
+describe('Select — keyboard', () => {
+  it('opens on ArrowDown / Enter / Space', async () => {
+    const w = createSelect();
+    const trigger = getTrigger();
+    press(trigger, 'ArrowDown');
+    await nextTick();
+    await nextTick();
+    expect(getContent()).toBeTruthy();
+    w.unmount();
+  });
+
+  it('Enter on an item selects it', async () => {
+    const w = createSelect();
+    await openByClick(getTrigger());
+    const cherry = getItems().find(i => i.textContent?.includes('Cherry'))!;
+    press(cherry, 'Enter');
+    await nextTick();
+    await nextTick();
+    expect(getTrigger().textContent).toContain('Cherry');
+    w.unmount();
+  });
+});
+
+describe('Select — disabled', () => {
+  it('root disabled prevents opening', async () => {
+    const w = createSelect({ disabled: true });
+    const trigger = getTrigger();
+    await openByClick(trigger);
+    expect(getContent()).toBeNull();
+    expect(trigger.getAttribute('data-disabled')).toBe('');
+    w.unmount();
+  });
+
+  it('disabled item does not select on click', async () => {
+    const w = createSelect({}, [
+      { value: 'a', label: 'A' },
+      { value: 'b', label: 'B', disabled: true },
+    ]);
+    await openByClick(getTrigger());
+    const b = getItems().find(i => i.textContent?.includes('B'))!;
+    expect(b.getAttribute('data-disabled')).toBe('');
+    b.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(getTrigger().textContent).not.toContain('B');
+    w.unmount();
+  });
+});
+
+describe('Select — multiple', () => {
+  it('toggles array membership and stays open', async () => {
+    createSelect({ multiple: true, modelValue: undefined, defaultValue: [] as string[] });
+    const trigger = getTrigger();
+    await openByClick(trigger);
+    getItems().find(i => i.textContent?.includes('Apple'))!.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await flush();
+    expect(getContent()).toBeTruthy(); // stays open
+    getItems().find(i => i.textContent?.includes('Cherry'))!.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await flush();
+    expect(valueRef.value).toEqual(['apple', 'cherry']);
+  });
+
+  it('reselecting a value removes it from the array', async () => {
+    createSelect({ multiple: true, modelValue: undefined, defaultValue: ['apple', 'banana'] as string[] });
+    await openByClick(getTrigger());
+    getItems().find(i => i.textContent?.includes('Apple'))!.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await flush();
+    expect(valueRef.value).toEqual(['banana']);
+  });
+});
+
+describe('Select — object values with `by`', () => {
+  it('compares object values by key', async () => {
+    const objs: Opt[] = [
+      { value: { id: 1 }, label: 'One' },
+      { value: { id: 2 }, label: 'Two' },
+    ];
+    const w = createSelect({ by: 'id', defaultValue: { id: 2 } }, objs);
+    await nextTick();
+    await nextTick();
+    expect(getTrigger().textContent).toContain('Two');
+    w.unmount();
+  });
+});
+
+describe('Select — select event is cancelable', () => {
+  it('preventDefault on the select event blocks the value change', async () => {
+    const onSelect = vi.fn((e: SelectItemSelectEvent) => e.preventDefault());
+    const w = createSelect({}, undefined, { onSelect });
+    await openByClick(getTrigger());
+    const apple = getItems().find(i => i.textContent?.includes('Apple'))!;
+    apple.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(onSelect).toHaveBeenCalled();
+    expect(getTrigger().textContent).not.toContain('Apple');
+    w.unmount();
+  });
+});
+
+describe('Select — empty-string value guard', () => {
+  it('throws if an item has an empty-string value', async () => {
+    const errors: unknown[] = [];
+    const original = globalThis.onerror;
+    const onRejection = (e: PromiseRejectionEvent) => {
+      errors.push(e.reason);
+      e.preventDefault();
+    };
+    globalThis.addEventListener('unhandledrejection', onRejection);
+    globalThis.onerror = (_m, _s, _l, _c, err) => {
+      errors.push(err);
+      return true;
+    };
+
+    const w = mount(
+      defineComponent({
+        errorCaptured(err) {
+          errors.push(err);
+          return false;
+        },
+        setup() {
+          return () => h(SelectRoot, { defaultOpen: true }, {
+            default: () => h(SelectPortal, null, {
+              default: () => h(SelectContent, null, {
+                default: () => h(SelectViewport, null, {
+                  default: () => h(SelectItem, { value: '' }, {
+                    default: () => h(SelectItemText, null, { default: () => 'Empty' }),
+                  }),
+                }),
+              }),
+            }),
+          });
+        },
+      }),
+      { attachTo: document.body },
+    );
+    track(w);
+    await flush();
+    globalThis.removeEventListener('unhandledrejection', onRejection);
+    globalThis.onerror = original;
+
+    expect(errors.some(e => (e as Error)?.message?.includes('empty string'))).toBe(true);
+  });
+});
+
+describe('Select — typeahead on closed trigger', () => {
+  it('typing selects a matching option without opening', async () => {
+    const w = createSelect();
+    await nextTick();
+    await nextTick();
+    const trigger = getTrigger();
+    press(trigger, 'c');
+    await nextTick();
+    await nextTick();
+    expect(getContent()).toBeNull();
+    expect(getTrigger().textContent).toContain('Cherry');
+    w.unmount();
+  });
+});
+
+describe('Select — native form submission', () => {
+  it('renders a hidden native select inside a form with options', async () => {
+    const w = mount(
+      defineComponent({
+        setup() {
+          const value = ref('banana');
+          return () => h('form', null, [
+            h(
+              SelectRoot,
+              { name: 'fruit', modelValue: value.value, 'onUpdate:modelValue': (v: never) => (value.value = v) },
+              {
+                default: () => [
+                  h(SelectTrigger, null, { default: () => h(SelectValue) }),
+                  h(SelectPortal, null, {
+                    default: () => h(SelectContent, null, {
+                      default: () => h(SelectViewport, null, {
+                        default: () => [
+                          h(SelectItem, { value: 'apple' }, { default: () => h(SelectItemText, null, { default: () => 'Apple' }) }),
+                          h(SelectItem, { value: 'banana' }, { default: () => h(SelectItemText, null, { default: () => 'Banana' }) }),
+                        ],
+                      }),
+                    }),
+                  }),
+                ],
+              },
+            ),
+          ]);
+        },
+      }),
+      { attachTo: document.body },
+    );
+    await nextTick();
+    await nextTick();
+    const nativeSelect = document.querySelector('form select[name="fruit"]') as HTMLSelectElement | null;
+    expect(nativeSelect).toBeTruthy();
+    expect(nativeSelect!.querySelectorAll('option').length).toBeGreaterThanOrEqual(2);
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---ARIA-skeleton-content-carries-role-listbox-and-matches-trigger-aria-controls-when-open-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---ARIA-skeleton-content-carries-role-listbox-and-matches-trigger-aria-controls-when-open-1.png
new file mode 100644
index 0000000..b5646fe
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---ARIA-skeleton-content-carries-role-listbox-and-matches-trigger-aria-controls-when-open-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---ARIA-skeleton-items-expose-role-option--aria-labelledby--aria-selected--data-state-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---ARIA-skeleton-items-expose-role-option--aria-labelledby--aria-selected--data-state-1.png
new file mode 100644
index 0000000..11dec68
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---ARIA-skeleton-items-expose-role-option--aria-labelledby--aria-selected--data-state-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---disabled-disabled-item-does-not-select-on-click-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---disabled-disabled-item-does-not-select-on-click-1.png
new file mode 100644
index 0000000..6104f12
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---disabled-disabled-item-does-not-select-on-click-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---disabled-root-disabled-prevents-opening-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---disabled-root-disabled-prevents-opening-1.png
new file mode 100644
index 0000000..b373eb8
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---disabled-root-disabled-prevents-opening-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---empty-string-value-guard-throws-if-an-item-has-an-empty-string-value-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---empty-string-value-guard-throws-if-an-item-has-an-empty-string-value-1.png
new file mode 100644
index 0000000..47767d2
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---empty-string-value-guard-throws-if-an-item-has-an-empty-string-value-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---initial-label-without-opening-SelectValue-shows-the-selected-label-before-the-dropdown-is-ever-opened-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---initial-label-without-opening-SelectValue-shows-the-selected-label-before-the-dropdown-is-ever-opened-1.png
new file mode 100644
index 0000000..3ec781a
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---initial-label-without-opening-SelectValue-shows-the-selected-label-before-the-dropdown-is-ever-opened-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---keyboard-Enter-on-an-item-selects-it-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---keyboard-Enter-on-an-item-selects-it-1.png
new file mode 100644
index 0000000..69bb035
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---keyboard-Enter-on-an-item-selects-it-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---keyboard-opens-on-ArrowDown---Enter---Space-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---keyboard-opens-on-ArrowDown---Enter---Space-1.png
new file mode 100644
index 0000000..f03fd7d
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---keyboard-opens-on-ArrowDown---Enter---Space-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---multiple-toggles-array-membership-and-stays-open-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---multiple-toggles-array-membership-and-stays-open-1.png
new file mode 100644
index 0000000..b5646fe
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---multiple-toggles-array-membership-and-stays-open-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---native-form-submission-renders-a-hidden-native-select-inside-a-form-with-options-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---native-form-submission-renders-a-hidden-native-select-inside-a-form-with-options-1.png
new file mode 100644
index 0000000..410ccf9
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---native-form-submission-renders-a-hidden-native-select-inside-a-form-with-options-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---object-values-with--by--compares-object-values-by-key-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---object-values-with--by--compares-object-values-by-key-1.png
new file mode 100644
index 0000000..0c745e4
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---object-values-with--by--compares-object-values-by-key-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---select-event-is-cancelable-preventDefault-on-the-select-event-blocks-the-value-change-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---select-event-is-cancelable-preventDefault-on-the-select-event-blocks-the-value-change-1.png
new file mode 100644
index 0000000..7cd26a2
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---select-event-is-cancelable-preventDefault-on-the-select-event-blocks-the-value-change-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---selection--controlled---uncontrolled--clicking-an-item-selects-its-value-and-closes--single--1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---selection--controlled---uncontrolled--clicking-an-item-selects-its-value-and-closes--single--1.png
new file mode 100644
index 0000000..30dfda4
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---selection--controlled---uncontrolled--clicking-an-item-selects-its-value-and-closes--single--1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---selection--controlled---uncontrolled--uncontrolled-defaultValue-drives-initial-selection-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---selection--controlled---uncontrolled--uncontrolled-defaultValue-drives-initial-selection-1.png
new file mode 100644
index 0000000..da43bbf
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---selection--controlled---uncontrolled--uncontrolled-defaultValue-drives-initial-selection-1.png differ
diff --git a/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---typeahead-on-closed-trigger-typing-selects-a-matching-option-without-opening-1.png b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---typeahead-on-closed-trigger-typing-selects-a-matching-option-without-opening-1.png
new file mode 100644
index 0000000..0ee9684
Binary files /dev/null and b/vue/primitives/src/selection/select/__test__/__screenshots__/Select.test.ts/Select---typeahead-on-closed-trigger-typing-selects-a-matching-option-without-opening-1.png differ
diff --git a/vue/primitives/src/select/context.ts b/vue/primitives/src/selection/select/context.ts
similarity index 51%
rename from vue/primitives/src/select/context.ts
rename to vue/primitives/src/selection/select/context.ts
index d17721c..237e006 100644
--- a/vue/primitives/src/select/context.ts
+++ b/vue/primitives/src/selection/select/context.ts
@@ -1,28 +1,50 @@
-import type { Ref, ShallowRef } from 'vue';
-import type { Direction } from '../config-provider';
+import type { ComputedRef, Ref, ShallowRef } from 'vue';
+import type { Direction } from '../../utilities/config-provider';
+import type { AcceptableValue } from './utils';
 
 import { useContextFactory } from '@robonen/vue';
 
+/**
+ * @deprecated Kept for backward compatibility. The select now accepts any
+ * {@link AcceptableValue} (string/number/boolean/object). `SelectValue` remains
+ * a string alias so existing `string`-typed consumers keep compiling.
+ */
 export type SelectValue = string;
 
+export interface SelectOption {
+  value: AcceptableValue;
+  disabled?: boolean;
+  textContent: string;
+}
+
 export interface SelectRootContext {
-  value: Ref<SelectValue | undefined>;
-  onValueChange: (value: SelectValue) => void;
+  value: Ref<AcceptableValue | AcceptableValue[] | undefined>;
+  onValueChange: (value: AcceptableValue) => void;
   open: Ref<boolean>;
   onOpenChange: (open: boolean) => void;
   dir: Ref<Direction | undefined>;
   disabled: Ref<boolean>;
   required: Ref<boolean>;
+  multiple: Ref<boolean>;
+  by?: string | ((a: AcceptableValue, b: AcceptableValue) => boolean);
   name: Ref<string | undefined>;
   triggerElement: ShallowRef<HTMLElement | undefined>;
   onTriggerChange: (el: HTMLElement | undefined) => void;
+  valueElement: ShallowRef<HTMLElement | undefined>;
+  onValueElementChange: (el: HTMLElement | undefined) => void;
+  triggerPointerDownPosRef: Ref<{ x: number; y: number } | null>;
   contentId: Ref<string>;
+  isEmptyModelValue: ComputedRef<boolean>;
+  /**
+   * @deprecated Superseded by `optionsSet`. The persisted single-value label
+   * still drives the legacy `displayValue` slot path.
+   */
   displayValue: Ref<string | undefined>;
-  optionsSet: ShallowRef<Map<SelectValue, string>>;
-  onOptionAdd: (value: SelectValue, textContent: string) => void;
-  onOptionRemove: (value: SelectValue) => void;
-  itemRefCallback: (el: HTMLElement | undefined, value: SelectValue, disabled: boolean) => void;
-  itemTextRefCallback: (el: HTMLElement | undefined, value: SelectValue) => void;
+  optionsSet: ShallowRef<Set<SelectOption>>;
+  onOptionAdd: (option: SelectOption) => void;
+  onOptionRemove: (option: SelectOption) => void;
+  itemRefCallback: (el: HTMLElement | undefined, value: AcceptableValue, disabled: boolean) => void;
+  itemTextRefCallback: (el: HTMLElement | undefined, value: AcceptableValue) => void;
   selectedItemRef: ShallowRef<HTMLElement | undefined>;
   selectedItemTextRef: ShallowRef<HTMLElement | undefined>;
 }
@@ -30,9 +52,11 @@ export interface SelectRootContext {
 export interface SelectContentContext {
   viewportRef: ShallowRef<HTMLElement | undefined>;
   onViewportChange: (el: HTMLElement | undefined) => void;
+  contentRef: ShallowRef<HTMLElement | undefined>;
   selectedItemRef: ShallowRef<HTMLElement | undefined>;
   selectedItemTextRef: ShallowRef<HTMLElement | undefined>;
   onItemLeave: () => void;
+  focusSelectedItem: () => void;
   itemRefCallback: SelectRootContext['itemRefCallback'];
   itemTextRefCallback: SelectRootContext['itemTextRefCallback'];
   isPositioned: Ref<boolean>;
@@ -40,14 +64,21 @@ export interface SelectContentContext {
   position: 'item-aligned' | 'popper';
 }
 
+export interface SelectItemAlignedPositionContext {
+  contentWrapper: ShallowRef<HTMLElement | undefined>;
+  shouldExpandOnScrollRef: Ref<boolean>;
+  onScrollButtonChange: (el: HTMLElement | undefined) => void;
+}
+
 export interface SelectGroupContext {
   id: Ref<string>;
 }
 
 export interface SelectItemContext {
-  value: SelectValue;
+  value: AcceptableValue;
   isSelected: Ref<boolean>;
   isDisabled: Ref<boolean>;
+  isFocused: Ref<boolean>;
   textId: Ref<string>;
   onItemTextChange: (el: HTMLElement | undefined) => void;
 }
@@ -62,6 +93,11 @@ const {
   provide: provideSelectContentContext,
 } = useContextFactory<SelectContentContext>('SelectContentContext');
 
+const {
+  inject: useSelectItemAlignedPositionContext,
+  provide: provideSelectItemAlignedPositionContext,
+} = useContextFactory<SelectItemAlignedPositionContext>('SelectItemAlignedPositionContext');
+
 const {
   inject: useSelectGroupContext,
   provide: provideSelectGroupContext,
@@ -77,6 +113,8 @@ export {
   provideSelectRootContext,
   useSelectContentContext,
   provideSelectContentContext,
+  useSelectItemAlignedPositionContext,
+  provideSelectItemAlignedPositionContext,
   useSelectGroupContext,
   provideSelectGroupContext,
   useSelectItemContext,
diff --git a/vue/primitives/src/select/demo.vue b/vue/primitives/src/selection/select/demo.vue
similarity index 100%
rename from vue/primitives/src/select/demo.vue
rename to vue/primitives/src/selection/select/demo.vue
diff --git a/vue/primitives/src/select/index.ts b/vue/primitives/src/selection/select/index.ts
similarity index 80%
rename from vue/primitives/src/select/index.ts
rename to vue/primitives/src/selection/select/index.ts
index 0ecc65b..bcc9906 100644
--- a/vue/primitives/src/select/index.ts
+++ b/vue/primitives/src/selection/select/index.ts
@@ -17,15 +17,27 @@ export { default as SelectItemText } from './SelectItemText.vue';
 export { default as SelectItemIndicator } from './SelectItemIndicator.vue';
 export { default as SelectSeparator } from './SelectSeparator.vue';
 export { default as SelectArrow } from './SelectArrow.vue';
+export { default as SelectProvider } from './SelectProvider.vue';
+export { default as SelectBubbleSelect } from './SelectBubbleSelect.vue';
 
 export {
   useSelectRootContext,
   useSelectContentContext,
+  useSelectItemAlignedPositionContext,
   useSelectGroupContext,
   useSelectItemContext,
 } from './context';
 
-export type { SelectValue, SelectRootContext, SelectContentContext, SelectGroupContext, SelectItemContext } from './context';
+export type {
+  SelectValue,
+  SelectOption,
+  SelectRootContext,
+  SelectContentContext,
+  SelectItemAlignedPositionContext,
+  SelectGroupContext,
+  SelectItemContext,
+} from './context';
+export type { AcceptableValue as SelectAcceptableValue } from './utils';
 export type { SelectRootProps, SelectRootEmits } from './SelectRoot.vue';
 export type { SelectTriggerProps } from './SelectTrigger.vue';
 export type { SelectValueProps } from './SelectValue.vue';
@@ -40,8 +52,10 @@ export type { SelectScrollUpButtonProps } from './SelectScrollUpButton.vue';
 export type { SelectScrollDownButtonProps } from './SelectScrollDownButton.vue';
 export type { SelectGroupProps } from './SelectGroup.vue';
 export type { SelectLabelProps } from './SelectLabel.vue';
-export type { SelectItemProps } from './SelectItem.vue';
+export type { SelectItemProps, SelectItemEmits, SelectItemSelectEvent } from './SelectItem.vue';
 export type { SelectItemTextProps } from './SelectItemText.vue';
 export type { SelectItemIndicatorProps } from './SelectItemIndicator.vue';
 export type { SelectSeparatorProps } from './SelectSeparator.vue';
 export type { SelectArrowProps } from './SelectArrow.vue';
+export type { SelectProviderProps } from './SelectProvider.vue';
+export type { SelectBubbleSelectProps } from './SelectBubbleSelect.vue';
diff --git a/vue/primitives/src/selection/select/utils.ts b/vue/primitives/src/selection/select/utils.ts
new file mode 100644
index 0000000..02ab7b3
--- /dev/null
+++ b/vue/primitives/src/selection/select/utils.ts
@@ -0,0 +1,124 @@
+/**
+ * Any serialisable value a select option can carry — not just strings. Mirrors
+ * the listbox/combobox value model so a select can hold numbers, booleans, or
+ * plain objects (compared via `by`).
+ */
+export type AcceptableValue = string | number | boolean | Record<string, unknown>;
+
+export const OPEN_KEYS = [' ', 'Enter', 'ArrowUp', 'ArrowDown'];
+export const SELECTION_KEYS = [' ', 'Enter'];
+export const CONTENT_MARGIN = 10;
+
+export function getOpenState(open: boolean): 'open' | 'closed' {
+  return open ? 'open' : 'closed';
+}
+
+/**
+ * Compare two option values. `by` selects the strategy: omitted → strict `===`
+ * for primitives / structural deep-equality for objects; a function → custom
+ * comparator; a string → compare that property key. Either side `undefined`
+ * never matches.
+ */
+export function compare<T>(
+  a: T | undefined,
+  b: T | undefined,
+  by?: string | ((a: T, b: T) => boolean),
+): boolean {
+  if (a === undefined || b === undefined) return false;
+  if (typeof by === 'function') return by(a, b);
+  if (typeof by === 'string') return (a as Record<string, unknown>)?.[by] === (b as Record<string, unknown>)?.[by];
+  if (typeof a === 'string') return a === b;
+  if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
+    return deepEqual(a, b);
+  }
+  return a === b;
+}
+
+/**
+ * Whether `current` is contained in `value` (a single value or array), using
+ * {@link compare} for each element.
+ */
+export function valueComparator<T>(
+  value: T | T[] | undefined,
+  current: T,
+  by?: string | ((a: T, b: T) => boolean),
+): boolean {
+  if (value === undefined) return false;
+  if (!Array.isArray(value)) return compare(value, current, by);
+  for (const v of value) {
+    if (compare(v, current, by)) return true;
+  }
+  return false;
+}
+
+/**
+ * Structural deep equality fallback for object values when `by` is omitted, so
+ * two structurally-equal plain objects are recognised as the same selection.
+ * Kept local (no external dependency) — option values are shallow plain
+ * objects/arrays.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
+
+  const aArray = Array.isArray(a);
+  const bArray = Array.isArray(b);
+  if (aArray !== bArray) return false;
+
+  if (aArray && bArray) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  const aKeys = Object.keys(a as Record<string, unknown>);
+  const bKeys = Object.keys(b as Record<string, unknown>);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) return false;
+  }
+  return true;
+}
+
+export function shouldShowPlaceholder(value?: AcceptableValue | AcceptableValue[]): boolean {
+  return value === undefined
+    || value === null
+    || value === ''
+    || (Array.isArray(value) && value.length === 0);
+}
+
+/**
+ * Rotates `array` so it starts at `startIndex`, wrapping around.
+ * `wrapArray(['a','b','c','d'], 2) === ['c','d','a','b']`.
+ */
+export function wrapArray<T>(array: T[], startIndex: number): T[] {
+  const len = array.length;
+  const out: T[] = Array.from({ length: len });
+  for (let i = 0; i < len; i++) out[i] = array[(startIndex + i) % len]!;
+  return out;
+}
+
+/**
+ * Core type-ahead matcher. Given the list of item text values, the accumulated
+ * `search` buffer, and the current match text, returns the next item text to
+ * focus (or `undefined`). Repeated single characters cycle through matches;
+ * longer buffers match by prefix without excluding the current item.
+ */
+export function getNextMatch(
+  values: string[],
+  search: string,
+  currentMatch?: string,
+): string | undefined {
+  const isRepeated = search.length > 1 && Array.from(search).every(c => c === search[0]);
+  const normalizedSearch = isRepeated ? search[0]! : search;
+  const currentMatchIndex = currentMatch ? values.indexOf(currentMatch) : -1;
+  let wrapped = wrapArray(values, Math.max(currentMatchIndex, 0));
+  const excludeCurrentMatch = normalizedSearch.length === 1;
+  if (excludeCurrentMatch) wrapped = wrapped.filter(v => v !== currentMatch);
+  const lower = normalizedSearch.toLowerCase();
+  const nextMatch = wrapped.find(v => v.toLowerCase().startsWith(lower));
+  return nextMatch !== currentMatch ? nextMatch : undefined;
+}
diff --git a/vue/primitives/src/separator/Separator.vue b/vue/primitives/src/separator/Separator.vue
deleted file mode 100644
index 1be53c2..0000000
--- a/vue/primitives/src/separator/Separator.vue
+++ /dev/null
@@ -1,45 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A thin visual divider that separates and gives meaning to groups of content,
- * such as items in a menu, sections of a toolbar, or rows in a list. Renders
- * horizontally or vertically and, unless marked `decorative`, exposes
- * `role="separator"` with the matching `aria-orientation` to assistive
- * technology. Use it to break up related content into distinct regions.
- */
-export interface SeparatorProps extends PrimitiveProps {
-  /** The orientation of the separator. */
-  orientation?: 'horizontal' | 'vertical';
-  /**
-   * When `true` the separator is purely decorative and is hidden from
-   * assistive technology (no role, `aria-hidden`). Otherwise it exposes
-   * `role="separator"` and the correct `aria-orientation`.
-   * @default false
-   */
-  decorative?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed } from 'vue';
-import { useForwardExpose } from '@robonen/vue';
-
-const { orientation = 'horizontal', decorative = false, as = 'div' } = defineProps<SeparatorProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const ariaProps = computed(() => decorative
-  ? { role: 'none' as const }
-  : {
-      role: 'separator' as const,
-      'aria-orientation': orientation === 'vertical' ? 'vertical' as const : undefined,
-    });
-</script>
-
-<template>
-  <Primitive :ref="forwardRef" :as="as" :data-orientation="orientation" v-bind="ariaProps">
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/separator/__test__/Separator.test.ts b/vue/primitives/src/separator/__test__/Separator.test.ts
deleted file mode 100644
index 30b91d0..0000000
--- a/vue/primitives/src/separator/__test__/Separator.test.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { Separator } from '../index';
-
-describe('Separator', () => {
-  it('renders with role="separator" by default', () => {
-    const wrapper = mount(Separator);
-    expect(wrapper.attributes('role')).toBe('separator');
-    expect(wrapper.attributes('data-orientation')).toBe('horizontal');
-    expect(wrapper.attributes('aria-orientation')).toBeUndefined();
-  });
-
-  it('sets aria-orientation="vertical" for vertical', () => {
-    const wrapper = mount(Separator, { props: { orientation: 'vertical' } });
-    expect(wrapper.attributes('aria-orientation')).toBe('vertical');
-    expect(wrapper.attributes('data-orientation')).toBe('vertical');
-  });
-
-  it('is decorative when requested', () => {
-    const wrapper = mount(Separator, { props: { decorative: true } });
-    expect(wrapper.attributes('role')).toBe('none');
-    expect(wrapper.attributes('aria-orientation')).toBeUndefined();
-  });
-
-  it('supports custom element via `as`', () => {
-    const wrapper = mount(Separator, { props: { as: 'hr' } });
-    expect(wrapper.element.tagName).toBe('HR');
-  });
-});
diff --git a/vue/primitives/src/separator/index.ts b/vue/primitives/src/separator/index.ts
deleted file mode 100644
index 64e1822..0000000
--- a/vue/primitives/src/separator/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { default as Separator } from './Separator.vue';
-export type { SeparatorProps } from './Separator.vue';
diff --git a/vue/primitives/src/slider/__test__/Slider.test.ts b/vue/primitives/src/slider/__test__/Slider.test.ts
deleted file mode 100644
index 1df9130..0000000
--- a/vue/primitives/src/slider/__test__/Slider.test.ts
+++ /dev/null
@@ -1,227 +0,0 @@
-import { mount } from '@vue/test-utils';
-import type { VueWrapper } from '@vue/test-utils';
-import { afterEach, describe, expect, it } from 'vitest';
-import { defineComponent, h, nextTick, ref } from 'vue';
-import { SliderRange, SliderRoot, SliderThumb, SliderTrack } from '../index';
-
-const wrappers: Array<VueWrapper<any>> = [];
-
-afterEach(() => {
-  while (wrappers.length) wrappers.pop()!.unmount();
-  document.body.innerHTML = '';
-});
-
-function track<T extends VueWrapper<any>>(w: T): T {
-  wrappers.push(w);
-  return w;
-}
-
-function mountSingle(opts: Partial<{ min: number; max: number; step: number; defaultValue: number; disabled: boolean; orientation: 'horizontal' | 'vertical'; dir: 'ltr' | 'rtl' }> = {}) {
-  const model = ref<number[] | undefined>(undefined);
-  const Harness = defineComponent({
-    setup() {
-      return () => h(SliderRoot, {
-        modelValue: model.value,
-        'onUpdate:modelValue': (v: number[]) => { model.value = v; },
-        ...opts,
-      }, {
-        default: () => [
-          h(SliderTrack, null, { default: () => h(SliderRange) }),
-          h(SliderThumb, { 'aria-label': 'Volume' }),
-        ],
-      });
-    },
-  });
-  const w = track(mount(Harness, { attachTo: document.body }));
-  return { wrapper: w, model };
-}
-
-function mountRange(opts: Partial<{ min: number; max: number; step: number; defaultValue: number[]; minStepsBetweenThumbs: number }> = {}) {
-  const model = ref<number[] | undefined>(undefined);
-  const Harness = defineComponent({
-    setup() {
-      return () => h(SliderRoot, {
-        modelValue: model.value,
-        'onUpdate:modelValue': (v: number[]) => { model.value = v; },
-        ...opts,
-      }, {
-        default: () => [
-          h(SliderTrack, null, { default: () => h(SliderRange) }),
-          h(SliderThumb, { id: 'thumb-0' }),
-          h(SliderThumb, { id: 'thumb-1' }),
-        ],
-      });
-    },
-  });
-  const w = track(mount(Harness, { attachTo: document.body }));
-  return { wrapper: w, model };
-}
-
-function keydown(el: Element, key: string): void {
-  const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true });
-  el.dispatchEvent(event);
-}
-
-describe('Slider — single thumb', () => {
-  it('renders with role="slider" and ARIA attrs', async () => {
-    mountSingle({ defaultValue: 40, min: 0, max: 100 });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    expect(thumb).toBeTruthy();
-    expect(thumb.getAttribute('aria-valuemin')).toBe('0');
-    expect(thumb.getAttribute('aria-valuemax')).toBe('100');
-    expect(thumb.getAttribute('aria-valuenow')).toBe('40');
-    expect(thumb.getAttribute('aria-orientation')).toBe('horizontal');
-    expect(thumb.tabIndex).toBe(0);
-  });
-
-  it('ArrowRight/ArrowLeft adjust by step', async () => {
-    const { model } = mountSingle({ defaultValue: 50, step: 5 });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    keydown(thumb, 'ArrowRight');
-    await nextTick();
-    expect(model.value).toEqual([55]);
-    keydown(thumb, 'ArrowLeft');
-    keydown(thumb, 'ArrowLeft');
-    await nextTick();
-    expect(model.value).toEqual([45]);
-  });
-
-  it('ArrowLeft is reversed in RTL', async () => {
-    const { model } = mountSingle({ defaultValue: 50, step: 5, dir: 'rtl' });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    keydown(thumb, 'ArrowLeft');
-    await nextTick();
-    expect(model.value).toEqual([55]);
-  });
-
-  it('Home/End clamp to min/max', async () => {
-    const { model } = mountSingle({ defaultValue: 50, min: 0, max: 100 });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    keydown(thumb, 'Home');
-    await nextTick();
-    expect(model.value).toEqual([0]);
-    keydown(thumb, 'End');
-    await nextTick();
-    expect(model.value).toEqual([100]);
-  });
-
-  it('PageUp / PageDown step by 10×', async () => {
-    const { model } = mountSingle({ defaultValue: 50, step: 1 });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    keydown(thumb, 'PageUp');
-    await nextTick();
-    expect(model.value).toEqual([60]);
-    keydown(thumb, 'PageDown');
-    keydown(thumb, 'PageDown');
-    await nextTick();
-    expect(model.value).toEqual([40]);
-  });
-
-  it('clamps at min / max', async () => {
-    const { model } = mountSingle({ defaultValue: 95, min: 0, max: 100, step: 10 });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    keydown(thumb, 'ArrowRight');
-    await nextTick();
-    expect(model.value).toEqual([100]);
-    keydown(thumb, 'End');
-    await nextTick();
-    expect(model.value).toEqual([100]);
-    keydown(thumb, 'Home');
-    await nextTick();
-    expect(model.value).toEqual([0]);
-    keydown(thumb, 'ArrowLeft');
-    await nextTick();
-    expect(model.value).toEqual([0]);
-  });
-
-  it('disabled: tabindex=-1 and keys do nothing', async () => {
-    const { model } = mountSingle({ defaultValue: 50, disabled: true });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    expect(thumb.tabIndex).toBe(-1);
-    expect(thumb.getAttribute('aria-disabled')).toBe('true');
-    keydown(thumb, 'ArrowRight');
-    await nextTick();
-    expect(model.value).toBeUndefined();
-  });
-
-  it('vertical orientation reports aria-orientation', async () => {
-    mountSingle({ defaultValue: 50, orientation: 'vertical' });
-    await nextTick();
-    const thumb = document.querySelector<HTMLElement>('[role="slider"]')!;
-    expect(thumb.getAttribute('aria-orientation')).toBe('vertical');
-  });
-
-  it('writes hidden input when name is set', async () => {
-    const Harness = defineComponent({
-      setup: () => () => h(SliderRoot, { defaultValue: 30, name: 'volume' }, {
-        default: () => [
-          h(SliderTrack, null, { default: () => h(SliderRange) }),
-          h(SliderThumb),
-        ],
-      }),
-    });
-    track(mount(Harness, { attachTo: document.body }));
-    await nextTick();
-    const input = document.querySelector<HTMLInputElement>('input[type="hidden"][name="volume"]')!;
-    expect(input).toBeTruthy();
-    expect(input.value).toBe('30');
-  });
-});
-
-describe('Slider — range (two thumbs)', () => {
-  it('renders two thumbs with independent aria-valuenow', async () => {
-    mountRange({ defaultValue: [20, 80] });
-    await nextTick();
-    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
-    expect(thumbs).toHaveLength(2);
-    expect(thumbs[0]!.getAttribute('aria-valuenow')).toBe('20');
-    expect(thumbs[1]!.getAttribute('aria-valuenow')).toBe('80');
-  });
-
-  it('preserves order by clamping against neighbour', async () => {
-    const { model } = mountRange({ defaultValue: [40, 50], step: 1 });
-    await nextTick();
-    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
-    // Push first thumb right past second
-    for (let i = 0; i < 20; i++) keydown(thumbs[0]!, 'ArrowRight');
-    await nextTick();
-    expect(model.value![0]).toBeLessThanOrEqual(model.value![1]!);
-    expect(model.value![0]).toBe(50);
-  });
-
-  it('respects minStepsBetweenThumbs', async () => {
-    const { model } = mountRange({ defaultValue: [30, 50], step: 1, minStepsBetweenThumbs: 10 });
-    await nextTick();
-    const thumbs = document.querySelectorAll<HTMLElement>('[role="slider"]');
-    // Try to move first thumb up; should stop 10 below second.
-    for (let i = 0; i < 30; i++) keydown(thumbs[0]!, 'ArrowRight');
-    await nextTick();
-    expect(model.value![0]).toBe(40);
-    expect(model.value![1]).toBe(50);
-  });
-
-  it('writes hidden inputs with [] suffix for range', async () => {
-    const Harness = defineComponent({
-      setup: () => () => h(SliderRoot, { defaultValue: [10, 90], name: 'range' }, {
-        default: () => [
-          h(SliderTrack, null, { default: () => h(SliderRange) }),
-          h(SliderThumb),
-          h(SliderThumb),
-        ],
-      }),
-    });
-    track(mount(Harness, { attachTo: document.body }));
-    await nextTick();
-    const inputs = document.querySelectorAll<HTMLInputElement>('input[type="hidden"][name="range[]"]');
-    expect(inputs).toHaveLength(2);
-    expect(inputs[0]!.value).toBe('10');
-    expect(inputs[1]!.value).toBe('90');
-  });
-});
diff --git a/vue/primitives/src/stepper/__test__/Stepper.test.ts b/vue/primitives/src/stepper/__test__/Stepper.test.ts
deleted file mode 100644
index bf8a73f..0000000
--- a/vue/primitives/src/stepper/__test__/Stepper.test.ts
+++ /dev/null
@@ -1,176 +0,0 @@
-import {
-  StepperDescription,
-  StepperIndicator,
-  StepperItem,
-  StepperRoot,
-  StepperSeparator,
-  StepperTitle,
-  StepperTrigger,
-} from '../index';
-import { defineComponent, h, nextTick, ref } from 'vue';
-import { describe, expect, it } from 'vitest';
-import { mount } from '@vue/test-utils';
-
-function createStepper(rootProps: Record<string, unknown> = {}, stepCount = 3, itemProps: Record<number, Record<string, unknown>> = {}) {
-  return mount(
-    defineComponent({
-      setup() {
-        return () => h(
-          StepperRoot,
-          rootProps,
-          {
-            default: () => Array.from({ length: stepCount }, (_, i) => {
-              const step = i + 1;
-              return h(
-                StepperItem,
-                { key: step, step, ...itemProps[step] },
-                {
-                  default: () => [
-                    h(StepperTrigger, null, { default: () => [
-                      h(StepperIndicator),
-                      h(StepperTitle, null, { default: () => `Step ${step}` }),
-                      h(StepperDescription, null, { default: () => `Description ${step}` }),
-                    ] }),
-                    i < stepCount - 1 ? h(StepperSeparator) : null,
-                  ],
-                },
-              );
-            }),
-          },
-        );
-      },
-    }),
-    { attachTo: document.body },
-  );
-}
-
-function press(el: Element, key: string) {
-  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
-}
-
-describe('Stepper', () => {
-  it('renders with role=group', () => {
-    const w = createStepper();
-    const root = w.find('[role="group"]');
-    expect(root.exists()).toBe(true);
-    expect(root.attributes('aria-label')).toBe('progress');
-    w.unmount();
-  });
-
-  it('first item is active by default (step=1)', () => {
-    const w = createStepper();
-    const items = w.findAllComponents(StepperItem);
-    expect(items[0]!.attributes('data-state')).toBe('active');
-    expect(items[0]!.attributes('aria-current')).toBe('step');
-    expect(items[1]!.attributes('data-state')).toBe('inactive');
-    w.unmount();
-  });
-
-  it('honors defaultValue', () => {
-    const w = createStepper({ defaultValue: 2 });
-    const items = w.findAllComponents(StepperItem);
-    expect(items[0]!.attributes('data-state')).toBe('completed');
-    expect(items[1]!.attributes('data-state')).toBe('active');
-    expect(items[2]!.attributes('data-state')).toBe('inactive');
-    w.unmount();
-  });
-
-  it('v-model moves the active step', async () => {
-    const value = ref(1);
-    const w = mount(
-      defineComponent({
-        setup() {
-          return () => h(
-            StepperRoot,
-            { modelValue: value.value, 'onUpdate:modelValue': (v: number) => (value.value = v) },
-            {
-              default: () => [1, 2, 3].map(step =>
-                h(StepperItem, { key: step, step }, { default: () => h(StepperTrigger, null, { default: () => `S${step}` }) }),
-              ),
-            },
-          );
-        },
-      }),
-      { attachTo: document.body },
-    );
-    const triggers = w.findAll('button');
-    await triggers[1]!.trigger('mousedown');
-    await nextTick();
-    expect(value.value).toBe(2);
-    w.unmount();
-  });
-
-  it('linear mode blocks skipping ahead', async () => {
-    const w = createStepper();
-    const triggers = w.findAll('button');
-    await triggers[2]!.trigger('mousedown'); // try to skip to 3
-    await nextTick();
-    const items = w.findAllComponents(StepperItem);
-    expect(items[0]!.attributes('data-state')).toBe('active'); // unchanged
-    w.unmount();
-  });
-
-  it('non-linear mode allows arbitrary step', async () => {
-    const w = createStepper({ linear: false });
-    const triggers = w.findAll('button');
-    await triggers[2]!.trigger('mousedown');
-    await nextTick();
-    const items = w.findAllComponents(StepperItem);
-    expect(items[2]!.attributes('data-state')).toBe('active');
-    w.unmount();
-  });
-
-  it('disabled item is not focusable and cannot be activated', async () => {
-    const w = createStepper({ linear: false }, 3, { 2: { disabled: true } });
-    const items = w.findAllComponents(StepperItem);
-    expect(items[1]!.attributes('data-disabled')).toBe('');
-    const triggers = w.findAll('button');
-    expect(triggers[1]!.attributes('tabindex')).toBe('-1');
-    await triggers[1]!.trigger('mousedown');
-    await nextTick();
-    expect(items[0]!.attributes('data-state')).toBe('active'); // unchanged
-    w.unmount();
-  });
-
-  it('Enter/Space on trigger activates step', async () => {
-    const w = createStepper({ linear: false });
-    const triggers = w.findAll('button');
-    (triggers[1]!.element as HTMLElement).focus();
-    press(triggers[1]!.element, 'Enter');
-    await nextTick();
-    const items = w.findAllComponents(StepperItem);
-    expect(items[1]!.attributes('data-state')).toBe('active');
-    w.unmount();
-  });
-
-  it('ArrowRight / ArrowLeft move focus between triggers', () => {
-    const w = createStepper({ linear: false });
-    const triggers = w.findAll('button').map(t => t.element as HTMLElement);
-    triggers[0]!.focus();
-    press(triggers[0]!, 'ArrowRight');
-    expect(document.activeElement).toBe(triggers[1]);
-    press(triggers[1]!, 'ArrowRight');
-    expect(document.activeElement).toBe(triggers[2]);
-    press(triggers[2]!, 'ArrowLeft');
-    expect(document.activeElement).toBe(triggers[1]);
-    w.unmount();
-  });
-
-  it('Home / End jump to first / last trigger', () => {
-    const w = createStepper({ linear: false });
-    const triggers = w.findAll('button').map(t => t.element as HTMLElement);
-    triggers[1]!.focus();
-    press(triggers[1]!, 'End');
-    expect(document.activeElement).toBe(triggers[2]);
-    press(triggers[2]!, 'Home');
-    expect(document.activeElement).toBe(triggers[0]);
-    w.unmount();
-  });
-
-  it('completed prop forces completed state', () => {
-    const w = createStepper({}, 3, { 1: { completed: true } });
-    const items = w.findAllComponents(StepperItem);
-    expect(items[0]!.attributes('data-state')).toBe('completed');
-    w.unmount();
-  });
-});
diff --git a/vue/primitives/src/switch/index.ts b/vue/primitives/src/switch/index.ts
deleted file mode 100644
index 0a5aa7d..0000000
--- a/vue/primitives/src/switch/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { default as Switch } from './Switch.vue';
-export type { SwitchProps } from './Switch.vue';
diff --git a/vue/primitives/src/tabs/TabsContent.vue b/vue/primitives/src/tabs/TabsContent.vue
deleted file mode 100644
index 19ca154..0000000
--- a/vue/primitives/src/tabs/TabsContent.vue
+++ /dev/null
@@ -1,43 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The panel shown when its matching `TabsTrigger` is active. Rendered only
- * while selected unless `forceMount` keeps it mounted (hidden) for animations
- * or to preserve state. Pair one with each trigger via a shared `value`.
- */
-export interface TabsContentProps extends PrimitiveProps {
-  /** Value that links this panel to a trigger. */
-  value: string;
-  /** Keep content mounted even when inactive. */
-  forceMount?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { computed } from 'vue';
-import { useForwardExpose } from '@robonen/vue';
-import { useTabsContext } from './context';
-
-const { value, forceMount = false, as = 'div' } = defineProps<TabsContentProps>();
-
-const { forwardRef } = useForwardExpose();
-const ctx = useTabsContext();
-const isSelected = computed(() => ctx.value.value === value);
-</script>
-
-<template>
-  <Primitive
-    v-if="forceMount || isSelected"
-    :ref="forwardRef"
-    :as="as"
-    role="tabpanel"
-    :data-state="isSelected ? 'active' : 'inactive'"
-    :data-orientation="ctx.orientation.value"
-    :tabindex="0"
-    :hidden="forceMount && !isSelected ? true : undefined"
-  >
-    <slot :selected="isSelected" />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/tabs/TabsRoot.vue b/vue/primitives/src/tabs/TabsRoot.vue
deleted file mode 100644
index b1c07f2..0000000
--- a/vue/primitives/src/tabs/TabsRoot.vue
+++ /dev/null
@@ -1,121 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { RovingDirection } from '../utils/roving-focus';
-
-/**
- * A set of layered sections of content — known as tab panels — where only one
- * panel is shown at a time, each surfaced by its own trigger. Use it to split
- * related content into switchable views without leaving the page: settings
- * panes, dashboards, or product detail sections.
- *
- * The root owns the selected value (controlled via `v-model` or uncontrolled
- * via `defaultValue`), orientation, keyboard roving focus across triggers, and
- * provides context to every `TabsList`, `TabsTrigger`, and `TabsContent`.
- */
-export interface TabsRootProps extends PrimitiveProps {
-  /** Uncontrolled initial value. */
-  defaultValue?: string;
-  /** Orientation of the tab list. @default 'horizontal' */
-  orientation?: 'horizontal' | 'vertical';
-  /** Writing direction. @default 'ltr' */
-  dir?: RovingDirection;
-  /** Wrap keyboard navigation. @default true */
-  loop?: boolean;
-  /** Disable all tabs. */
-  disabled?: boolean;
-  /** How tabs are activated. @default 'automatic' */
-  activationMode?: 'automatic' | 'manual';
-}
-</script>
-
-<script setup lang="ts">
-import { computed, ref, toRef } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { useCollectionProvider } from '../collection';
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { provideTabsContext } from './context';
-
-const {
-  orientation = 'horizontal',
-  dir = 'ltr',
-  loop = true,
-  disabled = false,
-  activationMode = 'automatic',
-  defaultValue,
-  as = 'div',
-} = defineProps<TabsRootProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const localValue = ref<string | undefined>(defaultValue);
-
-const value = defineModel<string | undefined>({
-  get: v => v ?? localValue.value,
-  set: (v) => {
-    localValue.value = v;
-    return v;
-  },
-});
-
-function select(v: string): void {
-  if (disabled) return;
-  value.value = v;
-}
-
-// DOM-order tabs via Collection primitive — survives `v-for` reorders and
-// teleport/portal children, unlike a mount-order array.
-const { getItems, CollectionSlot } = useCollectionProvider();
-const tabElements = computed(() => getItems(true).map(i => i.ref));
-
-function onTriggerKeyDown(event: KeyboardEvent, el: HTMLElement): void {
-  const action = rovingKeyToAction(event, { orientation, dir, loop });
-  if (!action) return;
-  event.preventDefault();
-  const enabled = tabElements.value.filter(x => !x.hasAttribute('data-disabled'));
-  if (enabled.length === 0) return;
-  const current = enabled.indexOf(el);
-  if (action.absolute === 'home') {
-    enabled[0]!.focus();
-    return;
-  }
-  if (action.absolute === 'end') {
-    enabled[enabled.length - 1]!.focus();
-    return;
-  }
-  const nextIdx = resolveNextIndex(current === -1 ? 0 : current, action.delta, enabled.length, loop);
-  const target = enabled[nextIdx]!;
-  target.focus();
-  if (activationMode === 'automatic') {
-    const val = target.getAttribute('data-value');
-    if (val !== null) select(val);
-  }
-}
-
-provideTabsContext({
-  value,
-  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
-  orientation: toRef(() => orientation),
-  direction: toRef(() => dir),
-  loop: toRef(() => loop),
-  disabled: toRef(() => disabled),
-  activationMode: toRef(() => activationMode),
-  tabElements,
-  select,
-  onTriggerKeyDown,
-});
-</script>
-
-<template>
-  <CollectionSlot>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      :dir="dir"
-      :data-orientation="orientation"
-      :data-disabled="disabled ? '' : undefined"
-    >
-      <slot :value="value" />
-    </Primitive>
-  </CollectionSlot>
-</template>
diff --git a/vue/primitives/src/tabs/__test__/Tabs.test.ts b/vue/primitives/src/tabs/__test__/Tabs.test.ts
deleted file mode 100644
index f31b87e..0000000
--- a/vue/primitives/src/tabs/__test__/Tabs.test.ts
+++ /dev/null
@@ -1,225 +0,0 @@
-import { TabsContent, TabsList, TabsRoot, TabsTrigger } from '../index';
-import { defineComponent, h, nextTick, ref } from 'vue';
-import { describe, expect, it } from 'vitest';
-import { mount } from '@vue/test-utils';
-
-function createTabs(props: Record<string, unknown> = {}) {
-  return mount(
-    defineComponent({
-      setup() {
-        return () => h(TabsRoot, { ...props }, {
-          default: () => [
-            h(TabsList, null, {
-              default: () => [
-                h(TabsTrigger, { value: 'a' }, { default: () => 'Tab A' }),
-                h(TabsTrigger, { value: 'b' }, { default: () => 'Tab B' }),
-                h(TabsTrigger, { value: 'c', disabled: true }, { default: () => 'Tab C' }),
-              ],
-            }),
-            h(TabsContent, { value: 'a' }, { default: () => 'Panel A' }),
-            h(TabsContent, { value: 'b' }, { default: () => 'Panel B' }),
-            h(TabsContent, { value: 'c' }, { default: () => 'Panel C' }),
-          ],
-        });
-      },
-    }),
-    { attachTo: document.body },
-  );
-}
-
-function press(el: Element, key: string, opts: Record<string, unknown> = {}) {
-  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...opts }));
-}
-
-describe('Tabs', () => {
-  it('renders tablist with correct roles', () => {
-    const w = createTabs({ defaultValue: 'a' });
-    expect(w.find('[role="tablist"]').exists()).toBe(true);
-    expect(w.findAll('[role="tab"]')).toHaveLength(3);
-    expect(w.find('[role="tabpanel"]').exists()).toBe(true);
-    w.unmount();
-  });
-
-  it('shows correct panel based on defaultValue', () => {
-    const w = createTabs({ defaultValue: 'b' });
-    const panels = w.findAll('[role="tabpanel"]');
-    expect(panels).toHaveLength(1);
-    expect(panels[0]!.text()).toBe('Panel B');
-    w.unmount();
-  });
-
-  it('selects tab on click', async () => {
-    const w = createTabs({ defaultValue: 'a' });
-    const tabs = w.findAll('[role="tab"]');
-    await tabs[1]!.trigger('click');
-    await nextTick();
-    expect(w.find('[role="tabpanel"]').text()).toBe('Panel B');
-    const tabB = tabs[1]!.element;
-    expect(tabB.getAttribute('aria-selected')).toBe('true');
-    expect(tabB.getAttribute('data-state')).toBe('active');
-    w.unmount();
-  });
-
-  it('supports v-model', async () => {
-    const value = ref('a');
-    const w = mount(
-      defineComponent({
-        setup() {
-          return () => h(TabsRoot, {
-            modelValue: value.value,
-            'onUpdate:modelValue': (v: string | undefined) => { value.value = v!; },
-          }, {
-            default: () => [
-              h(TabsList, null, {
-                default: () => [
-                  h(TabsTrigger, { value: 'a' }, { default: () => 'A' }),
-                  h(TabsTrigger, { value: 'b' }, { default: () => 'B' }),
-                ],
-              }),
-              h(TabsContent, { value: 'a' }, { default: () => 'PA' }),
-              h(TabsContent, { value: 'b' }, { default: () => 'PB' }),
-            ],
-          });
-        },
-      }),
-      { attachTo: document.body },
-    );
-
-    expect(w.find('[role="tabpanel"]').text()).toBe('PA');
-    const tabs = w.findAll('[role="tab"]');
-    await tabs[1]!.trigger('click');
-    await nextTick();
-    expect(value.value).toBe('b');
-    w.unmount();
-  });
-
-  it('navigates with arrow keys (horizontal)', async () => {
-    const w = createTabs({ defaultValue: 'a' });
-    await nextTick();
-    const tabs = w.findAll('[role="tab"]');
-    const tabA = tabs[0]!.element as HTMLElement;
-    tabA.focus();
-
-    press(tabA, 'ArrowRight');
-    await nextTick();
-    expect(document.activeElement).toBe(tabs[1]!.element);
-    // automatic mode → panel also switches
-    expect(w.find('[role="tabpanel"]').text()).toBe('Panel B');
-
-    // ArrowRight from B should skip disabled C and loop to A
-    press(tabs[1]!.element, 'ArrowRight');
-    await nextTick();
-    expect(document.activeElement).toBe(tabs[0]!.element);
-
-    w.unmount();
-  });
-
-  it('navigates with arrow keys (vertical)', async () => {
-    const w = createTabs({ defaultValue: 'a', orientation: 'vertical' });
-    await nextTick();
-    const tabs = w.findAll('[role="tab"]');
-    const tabA = tabs[0]!.element as HTMLElement;
-    tabA.focus();
-
-    press(tabA, 'ArrowDown');
-    await nextTick();
-    expect(document.activeElement).toBe(tabs[1]!.element);
-    w.unmount();
-  });
-
-  it('Home/End keys', async () => {
-    const w = createTabs({ defaultValue: 'a' });
-    await nextTick();
-    const tabs = w.findAll('[role="tab"]');
-    const tabB = tabs[1]!.element as HTMLElement;
-    tabB.focus();
-
-    press(tabB, 'Home');
-    await nextTick();
-    expect(document.activeElement).toBe(tabs[0]!.element);
-
-    press(tabs[0]!.element, 'End');
-    await nextTick();
-    // End goes to last enabled — B (C is disabled)
-    expect(document.activeElement).toBe(tabs[1]!.element);
-    w.unmount();
-  });
-
-  it('does not select disabled tabs', async () => {
-    const w = createTabs({ defaultValue: 'a' });
-    const tabs = w.findAll('[role="tab"]');
-    await tabs[2]!.trigger('click');
-    await nextTick();
-    // Should remain on panel A
-    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
-    w.unmount();
-  });
-
-  it('disabled root blocks all interaction', async () => {
-    const w = createTabs({ defaultValue: 'a', disabled: true });
-    const tabs = w.findAll('[role="tab"]');
-    await tabs[1]!.trigger('click');
-    await nextTick();
-    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
-    w.unmount();
-  });
-
-  it('manual activation mode: arrow keys move focus but do not select', async () => {
-    const w = createTabs({ defaultValue: 'a', activationMode: 'manual' });
-    await nextTick();
-    const tabs = w.findAll('[role="tab"]');
-    const tabA = tabs[0]!.element as HTMLElement;
-    tabA.focus();
-
-    press(tabA, 'ArrowRight');
-    await nextTick();
-    expect(document.activeElement).toBe(tabs[1]!.element);
-    // panel stays on A until explicit Enter/Space
-    expect(w.find('[role="tabpanel"]').text()).toBe('Panel A');
-    w.unmount();
-  });
-
-  it('sets correct tabindex: selected=0, others=-1', () => {
-    const w = createTabs({ defaultValue: 'b' });
-    const tabs = w.findAll('[role="tab"]');
-    expect(tabs[0]!.attributes('tabindex')).toBe('-1');
-    expect(tabs[1]!.attributes('tabindex')).toBe('0');
-    expect(tabs[2]!.attributes('tabindex')).toBe('-1');
-    w.unmount();
-  });
-
-  it('forceMount keeps panels in DOM', () => {
-    const w = mount(
-      defineComponent({
-        setup() {
-          return () => h(TabsRoot, { defaultValue: 'a' }, {
-            default: () => [
-              h(TabsList, null, {
-                default: () => [
-                  h(TabsTrigger, { value: 'a' }, { default: () => 'A' }),
-                  h(TabsTrigger, { value: 'b' }, { default: () => 'B' }),
-                ],
-              }),
-              h(TabsContent, { value: 'a', forceMount: true }, { default: () => 'PA' }),
-              h(TabsContent, { value: 'b', forceMount: true }, { default: () => 'PB' }),
-            ],
-          });
-        },
-      }),
-      { attachTo: document.body },
-    );
-
-    const panels = w.findAll('[role="tabpanel"]');
-    expect(panels).toHaveLength(2);
-    // inactive panel has hidden attribute
-    expect(panels[1]!.attributes('hidden')).toBeDefined();
-    w.unmount();
-  });
-
-  it('orientation reflects in data-orientation and aria-orientation', () => {
-    const w = createTabs({ defaultValue: 'a', orientation: 'vertical' });
-    expect(w.find('[role="tablist"]').attributes('aria-orientation')).toBe('vertical');
-    expect(w.find('[role="tablist"]').attributes('data-orientation')).toBe('vertical');
-    w.unmount();
-  });
-});
diff --git a/vue/primitives/src/tabs/context.ts b/vue/primitives/src/tabs/context.ts
deleted file mode 100644
index 150d1ba..0000000
--- a/vue/primitives/src/tabs/context.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { ComputedRef, Ref } from 'vue';
-import { useContextFactory } from '@robonen/vue';
-
-export interface TabsContext {
-  value: Ref<string | undefined>;
-  orientation: Ref<'horizontal' | 'vertical'>;
-  direction: Ref<'ltr' | 'rtl'>;
-  loop: Ref<boolean>;
-  disabled: Ref<boolean>;
-  activationMode: Ref<'automatic' | 'manual'>;
-  /** DOM-ordered tab elements, sourced from the internal Collection. */
-  tabElements: ComputedRef<HTMLElement[]>;
-  select: (value: string) => void;
-  onTriggerKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
-}
-
-export const {
-  inject: useTabsContext,
-  provide: provideTabsContext,
-} = useContextFactory<TabsContext>('TabsContext');
diff --git a/vue/primitives/src/teleport/__test__/Teleport.test.ts b/vue/primitives/src/teleport/__test__/Teleport.test.ts
deleted file mode 100644
index de8b674..0000000
--- a/vue/primitives/src/teleport/__test__/Teleport.test.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { mount } from '@vue/test-utils';
-import { defineComponent, h, nextTick } from 'vue';
-import Teleport from '../Teleport.vue';
-
-describe('Teleport primitive', () => {
-  let host: HTMLElement;
-
-  beforeEach(() => {
-    host = document.createElement('div');
-    host.id = 'teleport-target';
-    document.body.appendChild(host);
-  });
-
-  afterEach(() => {
-    host.remove();
-  });
-
-  it('teleports default slot content to `to` target', async () => {
-    const w = mount(Teleport, {
-      props: { to: '#teleport-target' },
-      slots: { default: () => h('span', { 'data-testid': 'child' }, 'hello') },
-      attachTo: document.body,
-    });
-
-    await nextTick();
-    expect(host.querySelector('[data-testid=child]')?.textContent).toBe('hello');
-    w.unmount();
-  });
-
-  it('accepts an HTMLElement as `to`', async () => {
-    const w = mount(Teleport, {
-      props: { to: host },
-      slots: { default: () => h('span', { 'data-testid': 'child' }, 'x') },
-      attachTo: document.body,
-    });
-
-    await nextTick();
-    expect(host.querySelector('[data-testid=child]')).toBeTruthy();
-    w.unmount();
-  });
-
-  it('renders children in place when disabled', async () => {
-    const Parent = defineComponent({
-      render() {
-        return h('div', { id: 'parent' }, [
-          h(Teleport, { to: '#teleport-target', disabled: true }, {
-            default: () => h('span', { 'data-testid': 'child' }, 'inline'),
-          }),
-        ]);
-      },
-    });
-
-    const w = mount(Parent, { attachTo: document.body });
-    await nextTick();
-
-    expect(document.querySelector('#parent [data-testid=child]')).toBeTruthy();
-    expect(host.querySelector('[data-testid=child]')).toBeFalsy();
-
-    w.unmount();
-  });
-
-  it('defaults to body when `to` is omitted', async () => {
-    const w = mount(Teleport, {
-      slots: { default: () => h('span', { 'data-testid': 'body-child' }, 'hi') },
-      attachTo: document.body,
-    });
-
-    await nextTick();
-    expect(document.body.querySelector('[data-testid=body-child]')).toBeTruthy();
-    w.unmount();
-  });
-});
diff --git a/vue/primitives/src/toast/ToastAction.vue b/vue/primitives/src/toast/ToastAction.vue
deleted file mode 100644
index 0cae5d4..0000000
--- a/vue/primitives/src/toast/ToastAction.vue
+++ /dev/null
@@ -1,36 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * An actionable control inside a toast (e.g. "Undo" or "View"). Renders a button by
- * default and requires `altText` so the action remains understandable to assistive
- * technology even when the toast is announced out of context.
- */
-export interface ToastActionProps extends PrimitiveProps {
-  /**
-   * Accessible description for screen readers (required).
-   * Describes what happens when the user triggers the action.
-   */
-  altText: string;
-}
-</script>
-
-<script setup lang="ts">
-import { useForwardExpose } from '@robonen/vue';
-
-import { Primitive } from '../primitive';
-
-const { as = 'button', altText } = defineProps<ToastActionProps>();
-const { forwardRef } = useForwardExpose();
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    :aria-label="altText"
-    data-primitives-toast-action
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/toast/ToastClose.vue b/vue/primitives/src/toast/ToastClose.vue
deleted file mode 100644
index 10992d7..0000000
--- a/vue/primitives/src/toast/ToastClose.vue
+++ /dev/null
@@ -1,31 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A button that dismisses the toast it lives in. Renders a button by default and
- * closes the parent `ToastRoot` via toast context on click.
- */
-export interface ToastCloseProps extends PrimitiveProps {}
-</script>
-
-<script setup lang="ts">
-import { useForwardExpose } from '@robonen/vue';
-
-import { Primitive } from '../primitive';
-import { useToastContext } from './context';
-
-const { as = 'button' } = defineProps<ToastCloseProps>();
-const { forwardRef } = useForwardExpose();
-const toastCtx = useToastContext();
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    data-primitives-toast-close
-    @click="toastCtx.onClose()"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/toast/ToastRoot.vue b/vue/primitives/src/toast/ToastRoot.vue
deleted file mode 100644
index 6c27ff8..0000000
--- a/vue/primitives/src/toast/ToastRoot.vue
+++ /dev/null
@@ -1,151 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A single toast notification. Manages its own open state and auto-dismiss timer,
- * and provides context to its `Title`, `Description`, `Action`, and `Close` children.
- * Control visibility with `v-model:open`; rendering is gated by `Presence` so exit
- * transitions can play before the element unmounts.
- */
-export interface ToastRootProps extends PrimitiveProps {
-  /** Override the provider's auto-dismiss duration. Use `Infinity` to disable. */
-  duration?: number;
-  /** Toast type — controls the `aria-live` politeness. @default 'background' */
-  type?: 'foreground' | 'background';
-}
-
-export interface ToastRootEmits {
-  escapeKeyDown: [event: KeyboardEvent];
-  pause: [];
-  resume: [];
-}
-</script>
-
-<script setup lang="ts">
-import { onBeforeUnmount, onMounted, toRef, watch } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { useId } from '../config-provider';
-import { Presence } from '../presence';
-import { Primitive } from '../primitive';
-import { provideToastContext, useToastProviderContext } from './context';
-import { VIEWPORT_PAUSE, VIEWPORT_RESUME } from './utils';
-
-const {
-  as = 'li',
-  duration,
-  type = 'background',
-} = defineProps<ToastRootProps>();
-
-const emit = defineEmits<ToastRootEmits>();
-
-const { forwardRef } = useForwardExpose();
-const providerCtx = useToastProviderContext();
-const toastId = useId(undefined, 'toast');
-const durationRef = toRef(() => duration);
-
-const open = defineModel<boolean>('open', {
-  default: true,
-});
-
-let closeTimer: ReturnType<typeof setTimeout> | null = null;
-
-function clearTimer() {
-  if (closeTimer) {
-    clearTimeout(closeTimer);
-    closeTimer = null;
-  }
-}
-
-function startTimer(ms: number) {
-  clearTimer();
-  if (ms === Infinity || ms <= 0 || !Number.isFinite(ms)) return;
-  closeTimer = setTimeout(() => {
-    open.value = false;
-  }, ms);
-}
-
-function handleClose() {
-  open.value = false;
-}
-
-function handleEscapeKeyDown(event: KeyboardEvent) {
-  emit('escapeKeyDown', event);
-  // Pressing Escape while a toast is focused dismisses it (matches the
-  // ToastClose / auto-dismiss path). Swipe-to-dismiss is not yet implemented.
-  if (!event.defaultPrevented)
-    handleClose();
-}
-
-function pauseTimer() {
-  clearTimer();
-  providerCtx.isClosePausedRef.value = true;
-  emit('pause');
-}
-
-function resumeTimer() {
-  providerCtx.isClosePausedRef.value = false;
-  const ms = durationRef.value ?? providerCtx.duration.value;
-  startTimer(ms);
-  emit('resume');
-}
-
-// Restart timer when reactive duration changes (and we are not paused).
-watch(
-  [durationRef, () => providerCtx.duration.value],
-  () => {
-    if (!open.value) return;
-    if (providerCtx.isClosePausedRef.value) return;
-    const ms = durationRef.value ?? providerCtx.duration.value;
-    startTimer(ms);
-  },
-);
-
-onMounted(() => {
-  providerCtx.onToastAdd();
-  const ms = durationRef.value ?? providerCtx.duration.value;
-  startTimer(ms);
-
-  const viewport = providerCtx.viewportRef.value;
-  if (viewport) {
-    viewport.addEventListener(VIEWPORT_PAUSE, pauseTimer);
-    viewport.addEventListener(VIEWPORT_RESUME, resumeTimer);
-  }
-});
-
-onBeforeUnmount(() => {
-  providerCtx.onToastRemove();
-  clearTimer();
-
-  const viewport = providerCtx.viewportRef.value;
-  if (viewport) {
-    viewport.removeEventListener(VIEWPORT_PAUSE, pauseTimer);
-    viewport.removeEventListener(VIEWPORT_RESUME, resumeTimer);
-  }
-});
-
-provideToastContext({
-  onClose: handleClose,
-  duration: durationRef,
-  open,
-  toastId,
-});
-</script>
-
-<template>
-  <Presence :present="open">
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      role="status"
-      :aria-live="type === 'foreground' ? 'assertive' : 'polite'"
-      :aria-atomic="true"
-      :data-state="open ? 'open' : 'closed'"
-      :data-type="type"
-      tabindex="-1"
-      @keydown.escape="handleEscapeKeyDown"
-    >
-      <slot />
-    </Primitive>
-  </Presence>
-</template>
diff --git a/vue/primitives/src/toast/ToastViewport.vue b/vue/primitives/src/toast/ToastViewport.vue
deleted file mode 100644
index b754aff..0000000
--- a/vue/primitives/src/toast/ToastViewport.vue
+++ /dev/null
@@ -1,89 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * The fixed-position region (an `<ol>`) where toasts are rendered. Provides the
- * accessible landmark for the toast list, pauses auto-dismiss timers on hover/focus,
- * and can be focused via a keyboard hotkey. Render exactly one per provider.
- */
-export interface ToastViewportProps extends PrimitiveProps {
-  /** Accessible label for the toast region. Overrides the provider label. */
-  label?: string;
-  /** Keyboard shortcut to focus the viewport. @default ['F8'] */
-  hotkey?: string[];
-}
-</script>
-
-<script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, watchPostEffect } from 'vue';
-
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { useToastProviderContext } from './context';
-import { VIEWPORT_PAUSE, VIEWPORT_RESUME } from './utils';
-
-const { as = 'ol', hotkey = ['F8'], label } = defineProps<ToastViewportProps>();
-
-const { forwardRef, currentElement } = useForwardExpose();
-const providerCtx = useToastProviderContext();
-
-watchPostEffect(() => providerCtx.onViewportChange(currentElement.value));
-
-const viewportLabel = computed(() => label ?? providerCtx.label.value);
-
-function handlePointerEnter() {
-  currentElement.value?.dispatchEvent(new CustomEvent(VIEWPORT_PAUSE, { bubbles: true }));
-}
-
-function handlePointerLeave() {
-  currentElement.value?.dispatchEvent(new CustomEvent(VIEWPORT_RESUME, { bubbles: true }));
-}
-
-function handleFocusIn() {
-  currentElement.value?.dispatchEvent(new CustomEvent(VIEWPORT_PAUSE, { bubbles: true }));
-}
-
-function handleFocusOut(event: FocusEvent) {
-  if (currentElement.value?.contains(event.relatedTarget as Node)) return;
-  currentElement.value?.dispatchEvent(new CustomEvent(VIEWPORT_RESUME, { bubbles: true }));
-}
-
-function handleGlobalKeyDown(event: KeyboardEvent) {
-  if (!hotkey || hotkey.length === 0) return;
-  const isHotkey = hotkey.every((key) => {
-    if (key === event.key) return true;
-    if (key === 'altKey') return event.altKey;
-    if (key === 'ctrlKey') return event.ctrlKey;
-    if (key === 'shiftKey') return event.shiftKey;
-    if (key === 'metaKey') return event.metaKey;
-    return false;
-  });
-  if (isHotkey) currentElement.value?.focus();
-}
-
-onMounted(() => {
-  document.addEventListener('keydown', handleGlobalKeyDown);
-});
-
-onBeforeUnmount(() => {
-  document.removeEventListener('keydown', handleGlobalKeyDown);
-});
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    role="region"
-    :aria-label="viewportLabel"
-    tabindex="-1"
-    style="outline: none"
-    data-primitives-toast-viewport
-    @pointerenter="handlePointerEnter"
-    @pointerleave="handlePointerLeave"
-    @focusin="handleFocusIn"
-    @focusout="handleFocusOut"
-  >
-    <slot />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/toast/utils.ts b/vue/primitives/src/toast/utils.ts
deleted file mode 100644
index 54b8da5..0000000
--- a/vue/primitives/src/toast/utils.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export const VIEWPORT_PAUSE = 'toast.viewportPause';
-export const VIEWPORT_RESUME = 'toast.viewportResume';
diff --git a/vue/primitives/src/toggle-group/ToggleGroupRoot.vue b/vue/primitives/src/toggle-group/ToggleGroupRoot.vue
deleted file mode 100644
index 526711e..0000000
--- a/vue/primitives/src/toggle-group/ToggleGroupRoot.vue
+++ /dev/null
@@ -1,153 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { RovingDirection } from '../utils/roving-focus';
-import type { ToggleGroupType } from './context';
-
-/**
- * A set of two-state toggle buttons that behave as one control, with full
- * keyboard roving focus (arrow keys move, Home/End jump to ends). Set `type`
- * to `'single'` for mutually exclusive options (like a segmented control) or
- * `'multiple'` to let several be pressed at once (like a text-formatting bar).
- * This is the container and state owner: it tracks the pressed value(s)
- * (controlled via `v-model` or uncontrolled via `defaultValue`) and provides
- * context to each `ToggleGroupItem`. Reach for it to group related toggles
- * such as text alignment, view modes, or formatting options.
- */
-export interface ToggleGroupRootProps extends PrimitiveProps {
-  type?: ToggleGroupType;
-  defaultValue?: string | string[];
-  disabled?: boolean;
-  orientation?: 'horizontal' | 'vertical';
-  dir?: RovingDirection;
-  loop?: boolean;
-  rovingFocus?: boolean;
-}
-
-export interface ToggleGroupRootEmits {
-  valueChange: [value: string | string[]];
-}
-</script>
-
-<script setup lang="ts">
-import { computed, toRef } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { useCollectionProvider } from '../collection';
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { provideToggleGroupContext } from './context';
-
-const {
-  type = 'single',
-  disabled = false,
-  orientation = 'horizontal',
-  dir = 'ltr',
-  loop = true,
-  rovingFocus = true,
-  defaultValue,
-  as = 'div',
-} = defineProps<ToggleGroupRootProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const emit = defineEmits<ToggleGroupRootEmits>();
-
-const model = defineModel<string | string[] | undefined>({ default: undefined });
-
-function normalize(v: string | string[] | undefined): string[] {
-  if (v === undefined) return [];
-  if (Array.isArray(v)) return v.slice();
-  return [v];
-}
-
-// Seed the uncontrolled default once; defineModel owns state thereafter.
-if (model.value === undefined && defaultValue !== undefined)
-  model.value = defaultValue;
-
-// Normalized string[] view of the public model (string | string[] | undefined).
-const localValue = computed<string[]>(() => normalize(model.value));
-
-function emitValue(next: string[]): void {
-  if (type === 'single') {
-    const v = next[0];
-    model.value = v;
-    emit('valueChange', v ?? '');
-  }
-  else {
-    model.value = next;
-    emit('valueChange', next);
-  }
-}
-
-function toggle(v: string): void {
-  if (disabled) return;
-  if (type === 'single') {
-    if (localValue.value[0] === v) emitValue([]);
-    else emitValue([v]);
-  }
-  else if (localValue.value.includes(v)) {
-    emitValue(localValue.value.filter(x => x !== v));
-  }
-  else {
-    emitValue([...localValue.value, v]);
-  }
-}
-
-function isPressed(v: string): boolean {
-  return localValue.value.includes(v);
-}
-
-// DOM-order items via Collection primitive — survives v-for reorders.
-const { getItems, CollectionSlot } = useCollectionProvider();
-const items = computed(() => getItems(true).map(i => i.ref));
-
-function onItemKeyDown(event: KeyboardEvent, el: HTMLElement): void {
-  if (!rovingFocus) return;
-  const action = rovingKeyToAction(event, { orientation, dir, loop });
-  if (!action) return;
-  event.preventDefault();
-  const enabled = items.value.filter(x => !x.hasAttribute('data-disabled'));
-  if (enabled.length === 0) return;
-  const current = enabled.indexOf(el);
-  if (action.absolute === 'home') {
-    enabled[0]!.focus();
-    return;
-  }
-  if (action.absolute === 'end') {
-    enabled[enabled.length - 1]!.focus();
-    return;
-  }
-  const nextIdx = resolveNextIndex(current === -1 ? 0 : current, action.delta, enabled.length, loop);
-  enabled[nextIdx]!.focus();
-}
-
-provideToggleGroupContext({
-  type: toRef(() => type),
-  value: localValue,
-  toggle,
-  isPressed,
-  orientation: toRef(() => orientation),
-  direction: toRef(() => dir),
-  loop: toRef(() => loop),
-  disabled: toRef(() => disabled),
-  rovingFocus: toRef(() => rovingFocus),
-  items,
-  onItemKeyDown,
-});
-</script>
-
-<template>
-  <CollectionSlot>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      :role="type === 'single' ? 'radiogroup' : 'group'"
-      :aria-orientation="orientation"
-      :aria-disabled="disabled || undefined"
-      :dir="dir"
-      :data-orientation="orientation"
-      :data-disabled="disabled ? '' : undefined"
-    >
-      <slot :value="localValue" />
-    </Primitive>
-  </CollectionSlot>
-</template>
diff --git a/vue/primitives/src/toggle-group/context.ts b/vue/primitives/src/toggle-group/context.ts
deleted file mode 100644
index 4b78769..0000000
--- a/vue/primitives/src/toggle-group/context.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import type { ComputedRef, Ref } from 'vue';
-import type { RovingDirection, RovingOrientation } from '../utils/roving-focus';
-import { useContextFactory } from '@robonen/vue';
-
-export type ToggleGroupType = 'single' | 'multiple';
-
-export interface ToggleGroupContext {
-  type: Ref<ToggleGroupType>;
-  value: Ref<string[]>;
-  toggle: (v: string) => void;
-  isPressed: (v: string) => boolean;
-  orientation: Ref<RovingOrientation>;
-  direction: Ref<RovingDirection>;
-  loop: Ref<boolean>;
-  disabled: Ref<boolean>;
-  rovingFocus: Ref<boolean>;
-  /** DOM-ordered items, sourced from the internal Collection. */
-  items: ComputedRef<HTMLElement[]>;
-  onItemKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
-}
-
-const ctx = useContextFactory<ToggleGroupContext>('ToggleGroupContext');
-
-export const provideToggleGroupContext = ctx.provide;
-export const useToggleGroupContext = ctx.inject;
diff --git a/vue/primitives/src/toggle/Toggle.vue b/vue/primitives/src/toggle/Toggle.vue
deleted file mode 100644
index 974403d..0000000
--- a/vue/primitives/src/toggle/Toggle.vue
+++ /dev/null
@@ -1,77 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A two-state button that can be pressed on or off, like a bold or italic
- * control in a text editor toolbar. Renders a native `<button>` by default
- * (handling Space/Enter and the `disabled` attribute for you), exposes
- * `aria-pressed`, `data-state` (`on`/`off`), and `data-disabled` for styling,
- * and works uncontrolled (`defaultPressed`) or controlled via `v-model:pressed`.
- * When rendered as a non-button element it synthesizes keyboard activation and
- * the appropriate `tabindex`/`aria-disabled`. Use it for a single standalone
- * toggle; for a set of mutually related toggles use `ToggleGroup` instead.
- */
-export interface ToggleProps extends PrimitiveProps {
-
-  /** Uncontrolled initial pressed state. */
-  defaultPressed?: boolean;
-  /** Disables the toggle. */
-  disabled?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { Primitive } from '../primitive';
-import { ref } from 'vue';
-import { useForwardExpose } from '@robonen/vue';
-
-const { defaultPressed = false, disabled = false, as = 'button' } = defineProps<ToggleProps>();
-
-const { forwardRef } = useForwardExpose();
-
-const localPressed = ref<boolean>(defaultPressed);
-
-const pressed = defineModel<boolean>('pressed', {
-  default: undefined,
-  get: v => v ?? localPressed.value,
-  set: (v) => {
-    localPressed.value = v;
-    return v;
-  },
-});
-
-function toggle() {
-  if (disabled) return;
-  pressed.value = !pressed.value;
-}
-
-function onClick() {
-  toggle();
-}
-
-function onKeydown(event: KeyboardEvent) {
-  // <button> handles Space/Enter natively; synthesize only for non-button hosts.
-  if (as === 'button') return;
-  if (event.key !== ' ' && event.key !== 'Enter') return;
-  event.preventDefault();
-  toggle();
-}
-</script>
-
-<template>
-  <Primitive
-    :ref="forwardRef"
-    :as="as"
-    :type="as === 'button' ? 'button' : undefined"
-    :tabindex="as === 'button' ? undefined : (disabled ? -1 : 0)"
-    :aria-pressed="pressed"
-    :aria-disabled="as === 'button' ? undefined : (disabled ? true : undefined)"
-    :data-state="pressed ? 'on' : 'off'"
-    :data-disabled="disabled ? '' : undefined"
-    :disabled="as === 'button' ? disabled : undefined"
-    @click="onClick"
-    @keydown="onKeydown"
-  >
-    <slot :pressed="pressed" />
-  </Primitive>
-</template>
diff --git a/vue/primitives/src/toggle/__test__/Toggle.test.ts b/vue/primitives/src/toggle/__test__/Toggle.test.ts
deleted file mode 100644
index e061ade..0000000
--- a/vue/primitives/src/toggle/__test__/Toggle.test.ts
+++ /dev/null
@@ -1,101 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { ref } from 'vue';
-import { Toggle } from '../index';
-
-describe('Toggle', () => {
-  it('defaults to unpressed and toggles on click', async () => {
-    const wrapper = mount(Toggle);
-    expect(wrapper.attributes('aria-pressed')).toBe('false');
-    expect(wrapper.attributes('data-state')).toBe('off');
-    await wrapper.trigger('click');
-    expect(wrapper.attributes('aria-pressed')).toBe('true');
-    expect(wrapper.attributes('data-state')).toBe('on');
-  });
-
-  it('respects defaultPressed', () => {
-    const wrapper = mount(Toggle, { props: { defaultPressed: true } });
-    expect(wrapper.attributes('aria-pressed')).toBe('true');
-  });
-
-  it('syncs with v-model', async () => {
-    const pressed = ref(false);
-    const wrapper = mount(Toggle, {
-      props: { pressed: pressed.value, 'onUpdate:pressed': (v: boolean) => { pressed.value = v; } },
-    });
-    await wrapper.trigger('click');
-    expect(pressed.value).toBe(true);
-  });
-
-  it('does not toggle when disabled', async () => {
-    const wrapper = mount(Toggle, { props: { disabled: true } });
-    await wrapper.trigger('click');
-    expect(wrapper.attributes('aria-pressed')).toBe('false');
-    expect(wrapper.attributes('data-disabled')).toBe('');
-  });
-
-  it('sets type="button" on button element', () => {
-    const wrapper = mount(Toggle);
-    expect(wrapper.attributes('type')).toBe('button');
-  });
-
-  describe('keyboard activation', () => {
-    it('toggles on Space when as is not a button', async () => {
-      const wrapper = mount(Toggle, { props: { as: 'div' } });
-      await wrapper.trigger('keydown', { key: ' ' });
-      expect(wrapper.attributes('aria-pressed')).toBe('true');
-      await wrapper.trigger('keydown', { key: ' ' });
-      expect(wrapper.attributes('aria-pressed')).toBe('false');
-    });
-
-    it('toggles on Enter when as is not a button', async () => {
-      const wrapper = mount(Toggle, { props: { as: 'div' } });
-      await wrapper.trigger('keydown', { key: 'Enter' });
-      expect(wrapper.attributes('aria-pressed')).toBe('true');
-    });
-
-    it('ignores other keys', async () => {
-      const wrapper = mount(Toggle, { props: { as: 'div' } });
-      await wrapper.trigger('keydown', { key: 'a' });
-      await wrapper.trigger('keydown', { key: 'Tab' });
-      expect(wrapper.attributes('aria-pressed')).toBe('false');
-    });
-
-    it('does not synthesize keyboard toggle on native button', async () => {
-      const wrapper = mount(Toggle);
-      await wrapper.trigger('keydown', { key: ' ' });
-      expect(wrapper.attributes('aria-pressed')).toBe('false');
-    });
-
-    it('does not toggle on keyboard when disabled (as=div)', async () => {
-      const wrapper = mount(Toggle, { props: { as: 'div', disabled: true } });
-      await wrapper.trigger('keydown', { key: ' ' });
-      await wrapper.trigger('keydown', { key: 'Enter' });
-      expect(wrapper.attributes('aria-pressed')).toBe('false');
-    });
-  });
-
-  describe('non-button host (as="div")', () => {
-    it('sets aria-disabled when disabled', () => {
-      const wrapper = mount(Toggle, { props: { as: 'div', disabled: true } });
-      expect(wrapper.attributes('aria-disabled')).toBe('true');
-    });
-
-    it('does not set aria-disabled when enabled', () => {
-      const wrapper = mount(Toggle, { props: { as: 'div' } });
-      expect(wrapper.attributes('aria-disabled')).toBeUndefined();
-    });
-
-    it('has tabindex=0 when enabled, -1 when disabled', () => {
-      const enabled = mount(Toggle, { props: { as: 'div' } });
-      expect(enabled.attributes('tabindex')).toBe('0');
-      const disabled = mount(Toggle, { props: { as: 'div', disabled: true } });
-      expect(disabled.attributes('tabindex')).toBe('-1');
-    });
-
-    it('button host has no synthesized tabindex', () => {
-      const wrapper = mount(Toggle);
-      expect(wrapper.attributes('tabindex')).toBeUndefined();
-    });
-  });
-});
diff --git a/vue/primitives/src/toggle/index.ts b/vue/primitives/src/toggle/index.ts
deleted file mode 100644
index 112bc61..0000000
--- a/vue/primitives/src/toggle/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { default as Toggle } from './Toggle.vue';
-export type { ToggleProps } from './Toggle.vue';
diff --git a/vue/primitives/src/toolbar/ToolbarRoot.vue b/vue/primitives/src/toolbar/ToolbarRoot.vue
deleted file mode 100644
index 2a9ed2e..0000000
--- a/vue/primitives/src/toolbar/ToolbarRoot.vue
+++ /dev/null
@@ -1,94 +0,0 @@
-<script lang="ts">
-import type { PrimitiveProps } from '../primitive';
-import type { RovingDirection } from '../utils/roving-focus';
-
-/**
- * A container that groups a set of controls — buttons, toggles, separators —
- * into a single keyboard-navigable strip (`role="toolbar"`). Like an editor's
- * formatting bar, the whole toolbar is one tab stop: Tab moves into it, then
- * arrow keys roam between items (Home/End jump to the ends), with optional
- * wrap-around via `loop`. It owns the roving-focus state, exposes
- * `data-orientation` for styling, and provides context to every
- * `ToolbarButton` and `ToolbarSeparator`. Reach for it to assemble action
- * bars, formatting toolbars, or any cluster of related controls.
- */
-export interface ToolbarRootProps extends PrimitiveProps {
-  orientation?: 'horizontal' | 'vertical';
-  dir?: RovingDirection;
-  loop?: boolean;
-}
-</script>
-
-<script setup lang="ts">
-import { computed, ref, toRef } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { useCollectionProvider } from '../collection';
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { provideToolbarContext } from './context';
-
-const { orientation = 'horizontal', dir = 'ltr', loop = true, as = 'div' } = defineProps<ToolbarRootProps>();
-
-const { forwardRef } = useForwardExpose();
-
-// DOM-order items via Collection primitive. Survives `v-for` reorders and
-// teleport/portal children, unlike a mount-order array.
-// Enabled-only: a disabled button is unfocusable, so letting it into the
-// roving list would freeze navigation on it and drop the toolbar's tab stop.
-const { getItems, CollectionSlot } = useCollectionProvider();
-const items = computed(() => getItems().map(i => i.ref));
-
-const activeIndex = ref(0);
-
-// Read fresh rather than through `items`: `getItems` filters on live
-// `data-disabled`, which the computed cannot track across runtime toggles.
-function enabledItems(): HTMLElement[] {
-  return getItems().map(i => i.ref);
-}
-
-function focusIndex(i: number): void {
-  const el = enabledItems()[i];
-  if (!el) return;
-  el.focus();
-  // Commit only when focus actually landed, so the tab stop never moves
-  // onto an element that refused focus.
-  if (document.activeElement === el) activeIndex.value = i;
-}
-
-function onItemKeyDown(event: KeyboardEvent, el: HTMLElement): void {
-  const action = rovingKeyToAction(event, { orientation, dir, loop });
-  if (!action) return;
-  event.preventDefault();
-  const list = enabledItems();
-  const idx = list.indexOf(el);
-  if (action.absolute === 'home') return focusIndex(0);
-  if (action.absolute === 'end') return focusIndex(list.length - 1);
-  focusIndex(resolveNextIndex(idx, action.delta, list.length, loop));
-}
-
-provideToolbarContext({
-  // Identity passthroughs via `toRef` — reactive without `computed`'s effect/cache.
-  orientation: toRef(() => orientation),
-  direction: toRef(() => dir),
-  loop: toRef(() => loop),
-  items,
-  activeIndex,
-  focusIndex,
-  onItemKeyDown,
-});
-</script>
-
-<template>
-  <CollectionSlot>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      role="toolbar"
-      :aria-orientation="orientation"
-      :dir="dir"
-      :data-orientation="orientation"
-    >
-      <slot />
-    </Primitive>
-  </CollectionSlot>
-</template>
diff --git a/vue/primitives/src/toolbar/context.ts b/vue/primitives/src/toolbar/context.ts
deleted file mode 100644
index 56d4af8..0000000
--- a/vue/primitives/src/toolbar/context.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import type { ComputedRef, Ref } from 'vue';
-import type { RovingDirection, RovingOrientation } from '../utils/roving-focus';
-import { useContextFactory } from '@robonen/vue';
-
-export interface ToolbarContext {
-  orientation: Ref<RovingOrientation>;
-  direction: Ref<RovingDirection>;
-  loop: Ref<boolean>;
-  /** DOM-ordered items, sourced from the internal Collection. */
-  items: ComputedRef<HTMLElement[]>;
-  activeIndex: Ref<number>;
-  focusIndex: (i: number) => void;
-  onItemKeyDown: (event: KeyboardEvent, el: HTMLElement) => void;
-}
-
-const ctx = useContextFactory<ToolbarContext>('ToolbarContext');
-
-export const provideToolbarContext = ctx.provide;
-export const useToolbarContext = ctx.inject;
diff --git a/vue/primitives/src/toolbar/index.ts b/vue/primitives/src/toolbar/index.ts
deleted file mode 100644
index 2d42e25..0000000
--- a/vue/primitives/src/toolbar/index.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-export { default as ToolbarButton } from './ToolbarButton.vue';
-export { default as ToolbarRoot } from './ToolbarRoot.vue';
-export { default as ToolbarSeparator } from './ToolbarSeparator.vue';
-export type { ToolbarButtonProps } from './ToolbarButton.vue';
-export type { ToolbarRootProps } from './ToolbarRoot.vue';
-export type { ToolbarSeparatorProps } from './ToolbarSeparator.vue';
diff --git a/vue/primitives/src/tree/TreeItem.vue b/vue/primitives/src/tree/TreeItem.vue
deleted file mode 100644
index 928cb8a..0000000
--- a/vue/primitives/src/tree/TreeItem.vue
+++ /dev/null
@@ -1,76 +0,0 @@
-<script lang="ts" generic="T">
-import type { FlatItem } from './utils';
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A single node within a `TreeRoot`, rendered once per visible `flatItem`.
- * Handles click-to-select, click-to-toggle for parents, keyboard interaction,
- * and the ARIA treeitem attributes (level, selected, expanded). Exposes
- * `isExpanded` / `isSelected` / `isDisabled` to its slot for styling and
- * rendering the node label and expand affordance.
- */
-export interface TreeItemProps<U = unknown> extends PrimitiveProps {
-  /** Flattened item produced by `TreeRoot` (from its default slot). */
-  item: FlatItem<U>;
-  /** Disable this specific item. */
-  disabled?: boolean;
-}
-</script>
-
-<script setup lang="ts" generic="T">
-import { computed } from 'vue';
-import { useCollectionInjector } from '../collection';
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { useTreeContext } from './context';
-
-const { as = 'li', item, disabled = false } = defineProps<TreeItemProps<T>>();
-
-const ctx = useTreeContext();
-const { forwardRef, currentElement } = useForwardExpose();
-const { CollectionItem } = useCollectionInjector();
-
-const isDisabled = computed(() => ctx.disabled.value || disabled);
-const isExpanded = computed(() => item.hasChildren && ctx.isExpanded(item.key));
-const isSelected = computed(() => ctx.isSelected(item.key));
-
-function onClick(event: MouseEvent): void {
-  if (isDisabled.value) return;
-  event.stopPropagation();
-  ctx.select(item.value as T);
-  if (item.hasChildren) ctx.toggleExpanded(item.value as T);
-}
-
-function onKeyDown(event: KeyboardEvent): void {
-  if (isDisabled.value || !currentElement.value) return;
-  ctx.onItemKeyDown(event, currentElement.value, item);
-}
-</script>
-
-<template>
-  <CollectionItem>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      role="treeitem"
-      :tabindex="isDisabled ? -1 : 0"
-      :aria-level="item.level"
-      :aria-selected="isSelected"
-      :aria-expanded="item.hasChildren ? isExpanded : undefined"
-      :aria-disabled="isDisabled || undefined"
-      :data-state="item.hasChildren ? (isExpanded ? 'open' : 'closed') : undefined"
-      :data-selected="isSelected ? '' : undefined"
-      :data-disabled="isDisabled ? '' : undefined"
-      :data-level="item.level"
-      @click="onClick"
-      @keydown="onKeyDown"
-    >
-      <slot
-        :item="item"
-        :is-expanded="isExpanded"
-        :is-selected="isSelected"
-        :is-disabled="isDisabled"
-      />
-    </Primitive>
-  </CollectionItem>
-</template>
diff --git a/vue/primitives/src/tree/TreeRoot.vue b/vue/primitives/src/tree/TreeRoot.vue
deleted file mode 100644
index 73cb566..0000000
--- a/vue/primitives/src/tree/TreeRoot.vue
+++ /dev/null
@@ -1,344 +0,0 @@
-<script lang="ts" generic="T">
-import type { FlatItem } from './utils';
-import type { PrimitiveProps } from '../primitive';
-
-/**
- * A hierarchical list of expandable/collapsible nodes with full keyboard
- * support. Use it to present nested data — file explorers, navigation
- * sidebars, category pickers, or any place users drill into parent/child
- * relationships. Works with either nested or flat source data via the
- * `getKey` / `getChildren` accessors.
- *
- * The root owns selection state (single or multiple, controlled via
- * `v-model` or uncontrolled via `defaultValue`), expanded state
- * (`v-model:expanded`), roving focus and arrow/Home/End navigation, and
- * exposes the computed visible `flatItems` through its default slot for
- * each `TreeItem` to render.
- */
-export interface TreeRootProps<U = unknown> extends PrimitiveProps {
-  /** Flat or nested item list — children are resolved via `getChildren`. */
-  items: readonly U[];
-  /** Extract a stable unique string key from an item. */
-  getKey: (item: U) => string;
-  /** Return the children of an item, or `undefined` if it is a leaf. */
-  getChildren?: (item: U) => readonly U[] | undefined | null;
-  /** Uncontrolled initial selected key(s). */
-  defaultValue?: string | string[];
-  /** Uncontrolled initial expanded keys. */
-  defaultExpanded?: string[];
-  /** Allow selecting multiple items. @default false */
-  multiple?: boolean;
-  /** Disable the entire tree. */
-  disabled?: boolean;
-  /** Writing direction. @default 'ltr' */
-  dir?: 'ltr' | 'rtl';
-  /** When `true`, selecting a parent also selects all of its descendants (requires `multiple`). */
-  propagateSelect?: boolean;
-}
-</script>
-
-<script setup lang="ts" generic="T">
-import { computed, ref, toRef, watch } from 'vue';
-import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
-import { flattenVisible } from './utils';
-import { useCollectionProvider } from '../collection';
-import { useConfig } from '../config-provider';
-import { useForwardExpose } from '@robonen/vue';
-import { Primitive } from '../primitive';
-import { provideTreeContext } from './context';
-
-// Hoisted roving-focus options — reused on every keydown to avoid per-event
-// object allocation (keeps the IC at `rovingKeyToAction` monomorphic).
-const ROVING_OPTS_LTR = { orientation: 'vertical', dir: 'ltr', loop: false } as const;
-const ROVING_OPTS_RTL = { orientation: 'vertical', dir: 'rtl', loop: false } as const;
-
-const {
-  as = 'ul',
-  items,
-  getKey,
-  getChildren = ((item: any) => item?.children) as (item: T) => readonly T[] | undefined | null,
-  defaultValue,
-  defaultExpanded,
-  multiple = false,
-  disabled = false,
-  dir,
-  propagateSelect = false,
-} = defineProps<TreeRootProps<T>>();
-
-const selectedModel = defineModel<string | string[] | undefined>();
-const expandedModel = defineModel<string[]>('expanded');
-
-const { forwardRef } = useForwardExpose();
-const config = useConfig();
-
-// Writing direction — local prop wins, else inherit from <ConfigProvider>.
-const direction = computed(() => dir ?? config.dir.value);
-
-function normalize(v: string | string[] | undefined): string[] {
-  if (v === undefined) return [];
-  return Array.isArray(v) ? v : [v];
-}
-
-// --- Selection state ------------------------------------------------------
-
-const localSelected = ref<string[]>(
-  selectedModel.value !== undefined ? normalize(selectedModel.value) : normalize(defaultValue),
-);
-
-watch(selectedModel, (v) => {
-  if (v === undefined) return;
-  const arr = normalize(v);
-  const cur = localSelected.value;
-  if (arr.length === cur.length && arr.every((x, i) => x === cur[i])) return;
-  localSelected.value = arr;
-});
-
-function commitSelected(next: string[]): void {
-  localSelected.value = next;
-  selectedModel.value = multiple ? next : next[0];
-}
-
-// O(1) membership lookup — replaces linear `.includes()` that was called once
-// per TreeItem's `isSelected` computed, causing O(n²) work on selection change.
-const selectedSet = computed(() => new Set(localSelected.value));
-
-function isSelected(key: string): boolean {
-  return selectedSet.value.has(key);
-}
-
-function select(value: T): void {
-  if (disabled) return;
-  const key = getKey(value);
-  const current = localSelected.value;
-
-  if (multiple) {
-    const alreadySelected = selectedSet.value.has(key);
-
-    if (propagateSelect) {
-      // Collect `key` + all descendant keys iteratively (avoids flattenAll's
-      // intermediate {key,value}[] allocation — we only need the keys here).
-      const cascadeKeys = new Set<string>();
-      cascadeKeys.add(key);
-      const stack: Array<readonly T[]> = [];
-      const firstChildren = getChildren(value);
-      if (firstChildren && firstChildren.length > 0) stack.push(firstChildren);
-      while (stack.length > 0) {
-        const nodes = stack.pop()!;
-        for (let i = 0; i < nodes.length; i++) {
-          const node = nodes[i]!;
-          cascadeKeys.add(getKey(node));
-          const ch = getChildren(node);
-          if (ch && ch.length > 0) stack.push(ch);
-        }
-      }
-
-      if (alreadySelected) {
-        // O(n) filter with Set lookup (was O(n*m) via Array.includes).
-        const next: string[] = [];
-        for (let i = 0; i < current.length; i++) {
-          const k = current[i]!;
-          if (!cascadeKeys.has(k)) next.push(k);
-        }
-        commitSelected(next);
-      }
-      else {
-        const merged = new Set(current);
-        cascadeKeys.forEach(k => merged.add(k));
-        commitSelected([...merged]);
-      }
-      return;
-    }
-
-    if (alreadySelected) {
-      const next: string[] = [];
-      for (let i = 0; i < current.length; i++) {
-        const k = current[i]!;
-        if (k !== key) next.push(k);
-      }
-      commitSelected(next);
-    }
-    else {
-      commitSelected([...current, key]);
-    }
-    return;
-  }
-
-  // single select — toggle off if already selected
-  if (current[0] === key) commitSelected([]);
-  else commitSelected([key]);
-}
-
-// --- Expanded state -------------------------------------------------------
-
-const localExpanded = ref<string[]>(
-  expandedModel.value !== undefined ? [...expandedModel.value] : [...(defaultExpanded ?? [])],
-);
-
-watch(expandedModel, (v) => {
-  if (v === undefined) return;
-  const cur = localExpanded.value;
-  if (v.length === cur.length && v.every((x, i) => x === cur[i])) return;
-  localExpanded.value = [...v];
-});
-
-const expandedSet = computed(() => new Set(localExpanded.value));
-
-function isExpanded(key: string): boolean {
-  return expandedSet.value.has(key);
-}
-
-function commitExpanded(next: string[]): void {
-  localExpanded.value = next;
-  expandedModel.value = next;
-}
-
-function toggleExpanded(value: T): void {
-  const children = getChildren(value);
-  if (!children || children.length === 0) return;
-  const key = getKey(value);
-  const current = localExpanded.value;
-  if (expandedSet.value.has(key)) {
-    const next: string[] = [];
-    for (let i = 0; i < current.length; i++) {
-      const k = current[i]!;
-      if (k !== key) next.push(k);
-    }
-    commitExpanded(next);
-  }
-  else {
-    commitExpanded([...current, key]);
-  }
-}
-
-// --- Flattened visible items ---------------------------------------------
-
-const flatItems = computed<Array<FlatItem<T>>>(() =>
-  flattenVisible(items, getKey, getChildren, expandedSet.value),
-);
-
-// --- Keyboard navigation --------------------------------------------------
-
-const { getItems, CollectionSlot } = useCollectionProvider();
-const treeItemElements = computed(() => getItems(true).map(i => i.ref));
-
-function collectEnabled(): HTMLElement[] {
-  const all = treeItemElements.value;
-  const out: HTMLElement[] = [];
-  for (let i = 0; i < all.length; i++) {
-    const el = all[i]!;
-    if (!el.hasAttribute('data-disabled')) out.push(el);
-  }
-  return out;
-}
-
-function onItemKeyDown(event: KeyboardEvent, el: HTMLElement, item: FlatItem<T>): void {
-  // Enter / Space → select (tree-specific, not covered by roving-focus helper)
-  if (event.key === 'Enter' || event.key === ' ') {
-    event.preventDefault();
-    select(item.value);
-    return;
-  }
-
-  const enabled = collectEnabled();
-  if (enabled.length === 0) return;
-  const idx = enabled.indexOf(el);
-
-  // Up / Down / Home / End → delegate to shared roving-focus helper.
-  const action = rovingKeyToAction(
-    event,
-    direction.value === 'rtl' ? ROVING_OPTS_RTL : ROVING_OPTS_LTR,
-  );
-  if (action) {
-    event.preventDefault();
-    if (action.absolute === 'home') {
-      enabled[0]!.focus();
-      return;
-    }
-    if (action.absolute === 'end') {
-      enabled[enabled.length - 1]!.focus();
-      return;
-    }
-    const nextIdx = resolveNextIndex(idx, action.delta, enabled.length, false);
-    enabled[nextIdx]!.focus();
-    return;
-  }
-
-  // Left / Right have tree-specific semantics beyond roving focus:
-  //   forward  — expand collapsed parent, else move to first child
-  //   back     — collapse expanded parent, else move to parent item
-  const ltr = direction.value !== 'rtl';
-  const forwardKey = ltr ? 'ArrowRight' : 'ArrowLeft';
-  const backKey = ltr ? 'ArrowLeft' : 'ArrowRight';
-
-  if (event.key === forwardKey) {
-    event.preventDefault();
-    if (!item.hasChildren) return;
-    if (!isExpanded(item.key)) {
-      toggleExpanded(item.value);
-      return;
-    }
-    const next = enabled[idx + 1];
-    if (next && Number(next.getAttribute('aria-level')) === item.level + 1) next.focus();
-    return;
-  }
-
-  if (event.key === backKey) {
-    event.preventDefault();
-    if (item.hasChildren && isExpanded(item.key)) {
-      toggleExpanded(item.value);
-      return;
-    }
-    const parentLevel = item.level - 1;
-    for (let i = idx - 1; i >= 0; i--) {
-      const candidate = enabled[i]!;
-      if (Number(candidate.getAttribute('aria-level')) === parentLevel) {
-        candidate.focus();
-        return;
-      }
-    }
-  }
-}
-
-provideTreeContext({
-  flatItems,
-  expandedKeys: localExpanded,
-  selectedKeys: localSelected,
-  multiple: toRef(() => multiple),
-  disabled: toRef(() => disabled),
-  direction,
-  propagateSelect: toRef(() => propagateSelect),
-  isExpanded,
-  isSelected,
-  toggleExpanded,
-  select,
-  treeItemElements,
-  onItemKeyDown,
-});
-
-defineSlots<{
-  default?: (props: {
-    flatItems: Array<FlatItem<T>>;
-    selectedKeys: string[];
-    expandedKeys: string[];
-  }) => unknown;
-}>();
-</script>
-
-<template>
-  <CollectionSlot>
-    <Primitive
-      :ref="forwardRef"
-      :as="as"
-      role="tree"
-      :aria-multiselectable="multiple ? true : undefined"
-      :aria-disabled="disabled || undefined"
-      :dir="direction"
-    >
-      <slot
-        :flat-items="flatItems"
-        :selected-keys="localSelected"
-        :expanded-keys="localExpanded"
-      />
-    </Primitive>
-  </CollectionSlot>
-</template>
diff --git a/vue/primitives/src/tree/__test__/Tree.test.ts b/vue/primitives/src/tree/__test__/Tree.test.ts
deleted file mode 100644
index c647bfa..0000000
--- a/vue/primitives/src/tree/__test__/Tree.test.ts
+++ /dev/null
@@ -1,262 +0,0 @@
-import { TreeItem, TreeRoot } from '../index';
-import { defineComponent, h, nextTick } from 'vue';
-import { describe, expect, it } from 'vitest';
-import { mount } from '@vue/test-utils';
-
-interface Node {
-  id: string;
-  label: string;
-  children?: Node[];
-}
-
-const TREE: Node[] = [
-  {
-    id: 'a',
-    label: 'A',
-    children: [
-      { id: 'a-1', label: 'A.1' },
-      {
-        id: 'a-2',
-        label: 'A.2',
-        children: [
-          { id: 'a-2-1', label: 'A.2.1' },
-          { id: 'a-2-2', label: 'A.2.2' },
-        ],
-      },
-    ],
-  },
-  { id: 'b', label: 'B' },
-  {
-    id: 'c',
-    label: 'C',
-    children: [{ id: 'c-1', label: 'C.1' }],
-  },
-];
-
-function createTree(rootProps: Record<string, unknown> = {}, items: Node[] = TREE) {
-  return mount(
-    defineComponent({
-      setup() {
-        return () => h(
-          TreeRoot,
-          {
-            items,
-            getKey: (n: unknown) => (n as Node).id,
-            getChildren: (n: unknown) => (n as Node).children,
-            ...rootProps,
-          },
-          {
-            default: ({ flatItems }: { flatItems: Array<{ key: string; value: Node; level: number; hasChildren: boolean }> }) =>
-              flatItems.map(item =>
-                h(TreeItem, { key: item.key, item }, { default: () => item.value.label }),
-              ),
-          },
-        );
-      },
-    }),
-    { attachTo: document.body },
-  );
-}
-
-function press(el: Element, key: string) {
-  el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
-}
-
-async function flush() {
-  await nextTick();
-  await nextTick();
-}
-
-describe('Tree', () => {
-  it('renders only top-level items when nothing is expanded', () => {
-    const w = createTree();
-    const items = w.findAll('[role="treeitem"]');
-    expect(items).toHaveLength(3);
-    expect(items.map(i => i.text())).toEqual(['A', 'B', 'C']);
-    w.unmount();
-  });
-
-  it('sets role="tree" on root', () => {
-    const w = createTree();
-    expect(w.find('[role="tree"]').exists()).toBe(true);
-    w.unmount();
-  });
-
-  it('wires aria-level and aria-expanded', () => {
-    const w = createTree({ defaultExpanded: ['a'] });
-    const items = w.findAll('[role="treeitem"]');
-    // A (has children, expanded), A.1 (leaf), A.2 (has children, closed), B, C
-    expect(items[0]!.attributes('aria-level')).toBe('1');
-    expect(items[0]!.attributes('aria-expanded')).toBe('true');
-    expect(items[0]!.attributes('data-state')).toBe('open');
-
-    expect(items[1]!.attributes('aria-level')).toBe('2');
-    expect(items[1]!.attributes('aria-expanded')).toBeUndefined();
-    expect(items[1]!.attributes('data-state')).toBeUndefined();
-
-    expect(items[2]!.attributes('aria-level')).toBe('2');
-    expect(items[2]!.attributes('aria-expanded')).toBe('false');
-    expect(items[2]!.attributes('data-state')).toBe('closed');
-    w.unmount();
-  });
-
-  it('click toggles expansion of a parent node', async () => {
-    const w = createTree();
-    const a = w.findAll('[role="treeitem"]')[0]!;
-    await a.trigger('click');
-    await flush();
-    // now A is expanded, A.1 + A.2 visible
-    const items = w.findAll('[role="treeitem"]');
-    expect(items).toHaveLength(5);
-    expect(items.map(i => i.text())).toEqual(['A', 'A.1', 'A.2', 'B', 'C']);
-    w.unmount();
-  });
-
-  it('click selects a node (single-select)', async () => {
-    const w = createTree();
-    const b = w.findAll('[role="treeitem"]')[1]!;
-    await b.trigger('click');
-    await flush();
-    expect(b.attributes('aria-selected')).toBe('true');
-    expect(b.attributes('data-selected')).toBe('');
-    w.unmount();
-  });
-
-  it('single-select: selecting another item replaces the previous selection', async () => {
-    const w = createTree({ defaultValue: 'b' });
-    const items = w.findAll('[role="treeitem"]');
-    expect(items[1]!.attributes('aria-selected')).toBe('true');
-
-    await items[0]!.trigger('click');
-    await flush();
-
-    const after = w.findAll('[role="treeitem"]');
-    expect(after[0]!.attributes('aria-selected')).toBe('true');
-    expect(after.find(i => i.text() === 'B')!.attributes('aria-selected')).toBe('false');
-    w.unmount();
-  });
-
-  it('multiple-select: selections accumulate', async () => {
-    const w = createTree({ multiple: true });
-    const items = w.findAll('[role="treeitem"]');
-    await items[0]!.trigger('click'); // A (also expands)
-    await flush();
-    await w.findAll('[role="treeitem"]').find(i => i.text() === 'B')!.trigger('click');
-    await flush();
-    const all = w.findAll('[role="treeitem"]');
-    const selected = all.filter(i => i.attributes('aria-selected') === 'true').map(i => i.text());
-    expect(selected).toContain('A');
-    expect(selected).toContain('B');
-    w.unmount();
-  });
-
-  it('ArrowDown / ArrowUp move focus through visible items', async () => {
-    const w = createTree({ defaultExpanded: ['a'] });
-    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
-    items[0]!.focus();
-    expect(document.activeElement).toBe(items[0]);
-    press(items[0]!, 'ArrowDown');
-    expect(document.activeElement).toBe(items[1]); // A.1
-    press(items[1]!, 'ArrowDown');
-    expect(document.activeElement).toBe(items[2]); // A.2
-    press(items[2]!, 'ArrowUp');
-    expect(document.activeElement).toBe(items[1]);
-    w.unmount();
-  });
-
-  it('Home / End jump to first / last visible item', () => {
-    const w = createTree({ defaultExpanded: ['a'] });
-    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
-    items[2]!.focus();
-    press(items[2]!, 'End');
-    expect(document.activeElement).toBe(items[items.length - 1]);
-    press(items[items.length - 1]!, 'Home');
-    expect(document.activeElement).toBe(items[0]);
-    w.unmount();
-  });
-
-  it('ArrowRight expands a collapsed parent; ArrowRight again moves to first child', async () => {
-    const w = createTree();
-    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
-    items[0]!.focus();
-    press(items[0]!, 'ArrowRight');
-    await flush();
-    const next = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
-    expect(next[0]!.getAttribute('aria-expanded')).toBe('true');
-    press(next[0]!, 'ArrowRight');
-    expect(document.activeElement).toBe(next[1]); // A.1
-    w.unmount();
-  });
-
-  it('ArrowLeft collapses an expanded parent; ArrowLeft on a leaf jumps to its parent', async () => {
-    const w = createTree({ defaultExpanded: ['a'] });
-    const items = w.findAll('[role="treeitem"]').map(i => i.element as HTMLElement);
-    const a1 = items[1]!; // leaf
-    a1.focus();
-    press(a1, 'ArrowLeft');
-    expect(document.activeElement).toBe(items[0]); // back to A
-
-    // Now collapse A with another ArrowLeft
-    press(items[0]!, 'ArrowLeft');
-    await flush();
-    const updated = w.findAll('[role="treeitem"]');
-    expect(updated).toHaveLength(3);
-    w.unmount();
-  });
-
-  it('Enter / Space select the focused item', async () => {
-    const w = createTree();
-    const first = w.find('[role="treeitem"]').element as HTMLElement;
-    first.focus();
-    press(first, 'Enter');
-    await flush();
-    expect(first.getAttribute('aria-selected')).toBe('true');
-    w.unmount();
-  });
-
-  it('emits update:modelValue and update:expanded', async () => {
-    const onModel: string[][] = [];
-    const onExpanded: string[][] = [];
-    const w = createTree({
-      'onUpdate:modelValue': (v: string | string[] | undefined) => {
-        onModel.push(Array.isArray(v) ? v : v === undefined ? [] : [v]);
-      },
-      'onUpdate:expanded': (v: string[]) => {
-        onExpanded.push(v);
-      },
-    });
-    const first = w.find('[role="treeitem"]');
-    await first.trigger('click');
-    await flush();
-    expect(onModel[0]).toEqual(['a']);
-    expect(onExpanded[0]).toEqual(['a']);
-    w.unmount();
-  });
-
-  it('disabled tree ignores clicks and keyboard selection', async () => {
-    const onModel: unknown[] = [];
-    const w = createTree({ disabled: true, 'onUpdate:modelValue': (v: unknown) => onModel.push(v) });
-    const first = w.find('[role="treeitem"]');
-    await first.trigger('click');
-    await flush();
-    expect(first.attributes('aria-selected')).toBe('false');
-    expect(onModel).toHaveLength(0);
-    w.unmount();
-  });
-
-  it('propagateSelect cascades selection to all descendants', async () => {
-    const captured: string[][] = [];
-    const w = createTree({
-      multiple: true,
-      propagateSelect: true,
-      defaultExpanded: ['a', 'a-2'],
-      'onUpdate:modelValue': (v: string[]) => captured.push(v),
-    });
-    const a = w.findAll('[role="treeitem"]')[0]!; // A
-    await a.trigger('click');
-    await flush();
-    const emitted = captured.at(-1)!;
-    expect(emitted).toEqual(expect.arrayContaining(['a', 'a-1', 'a-2', 'a-2-1', 'a-2-2']));
-    w.unmount();
-  });
-});
diff --git a/vue/primitives/src/tree/index.ts b/vue/primitives/src/tree/index.ts
deleted file mode 100644
index 50009fa..0000000
--- a/vue/primitives/src/tree/index.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-export { default as TreeRoot } from './TreeRoot.vue';
-export { default as TreeItem } from './TreeItem.vue';
-
-export { useTreeContext, provideTreeContext } from './context';
-
-export type { TreeRootProps } from './TreeRoot.vue';
-export type { TreeItemProps } from './TreeItem.vue';
-export type { TreeContext } from './context';
-export type { FlatItem } from './utils';
-export { flattenAll, flattenVisible } from './utils';
diff --git a/vue/primitives/src/tree/utils.ts b/vue/primitives/src/tree/utils.ts
deleted file mode 100644
index ab6190c..0000000
--- a/vue/primitives/src/tree/utils.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-/**
- * Shared Tree helpers. Pure, no Vue imports.
- */
-
-export interface FlatItem<T = unknown> {
-  /** Unique string key produced by `getKey(value)`. */
-  key: string;
-  /** Original item value. */
-  value: T;
-  /** 1-based depth — top-level is 1. */
-  level: number;
-  /** Whether the item has a non-empty children array. */
-  hasChildren: boolean;
-  /** Parent key, or `undefined` for root-level items. */
-  parentKey?: string;
-}
-
-/**
- * Depth-first flattening of a tree into a visible list, honoring `expandedKeys`.
- * Collapsed subtrees are skipped entirely. Iterative implementation to avoid
- * deep recursion on large trees.
- */
-export function flattenVisible<T>(
-  items: readonly T[],
-  getKey: (item: T) => string,
-  getChildren: (item: T) => readonly T[] | undefined | null,
-  expandedKeys: ReadonlySet<string>,
-): Array<FlatItem<T>> {
-  const out: Array<FlatItem<T>> = [];
-  // Stack holds frames to expand. Seed in reverse so first child pops first.
-  interface Frame { nodes: readonly T[]; index: number; level: number; parentKey?: string }
-  const stack: Frame[] = [{ nodes: items, index: 0, level: 1, parentKey: undefined }];
-
-  while (stack.length > 0) {
-    const frame = stack[stack.length - 1]!;
-    if (frame.index >= frame.nodes.length) {
-      stack.pop();
-      continue;
-    }
-    const node = frame.nodes[frame.index]!;
-    frame.index += 1;
-
-    const key = getKey(node);
-    const children = getChildren(node);
-    const hasChildren = Array.isArray(children) && children.length > 0;
-    out.push({
-      key,
-      value: node,
-      level: frame.level,
-      hasChildren,
-      parentKey: frame.parentKey,
-    });
-
-    if (hasChildren && expandedKeys.has(key)) {
-      stack.push({
-        nodes: children as readonly T[],
-        index: 0,
-        level: frame.level + 1,
-        parentKey: key,
-      });
-    }
-  }
-
-  return out;
-}
-
-/**
- * Flattens all descendants (regardless of expansion) — used for cascade
- * select/deselect operations.
- */
-export function flattenAll<T>(
-  items: readonly T[],
-  getKey: (item: T) => string,
-  getChildren: (item: T) => readonly T[] | undefined | null,
-): Array<{ key: string; value: T }> {
-  const out: Array<{ key: string; value: T }> = [];
-  const stack: Array<readonly T[]> = [items];
-  while (stack.length > 0) {
-    const nodes = stack.pop()!;
-    for (const node of nodes) {
-      out.push({ key: getKey(node), value: node });
-      const children = getChildren(node);
-      if (Array.isArray(children) && children.length > 0) stack.push(children);
-    }
-  }
-  return out;
-}
diff --git a/vue/primitives/src/collection/__test__/useCollection.test.ts b/vue/primitives/src/utilities/collection/__test__/useCollection.test.ts
similarity index 74%
rename from vue/primitives/src/collection/__test__/useCollection.test.ts
rename to vue/primitives/src/utilities/collection/__test__/useCollection.test.ts
index 687b868..061fb16 100644
--- a/vue/primitives/src/collection/__test__/useCollection.test.ts
+++ b/vue/primitives/src/utilities/collection/__test__/useCollection.test.ts
@@ -2,7 +2,7 @@ import type { VueWrapper } from '@vue/test-utils';
 import type { CollectionContext } from '../useCollection';
 import { mount } from '@vue/test-utils';
 import { afterEach, describe, expect, it } from 'vitest';
-import { defineComponent, h, nextTick } from 'vue';
+import { createCommentVNode, defineComponent, h, nextTick } from 'vue';
 
 import { useCollectionInjector, useCollectionProvider } from '../useCollection';
 
@@ -56,6 +56,38 @@ describe('useCollection — default key', () => {
   });
 });
 
+describe('useCollection — element resolution', () => {
+  it('registers the next element sibling when an item child exposes a comment node as $el', async () => {
+    // A multi-root child whose first root is a comment, so `$el` is a `#comment`
+    // node followed by the real element — mirrors conditional/async component roots.
+    const CommentRooted = defineComponent({
+      inheritAttrs: false,
+      setup() {
+        return () => [createCommentVNode('placeholder'), h('button', { id: 'real' })];
+      },
+    });
+    const Item = defineComponent({
+      setup() {
+        const { CollectionItem } = useCollectionInjector();
+        return () => h(CollectionItem, null, { default: () => h(CommentRooted) });
+      },
+    });
+
+    let ctx!: CollectionContext;
+    const Provider = makeProvider(c => (ctx = c));
+    const Harness = defineComponent({
+      setup() {
+        return () => h(Provider, null, { default: () => h(Item) });
+      },
+    });
+    track(mount(Harness, { attachTo: document.body }));
+    await nextTick();
+
+    expect(ctx.getItems().map(i => i.ref.id)).toEqual(['real']);
+    expect(ctx.getItems()[0]!.ref).toBeInstanceOf(HTMLElement);
+  });
+});
+
 describe('useCollection — namespaced keys', () => {
   it('a nested default-key provider does not shadow an outer namespaced provider', async () => {
     let outer!: CollectionContext;
diff --git a/vue/primitives/src/collection/index.ts b/vue/primitives/src/utilities/collection/index.ts
similarity index 100%
rename from vue/primitives/src/collection/index.ts
rename to vue/primitives/src/utilities/collection/index.ts
diff --git a/vue/primitives/src/collection/useCollection.ts b/vue/primitives/src/utilities/collection/useCollection.ts
similarity index 74%
rename from vue/primitives/src/collection/useCollection.ts
rename to vue/primitives/src/utilities/collection/useCollection.ts
index 1d2e9ee..6bb1605 100644
--- a/vue/primitives/src/collection/useCollection.ts
+++ b/vue/primitives/src/utilities/collection/useCollection.ts
@@ -9,7 +9,7 @@ import {
   watch,
 } from 'vue';
 import { unrefElement, useContextFactory } from '@robonen/vue';
-import { Slot } from '../primitive';
+import { Slot } from '../../internal/primitive';
 
 /**
  * Data attribute used to locate items inside a collection via `querySelectorAll`.
@@ -17,6 +17,31 @@ import { Slot } from '../primitive';
  */
 const ITEM_DATA_ATTR = 'data-collection-item';
 
+/**
+ * Resolves the DOM element behind a `:ref` callback value.
+ *
+ * Multi-root / conditional components expose a `#comment` (or `#text`) node as
+ * their `$el`; in that case we fall back to the next real element sibling, so
+ * such children still register instead of being silently skipped. Mirrors the
+ * resolver used by the toolkit's forward-expose. The common case (a plain
+ * element) takes a single `instanceof` check, so there is no hot-path overhead.
+ */
+function resolveItemElement(el: unknown): HTMLElement | undefined {
+  const node = unrefElement(el as Parameters<typeof unrefElement>[0]) as
+    | Node
+    | null
+    | undefined;
+
+  if (node instanceof HTMLElement) return node;
+
+  if (node instanceof CharacterData) {
+    const sibling = node.nextElementSibling;
+    return sibling instanceof HTMLElement ? sibling : undefined;
+  }
+
+  return undefined;
+}
+
 export interface CollectionItemData<Value = unknown> {
   /** DOM element that represents the item. */
   ref: HTMLElement;
@@ -61,13 +86,29 @@ function createCollectionState<Value = unknown>(): CollectionContext<Value> {
     const collectionNode = collectionRef.value;
     if (!collectionNode) return [];
 
-    const orderedNodes = Array.from(
-      collectionNode.querySelectorAll(`[${ITEM_DATA_ATTR}]`),
-    );
     const items = Array.from(itemMap.value.values());
-    items.sort(
-      (a, b) => orderedNodes.indexOf(a.ref) - orderedNodes.indexOf(b.ref),
-    );
+
+    // Sort by DOM order. Build a node→index lookup ONCE (O(n)) instead of calling
+    // `orderedNodes.indexOf()` inside the comparator — that was O(n) per call,
+    // i.e. O(n² log n) overall, and `getItems()` runs per keystroke / per
+    // pointer-move across the roving-focus / menu / listbox / tree family.
+    // 0 or 1 items need no DOM query and no sort.
+    if (items.length > 1) {
+      const orderedNodes = collectionNode.querySelectorAll(
+        `[${ITEM_DATA_ATTR}]`,
+      );
+      const orderByNode = new Map<Element, number>();
+      for (let i = 0; i < orderedNodes.length; i++) {
+        orderByNode.set(orderedNodes[i]!, i);
+      }
+      // Preserve prior semantics: nodes not present in the query (e.g. just
+      // registered, not yet in the DOM) sort to the front via index -1.
+      items.sort((a, b) => {
+        const ai = orderByNode.get(a.ref);
+        const bi = orderByNode.get(b.ref);
+        return (ai === undefined ? -1 : ai) - (bi === undefined ? -1 : bi);
+      });
+    }
 
     return includeDisabled
       ? items
@@ -84,8 +125,8 @@ function createCollectionState<Value = unknown>(): CollectionContext<Value> {
           {
             ...attrs,
             ref: (el: unknown) => {
-              const element = unrefElement(el as Parameters<typeof unrefElement>[0]);
-              if (element instanceof HTMLElement) {
+              const element = resolveItemElement(el);
+              if (element) {
                 collectionRef.value = element;
               }
             },
@@ -132,8 +173,8 @@ function createCollectionState<Value = unknown>(): CollectionContext<Value> {
             ...attrs,
             [ITEM_DATA_ATTR]: '',
             ref: (el: unknown) => {
-              const element = unrefElement(el as Parameters<typeof unrefElement>[0]);
-              if (element instanceof HTMLElement) {
+              const element = resolveItemElement(el);
+              if (element) {
                 currentElement.value = element;
               }
             },
diff --git a/vue/primitives/src/utilities/config-provider/__test__/config-provider.test.ts b/vue/primitives/src/utilities/config-provider/__test__/config-provider.test.ts
new file mode 100644
index 0000000..bbc8ecb
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/__test__/config-provider.test.ts
@@ -0,0 +1,625 @@
+import { describe, expect, it } from 'vitest';
+import { computed, defineComponent, h, nextTick, ref, shallowRef } from 'vue';
+import { mount } from '@vue/test-utils';
+import {
+  nativeDateAdapter,
+  provideAppConfig,
+  provideConfig,
+  useConfig,
+  useDateAdapter,
+  useDirection,
+  useId,
+  useLocale,
+  useNonce,
+} from '..';
+
+// --- useConfig ---
+
+describe('useConfig', () => {
+  it('returns default config when no provider exists', () => {
+    const wrapper = mount(
+      defineComponent({
+        setup() {
+          const config = useConfig();
+          return { config };
+        },
+        render() {
+          return h('div', {
+            'data-dir': this.config.dir.value,
+            'data-target': this.config.teleportTarget.value,
+          });
+        },
+      }),
+    );
+
+    expect(wrapper.find('div').attributes('data-dir')).toBe('ltr');
+    expect(wrapper.find('div').attributes('data-target')).toBe('body');
+
+    wrapper.unmount();
+  });
+
+  it('returns custom config from provideConfig', () => {
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        return { config };
+      },
+      render() {
+        return h('div', {
+          'data-dir': this.config.dir.value,
+          'data-target': this.config.teleportTarget.value,
+        });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({
+          dir: 'rtl',
+          teleportTarget: '#app',
+        });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+
+    expect(wrapper.find('div').attributes('data-dir')).toBe('rtl');
+    expect(wrapper.find('div').attributes('data-target')).toBe('#app');
+
+    wrapper.unmount();
+  });
+
+  it('exposes mutable refs for runtime updates', async () => {
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        return { config };
+      },
+      render() {
+        return h('div', { 'data-dir': this.config.dir.value });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        const config = provideConfig({ dir: 'ltr' });
+        return { config };
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-dir')).toBe('ltr');
+
+    wrapper.vm.config.dir.value = 'rtl';
+    await wrapper.vm.$nextTick();
+
+    expect(wrapper.find('div').attributes('data-dir')).toBe('rtl');
+
+    wrapper.unmount();
+  });
+});
+
+// --- provideAppConfig ---
+
+describe('provideAppConfig', () => {
+  it('provides config at app level', () => {
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        return { config };
+      },
+      render() {
+        return h('div', {
+          'data-dir': this.config.dir.value,
+        });
+      },
+    });
+
+    const wrapper = mount(Child, {
+      global: {
+        plugins: [
+          app => provideAppConfig(app, { dir: 'rtl' }),
+        ],
+      },
+    });
+
+    expect(wrapper.find('div').attributes('data-dir')).toBe('rtl');
+
+    wrapper.unmount();
+  });
+});
+
+// --- useId override ---
+
+describe('useId (config override)', () => {
+  it('uses the toolkit fallback when no override is provided', () => {
+    const Child = defineComponent({
+      setup() {
+        const id = useId();
+        return { id };
+      },
+      render() {
+        return h('div', { 'data-id': this.id });
+      },
+    });
+
+    const wrapper = mount(Child);
+    expect(wrapper.find('div').attributes('data-id')).toMatch(/^robonen-/);
+    wrapper.unmount();
+  });
+
+  it('routes through a provided useId override', () => {
+    let count = 0;
+    const customUseId = (_deterministic?: unknown, prefix = 'x') => {
+      count += 1;
+      const n = count;
+      return computed(() => `${prefix}-${n}`);
+    };
+
+    const Child = defineComponent({
+      setup() {
+        const a = useId();
+        const b = useId(undefined, 'custom');
+        return { a, b };
+      },
+      render() {
+        return h('div', { 'data-a': this.a, 'data-b': this.b });
+      },
+    });
+
+    const wrapper = mount(Child, {
+      global: {
+        plugins: [app => provideAppConfig(app, { useId: customUseId })],
+      },
+    });
+
+    expect(wrapper.find('div').attributes('data-a')).toBe('x-1');
+    expect(wrapper.find('div').attributes('data-b')).toBe('custom-2');
+    wrapper.unmount();
+  });
+
+  it('respects deterministic id passed through the override', () => {
+    const Child = defineComponent({
+      setup() {
+        const id = useId(() => 'fixed-id');
+        return { id };
+      },
+      render() {
+        return h('div', { 'data-id': this.id });
+      },
+    });
+
+    const wrapper = mount(Child);
+    expect(wrapper.find('div').attributes('data-id')).toBe('fixed-id');
+    wrapper.unmount();
+  });
+});
+
+// --- new global fields: locale / nonce / scrollBody ---
+
+describe('config fields (locale / nonce / scrollBody)', () => {
+  function renderConfig() {
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        return { config };
+      },
+      render() {
+        return h('div', {
+          'data-locale': this.config.locale.value,
+          'data-nonce': this.config.nonce.value ?? '',
+          'data-scroll': JSON.stringify(this.config.scrollBody.value),
+        });
+      },
+    });
+    return Child;
+  }
+
+  it('exposes documented defaults when no provider exists', () => {
+    const wrapper = mount(renderConfig());
+    const div = wrapper.find('div');
+    expect(div.attributes('data-locale')).toBe('en');
+    expect(div.attributes('data-nonce')).toBe('');
+    expect(div.attributes('data-scroll')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('inherits custom locale / nonce / scrollBody from provideConfig', () => {
+    const Child = renderConfig();
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({
+          locale: 'fr',
+          nonce: 'abc123',
+          scrollBody: { padding: 20, margin: 0 },
+        });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    const div = wrapper.find('div');
+    expect(div.attributes('data-locale')).toBe('fr');
+    expect(div.attributes('data-nonce')).toBe('abc123');
+    expect(div.attributes('data-scroll')).toBe('{"padding":20,"margin":0}');
+    wrapper.unmount();
+  });
+
+  it('supports scrollBody=false', () => {
+    const Child = renderConfig();
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ scrollBody: false });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-scroll')).toBe('false');
+    wrapper.unmount();
+  });
+});
+
+// --- reactivity preservation (the fixed defect) ---
+
+describe('reactive source preservation', () => {
+  it('stays live when dir is provided as a ref', async () => {
+    const source = ref<'ltr' | 'rtl'>('ltr');
+
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        return { config };
+      },
+      render() {
+        return h('div', { 'data-dir': this.config.dir.value });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ dir: source });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-dir')).toBe('ltr');
+
+    source.value = 'rtl';
+    await nextTick();
+    expect(wrapper.find('div').attributes('data-dir')).toBe('rtl');
+
+    wrapper.unmount();
+  });
+
+  it('stays live when locale is provided as a getter', async () => {
+    const source = ref('en');
+
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        return { config };
+      },
+      render() {
+        return h('div', { 'data-locale': this.config.locale.value });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ locale: () => source.value });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-locale')).toBe('en');
+
+    source.value = 'de';
+    await nextTick();
+    expect(wrapper.find('div').attributes('data-locale')).toBe('de');
+
+    wrapper.unmount();
+  });
+
+  it('teleportTarget getter stays live and resolves default', async () => {
+    const source = ref<string>('body');
+
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        return { config };
+      },
+      render() {
+        return h('div', { 'data-target': this.config.teleportTarget.value });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ teleportTarget: () => source.value });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-target')).toBe('body');
+
+    source.value = '#app';
+    await nextTick();
+    expect(wrapper.find('div').attributes('data-target')).toBe('#app');
+
+    wrapper.unmount();
+  });
+});
+
+// --- resolver composables ---
+
+describe('useDirection / useLocale / useNonce', () => {
+  it('useDirection prefers local override over config and default', () => {
+    const A = defineComponent({
+      setup() {
+        const dir = useDirection();
+        return { dir };
+      },
+      render() {
+        return h('div', { 'data-dir': this.dir });
+      },
+    });
+    const B = defineComponent({
+      setup() {
+        const dir = useDirection('rtl');
+        return { dir };
+      },
+      render() {
+        return h('div', { 'data-dir': this.dir });
+      },
+    });
+
+    const noProvider = mount(A);
+    expect(noProvider.find('div').attributes('data-dir')).toBe('ltr');
+    noProvider.unmount();
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ dir: 'rtl' });
+      },
+      render() {
+        return h(A);
+      },
+    });
+    const inherited = mount(Parent);
+    expect(inherited.find('div').attributes('data-dir')).toBe('rtl');
+    inherited.unmount();
+
+    const override = mount(B);
+    expect(override.find('div').attributes('data-dir')).toBe('rtl');
+    override.unmount();
+  });
+
+  it('useLocale prefers local override, then config, then en', () => {
+    const Local = defineComponent({
+      setup() {
+        const locale = useLocale('it');
+        return { locale };
+      },
+      render() {
+        return h('div', { 'data-locale': this.locale });
+      },
+    });
+    const wrapper = mount(Local);
+    expect(wrapper.find('div').attributes('data-locale')).toBe('it');
+    wrapper.unmount();
+
+    const Inherited = defineComponent({
+      setup() {
+        const locale = useLocale();
+        return { locale };
+      },
+      render() {
+        return h('div', { 'data-locale': this.locale });
+      },
+    });
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ locale: 'es' });
+      },
+      render() {
+        return h(Inherited);
+      },
+    });
+    const w2 = mount(Parent);
+    expect(w2.find('div').attributes('data-locale')).toBe('es');
+    w2.unmount();
+  });
+
+  it('useNonce prefers local override, then config', () => {
+    const Inherited = defineComponent({
+      setup() {
+        const nonce = useNonce();
+        return { nonce };
+      },
+      render() {
+        return h('div', { 'data-nonce': this.nonce ?? '' });
+      },
+    });
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ nonce: 'cfg-nonce' });
+      },
+      render() {
+        return h(Inherited);
+      },
+    });
+    const w = mount(Parent);
+    expect(w.find('div').attributes('data-nonce')).toBe('cfg-nonce');
+    w.unmount();
+
+    const Local = defineComponent({
+      setup() {
+        const nonce = useNonce('local-nonce');
+        return { nonce };
+      },
+      render() {
+        return h('div', { 'data-nonce': this.nonce ?? '' });
+      },
+    });
+    const Parent2 = defineComponent({
+      setup() {
+        provideConfig({ nonce: 'cfg-nonce' });
+      },
+      render() {
+        return h(Local);
+      },
+    });
+    const w2 = mount(Parent2);
+    expect(w2.find('div').attributes('data-nonce')).toBe('local-nonce');
+    w2.unmount();
+
+    const NoConfig = defineComponent({
+      setup() {
+        const nonce = useNonce();
+        return { nonce };
+      },
+      render() {
+        return h('div', { 'data-nonce': this.nonce ?? 'none' });
+      },
+    });
+    const w3 = mount(NoConfig);
+    expect(w3.find('div').attributes('data-nonce')).toBe('none');
+    w3.unmount();
+  });
+});
+
+// --- dateAdapter config + useDateAdapter resolver ---
+
+describe('dateAdapter / useDateAdapter', () => {
+  it('exposes the native date adapter by default', () => {
+    const Child = defineComponent({
+      setup() {
+        const config = useConfig();
+        const adapter = useDateAdapter();
+        return { config, adapter };
+      },
+      render() {
+        return h('div', {
+          'data-config-native': this.config.dateAdapter.value === nativeDateAdapter,
+          'data-resolved-native': this.adapter === nativeDateAdapter,
+        });
+      },
+    });
+
+    const wrapper = mount(Child);
+    expect(wrapper.find('div').attributes('data-config-native')).toBe('true');
+    expect(wrapper.find('div').attributes('data-resolved-native')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('inherits a custom adapter from provideConfig', () => {
+    const customAdapter = { ...nativeDateAdapter };
+
+    const Child = defineComponent({
+      setup() {
+        const adapter = useDateAdapter();
+        return { adapter };
+      },
+      render() {
+        return h('div', { 'data-custom': this.adapter === customAdapter });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ dateAdapter: customAdapter });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-custom')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('prefers a per-call override over config and the native default', () => {
+    const configAdapter = { ...nativeDateAdapter };
+    const overrideAdapter = { ...nativeDateAdapter };
+
+    const Child = defineComponent({
+      setup() {
+        const adapter = useDateAdapter(overrideAdapter);
+        return { adapter };
+      },
+      render() {
+        return h('div', { 'data-override': this.adapter === overrideAdapter });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ dateAdapter: configAdapter });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-override')).toBe('true');
+    wrapper.unmount();
+  });
+
+  it('stays live when the config adapter is a ref', async () => {
+    const a = { ...nativeDateAdapter };
+    const b = { ...nativeDateAdapter };
+    // shallowRef: an adapter is an opaque object — deep-reactivizing it (plain
+    // `ref`) would wrap it in a proxy and break identity comparison.
+    const source = shallowRef(a);
+
+    const Child = defineComponent({
+      setup() {
+        const adapter = useDateAdapter();
+        return { adapter };
+      },
+      render() {
+        return h('div', { 'data-which': this.adapter === a ? 'a' : 'b' });
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        provideConfig({ dateAdapter: source });
+      },
+      render() {
+        return h(Child);
+      },
+    });
+
+    const wrapper = mount(Parent);
+    expect(wrapper.find('div').attributes('data-which')).toBe('a');
+
+    source.value = b;
+    await nextTick();
+    expect(wrapper.find('div').attributes('data-which')).toBe('b');
+
+    wrapper.unmount();
+  });
+});
diff --git a/vue/primitives/src/utilities/config-provider/context.ts b/vue/primitives/src/utilities/config-provider/context.ts
new file mode 100644
index 0000000..1e91363
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/context.ts
@@ -0,0 +1,179 @@
+import type { App, ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from 'vue';
+import type { AnyDateAdapter } from './date-adapter';
+import { getCurrentScope, isRef, ref, shallowRef, toValue, watch } from 'vue';
+import { useId as toolkitUseId, useInjectionStore } from '@robonen/vue';
+import { nativeDateAdapter } from './date-adapter';
+
+export type Direction = 'ltr' | 'rtl';
+
+/**
+ * Fine-grained control over the body scroll-lock compensation applied while a
+ * modal layer (dialog, popover, menu, select) holds the page locked. Mirrors
+ * the structure consumed by the global body-scroll-lock composable:
+ *
+ * - `padding` — compensate the removed scrollbar with right padding.
+ * - `margin` — compensate the removed scrollbar with right margin.
+ *
+ * `true` reuses the measured scrollbar width; a `number`/`string` overrides it.
+ */
+export interface ScrollBodyOption {
+  padding?: boolean | number | string;
+  margin?: boolean | number | string;
+}
+
+export type UseIdFn = (
+  deterministic?: MaybeRefOrGetter<string | undefined>,
+  prefix?: string,
+) => ComputedRef<string>;
+
+export interface ConfigContext {
+  /** Global reading direction inherited by every primitive. */
+  dir: Ref<Direction>;
+  /** Global locale inherited by date/calendar primitives. */
+  locale: Ref<string>;
+  /** Global CSP `nonce` inherited by style-injecting primitives. */
+  nonce: Ref<string | undefined>;
+  /** Global body scroll-lock compensation behavior. */
+  scrollBody: Ref<boolean | ScrollBodyOption>;
+  /** Global teleport/portal destination. */
+  teleportTarget: ShallowRef<string | HTMLElement>;
+  /** Pluggable id factory, used to control hydration-safe id generation. */
+  useId: UseIdFn;
+  /**
+   * Pluggable date backend inherited by every date/calendar primitive. The
+   * adapter is type-erased here; resolve it with `useDateAdapter<TDate>()` to
+   * recover the concrete date type at the call site.
+   */
+  dateAdapter: ShallowRef<AnyDateAdapter>;
+}
+
+export interface ConfigOptions {
+  /**
+   * Global reading direction of the application, inherited by all primitives.
+   * A per-component `dir` prop always overrides this.
+   * @default 'ltr'
+   */
+  dir?: MaybeRefOrGetter<Direction | undefined>;
+  /**
+   * Global locale of the application, inherited by date/calendar primitives.
+   * A per-component `locale` prop always overrides this.
+   * @default 'en'
+   */
+  locale?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * Global CSP `nonce`, inherited by primitives that inject a `<style>` tag.
+   * A per-component `nonce` prop always overrides this.
+   */
+  nonce?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * Global body scroll-lock compensation behavior, inherited by modal
+   * primitives. `true` keeps the default padding compensation, `false`
+   * disables it, or pass `{ padding, margin }` for fine-grained control.
+   * @default true
+   */
+  scrollBody?: MaybeRefOrGetter<boolean | ScrollBodyOption | undefined>;
+  /**
+   * Global teleport/portal destination consumed by `Teleport`.
+   * @default 'body'
+   */
+  teleportTarget?: MaybeRefOrGetter<string | HTMLElement | undefined>;
+  /**
+   * Pluggable id factory, useful as a workaround for hydration mismatches.
+   * Signature matches the toolkit `useId`: `(deterministic?, prefix?)`.
+   */
+  useId?: UseIdFn;
+  /**
+   * Pluggable date backend inherited by date/calendar primitives, letting them
+   * run on a custom calendar system or date library instead of the native
+   * `Date`. A per-component `dateAdapter` prop always overrides this.
+   * @default nativeDateAdapter
+   */
+  dateAdapter?: MaybeRefOrGetter<AnyDateAdapter | undefined>;
+}
+
+const DEFAULT_CONFIG = {
+  dir: 'ltr' as Direction,
+  locale: 'en',
+  nonce: undefined as string | undefined,
+  scrollBody: true as boolean | ScrollBodyOption,
+  teleportTarget: 'body' as string | HTMLElement,
+  dateAdapter: nativeDateAdapter as AnyDateAdapter,
+};
+
+/**
+ * Builds a writable `Ref` from a `MaybeRefOrGetter` source while preserving its
+ * reactivity:
+ *
+ * - a `Ref` source is reused directly (live + writable, zero overhead),
+ * - a getter/value source becomes a writable ref that mirrors later source
+ *   updates via a scoped watcher (no leak when no scope is active, e.g.
+ *   app-level provisioning, where the snapshot is the documented behavior).
+ *
+ * This fixes the prior snapshot-into-a-fresh-ref behavior that silently
+ * disconnected a reactive `dir`/`teleportTarget`/`locale` source.
+ */
+function resolveConfigRef<T>(
+  source: MaybeRefOrGetter<T | undefined> | undefined,
+  fallback: T,
+  shallow = false,
+): Ref<T> {
+  if (isRef(source))
+    return source as Ref<T>;
+
+  const initial = source === undefined ? fallback : (toValue(source) ?? fallback);
+  const target = (shallow ? shallowRef(initial) : ref(initial)) as Ref<T>;
+
+  // Only a getter (function) can carry live reactivity beyond the snapshot.
+  if (typeof source === 'function' && getCurrentScope()) {
+    watch(
+      () => toValue(source) ?? fallback,
+      (next) => { target.value = next; },
+    );
+  }
+
+  return target;
+}
+
+function resolveContext(options?: ConfigOptions): ConfigContext {
+  return {
+    dir: resolveConfigRef(options?.dir, DEFAULT_CONFIG.dir),
+    locale: resolveConfigRef(options?.locale, DEFAULT_CONFIG.locale),
+    nonce: resolveConfigRef(options?.nonce, DEFAULT_CONFIG.nonce),
+    scrollBody: resolveConfigRef(options?.scrollBody, DEFAULT_CONFIG.scrollBody),
+    teleportTarget: resolveConfigRef(
+      options?.teleportTarget,
+      DEFAULT_CONFIG.teleportTarget,
+      true,
+    ) as ShallowRef<string | HTMLElement>,
+    useId: options?.useId ?? toolkitUseId,
+    dateAdapter: resolveConfigRef(
+      options?.dateAdapter,
+      DEFAULT_CONFIG.dateAdapter,
+      true,
+    ) as ShallowRef<AnyDateAdapter>,
+  };
+}
+
+/**
+ * Global config store, backed by the toolkit's `useInjectionStore`. Each
+ * `provideConfig`/`provideAppConfig` call builds a fresh `ConfigContext` from
+ * the given options and provides it; `useConfig` injects it, falling back to a
+ * fully-resolved default context (all fields present, native date adapter) when
+ * no provider exists above the consumer.
+ */
+const ConfigStore = useInjectionStore(resolveContext, {
+  injectionName: 'ConfigContext',
+  defaultValue: resolveContext(),
+});
+
+export function provideConfig(options?: ConfigOptions): ConfigContext {
+  return ConfigStore.useProvidingState(options);
+}
+
+export function provideAppConfig(app: App, options?: ConfigOptions): ConfigContext {
+  return ConfigStore.useAppProvidingState(app)(options);
+}
+
+export function useConfig(): ConfigContext {
+  return ConfigStore.useInjectedState();
+}
diff --git a/vue/primitives/src/utilities/config-provider/date-adapter.ts b/vue/primitives/src/utilities/config-provider/date-adapter.ts
new file mode 100644
index 0000000..163257a
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/date-adapter.ts
@@ -0,0 +1,203 @@
+import type {
+  CalendarMonth,
+  CreateMonthsOptions,
+  WeekDayFormat,
+} from '../../display/calendar/utils';
+import {
+  addDays,
+  addMonths,
+  addYears,
+  clamp,
+  createMonths,
+  endOfMonth,
+  findFirstFocusableDate,
+  formatDate,
+  formatFullDate,
+  formatMonthYear,
+  formatWeekday,
+  getDaysInMonth,
+  getLocaleWeekStartsOn,
+  getWeekdayLabels,
+  getWeeks,
+  isAfter,
+  isBefore,
+  isDateUnavailable,
+  isSameDay,
+  isSameMonth,
+  startOfMonth,
+  startOfWeek,
+  toDateOnly,
+  toIsoDate,
+} from '../../display/calendar/utils';
+
+/** First day of the week, `0` (Sunday) through `6` (Saturday). */
+export type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * A calendar date broken into numeric fields. `month` is **1-based** (January
+ * is `1`) to mirror the segmented field's user-facing values; `fromParts`
+ * converts it back to the native representation. Time fields are optional and
+ * default to `0` when constructing.
+ */
+export interface DateParts {
+  year: number;
+  /** 1-based month (January = 1). */
+  month: number;
+  day: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+}
+
+/** `DateParts` with every field resolved (used as `getParts` output). */
+export type ResolvedDateParts = Required<DateParts>;
+
+/**
+ * Pluggable date backend abstracting every date operation the calendar and
+ * date-picker primitives need, generic over the date representation `TDate`.
+ * The default {@link nativeDateAdapter} operates on the JS `Date`; provide a
+ * custom adapter through `ConfigProvider`/`provideConfig({ dateAdapter })` (or a
+ * per-component `dateAdapter` prop) to swap in another calendar system or date
+ * library while keeping the primitives unchanged.
+ *
+ * The boundary type is `TDate` throughout: a primitive that resolves the
+ * adapter via `useDateAdapter<TDate>()` hands the adapter its own date values
+ * and receives `TDate` back, so a single adapter governs construction,
+ * arithmetic, comparison, formatting and grid building consistently.
+ */
+export interface DateAdapter<TDate = Date> {
+  // --- construction / identity ---
+  /** The current date-time ("now"/"today"). */
+  now: () => TDate;
+  /** An independent copy of `date`, preserving the full time-of-day. */
+  clone: (date: TDate) => TDate;
+  /** A copy of `date` with the time-of-day stripped to local midnight. */
+  toDateOnly: (date: TDate) => TDate;
+  /** Build a date from numeric fields (`month` is 1-based; time defaults to 0). */
+  fromParts: (parts: DateParts) => TDate;
+  /** Extract the numeric fields of `date` (`month` is 1-based). */
+  getParts: (date: TDate) => ResolvedDateParts;
+  /** Day of week, `0` (Sunday) through `6` (Saturday). */
+  getDay: (date: TDate) => number;
+  /** Parse free-form user text into a date, or `null` when unparseable. */
+  parse: (text: string) => TDate | null;
+  /** Full ISO-8601 string (UTC), used for hidden form-input serialization. */
+  toISO: (date: TDate) => string;
+
+  // --- arithmetic ---
+  addDays: (date: TDate, amount: number) => TDate;
+  addMonths: (date: TDate, amount: number) => TDate;
+  addYears: (date: TDate, amount: number) => TDate;
+  startOfMonth: (date: TDate) => TDate;
+  endOfMonth: (date: TDate) => TDate;
+  startOfWeek: (date: TDate, weekStartsOn: WeekDay) => TDate;
+  /** Number of days in `date`'s month. */
+  getDaysInMonth: (date: TDate) => number;
+
+  // --- comparison ---
+  isSameDay: (a: TDate, b: TDate) => boolean;
+  isSameMonth: (a: TDate, b: TDate) => boolean;
+  /** Date-only `a < b` (time-of-day ignored). */
+  isBefore: (a: TDate, b: TDate) => boolean;
+  /** Date-only `a > b` (time-of-day ignored). */
+  isAfter: (a: TDate, b: TDate) => boolean;
+  /** Full-timestamp ordering: negative if `a < b`, `0` if equal, positive if `a > b`. */
+  compare: (a: TDate, b: TDate) => number;
+  /** Clamp `date` (date-only) into the optional `[min, max]` range. */
+  clamp: (date: TDate, min?: TDate, max?: TDate) => TDate;
+  /** Whether `date` is out of `[min, max]` bounds or matched by `predicate`. */
+  isDateUnavailable: (
+    date: TDate,
+    predicate?: (date: TDate) => boolean,
+    min?: TDate,
+    max?: TDate,
+  ) => boolean;
+
+  // --- locale / formatting ---
+  getLocaleWeekStartsOn: (locale: string) => WeekDay;
+  format: (date: TDate, options: Intl.DateTimeFormatOptions, locale: string) => string;
+  formatWeekday: (date: TDate, locale: string, width: WeekDayFormat) => string;
+  formatMonthYear: (date: TDate, locale: string) => string;
+  formatFullDate: (date: TDate, locale: string) => string;
+  /** Local `YYYY-MM-DD` (does not shift across the UTC boundary). */
+  toIsoDate: (date: TDate) => string;
+
+  // --- grid building ---
+  getWeeks: (month: TDate, weekStartsOn: WeekDay) => TDate[][];
+  createMonths: (options: CreateMonthsOptions<TDate>) => Array<CalendarMonth<TDate>>;
+  getWeekdayLabels: (weekStartsOn: WeekDay, locale: string, width: WeekDayFormat) => string[];
+  findFirstFocusableDate: (
+    months: Array<CalendarMonth<TDate>>,
+    isDisabled: (date: TDate) => boolean,
+    isUnavailable: (date: TDate) => boolean,
+  ) => TDate | undefined;
+}
+
+/**
+ * A type-erased {@link DateAdapter}, used where the concrete date
+ * representation is not statically known (e.g. the global config context, which
+ * may hold an adapter for any date library). Recover the precise type at the
+ * consumer with `useDateAdapter<TDate>()`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- intentional erasure across the inject boundary
+export type AnyDateAdapter = DateAdapter<any>;
+
+/**
+ * Default {@link DateAdapter} backed by the native JS `Date`. Delegates to the
+ * package's `Date`-based date utilities, so it is the zero-config behavior when
+ * no custom adapter is provided.
+ */
+export const nativeDateAdapter: DateAdapter<Date> = {
+  // --- construction / identity ---
+  now: () => new Date(),
+  clone: date => new Date(date.getTime()),
+  toDateOnly,
+  fromParts: ({ year, month, day, hour = 0, minute = 0, second = 0 }) =>
+    new Date(year, month - 1, day, hour, minute, second, 0),
+  getParts: date => ({
+    year: date.getFullYear(),
+    month: date.getMonth() + 1,
+    day: date.getDate(),
+    hour: date.getHours(),
+    minute: date.getMinutes(),
+    second: date.getSeconds(),
+  }),
+  getDay: date => date.getDay(),
+  parse: (text) => {
+    const parsed = new Date(text);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  },
+  toISO: date => date.toISOString(),
+
+  // --- arithmetic ---
+  addDays,
+  addMonths,
+  addYears,
+  startOfMonth,
+  endOfMonth,
+  startOfWeek,
+  getDaysInMonth,
+
+  // --- comparison ---
+  isSameDay,
+  isSameMonth,
+  isBefore,
+  isAfter,
+  compare: (a, b) => a.getTime() - b.getTime(),
+  clamp,
+  isDateUnavailable,
+
+  // --- locale / formatting ---
+  getLocaleWeekStartsOn,
+  format: formatDate,
+  formatWeekday,
+  formatMonthYear,
+  formatFullDate,
+  toIsoDate,
+
+  // --- grid building ---
+  getWeeks,
+  createMonths,
+  getWeekdayLabels,
+  findFirstFocusableDate,
+};
diff --git a/vue/primitives/src/utilities/config-provider/index.ts b/vue/primitives/src/utilities/config-provider/index.ts
new file mode 100644
index 0000000..8100b00
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/index.ts
@@ -0,0 +1,23 @@
+export {
+  provideConfig,
+  provideAppConfig,
+  useConfig,
+  type ConfigContext,
+  type ConfigOptions,
+  type Direction,
+  type ScrollBodyOption,
+  type UseIdFn,
+} from './context';
+export { useId } from './useId';
+export { useDirection } from './useDirection';
+export { useLocale } from './useLocale';
+export { useNonce } from './useNonce';
+export {
+  nativeDateAdapter,
+  type AnyDateAdapter,
+  type DateAdapter,
+  type DateParts,
+  type ResolvedDateParts,
+  type WeekDay,
+} from './date-adapter';
+export { useDateAdapter } from './useDateAdapter';
diff --git a/vue/primitives/src/utilities/config-provider/useDateAdapter.ts b/vue/primitives/src/utilities/config-provider/useDateAdapter.ts
new file mode 100644
index 0000000..005741d
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/useDateAdapter.ts
@@ -0,0 +1,26 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import type { DateAdapter } from './date-adapter';
+import { computed, toValue } from 'vue';
+import { useConfig } from './context';
+
+/**
+ * Resolves the effective {@link DateAdapter}: a per-component override wins over
+ * the active `ConfigProvider` `dateAdapter`, which falls back to the native
+ * `Date` adapter. Lets calendar/date-picker primitives route every date
+ * operation through a single, swappable backend instead of hard-coding `Date`.
+ *
+ * The type parameter `TDate` re-asserts the concrete date representation at the
+ * call site (the context stores a type-erased adapter), so a primitive built on
+ * a custom adapter gets correctly-typed dates back.
+ *
+ * @param override Optional per-component adapter override.
+ * @returns A computed `DateAdapter<TDate>` combining the override with config.
+ */
+export function useDateAdapter<TDate = Date>(
+  override?: MaybeRefOrGetter<DateAdapter<TDate> | undefined>,
+): ComputedRef<DateAdapter<TDate>> {
+  const config = useConfig();
+  return computed(
+    () => (toValue(override) ?? config.dateAdapter.value) as DateAdapter<TDate>,
+  );
+}
diff --git a/vue/primitives/src/utilities/config-provider/useDirection.ts b/vue/primitives/src/utilities/config-provider/useDirection.ts
new file mode 100644
index 0000000..a2309dd
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/useDirection.ts
@@ -0,0 +1,21 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { computed, toValue } from 'vue';
+import type { Direction } from './context';
+import { useConfig } from './context';
+
+/**
+ * Resolves the effective reading direction: a per-component override wins over
+ * the active `ConfigProvider` `dir`, falling back to `'ltr'`.
+ *
+ * Mirrors the `dir ?? config.dir.value` pattern used by primitive roots, as a
+ * reusable composable.
+ *
+ * @param dir Optional per-component direction override.
+ * @returns A computed `Direction` combining the override with the config.
+ */
+export function useDirection(
+  dir?: MaybeRefOrGetter<Direction | undefined>,
+): ComputedRef<Direction> {
+  const config = useConfig();
+  return computed(() => toValue(dir) ?? config.dir.value ?? 'ltr');
+}
diff --git a/vue/primitives/src/config-provider/useId.ts b/vue/primitives/src/utilities/config-provider/useId.ts
similarity index 100%
rename from vue/primitives/src/config-provider/useId.ts
rename to vue/primitives/src/utilities/config-provider/useId.ts
diff --git a/vue/primitives/src/utilities/config-provider/useLocale.ts b/vue/primitives/src/utilities/config-provider/useLocale.ts
new file mode 100644
index 0000000..142b048
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/useLocale.ts
@@ -0,0 +1,19 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { computed, toValue } from 'vue';
+import { useConfig } from './context';
+
+/**
+ * Resolves the effective locale: a per-component override wins over the active
+ * `ConfigProvider` `locale`, falling back to `'en'`. Lets date/calendar
+ * primitives inherit a single app-wide locale instead of repeating it per
+ * instance.
+ *
+ * @param locale Optional per-component locale override.
+ * @returns A computed locale string combining the override with the config.
+ */
+export function useLocale(
+  locale?: MaybeRefOrGetter<string | undefined>,
+): ComputedRef<string> {
+  const config = useConfig();
+  return computed(() => toValue(locale) || config.locale.value || 'en');
+}
diff --git a/vue/primitives/src/utilities/config-provider/useNonce.ts b/vue/primitives/src/utilities/config-provider/useNonce.ts
new file mode 100644
index 0000000..c6cd2c2
--- /dev/null
+++ b/vue/primitives/src/utilities/config-provider/useNonce.ts
@@ -0,0 +1,18 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { computed, toValue } from 'vue';
+import { useConfig } from './context';
+
+/**
+ * Resolves the effective CSP `nonce`: a per-component override wins over the
+ * active `ConfigProvider` `nonce`. Lets style-injecting primitives inherit a
+ * single app-wide nonce instead of being passed one manually.
+ *
+ * @param nonce Optional per-component nonce override.
+ * @returns A computed nonce (or `undefined`) combining the override with config.
+ */
+export function useNonce(
+  nonce?: MaybeRefOrGetter<string | undefined>,
+): ComputedRef<string | undefined> {
+  const config = useConfig();
+  return computed(() => toValue(nonce) || config.nonce.value);
+}
diff --git a/vue/primitives/src/dismissable-layer/DismissableLayer.vue b/vue/primitives/src/utilities/dismissable-layer/DismissableLayer.vue
similarity index 64%
rename from vue/primitives/src/dismissable-layer/DismissableLayer.vue
rename to vue/primitives/src/utilities/dismissable-layer/DismissableLayer.vue
index 4062886..b7900f9 100644
--- a/vue/primitives/src/dismissable-layer/DismissableLayer.vue
+++ b/vue/primitives/src/utilities/dismissable-layer/DismissableLayer.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A low-level building block that detects when the user interacts away from its
@@ -34,9 +34,9 @@ export interface DismissableLayerEmits {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
-import { onBeforeUnmount, onMounted, watchPostEffect } from 'vue';
-import { dismissableLayerStack } from './stack';
+import { Primitive } from '../../internal/primitive';
+import { computed, onBeforeUnmount, onMounted, onWatcherCleanup, watch, watchPostEffect } from 'vue';
+import { dismissableLayerStack, dismissableLayerVersion } from './stack';
 import { useClickOutside, useEscapeKey, useEventListener, useForwardExpose } from '@robonen/vue';
 
 const { disableOutsidePointerEvents = false, as = 'div' } = defineProps<DismissableLayerProps>();
@@ -46,9 +46,20 @@ const { forwardRef, currentElement: nodeRef } = useForwardExpose();
 
 const layer = { el: null as unknown as HTMLElement, disableOutsidePointerEvents: false };
 
-watchPostEffect(() => {
-  layer.disableOutsidePointerEvents = disableOutsidePointerEvents;
-});
+// Resolve the document that actually owns the layer node so iframe / multi-window
+// scenarios attach the focus listener and toggle the body style on the correct
+// document, falling back to the global one before the node is resolved.
+function ownerDocument(): Document {
+  return nodeRef.value?.ownerDocument ?? document;
+}
+
+// Use an explicit-source `watch` (not `watchEffect`) so the in-callback
+// `touch()` write does not establish a dependency on the version ref and loop.
+watch(() => disableOutsidePointerEvents, (value) => {
+  layer.disableOutsidePointerEvents = value;
+  // Re-derive every layer's pointer-events when this flag toggles.
+  dismissableLayerStack.touch();
+}, { immediate: true });
 
 onMounted(() => {
   if (!nodeRef.value) return;
@@ -60,6 +71,20 @@ onBeforeUnmount(() => {
   dismissableLayerStack.remove(layer);
 });
 
+// Per-layer `pointer-events`: while any layer blocks outside pointer events the
+// body is `none`, so a layer at or above the highest blocking layer must stay
+// interactive (`auto`), and a layer below it must be made non-interactive
+// (`none`). Reading the reactive version keeps this in sync with stack mutations.
+const pointerEvents = computed<'auto' | 'none' | undefined>(() => {
+  // Track stack mutations so the per-layer value re-derives when layers change.
+  void dismissableLayerVersion.value;
+  return dismissableLayerStack.pointerEventsFor(layer);
+});
+
+const layerStyle = computed(() =>
+  pointerEvents.value ? { pointerEvents: pointerEvents.value } : undefined,
+);
+
 // `focusin` is non-cancelable (and synthetic pointer events may be too), so the
 // native `defaultPrevented` flag can never flip — track prevention via a patched
 // `preventDefault` instead, keeping the "Preventable." emit contract honest.
@@ -90,15 +115,20 @@ useClickOutside(nodeRef, (event) => {
   if (emitPreventable(event, e => emit('interactOutside', e))) return;
   if (emitPreventable(event, e => emit('pointerDownOutside', e))) return;
   emit('dismiss');
+}, {
+  // Interactions inside a registered branch (portaled trigger, anchor, toast
+  // viewport, …) are semantically *inside* this layer and must not dismiss it.
+  ignore: () => dismissableLayerStack.getBranches(),
 });
 
 // Focus outside detection — fires when focus leaves this layer to an element
-// outside it. We use the `focusin` event at document level.
-useEventListener(document, 'focusin', (event: FocusEvent) => {
+// outside it. We use the `focusin` event at the owning-document level.
+useEventListener(() => ownerDocument(), 'focusin', (event: FocusEvent) => {
   const el = nodeRef.value;
   const target = event.target as Node | null;
   if (!el || !target) return;
   if (el === target || el.contains(target)) return;
+  if (dismissableLayerStack.isInBranch(target)) return;
   if (!dismissableLayerStack.isTopmost(layer)) return;
 
   if (emitPreventable(event, e => emit('interactOutside', e))) return;
@@ -108,24 +138,23 @@ useEventListener(document, 'focusin', (event: FocusEvent) => {
 
 // When this layer disables outside pointer events, the body gets a data
 // attribute so consumers can style `[data-dismissable-blocking] *:not([data-dismissable-layer]) { pointer-events: none }`.
-// We toggle via a style element approach for robustness.
 // `disableOutsidePointerEvents` is a reactive prop destructure — reading it
 // inside `watchPostEffect` already registers the dependency, no need for a
 // computed wrapper.
-
-watchPostEffect((onCleanup) => {
+watchPostEffect(() => {
   if (!disableOutsidePointerEvents) return;
   if (typeof document === 'undefined') return;
 
-  const original = document.body.style.pointerEvents;
-  document.body.style.pointerEvents = 'none';
-  document.body.dataset['dismissableBlocking'] = 'true';
+  const doc = ownerDocument();
+  const original = doc.body.style.pointerEvents;
+  doc.body.style.pointerEvents = 'none';
+  doc.body.dataset['dismissableBlocking'] = 'true';
 
-  onCleanup(() => {
+  onWatcherCleanup(() => {
     // Only clear if no other disabling layer remains
     if (!dismissableLayerStack.anyDisabling()) {
-      document.body.style.pointerEvents = original;
-      delete document.body.dataset['dismissableBlocking'];
+      doc.body.style.pointerEvents = original;
+      delete doc.body.dataset['dismissableBlocking'];
     }
   });
 });
@@ -136,7 +165,7 @@ watchPostEffect((onCleanup) => {
     :ref="forwardRef"
     :as="as"
     :data-dismissable-layer="true"
-    :style="disableOutsidePointerEvents ? { pointerEvents: 'auto' } : undefined"
+    :style="layerStyle"
   >
     <slot />
   </Primitive>
diff --git a/vue/primitives/src/utilities/dismissable-layer/DismissableLayerBranch.vue b/vue/primitives/src/utilities/dismissable-layer/DismissableLayerBranch.vue
new file mode 100644
index 0000000..ca8e0fd
--- /dev/null
+++ b/vue/primitives/src/utilities/dismissable-layer/DismissableLayerBranch.vue
@@ -0,0 +1,45 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../../internal/primitive';
+
+/**
+ * Marks a subtree as belonging to a sibling DismissableLayer even though it is
+ * rendered elsewhere in the DOM (e.g. a portaled trigger, an anchor, or a toast
+ * viewport). Pointer-down and focus interactions that originate inside a branch
+ * are treated as *inside* the layer, so they will not trigger a dismiss. Renders
+ * no UI of its own beyond the element you ask for via `as`.
+ */
+
+export interface DismissableLayerBranchProps extends PrimitiveProps {}
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../../internal/primitive';
+import { onScopeDispose, watch } from 'vue';
+import { dismissableLayerStack } from './stack';
+import { useForwardExpose } from '@robonen/vue';
+
+const { as = 'div' } = defineProps<DismissableLayerBranchProps>();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Register/unregister against the shared branch set as the resolved element
+// changes (covers `as="template"` and conditional rendering). `onScopeDispose`
+// guarantees teardown when the branch's effect scope is torn down.
+watch(currentElement, (el, prev) => {
+  if (prev) dismissableLayerStack.removeBranch(prev);
+  if (el) dismissableLayerStack.addBranch(el);
+});
+
+onScopeDispose(() => {
+  if (currentElement.value) dismissableLayerStack.removeBranch(currentElement.value);
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+  >
+    <slot />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/dismissable-layer/__test__/DismissableLayer.test.ts b/vue/primitives/src/utilities/dismissable-layer/__test__/DismissableLayer.test.ts
similarity index 55%
rename from vue/primitives/src/dismissable-layer/__test__/DismissableLayer.test.ts
rename to vue/primitives/src/utilities/dismissable-layer/__test__/DismissableLayer.test.ts
index 63446ba..99e3523 100644
--- a/vue/primitives/src/dismissable-layer/__test__/DismissableLayer.test.ts
+++ b/vue/primitives/src/utilities/dismissable-layer/__test__/DismissableLayer.test.ts
@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { mount } from '@vue/test-utils';
-import { nextTick } from 'vue';
+import { defineComponent, h, nextTick } from 'vue';
 import DismissableLayer from '../DismissableLayer.vue';
+import DismissableLayerBranch from '../DismissableLayerBranch.vue';
 
 describe('DismissableLayer', () => {
   afterEach(() => {
@@ -215,4 +216,163 @@ describe('DismissableLayer', () => {
 
     bottom.unmount();
   });
+
+  describe('branches', () => {
+    function mountWithBranch(handlers: Record<string, unknown>) {
+      const Harness = defineComponent({
+        props: ['handlers'],
+        setup(props) {
+          return () =>
+            h('div', [
+              h(DismissableLayer, props.handlers, { default: () => h('button', 'inside') }),
+              h(DismissableLayerBranch, null, {
+                default: () => h('button', { 'data-testid': 'branch' }, 'related'),
+              }),
+            ]);
+        },
+      });
+      return mount(Harness, { attachTo: document.body, props: { handlers } });
+    }
+
+    it('does not dismiss on pointerdown inside a registered branch', async () => {
+      const onDismiss = vi.fn();
+      const w = mountWithBranch({ onDismiss });
+      await nextTick();
+      await nextTick();
+
+      const branchBtn = w.find('[data-testid=branch]').element as HTMLElement;
+      branchBtn.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, composed: true }));
+
+      expect(onDismiss).not.toHaveBeenCalled();
+      w.unmount();
+    });
+
+    it('does not dismiss on focusin inside a registered branch', async () => {
+      const onDismiss = vi.fn();
+      const onFocusOutside = vi.fn();
+      const w = mountWithBranch({ onDismiss, onFocusOutside });
+      await nextTick();
+      await nextTick();
+
+      const branchBtn = w.find('[data-testid=branch]').element as HTMLElement;
+      branchBtn.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+
+      expect(onFocusOutside).not.toHaveBeenCalled();
+      expect(onDismiss).not.toHaveBeenCalled();
+      w.unmount();
+    });
+
+    it('still dismisses on pointerdown outside both layer and branch', async () => {
+      const outside = document.createElement('button');
+      document.body.appendChild(outside);
+
+      const onDismiss = vi.fn();
+      const w = mountWithBranch({ onDismiss });
+      await nextTick();
+      await nextTick();
+
+      outside.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, composed: true }));
+
+      expect(onDismiss).toHaveBeenCalledTimes(1);
+      w.unmount();
+      outside.remove();
+    });
+
+    it('unregisters the branch on unmount so it no longer shields outside clicks', async () => {
+      const outside = document.createElement('button');
+      document.body.appendChild(outside);
+
+      const Harness = defineComponent({
+        components: { DismissableLayer, DismissableLayerBranch },
+        props: ['onDismiss', 'showBranch'],
+        setup(props) {
+          return () =>
+            h('div', [
+              h(DismissableLayer, { onDismiss: props.onDismiss }, { default: () => h('button', 'inside') }),
+              props.showBranch
+                ? h(DismissableLayerBranch, null, { default: () => h('button', { 'data-testid': 'branch' }, 'related') })
+                : null,
+            ]);
+        },
+      });
+
+      const onDismiss = vi.fn();
+      const w = mount(Harness, { attachTo: document.body, props: { onDismiss, showBranch: true } });
+      await nextTick();
+      await nextTick();
+
+      // Branch present: clicking it does not dismiss.
+      const branchBtn = w.find('[data-testid=branch]').element as HTMLElement;
+      branchBtn.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, composed: true }));
+      expect(onDismiss).not.toHaveBeenCalled();
+
+      // Remove the branch; a fresh outside pointerdown now dismisses.
+      await w.setProps({ showBranch: false });
+      await nextTick();
+      outside.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, composed: true }));
+      expect(onDismiss).toHaveBeenCalledTimes(1);
+
+      w.unmount();
+      outside.remove();
+    });
+  });
+
+  describe('per-layer pointer-events', () => {
+    it('does not set a pointer-events override when no layer disables outside events', async () => {
+      const w = mount(DismissableLayer, {
+        attachTo: document.body,
+        slots: { default: '<button>x</button>' },
+      });
+      await nextTick();
+
+      const el = w.find('[data-dismissable-layer]').element as HTMLElement;
+      expect(el.style.pointerEvents).toBe('');
+      w.unmount();
+    });
+
+    it('keeps the disabling layer interactive and makes a lower non-disabling layer inert', async () => {
+      const bottom = mount(DismissableLayer, {
+        attachTo: document.body,
+        slots: { default: '<button>bottom</button>' },
+      });
+      await nextTick();
+
+      const top = mount(DismissableLayer, {
+        attachTo: document.body,
+        props: { disableOutsidePointerEvents: true },
+        slots: { default: '<button>top</button>' },
+      });
+      await nextTick();
+      await nextTick();
+
+      const bottomEl = bottom.find('[data-dismissable-layer]').element as HTMLElement;
+      const topEl = top.find('[data-dismissable-layer]').element as HTMLElement;
+
+      // The blocking layer (top) stays clickable; the layer beneath it is sealed off.
+      expect(topEl.style.pointerEvents).toBe('auto');
+      expect(bottomEl.style.pointerEvents).toBe('none');
+
+      top.unmount();
+      await nextTick();
+
+      // Once the blocking layer is gone, the override is cleared everywhere.
+      expect(bottomEl.style.pointerEvents).toBe('');
+      bottom.unmount();
+    });
+  });
+
+  describe('DismissableLayerBranch', () => {
+    it('renders its slot through the polymorphic element and forwards as', async () => {
+      const w = mount(DismissableLayerBranch, {
+        attachTo: document.body,
+        props: { as: 'section' },
+        slots: { default: '<span data-testid="child">x</span>' },
+      });
+      await nextTick();
+
+      expect(w.element.tagName).toBe('SECTION');
+      expect(w.find('[data-testid=child]').exists()).toBe(true);
+      w.unmount();
+    });
+  });
 });
diff --git a/vue/primitives/src/dismissable-layer/index.ts b/vue/primitives/src/utilities/dismissable-layer/index.ts
similarity index 56%
rename from vue/primitives/src/dismissable-layer/index.ts
rename to vue/primitives/src/utilities/dismissable-layer/index.ts
index 9f61932..f079612 100644
--- a/vue/primitives/src/dismissable-layer/index.ts
+++ b/vue/primitives/src/utilities/dismissable-layer/index.ts
@@ -1,7 +1,12 @@
 export { default as DismissableLayer } from './DismissableLayer.vue';
+export { default as DismissableLayerBranch } from './DismissableLayerBranch.vue';
 export { dismissableLayerStack } from './stack';
 
 export type {
   DismissableLayerEmits,
   DismissableLayerProps,
 } from './DismissableLayer.vue';
+
+export type {
+  DismissableLayerBranchProps,
+} from './DismissableLayerBranch.vue';
diff --git a/vue/primitives/src/utilities/dismissable-layer/stack.ts b/vue/primitives/src/utilities/dismissable-layer/stack.ts
new file mode 100644
index 0000000..3bbd1a9
--- /dev/null
+++ b/vue/primitives/src/utilities/dismissable-layer/stack.ts
@@ -0,0 +1,121 @@
+import { shallowRef } from 'vue';
+
+export interface DismissableLayerElement {
+  el: HTMLElement;
+  disableOutsidePointerEvents: boolean;
+}
+
+const layers: DismissableLayerElement[] = [];
+
+// Subtrees that are physically rendered outside a layer's DOM node but belong to
+// it semantically (e.g. a portaled trigger, an anchor, a toast viewport). Pointer
+// and focus interactions originating inside a registered branch are treated as
+// *inside* — they must never dismiss the layer.
+const branches = new Set<HTMLElement>();
+
+/**
+ * Reactive revision counter. Bumped whenever the stack or branch set mutates so
+ * that `computed`s reading derived stack state (e.g. per-layer pointer-events)
+ * re-evaluate. The stack itself stays a plain array for cheap, allocation-free
+ * topmost/index lookups on hot paths.
+ */
+export const dismissableLayerVersion = shallowRef(0);
+
+function bump() {
+  dismissableLayerVersion.value++;
+}
+
+/**
+ * Module-level stack of active DismissableLayers. The most recently-pushed
+ * non-disabled layer is considered the topmost and is the only one that
+ * should dispatch dismiss-style events (escape, pointer-outside, focus-outside).
+ */
+export const dismissableLayerStack = {
+  push(layer: DismissableLayerElement) {
+    layers.push(layer);
+    bump();
+  },
+
+  remove(layer: DismissableLayerElement) {
+    const i = layers.indexOf(layer);
+    if (i !== -1) {
+      layers.splice(i, 1);
+      bump();
+    }
+  },
+
+  isTopmost(layer: DismissableLayerElement): boolean {
+    return layers.at(-1) === layer;
+  },
+
+  indexOf(layer: DismissableLayerElement): number {
+    return layers.indexOf(layer);
+  },
+
+  hasDisablingLayerAbove(layer: DismissableLayerElement): boolean {
+    const i = layers.indexOf(layer);
+    if (i === -1) return false;
+    return layers.slice(i + 1).some(l => l.disableOutsidePointerEvents);
+  },
+
+  any(): boolean {
+    return layers.length > 0;
+  },
+
+  anyDisabling(): boolean {
+    return layers.some(l => l.disableOutsidePointerEvents);
+  },
+
+  /** Notify derived `computed`s that stack-affecting layer state changed in place. */
+  touch() {
+    bump();
+  },
+
+  /**
+   * Resolves the `pointer-events` value a given layer should carry, mirroring the
+   * nested-modal contract: while any layer disables outside pointer events the
+   * document body is `pointer-events: none`. A layer at or above the highest
+   * disabling layer stays interactive (`auto`); a layer below it is made
+   * non-interactive (`none`). When nothing is blocking, no override is applied.
+   */
+  pointerEventsFor(layer: DismissableLayerElement): 'auto' | 'none' | undefined {
+    let highestDisablingIndex = -1;
+    for (let i = layers.length - 1; i >= 0; i--) {
+      if (layers[i]!.disableOutsidePointerEvents) {
+        highestDisablingIndex = i;
+        break;
+      }
+    }
+
+    if (highestDisablingIndex === -1) return undefined;
+
+    const index = layers.indexOf(layer);
+    return index >= highestDisablingIndex ? 'auto' : 'none';
+  },
+
+  // Branch registry -------------------------------------------------------
+
+  addBranch(el: HTMLElement) {
+    branches.add(el);
+    bump();
+  },
+
+  removeBranch(el: HTMLElement) {
+    branches.delete(el);
+    bump();
+  },
+
+  /** Live snapshot of registered branch elements (for outside-detection ignore lists). */
+  getBranches(): HTMLElement[] {
+    return Array.from(branches);
+  },
+
+  /** Whether `target` lives inside any registered branch subtree. */
+  isInBranch(target: Node | null): boolean {
+    if (!target) return false;
+    for (const branch of branches) {
+      if (branch === target || branch.contains(target)) return true;
+    }
+    return false;
+  },
+};
diff --git a/vue/primitives/src/focus-scope/FocusScope.vue b/vue/primitives/src/utilities/focus-scope/FocusScope.vue
similarity index 96%
rename from vue/primitives/src/focus-scope/FocusScope.vue
rename to vue/primitives/src/utilities/focus-scope/FocusScope.vue
index 49eac2d..80675a3 100644
--- a/vue/primitives/src/focus-scope/FocusScope.vue
+++ b/vue/primitives/src/utilities/focus-scope/FocusScope.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 export interface FocusScopeEmits {
   /** Автофокус при монтировании. Можно предотвратить через `event.preventDefault()`. */
@@ -37,7 +37,7 @@ export interface FocusScopeProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import type { FocusScopeAPI } from './stack';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { focus, getActiveElement, getTabbableEdges } from '@robonen/platform/browsers';
 import { useAutoFocus } from './useAutoFocus';
 import { useFocusTrap } from './useFocusTrap';
diff --git a/vue/primitives/src/focus-scope/__test__/FocusScope.test.ts b/vue/primitives/src/utilities/focus-scope/__test__/FocusScope.test.ts
similarity index 100%
rename from vue/primitives/src/focus-scope/__test__/FocusScope.test.ts
rename to vue/primitives/src/utilities/focus-scope/__test__/FocusScope.test.ts
diff --git a/vue/primitives/src/focus-scope/__test__/a11y.test.ts b/vue/primitives/src/utilities/focus-scope/__test__/a11y.test.ts
similarity index 100%
rename from vue/primitives/src/focus-scope/__test__/a11y.test.ts
rename to vue/primitives/src/utilities/focus-scope/__test__/a11y.test.ts
diff --git a/vue/primitives/src/focus-scope/index.ts b/vue/primitives/src/utilities/focus-scope/index.ts
similarity index 100%
rename from vue/primitives/src/focus-scope/index.ts
rename to vue/primitives/src/utilities/focus-scope/index.ts
diff --git a/vue/primitives/src/focus-scope/stack.ts b/vue/primitives/src/utilities/focus-scope/stack.ts
similarity index 100%
rename from vue/primitives/src/focus-scope/stack.ts
rename to vue/primitives/src/utilities/focus-scope/stack.ts
diff --git a/vue/primitives/src/focus-scope/useAutoFocus.ts b/vue/primitives/src/utilities/focus-scope/useAutoFocus.ts
similarity index 93%
rename from vue/primitives/src/focus-scope/useAutoFocus.ts
rename to vue/primitives/src/utilities/focus-scope/useAutoFocus.ts
index 780fdb5..f1d9aff 100644
--- a/vue/primitives/src/focus-scope/useAutoFocus.ts
+++ b/vue/primitives/src/utilities/focus-scope/useAutoFocus.ts
@@ -10,7 +10,7 @@ import {
 import type { FocusScopeAPI } from './stack';
 import type { Ref } from 'vue';
 import { createFocusScopesStack } from './stack';
-import { watchPostEffect } from 'vue';
+import { onWatcherCleanup, watchPostEffect } from 'vue';
 
 function dispatchCancelableEvent(
   container: HTMLElement,
@@ -32,7 +32,7 @@ export function useAutoFocus(
 ) {
   const stack = createFocusScopesStack();
 
-  watchPostEffect((onCleanup) => {
+  watchPostEffect(() => {
     const el = container.value;
     if (!el) return;
 
@@ -50,7 +50,7 @@ export function useAutoFocus(
       }
     }
 
-    onCleanup(() => {
+    onWatcherCleanup(() => {
       const event = dispatchCancelableEvent(el, AUTOFOCUS_ON_UNMOUNT, onUnmountAutoFocus);
 
       if (!event.defaultPrevented) {
diff --git a/vue/primitives/src/focus-scope/useFocusTrap.ts b/vue/primitives/src/utilities/focus-scope/useFocusTrap.ts
similarity index 92%
rename from vue/primitives/src/focus-scope/useFocusTrap.ts
rename to vue/primitives/src/utilities/focus-scope/useFocusTrap.ts
index cb81dd1..3aa4b1a 100644
--- a/vue/primitives/src/focus-scope/useFocusTrap.ts
+++ b/vue/primitives/src/utilities/focus-scope/useFocusTrap.ts
@@ -1,5 +1,5 @@
 import type { MaybeRefOrGetter, Ref } from 'vue';
-import { shallowRef, toValue, watchPostEffect } from 'vue';
+import { onWatcherCleanup, shallowRef, toValue, watchPostEffect } from 'vue';
 import type { FocusScopeAPI } from './stack';
 import { focus } from '@robonen/platform/browsers';
 
@@ -10,7 +10,7 @@ export function useFocusTrap(
 ) {
   const lastFocusedElement = shallowRef<HTMLElement | null>(null);
 
-  watchPostEffect((onCleanup) => {
+  watchPostEffect(() => {
     const el = container.value;
     if (!toValue(trapped) || !el) return;
 
@@ -51,7 +51,7 @@ export function useFocusTrap(
     const observer = new MutationObserver(handleMutations);
     observer.observe(el, { childList: true, subtree: true });
 
-    onCleanup(() => {
+    onWatcherCleanup(() => {
       document.removeEventListener('focusin', handleFocusIn);
       document.removeEventListener('focusout', handleFocusOut);
       observer.disconnect();
diff --git a/vue/primitives/src/presence/Presence.vue b/vue/primitives/src/utilities/presence/Presence.vue
similarity index 93%
rename from vue/primitives/src/presence/Presence.vue
rename to vue/primitives/src/utilities/presence/Presence.vue
index ee3e74c..3526e64 100644
--- a/vue/primitives/src/presence/Presence.vue
+++ b/vue/primitives/src/utilities/presence/Presence.vue
@@ -26,7 +26,7 @@ export default {
 </script>
 
 <script setup lang="ts">
-import { Slot } from '../primitive/Slot';
+import { Slot } from '../../internal/primitive/Slot';
 import { usePresence } from './usePresence';
 
 const {
@@ -35,7 +35,7 @@ const {
 } = defineProps<PresenceProps>();
 
 defineSlots<{
-  default?: (props: { present: boolean }) => any;
+  default?: (props: { present: boolean }) => unknown;
 }>();
 
 const { isPresent, setRef } = usePresence(() => present);
diff --git a/vue/primitives/src/presence/__test__/Presence.test.ts b/vue/primitives/src/utilities/presence/__test__/Presence.test.ts
similarity index 100%
rename from vue/primitives/src/presence/__test__/Presence.test.ts
rename to vue/primitives/src/utilities/presence/__test__/Presence.test.ts
diff --git a/vue/primitives/src/presence/index.ts b/vue/primitives/src/utilities/presence/index.ts
similarity index 100%
rename from vue/primitives/src/presence/index.ts
rename to vue/primitives/src/utilities/presence/index.ts
diff --git a/vue/primitives/src/presence/usePresence.ts b/vue/primitives/src/utilities/presence/usePresence.ts
similarity index 93%
rename from vue/primitives/src/presence/usePresence.ts
rename to vue/primitives/src/utilities/presence/usePresence.ts
index 674e132..b06caea 100644
--- a/vue/primitives/src/presence/usePresence.ts
+++ b/vue/primitives/src/utilities/presence/usePresence.ts
@@ -1,5 +1,5 @@
 import type { MaybeRefOrGetter, Ref } from 'vue';
-import { computed, readonly, shallowRef, toValue, watch } from 'vue';
+import { computed, onWatcherCleanup, readonly, shallowRef, toValue, watch } from 'vue';
 import {
   dispatchAnimationEvent,
   getAnimationName,
@@ -48,7 +48,7 @@ export function usePresence(
     }
   }, { flush: 'sync' });
 
-  watch(node, (el, _oldEl, onCleanup) => {
+  watch(node, (el) => {
     if (el) {
       const cleanup = onAnimationSettle(el, {
         onSettle: () => {
@@ -61,7 +61,7 @@ export function usePresence(
         },
       });
 
-      onCleanup(cleanup);
+      onWatcherCleanup(cleanup);
     }
     else {
       isAnimating.value = false;
diff --git a/vue/primitives/src/roving-focus/RovingFocusGroup.vue b/vue/primitives/src/utilities/roving-focus/RovingFocusGroup.vue
similarity index 72%
rename from vue/primitives/src/roving-focus/RovingFocusGroup.vue
rename to vue/primitives/src/utilities/roving-focus/RovingFocusGroup.vue
index b68ab46..8f6df2a 100644
--- a/vue/primitives/src/roving-focus/RovingFocusGroup.vue
+++ b/vue/primitives/src/utilities/roving-focus/RovingFocusGroup.vue
@@ -1,7 +1,7 @@
 <script lang="ts">
 import type { Direction } from '../config-provider';
 import type { Orientation } from './utils';
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 import type { Ref } from 'vue';
 import { useContextFactory } from '@robonen/vue';
 
@@ -25,7 +25,10 @@ export interface RovingFocusGroupProps extends PrimitiveProps {
    * @default false
    */
   loop?: boolean;
-  /** Controlled current tab-stop id. */
+  /**
+   * Controlled current tab-stop id — bind with `v-model:currentTabStopId`.
+   * Registered automatically by the model macro; emits `update:currentTabStopId`.
+   */
   currentTabStopId?: string | null;
   /** Initial current tab-stop id (uncontrolled). */
   defaultCurrentTabStopId?: string;
@@ -38,6 +41,8 @@ export interface RovingFocusGroupProps extends PrimitiveProps {
 
 export interface RovingFocusGroupEmits {
   entryFocus: [event: Event];
+  /** Emitted whenever the current tab stop changes — backs `v-model:currentTabStopId`. */
+  'update:currentTabStopId': [value: string | null | undefined];
 }
 
 export interface RovingFocusGroupContext {
@@ -59,7 +64,7 @@ export const RovingFocusGroupCtx = useContextFactory<RovingFocusGroupContext>(
 <script setup lang="ts">
 import { ENTRY_FOCUS, EVENT_OPTIONS, focusFirst } from './utils';
 import { ref, toRef } from 'vue';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useCollectionProvider } from '../collection';
 import { useConfig } from '../config-provider';
 
@@ -67,7 +72,6 @@ const {
   orientation,
   dir,
   loop = false,
-  currentTabStopId: currentTabStopIdProp,
   defaultCurrentTabStopId,
   preventScrollOnEntryFocus = false,
   as = 'div',
@@ -81,9 +85,23 @@ const dirRef = toRef(() => dir ?? config.dir.value);
 const orientationRef = toRef(() => orientation);
 const loopRef = toRef(() => loop);
 
-const currentTabStopId = ref<string | null | undefined>(
-  currentTabStopIdProp ?? defaultCurrentTabStopId,
-);
+// Uncontrolled backing state, seeded from `defaultCurrentTabStopId`.
+const localTabStopId = ref<string | null | undefined>(defaultCurrentTabStopId);
+
+// `currentTabStopId` is a real `v-model`: when the parent binds it (controlled)
+// the external value is the source of truth and the model emits
+// `update:currentTabStopId`; when unbound, the local ref drives the component.
+// The model const shares the declared prop name on purpose (controlled/uncontrolled
+// merge happens inside get/set), hence the dupe-keys exception.
+// eslint-disable-next-line vue/no-dupe-keys
+const currentTabStopId = defineModel<string | null | undefined>('currentTabStopId', {
+  default: undefined,
+  get: external => external ?? localTabStopId.value,
+  set: (value) => {
+    localTabStopId.value = value;
+    return value;
+  },
+});
 
 const isTabbingBackOut = ref(false);
 const isClickFocus = ref(false);
@@ -109,8 +127,14 @@ function handleFocus(event: FocusEvent): void {
         .map(i => i.ref)
         .filter(i => i.dataset['disabled'] !== '');
       const activeItem = items.find(item => item.getAttribute('data-active') === '');
+      // Items rendered by listbox / combobox / menu mark the keyboard-highlighted
+      // option with `data-highlighted`; prioritise it on entry so focus lands on
+      // what the user was last navigating, ahead of the generic current tab stop.
+      const highlightedItem = items.find(
+        item => item.getAttribute('data-highlighted') === '',
+      );
       const currentItem = items.find(item => item.id === currentTabStopId.value);
-      const candidateItems = [activeItem, currentItem, ...items].filter(
+      const candidateItems = [activeItem, highlightedItem, currentItem, ...items].filter(
         Boolean,
       ) as HTMLElement[];
       focusFirst(candidateItems, preventScrollOnEntryFocus);
@@ -125,7 +149,7 @@ function handleMouseUp(): void {
   }, 1);
 }
 
-defineExpose({ getItems });
+defineExpose({ getItems, currentTabStopId });
 
 RovingFocusGroupCtx.provide({
   loop: loopRef,
diff --git a/vue/primitives/src/roving-focus/RovingFocusItem.vue b/vue/primitives/src/utilities/roving-focus/RovingFocusItem.vue
similarity index 96%
rename from vue/primitives/src/roving-focus/RovingFocusItem.vue
rename to vue/primitives/src/utilities/roving-focus/RovingFocusItem.vue
index 72ba621..bcc8053 100644
--- a/vue/primitives/src/roving-focus/RovingFocusItem.vue
+++ b/vue/primitives/src/utilities/roving-focus/RovingFocusItem.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * A single focusable item within a `RovingFocusGroup`. It registers itself with
@@ -29,7 +29,7 @@ export interface RovingFocusItemProps extends PrimitiveProps {
 <script setup lang="ts">
 import { computed, nextTick, onMounted, onUnmounted } from 'vue';
 import { focusFirst, getFocusIntent, wrapArray } from './utils';
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { RovingFocusGroupCtx } from './RovingFocusGroup.vue';
 import { useCollectionInjector } from '../collection';
 import { useId } from '../config-provider';
diff --git a/vue/primitives/src/utilities/roving-focus/__test__/RovingFocus.test.ts b/vue/primitives/src/utilities/roving-focus/__test__/RovingFocus.test.ts
new file mode 100644
index 0000000..85f841a
--- /dev/null
+++ b/vue/primitives/src/utilities/roving-focus/__test__/RovingFocus.test.ts
@@ -0,0 +1,380 @@
+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 } from 'vue';
+
+import RovingFocusGroup from '../RovingFocusGroup.vue';
+import RovingFocusItem from '../RovingFocusItem.vue';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+interface ItemSpec {
+  id: string;
+  disabled?: boolean;
+  active?: boolean;
+  highlighted?: boolean;
+}
+
+function renderItem(spec: ItemSpec) {
+  return h(
+    RovingFocusItem,
+    {
+      as: 'button',
+      tabStopId: spec.id,
+      id: spec.id,
+      focusable: !spec.disabled,
+      active: spec.active,
+      'data-highlighted': spec.highlighted ? '' : undefined,
+    },
+    { default: () => spec.id },
+  );
+}
+
+function makeGroup(
+  items: ItemSpec[],
+  groupProps: Record<string, unknown> = {},
+) {
+  return defineComponent({
+    setup() {
+      return () =>
+        h(
+          RovingFocusGroup,
+          { ...groupProps },
+          { default: () => items.map(renderItem) },
+        );
+    },
+  });
+}
+
+function press(el: Element, key: string, init: KeyboardEventInit = {}) {
+  el.dispatchEvent(
+    new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init }),
+  );
+}
+
+const ITEMS: ItemSpec[] = [
+  { id: 'one' },
+  { id: 'two' },
+  { id: 'three', disabled: true },
+  { id: 'four' },
+];
+
+describe('rovingFocus — ARIA / tab-order skeleton', () => {
+  it('keeps a single tab stop: current item tabindex=0, the rest -1', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'one' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    expect(buttons[0]!.attributes('tabindex')).toBe('0');
+    expect(buttons[1]!.attributes('tabindex')).toBe('-1');
+    expect(buttons[3]!.attributes('tabindex')).toBe('-1');
+  });
+
+  it('marks active items with data-active and disabled with data-disabled', async () => {
+    const wrapper = track(
+      mount(
+        makeGroup([
+          { id: 'one', active: true },
+          { id: 'two', disabled: true },
+        ]),
+        { attachTo: document.body },
+      ),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    expect(buttons[0]!.attributes('data-active')).toBe('');
+    expect(buttons[1]!.attributes('data-active')).toBeUndefined();
+    expect(buttons[1]!.attributes('data-disabled')).toBe('');
+  });
+
+  it('reflects orientation onto the group container', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { orientation: 'vertical' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    expect(wrapper.find('[data-orientation="vertical"]').exists()).toBe(true);
+  });
+});
+
+describe('rovingFocus — uncontrolled (defaultCurrentTabStopId)', () => {
+  it('seeds the current tab stop from defaultCurrentTabStopId', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'two' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    expect(buttons[1]!.attributes('tabindex')).toBe('0');
+    expect(buttons[0]!.attributes('tabindex')).toBe('-1');
+  });
+
+  it('updates the current tab stop on item focus without external binding', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'one' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[1]!.element.dispatchEvent(new FocusEvent('focus', { bubbles: false }));
+    await nextTick();
+    expect(buttons[1]!.attributes('tabindex')).toBe('0');
+    expect(buttons[0]!.attributes('tabindex')).toBe('-1');
+  });
+});
+
+describe('rovingFocus — controlled (v-model:currentTabStopId)', () => {
+  it('respects an externally controlled currentTabStopId prop and re-syncs on change', async () => {
+    const wrapper = track(
+      mount(RovingFocusGroup, {
+        attachTo: document.body,
+        props: { currentTabStopId: 'four' },
+        slots: { default: () => ITEMS.map(renderItem) },
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    expect(buttons[3]!.attributes('tabindex')).toBe('0');
+
+    // Pushing a new controlled value re-syncs the tab stop (no internal-state race).
+    await wrapper.setProps({ currentTabStopId: 'one' });
+    await nextTick();
+    expect(buttons[0]!.attributes('tabindex')).toBe('0');
+    expect(buttons[3]!.attributes('tabindex')).toBe('-1');
+  });
+
+  it('emits update:currentTabStopId when an item gains focus', async () => {
+    const onUpdate = vi.fn();
+    const wrapper = track(
+      mount(RovingFocusGroup, {
+        attachTo: document.body,
+        props: {
+          currentTabStopId: 'one',
+          'onUpdate:currentTabStopId': onUpdate,
+        },
+        slots: { default: () => ITEMS.map(renderItem) },
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[1]!.element.dispatchEvent(new FocusEvent('focus', { bubbles: false }));
+    await nextTick();
+    expect(onUpdate).toHaveBeenCalledWith('two');
+  });
+});
+
+describe('rovingFocus — keyboard navigation', () => {
+  it('[loop=false] moves to next, skips disabled, and stops at the last item', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'two' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[1]!.element.focus();
+
+    press(buttons[1]!.element, 'ArrowRight');
+    await nextTick();
+    // index 2 is disabled, so focus lands on index 3
+    expect(document.activeElement).toBe(buttons[3]!.element);
+
+    press(buttons[3]!.element, 'ArrowRight');
+    await nextTick();
+    // loop=false: stay at the last item
+    expect(document.activeElement).toBe(buttons[3]!.element);
+  });
+
+  it('[loop=true] wraps around past the last item, skipping disabled', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'two', loop: true }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[1]!.element.focus();
+
+    press(buttons[1]!.element, 'ArrowRight');
+    await nextTick();
+    expect(document.activeElement).toBe(buttons[3]!.element);
+
+    press(buttons[3]!.element, 'ArrowRight');
+    await nextTick();
+    // wraps to first enabled item
+    expect(document.activeElement).toBe(buttons[0]!.element);
+  });
+
+  it('Home / End jump to first and last enabled items', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'two' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[1]!.element.focus();
+
+    press(buttons[1]!.element, 'End');
+    await nextTick();
+    expect(document.activeElement).toBe(buttons[3]!.element);
+
+    press(buttons[3]!.element, 'Home');
+    await nextTick();
+    expect(document.activeElement).toBe(buttons[0]!.element);
+  });
+
+  it('does not navigate on the orientation-incompatible arrow key', async () => {
+    const wrapper = track(
+      mount(
+        makeGroup(ITEMS, { orientation: 'horizontal', defaultCurrentTabStopId: 'one' }),
+        { attachTo: document.body },
+      ),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[0]!.element.focus();
+
+    press(buttons[0]!.element, 'ArrowDown');
+    await nextTick();
+    // vertical arrow ignored in horizontal orientation
+    expect(document.activeElement).toBe(buttons[0]!.element);
+  });
+
+  it('respects RTL by swapping ArrowLeft / ArrowRight', async () => {
+    const wrapper = track(
+      mount(
+        makeGroup(ITEMS, {
+          orientation: 'horizontal',
+          dir: 'rtl',
+          defaultCurrentTabStopId: 'two',
+        }),
+        { attachTo: document.body },
+      ),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[1]!.element.focus();
+
+    // In RTL, ArrowLeft means "next"
+    press(buttons[1]!.element, 'ArrowLeft');
+    await nextTick();
+    expect(document.activeElement).toBe(buttons[3]!.element);
+  });
+
+  it('ignores arrow navigation when a modifier (ctrl) is held', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'one' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    buttons[0]!.element.focus();
+
+    press(buttons[0]!.element, 'ArrowRight', { ctrlKey: true });
+    await nextTick();
+    expect(document.activeElement).toBe(buttons[0]!.element);
+  });
+});
+
+describe('rovingFocus — disabled items', () => {
+  it('does not register a non-focusable item as a tab-order participant', async () => {
+    const wrapper = track(
+      mount(
+        makeGroup([
+          { id: 'one', disabled: true },
+          { id: 'two' },
+        ]),
+        { attachTo: document.body },
+      ),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    // disabled item carries data-disabled and is never the navigation target
+    expect(buttons[0]!.attributes('data-disabled')).toBe('');
+    buttons[1]!.element.focus();
+    press(buttons[1]!.element, 'Home');
+    await nextTick();
+    expect(document.activeElement).toBe(buttons[1]!.element);
+  });
+});
+
+describe('rovingFocus — entry focus priority', () => {
+  it('prioritises the highlighted item over the current tab stop on entry', async () => {
+    const wrapper = track(
+      mount(
+        makeGroup(
+          [
+            { id: 'one' },
+            { id: 'two', highlighted: true },
+            { id: 'four' },
+          ],
+          { defaultCurrentTabStopId: 'one' },
+        ),
+        { attachTo: document.body },
+      ),
+    );
+    await nextTick();
+    const groupEl = wrapper.find('button')!.element.closest('[style]') as HTMLElement;
+    // Dispatch a keyboard-driven focus onto the group container.
+    groupEl.dispatchEvent(new FocusEvent('focus', { bubbles: false }));
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    // highlighted item ('two') wins entry focus over current tab stop ('one')
+    expect(document.activeElement).toBe(buttons[1]!.element);
+  });
+
+  it('falls back to the active item when nothing is highlighted', async () => {
+    const wrapper = track(
+      mount(
+        makeGroup([
+          { id: 'one' },
+          { id: 'two', active: true },
+          { id: 'four' },
+        ]),
+        { attachTo: document.body },
+      ),
+    );
+    await nextTick();
+    const groupEl = wrapper.find('button')!.element.closest('[style]') as HTMLElement;
+    groupEl.dispatchEvent(new FocusEvent('focus', { bubbles: false }));
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    expect(document.activeElement).toBe(buttons[1]!.element);
+  });
+});
+
+describe('rovingFocus — Tab back out', () => {
+  it('marks the group tabindex=-1 after Shift+Tab from an item', async () => {
+    const wrapper = track(
+      mount(makeGroup(ITEMS, { defaultCurrentTabStopId: 'one' }), {
+        attachTo: document.body,
+      }),
+    );
+    await nextTick();
+    const buttons = wrapper.findAll('button');
+    const groupEl = buttons[0]!.element.closest('[style]') as HTMLElement;
+    expect(groupEl.getAttribute('tabindex')).toBe('0');
+
+    press(buttons[0]!.element, 'Tab', { shiftKey: true });
+    await nextTick();
+    expect(groupEl.getAttribute('tabindex')).toBe('-1');
+  });
+});
diff --git a/vue/primitives/src/roving-focus/index.ts b/vue/primitives/src/utilities/roving-focus/index.ts
similarity index 100%
rename from vue/primitives/src/roving-focus/index.ts
rename to vue/primitives/src/utilities/roving-focus/index.ts
diff --git a/vue/primitives/src/roving-focus/utils.ts b/vue/primitives/src/utilities/roving-focus/utils.ts
similarity index 100%
rename from vue/primitives/src/roving-focus/utils.ts
rename to vue/primitives/src/utilities/roving-focus/utils.ts
diff --git a/vue/primitives/src/teleport/Teleport.vue b/vue/primitives/src/utilities/teleport/Teleport.vue
similarity index 100%
rename from vue/primitives/src/teleport/Teleport.vue
rename to vue/primitives/src/utilities/teleport/Teleport.vue
diff --git a/vue/primitives/src/utilities/teleport/__test__/Teleport.test.ts b/vue/primitives/src/utilities/teleport/__test__/Teleport.test.ts
new file mode 100644
index 0000000..0a7039b
--- /dev/null
+++ b/vue/primitives/src/utilities/teleport/__test__/Teleport.test.ts
@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { defineComponent, h, nextTick } from 'vue';
+import Teleport from '../Teleport.vue';
+
+describe('Teleport primitive', () => {
+  let host: HTMLElement;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    host.id = 'teleport-target';
+    document.body.appendChild(host);
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it('teleports default slot content to `to` target', async () => {
+    const w = mount(Teleport, {
+      props: { to: '#teleport-target' },
+      slots: { default: () => h('span', { 'data-testid': 'child' }, 'hello') },
+      attachTo: document.body,
+    });
+
+    await nextTick();
+    expect(host.querySelector('[data-testid=child]')?.textContent).toBe('hello');
+    w.unmount();
+  });
+
+  it('accepts an HTMLElement as `to`', async () => {
+    const w = mount(Teleport, {
+      props: { to: host },
+      slots: { default: () => h('span', { 'data-testid': 'child' }, 'x') },
+      attachTo: document.body,
+    });
+
+    await nextTick();
+    expect(host.querySelector('[data-testid=child]')).toBeTruthy();
+    w.unmount();
+  });
+
+  it('renders children in place when disabled', async () => {
+    const Parent = defineComponent({
+      render() {
+        return h('div', { id: 'parent' }, [
+          h(Teleport, { to: '#teleport-target', disabled: true }, {
+            default: () => h('span', { 'data-testid': 'child' }, 'inline'),
+          }),
+        ]);
+      },
+    });
+
+    const w = mount(Parent, { attachTo: document.body });
+    await nextTick();
+
+    expect(document.querySelector('#parent [data-testid=child]')).toBeTruthy();
+    expect(host.querySelector('[data-testid=child]')).toBeFalsy();
+
+    w.unmount();
+  });
+
+  it('defaults to body when `to` is omitted', async () => {
+    const w = mount(Teleport, {
+      slots: { default: () => h('span', { 'data-testid': 'body-child' }, 'hi') },
+      attachTo: document.body,
+    });
+
+    await nextTick();
+    expect(document.body.querySelector('[data-testid=body-child]')).toBeTruthy();
+    w.unmount();
+  });
+
+  it('teleports content to the target on the client mount tick', async () => {
+    // Once mounted, content must end up inside the target rather than in place,
+    // proving the reactive mounted gating flips `effectiveDisabled` to false.
+    const w = mount(Teleport, {
+      props: { to: '#teleport-target' },
+      slots: { default: () => h('span', { 'data-testid': 'mounted-child' }, 'm') },
+      attachTo: document.body,
+    });
+
+    await nextTick();
+    expect(host.querySelector('[data-testid=mounted-child]')).toBeTruthy();
+    w.unmount();
+  });
+
+  it('reacts to a changing `to` target', async () => {
+    const second = document.createElement('div');
+    second.id = 'teleport-target-2';
+    document.body.appendChild(second);
+
+    const w = mount(Teleport, {
+      props: { to: '#teleport-target' },
+      slots: { default: () => h('span', { 'data-testid': 'movable' }, 'mv') },
+      attachTo: document.body,
+    });
+
+    await nextTick();
+    expect(host.querySelector('[data-testid=movable]')).toBeTruthy();
+    expect(second.querySelector('[data-testid=movable]')).toBeFalsy();
+
+    await w.setProps({ to: '#teleport-target-2' });
+    await nextTick();
+
+    expect(host.querySelector('[data-testid=movable]')).toBeFalsy();
+    expect(second.querySelector('[data-testid=movable]')).toBeTruthy();
+
+    w.unmount();
+    second.remove();
+  });
+
+  it('renders the Teleport node when forceMount is true (default)', async () => {
+    // With forceMount the node always renders; teleporting still occurs once
+    // mounted because `disabled` alone gates inline-vs-teleported.
+    const w = mount(Teleport, {
+      props: { to: '#teleport-target', forceMount: true },
+      slots: { default: () => h('span', { 'data-testid': 'forced' }, 'f') },
+      attachTo: document.body,
+    });
+
+    await nextTick();
+    expect(host.querySelector('[data-testid=forced]')).toBeTruthy();
+    w.unmount();
+  });
+
+  it('teleports after mount even with forceMount disabled', async () => {
+    // forceMount=false only changes pre-mount rendering; after the mount tick
+    // content must still teleport to the target.
+    const w = mount(Teleport, {
+      props: { to: '#teleport-target', forceMount: false },
+      slots: { default: () => h('span', { 'data-testid': 'gated' }, 'g') },
+      attachTo: document.body,
+    });
+
+    await nextTick();
+    expect(host.querySelector('[data-testid=gated]')).toBeTruthy();
+    w.unmount();
+  });
+
+  it('keeps children inline when disabled regardless of mount state', async () => {
+    const Parent = defineComponent({
+      render() {
+        return h('div', { id: 'parent-disabled' }, [
+          h(Teleport, { to: '#teleport-target', disabled: true, forceMount: true }, {
+            default: () => h('span', { 'data-testid': 'still-inline' }, 'i'),
+          }),
+        ]);
+      },
+    });
+
+    const w = mount(Parent, { attachTo: document.body });
+    await nextTick();
+
+    expect(document.querySelector('#parent-disabled [data-testid=still-inline]')).toBeTruthy();
+    expect(host.querySelector('[data-testid=still-inline]')).toBeFalsy();
+
+    w.unmount();
+  });
+});
diff --git a/vue/primitives/src/teleport/index.ts b/vue/primitives/src/utilities/teleport/index.ts
similarity index 100%
rename from vue/primitives/src/teleport/index.ts
rename to vue/primitives/src/utilities/teleport/index.ts
diff --git a/vue/primitives/src/visually-hidden/VisuallyHidden.vue b/vue/primitives/src/utilities/visually-hidden/VisuallyHidden.vue
similarity index 93%
rename from vue/primitives/src/visually-hidden/VisuallyHidden.vue
rename to vue/primitives/src/utilities/visually-hidden/VisuallyHidden.vue
index b83f03f..18c114b 100644
--- a/vue/primitives/src/visually-hidden/VisuallyHidden.vue
+++ b/vue/primitives/src/utilities/visually-hidden/VisuallyHidden.vue
@@ -1,5 +1,5 @@
 <script lang="ts">
-import type { PrimitiveProps } from '../primitive';
+import type { PrimitiveProps } from '../../internal/primitive';
 
 /**
  * Visually hides its content while keeping it available to assistive
@@ -21,7 +21,7 @@ export interface VisuallyHiddenProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '../primitive';
+import { Primitive } from '../../internal/primitive';
 import { useForwardExpose } from '@robonen/vue';
 
 const { as = 'span', feature = 'focusable' } = defineProps<VisuallyHiddenProps>();
diff --git a/vue/primitives/src/utilities/visually-hidden/VisuallyHiddenInput.vue b/vue/primitives/src/utilities/visually-hidden/VisuallyHiddenInput.vue
new file mode 100644
index 0000000..9092c63
--- /dev/null
+++ b/vue/primitives/src/utilities/visually-hidden/VisuallyHiddenInput.vue
@@ -0,0 +1,95 @@
+<script lang="ts">
+import type { VisuallyHiddenInputBubbleProps } from './VisuallyHiddenInputBubble.vue';
+
+/**
+ * Bridges a custom control's value into native form submission. It serializes
+ * the bound `value` into one visually-hidden native `<input>` per leaf so the
+ * data is submitted with the owning `<form>` and participates in native
+ * constraint validation:
+ *
+ * - primitives (`string | number | boolean | null | undefined`) → a single
+ *   input named `name`;
+ * - arrays of primitives → `name[index]`;
+ * - arrays of objects → `name[index][key]`;
+ * - plain objects → `name[key]`.
+ *
+ * A `required` field bound to an empty array still renders one input, so native
+ * `required` validation fires on empty multi-selects.
+ */
+export interface VisuallyHiddenInputProps<T = unknown> extends Omit<VisuallyHiddenInputBubbleProps<T>, 'value'> {
+  /** The value to serialize and submit. */
+  value: T;
+}
+</script>
+
+<script setup lang="ts" generic="T = unknown">
+import { computed } from 'vue';
+import { isArray, isObject } from '@vue/shared';
+import VisuallyHiddenInputBubble from './VisuallyHiddenInputBubble.vue';
+
+const props = withDefaults(defineProps<VisuallyHiddenInputProps<T>>(), {
+  feature: 'hidden',
+  checked: undefined,
+});
+
+defineOptions({ inheritAttrs: false });
+
+// Keep a single input for a `required` empty multi-select so the browser's
+// native validation still blocks submission.
+const requiresEmptyArrayInput = computed(() =>
+  isArray(props.value) && props.value.length === 0 && props.required);
+
+interface SerializedLeaf {
+  name: string;
+  value: unknown;
+}
+
+const leaves = computed<SerializedLeaf[]>(() => {
+  const value = props.value;
+  const name = props.name;
+
+  // Primitive (or nullish) value → one input.
+  if (!isObject(value))
+    return [{ name, value }];
+
+  // Array value → `name[index]` for primitives, `name[index][key]` for objects.
+  if (isArray(value)) {
+    return value.flatMap((item, index) => {
+      if (isObject(item) && !isArray(item))
+        return Object.entries(item).map(([key, v]) => ({ name: `${name}[${index}][${key}]`, value: v }));
+
+      return { name: `${name}[${index}]`, value: item };
+    });
+  }
+
+  // Plain object value → `name[key]`.
+  return Object.entries(value).map(([key, v]) => ({ name: `${name}[${key}]`, value: v }));
+});
+</script>
+
+<template>
+  <VisuallyHiddenInputBubble
+    v-if="requiresEmptyArrayInput"
+    :key="name"
+    v-bind="$attrs"
+    :name="name"
+    :value="value"
+    :checked="checked"
+    :required="required"
+    :disabled="disabled"
+    :feature="feature"
+  />
+
+  <VisuallyHiddenInputBubble
+    v-for="leaf in leaves"
+    v-else
+    :key="leaf.name"
+    v-bind="$attrs"
+    :name="leaf.name"
+    :value="leaf.value"
+    :checked="checked"
+    :required="required"
+    :disabled="disabled"
+    :feature="feature"
+  />
+</template>
diff --git a/vue/primitives/src/utilities/visually-hidden/VisuallyHiddenInputBubble.vue b/vue/primitives/src/utilities/visually-hidden/VisuallyHiddenInputBubble.vue
new file mode 100644
index 0000000..35a8558
--- /dev/null
+++ b/vue/primitives/src/utilities/visually-hidden/VisuallyHiddenInputBubble.vue
@@ -0,0 +1,115 @@
+<script lang="ts">
+import type { VisuallyHiddenProps } from './VisuallyHidden.vue';
+
+/**
+ * A single native, visually-hidden `<input>` that mirrors a custom control's
+ * value into native form submission. It keeps the input out of the visual
+ * layout (and the accessibility tree) while staying part of the owning
+ * `<form>`, so the value is submitted and native constraint validation
+ * (`required`) still fires.
+ *
+ * When `value`/`checked` change programmatically, it writes through the native
+ * `HTMLInputElement` property setter and dispatches bubbling `input` and
+ * `change` events, so third-party form libraries and listeners observe the
+ * change exactly as they would for direct user input.
+ */
+// Module-scope cache for the native `value`/`checked` property setters.
+// Resolving `Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, ...)`
+// is constant for the whole page lifetime, so we resolve once (lazily, behind
+// the caller's `window` guard for SSR-safety) and reuse a stable monomorphic
+// setter reference for every programmatic value/checked change.
+type InputSetter = (this: HTMLInputElement, v: unknown) => void;
+let valueSetter: InputSetter | undefined;
+let checkedSetter: InputSetter | undefined;
+let nativeSettersResolved = false;
+
+function resolveNativeSetters(): void {
+  if (nativeSettersResolved) return;
+  nativeSettersResolved = true;
+  const proto = globalThis.HTMLInputElement.prototype;
+  valueSetter = Object.getOwnPropertyDescriptor(proto, 'value')?.set as InputSetter | undefined;
+  checkedSetter = Object.getOwnPropertyDescriptor(proto, 'checked')?.set as InputSetter | undefined;
+}
+
+export interface VisuallyHiddenInputBubbleProps<T = unknown> {
+  /** Name submitted with the owning form. */
+  name: string;
+  /** Value submitted with the owning form. */
+  value: T;
+  /**
+   * Checked state for checkbox/radio-style submission. When provided it is the
+   * source of truth driven through the native `checked` setter; otherwise
+   * `value` is driven through the native `value` setter.
+   */
+  checked?: boolean;
+  /** Mirror the `required` constraint so native validation fires. */
+  required?: boolean;
+  /** Mirror the `disabled` state so the field is excluded from submission. */
+  disabled?: boolean;
+  /**
+   * Visual-hiding strategy passed through to `VisuallyHidden`.
+   * @default 'hidden'
+   */
+  feature?: VisuallyHiddenProps['feature'];
+}
+</script>
+
+<script setup lang="ts" generic="T = unknown">
+import { computed, watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import VisuallyHidden from './VisuallyHidden.vue';
+
+const props = withDefaults(defineProps<VisuallyHiddenInputBubbleProps<T>>(), {
+  feature: 'hidden',
+  checked: undefined,
+});
+
+defineOptions({ inheritAttrs: false });
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// `checked` (when provided) drives a checkbox-style input via the native
+// `checked` setter; otherwise `value` drives a text-style input via `value`.
+const isCheckbox = computed(() => props.checked !== undefined);
+
+// Single reactive source describing what the native input should reflect.
+const driven = computed(() => (isCheckbox.value ? props.checked : props.value));
+
+watch(
+  driven,
+  (next, prev) => syncNativeInput(next, prev),
+  { flush: 'post' },
+);
+
+function syncNativeInput(next: unknown, prev: unknown): void {
+  if (next === prev) return;
+
+  const input = currentElement.value as HTMLInputElement | undefined;
+  if (!input || globalThis.window === undefined) return;
+
+  // Write through the native property setter so frameworks that monkey-patch
+  // the input's value/checked tracker (e.g. synthetic event systems) observe
+  // the programmatic change, then emit the events a real edit would produce.
+  resolveNativeSetters();
+  const setter = isCheckbox.value ? checkedSetter : valueSetter;
+  setter?.call(input, next);
+
+  input.dispatchEvent(new Event('input', { bubbles: true }));
+  input.dispatchEvent(new Event('change', { bubbles: true }));
+}
+</script>
+
+<template>
+  <VisuallyHidden
+    :ref="forwardRef"
+    as="input"
+    :type="isCheckbox ? 'checkbox' : 'text'"
+    :name="name"
+    :value="value"
+    :checked="checked"
+    :required="required"
+    :disabled="disabled"
+    :feature="feature"
+    v-bind="$attrs"
+  />
+</template>
diff --git a/vue/primitives/src/visually-hidden/__test__/VisuallyHidden.test.ts b/vue/primitives/src/utilities/visually-hidden/__test__/VisuallyHidden.test.ts
similarity index 100%
rename from vue/primitives/src/visually-hidden/__test__/VisuallyHidden.test.ts
rename to vue/primitives/src/utilities/visually-hidden/__test__/VisuallyHidden.test.ts
diff --git a/vue/primitives/src/utilities/visually-hidden/__test__/VisuallyHiddenInput.test.ts b/vue/primitives/src/utilities/visually-hidden/__test__/VisuallyHiddenInput.test.ts
new file mode 100644
index 0000000..56544d5
--- /dev/null
+++ b/vue/primitives/src/utilities/visually-hidden/__test__/VisuallyHiddenInput.test.ts
@@ -0,0 +1,226 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { nextTick } from 'vue';
+import VisuallyHiddenInput from '../VisuallyHiddenInput.vue';
+import VisuallyHiddenInputBubble from '../VisuallyHiddenInputBubble.vue';
+
+function inputs(el: Element): HTMLInputElement[] {
+  return Array.from(el.querySelectorAll('input')) as HTMLInputElement[];
+}
+
+describe('VisuallyHiddenInput', () => {
+  let wrapper: ReturnType<typeof mount> | undefined;
+
+  afterEach(() => {
+    wrapper?.unmount();
+    wrapper = undefined;
+  });
+
+  it('renders a single hidden input for a primitive value', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'color', value: 'red' },
+    });
+
+    const all = inputs(wrapper.element.parentElement!);
+    expect(all).toHaveLength(1);
+    expect(all[0]!.name).toBe('color');
+    expect(all[0]!.value).toBe('red');
+  });
+
+  it('hides the input from layout and the accessibility tree by default', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'color', value: 'red' },
+    });
+
+    const input = inputs(wrapper.element.parentElement!)[0]!;
+    expect(input.style.position).toBe('absolute');
+    expect(input.getAttribute('aria-hidden')).toBe('true');
+    expect(input.getAttribute('tabindex')).toBe('-1');
+    expect(input.getAttribute('data-visually-hidden')).toBe('hidden');
+  });
+
+  it('serializes an array of primitives to name[index]', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'tags', value: ['a', 'b', 'c'] },
+    });
+
+    const all = inputs(wrapper.element.parentElement!);
+    expect(all.map(i => i.name)).toEqual(['tags[0]', 'tags[1]', 'tags[2]']);
+    expect(all.map(i => i.value)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('serializes an array of objects to name[index][key]', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'items', value: [{ id: 1, label: 'x' }, { id: 2, label: 'y' }] },
+    });
+
+    const all = inputs(wrapper.element.parentElement!);
+    expect(all.map(i => i.name)).toEqual([
+      'items[0][id]',
+      'items[0][label]',
+      'items[1][id]',
+      'items[1][label]',
+    ]);
+    expect(all.map(i => i.value)).toEqual(['1', 'x', '2', 'y']);
+  });
+
+  it('serializes a plain object to name[key]', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'coords', value: { x: 10, y: 20 } },
+    });
+
+    const all = inputs(wrapper.element.parentElement!);
+    expect(all.map(i => i.name)).toEqual(['coords[x]', 'coords[y]']);
+    expect(all.map(i => i.value)).toEqual(['10', '20']);
+  });
+
+  it('renders nothing for an empty, non-required array', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'tags', value: [] },
+    });
+
+    expect(inputs(wrapper.element.parentElement!)).toHaveLength(0);
+  });
+
+  it('renders one required input for an empty required array (native validation fires)', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'tags', value: [], required: true },
+    });
+
+    const all = inputs(wrapper.element.parentElement!);
+    expect(all).toHaveLength(1);
+    expect(all[0]!.name).toBe('tags');
+    expect(all[0]!.required).toBe(true);
+  });
+
+  it('forwards required and disabled to every leaf input', () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'tags', value: ['a', 'b'], required: true, disabled: true },
+    });
+
+    for (const input of inputs(wrapper.element.parentElement!)) {
+      expect(input.required).toBe(true);
+      expect(input.disabled).toBe(true);
+    }
+  });
+
+  it('updates the rendered inputs when the array value changes', async () => {
+    wrapper = mount(VisuallyHiddenInput, {
+      attachTo: document.body,
+      props: { name: 'tags', value: ['a'] },
+    });
+
+    expect(inputs(wrapper.element.parentElement!)).toHaveLength(1);
+
+    await wrapper.setProps({ value: ['a', 'b'] });
+    await nextTick();
+
+    const all = inputs(wrapper.element.parentElement!);
+    expect(all.map(i => i.name)).toEqual(['tags[0]', 'tags[1]']);
+  });
+});
+
+describe('VisuallyHiddenInputBubble', () => {
+  let wrapper: ReturnType<typeof mount> | undefined;
+
+  afterEach(() => {
+    wrapper?.unmount();
+    wrapper = undefined;
+  });
+
+  it('renders a hidden text input mirroring the value', () => {
+    wrapper = mount(VisuallyHiddenInputBubble, {
+      attachTo: document.body,
+      props: { name: 'q', value: 'hello' },
+    });
+
+    const input = wrapper.element as HTMLInputElement;
+    expect(input.tagName).toBe('INPUT');
+    expect(input.type).toBe('text');
+    expect(input.name).toBe('q');
+    expect(input.value).toBe('hello');
+  });
+
+  it('renders a checkbox-style input when checked is provided', () => {
+    wrapper = mount(VisuallyHiddenInputBubble, {
+      attachTo: document.body,
+      props: { name: 'agree', value: 'on', checked: true },
+    });
+
+    const input = wrapper.element as HTMLInputElement;
+    expect(input.type).toBe('checkbox');
+    expect(input.checked).toBe(true);
+  });
+
+  it('dispatches bubbling input and change events when the value changes programmatically', async () => {
+    const onInput = vi.fn();
+    const onChange = vi.fn();
+    document.body.addEventListener('input', onInput);
+    document.body.addEventListener('change', onChange);
+
+    wrapper = mount(VisuallyHiddenInputBubble, {
+      attachTo: document.body,
+      props: { name: 'q', value: 'a' },
+    });
+
+    onInput.mockClear();
+    onChange.mockClear();
+
+    await wrapper.setProps({ value: 'b' });
+    await nextTick();
+
+    expect((wrapper.element as HTMLInputElement).value).toBe('b');
+    expect(onInput).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    document.body.removeEventListener('input', onInput);
+    document.body.removeEventListener('change', onChange);
+  });
+
+  it('dispatches change events when the checked state changes programmatically', async () => {
+    const onChange = vi.fn();
+    document.body.addEventListener('change', onChange);
+
+    wrapper = mount(VisuallyHiddenInputBubble, {
+      attachTo: document.body,
+      props: { name: 'agree', value: 'on', checked: false },
+    });
+
+    onChange.mockClear();
+
+    await wrapper.setProps({ checked: true });
+    await nextTick();
+
+    expect((wrapper.element as HTMLInputElement).checked).toBe(true);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    document.body.removeEventListener('change', onChange);
+  });
+
+  it('does not dispatch when the value is unchanged', async () => {
+    const onChange = vi.fn();
+    document.body.addEventListener('change', onChange);
+
+    wrapper = mount(VisuallyHiddenInputBubble, {
+      attachTo: document.body,
+      props: { name: 'q', value: 'a' },
+    });
+
+    onChange.mockClear();
+
+    await wrapper.setProps({ value: 'a' });
+    await nextTick();
+
+    expect(onChange).not.toHaveBeenCalled();
+
+    document.body.removeEventListener('change', onChange);
+  });
+});
diff --git a/vue/primitives/src/visually-hidden/demo.vue b/vue/primitives/src/utilities/visually-hidden/demo.vue
similarity index 68%
rename from vue/primitives/src/visually-hidden/demo.vue
rename to vue/primitives/src/utilities/visually-hidden/demo.vue
index 1c90d69..02fd0f8 100644
--- a/vue/primitives/src/visually-hidden/demo.vue
+++ b/vue/primitives/src/utilities/visually-hidden/demo.vue
@@ -6,12 +6,12 @@ const count = ref(0);
 </script>
 
 <template>
-  <div class="flex w-full max-w-sm flex-col gap-5 rounded-xl border border-(--border) bg-(--bg-elevated) p-5 text-(--fg)">
+  <div class="demo-card flex w-full max-w-sm flex-col gap-5 p-5 text-fg">
     <div class="flex flex-col gap-1">
       <h3 class="text-sm font-semibold">
         Icon-only buttons
       </h3>
-      <p class="text-sm text-(--fg-muted)">
+      <p class="text-sm text-fg-muted">
         Each button shows only an icon, but exposes a real accessible name to screen readers.
       </p>
     </div>
@@ -19,7 +19,7 @@ const count = ref(0);
     <div class="flex items-center gap-2">
       <button
         type="button"
-        class="inline-flex size-9 items-center justify-center rounded-md border border-(--border) bg-(--bg-subtle) text-(--fg) transition-colors hover:bg-(--bg-inset) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex size-9 items-center justify-center rounded-md border border-border bg-bg-subtle text-fg transition-colors hover:bg-bg-inset focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         @click="count -= 1"
       >
         <span
@@ -35,7 +35,7 @@ const count = ref(0);
 
       <button
         type="button"
-        class="inline-flex size-9 items-center justify-center rounded-md border border-(--border) bg-(--bg-subtle) text-(--fg) transition-colors hover:bg-(--bg-inset) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+        class="inline-flex size-9 items-center justify-center rounded-md border border-border bg-bg-subtle text-fg transition-colors hover:bg-bg-inset focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         @click="count += 1"
       >
         <span
@@ -46,9 +46,9 @@ const count = ref(0);
       </button>
     </div>
 
-    <p class="text-sm text-(--fg-subtle)">
+    <p class="text-sm text-fg-subtle">
       Quantity is now
-      <span class="font-medium text-(--fg)">{{ count }}</span>.
+      <span class="font-medium text-fg">{{ count }}</span>.
       <VisuallyHidden
         as="span"
         aria-live="polite"
diff --git a/vue/primitives/src/utilities/visually-hidden/index.ts b/vue/primitives/src/utilities/visually-hidden/index.ts
new file mode 100644
index 0000000..f6f9a0d
--- /dev/null
+++ b/vue/primitives/src/utilities/visually-hidden/index.ts
@@ -0,0 +1,6 @@
+export { default as VisuallyHidden } from './VisuallyHidden.vue';
+export type { VisuallyHiddenProps } from './VisuallyHidden.vue';
+export { default as VisuallyHiddenInput } from './VisuallyHiddenInput.vue';
+export type { VisuallyHiddenInputProps } from './VisuallyHiddenInput.vue';
+export { default as VisuallyHiddenInputBubble } from './VisuallyHiddenInputBubble.vue';
+export type { VisuallyHiddenInputBubbleProps } from './VisuallyHiddenInputBubble.vue';
diff --git a/vue/primitives/src/utils/__test__/getRawChildren.bench.ts b/vue/primitives/src/utils/__test__/getRawChildren.bench.ts
deleted file mode 100644
index ca0d15c..0000000
--- a/vue/primitives/src/utils/__test__/getRawChildren.bench.ts
+++ /dev/null
@@ -1,142 +0,0 @@
-import { bench, describe } from 'vitest';
-import { Comment, Fragment, createVNode, h, render } from 'vue';
-import { PatchFlags } from '@vue/shared';
-import { getRawChildren } from '../getRawChildren';
-
-// -- Helpers --
-
-function keyedFragment(children: Array<ReturnType<typeof h>>) {
-  return createVNode(Fragment, null, children, PatchFlags.KEYED_FRAGMENT);
-}
-
-const flatChildren = [h('div'), h('span'), h('p')];
-
-const keyedChildren = Array.from({ length: 10 }, (_, i) =>
-  h('div', { key: i }, `child-${i}`),
-);
-
-// ---- Processing cost ----
-
-describe('getRawChildren', () => {
-  bench('flat elements', () => {
-    getRawChildren(flatChildren);
-  });
-
-  bench('mixed elements and comments', () => {
-    getRawChildren([
-      createVNode(Comment, null, 'c'),
-      h('div'),
-      createVNode(Comment, null, 'c'),
-      h('span'),
-      createVNode(Comment, null, 'c'),
-    ]);
-  });
-
-  bench('single fragment with children', () => {
-    getRawChildren([createVNode(Fragment, null, [h('a'), h('b'), h('c')])]);
-  });
-
-  bench('nested fragments (depth 5)', () => {
-    let current: ReturnType<typeof h> = h('div');
-    for (let i = 0; i < 5; i++) {
-      current = createVNode(Fragment, null, [current, h('span')]);
-    }
-    getRawChildren([current]);
-  });
-
-  bench('wide fragment (50 children)', () => {
-    const children = Array.from({ length: 50 }, (_, i) => h('div', `child-${i}`));
-    getRawChildren([createVNode(Fragment, null, children)]);
-  });
-});
-
-// ---- BAIL path cost ----
-
-describe('getRawChildren — BAIL path', () => {
-  bench('1 keyed fragment (no BAIL)', () => {
-    getRawChildren([keyedFragment([...keyedChildren])]);
-  });
-
-  bench('2 keyed fragments (BAIL triggered)', () => {
-    getRawChildren([
-      keyedFragment(keyedChildren.slice(0, 5)),
-      keyedFragment(keyedChildren.slice(5)),
-    ]);
-  });
-
-  bench('3 keyed fragments (BAIL triggered)', () => {
-    getRawChildren([
-      keyedFragment(keyedChildren.slice(0, 3)),
-      keyedFragment(keyedChildren.slice(3, 7)),
-      keyedFragment(keyedChildren.slice(7)),
-    ]);
-  });
-});
-
-// ---- Render impact: optimized patchFlags vs BAIL ----
-
-describe('patch — optimized vs BAIL patchFlag', () => {
-  bench('patch with TEXT patchFlag', () => {
-    const container = document.createElement('div');
-    const initial = h('div', null, [
-      createVNode('span', null, 'a', PatchFlags.TEXT),
-      createVNode('span', null, 'b', PatchFlags.TEXT),
-      createVNode('span', null, 'c', PatchFlags.TEXT),
-    ]);
-    const updated = h('div', null, [
-      createVNode('span', null, 'x', PatchFlags.TEXT),
-      createVNode('span', null, 'y', PatchFlags.TEXT),
-      createVNode('span', null, 'z', PatchFlags.TEXT),
-    ]);
-    render(initial, container);
-    render(updated, container);
-  });
-
-  bench('patch with BAIL patchFlag', () => {
-    const container = document.createElement('div');
-    const initial = h('div', null, [
-      createVNode('span', null, 'a', PatchFlags.BAIL),
-      createVNode('span', null, 'b', PatchFlags.BAIL),
-      createVNode('span', null, 'c', PatchFlags.BAIL),
-    ]);
-    const updated = h('div', null, [
-      createVNode('span', null, 'x', PatchFlags.BAIL),
-      createVNode('span', null, 'y', PatchFlags.BAIL),
-      createVNode('span', null, 'z', PatchFlags.BAIL),
-    ]);
-    render(initial, container);
-    render(updated, container);
-  });
-
-  bench('patch with CLASS patchFlag', () => {
-    const container = document.createElement('div');
-    const initial = h('div', null, [
-      createVNode('span', { class: 'a' }, null, PatchFlags.CLASS),
-      createVNode('span', { class: 'b' }, null, PatchFlags.CLASS),
-      createVNode('span', { class: 'c' }, null, PatchFlags.CLASS),
-    ]);
-    const updated = h('div', null, [
-      createVNode('span', { class: 'x' }, null, PatchFlags.CLASS),
-      createVNode('span', { class: 'y' }, null, PatchFlags.CLASS),
-      createVNode('span', { class: 'z' }, null, PatchFlags.CLASS),
-    ]);
-    render(initial, container);
-    render(updated, container);
-  });
-
-  bench('patch with CLASS→BAIL patchFlag', () => {
-    const container = document.createElement('div');
-    const initial = h('div', null, [
-      createVNode('span', { class: 'a' }, null, PatchFlags.BAIL),
-      createVNode('span', { class: 'b' }, null, PatchFlags.BAIL),
-      createVNode('span', { class: 'c' }, null, PatchFlags.BAIL),
-    ]);
-    const updated = h('div', null, [
-      createVNode('span', { class: 'x' }, null, PatchFlags.BAIL),
-      createVNode('span', { class: 'y' }, null, PatchFlags.BAIL),
-      createVNode('span', { class: 'z' }, null, PatchFlags.BAIL),
-    ]);
-    render(initial, container);
-    render(updated, container);
-  });
-});
diff --git a/vue/primitives/src/visually-hidden/index.ts b/vue/primitives/src/visually-hidden/index.ts
deleted file mode 100644
index c9a2ee5..0000000
--- a/vue/primitives/src/visually-hidden/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { default as VisuallyHidden } from './VisuallyHidden.vue';
-export type { VisuallyHiddenProps } from './VisuallyHidden.vue';
diff --git a/vue/primitives/tsdown.config.ts b/vue/primitives/tsdown.config.ts
index c315bda..ea51e7d 100644
--- a/vue/primitives/tsdown.config.ts
+++ b/vue/primitives/tsdown.config.ts
@@ -5,7 +5,8 @@ import Vue from 'unplugin-vue/rolldown';
 export default defineConfig({
   ...sharedConfig,
   tsconfig: './tsconfig.src.json',
-  entry: ['src/index.ts', 'src/*/index.ts'],
+  // Components live one level deep now: src/<category>/<component>/index.ts.
+  entry: ['src/index.ts', 'src/*/*/index.ts'],
   plugins: [Vue({ isProduction: true })],
   dts: { vue: true },
   deps: {