diff --git a/core/encoding/src/index.ts b/core/encoding/src/index.ts
index 0de9894..450cbcf 100644
--- a/core/encoding/src/index.ts
+++ b/core/encoding/src/index.ts
@@ -1,2 +1,3 @@
+export * from './luhn';
 export * from './reed-solomon';
 export * from './qr';
diff --git a/core/encoding/src/luhn/index.test.ts b/core/encoding/src/luhn/index.test.ts
new file mode 100644
index 0000000..00eac10
--- /dev/null
+++ b/core/encoding/src/luhn/index.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { luhn } from './index';
+
+describe(luhn, () => {
+  it('passes valid checksums (separators ignored)', () => {
+    expect(luhn('4111 1111 1111 1111')).toBe(true);
+    expect(luhn('5500005555555559')).toBe(true);
+    expect(luhn('371449635398431')).toBe(true);
+    expect(luhn('79927398713')).toBe(true); // classic Luhn example
+  });
+
+  it('fails bad checksums', () => {
+    expect(luhn('4111 1111 1111 1112')).toBe(false);
+    expect(luhn('79927398710')).toBe(false);
+  });
+
+  it('returns false for empty input', () => {
+    expect(luhn('')).toBe(false);
+    expect(luhn('----')).toBe(false);
+  });
+});
diff --git a/core/encoding/src/luhn/index.ts b/core/encoding/src/luhn/index.ts
new file mode 100644
index 0000000..05b4c75
--- /dev/null
+++ b/core/encoding/src/luhn/index.ts
@@ -0,0 +1,39 @@
+const NON_DIGIT = /\D/g;
+const ASCII_ZERO = 0x30;
+
+/**
+ * @name luhn
+ * @category Encoding
+ * @description Validate a number string against the Luhn (mod 10) checksum — the
+ * check digit used by payment cards, IMEIs, SIM ICCIDs, and more. Non-digits are
+ * ignored; an empty input is `false`.
+ *
+ * @param {string} value The number (separators allowed)
+ * @returns {boolean} Whether the Luhn checksum passes
+ *
+ * @example
+ * luhn('4111 1111 1111 1111'); // true
+ * luhn('4111 1111 1111 1112'); // false
+ *
+ * @since 0.0.2
+ */
+export function luhn(value: string): boolean {
+  const digits = value.replaceAll(NON_DIGIT, '');
+  if (!digits)
+    return false;
+
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let digit = digits.charCodeAt(i) - ASCII_ZERO;
+    if (double) {
+      digit *= 2;
+      if (digit > 9)
+        digit -= 9;
+    }
+    sum += digit;
+    double = !double;
+  }
+
+  return sum % 10 === 0;
+}
diff --git a/core/platform/package.json b/core/platform/package.json
index f2d13dd..9092c74 100644
--- a/core/platform/package.json
+++ b/core/platform/package.json
@@ -56,6 +56,7 @@
     "build": "tsdown"
   },
   "devDependencies": {
+    "@robonen/encoding": "workspace:*",
     "@robonen/eslint": "workspace:*",
     "@robonen/stdlib": "workspace:*",
     "@robonen/tsconfig": "workspace:*",
diff --git a/core/platform/src/browsers/domStyle/index.test.ts b/core/platform/src/browsers/domStyle/index.test.ts
new file mode 100644
index 0000000..c50075b
--- /dev/null
+++ b/core/platform/src/browsers/domStyle/index.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { assignStyle, getTranslate, isInView, resetStyle, setStyle } from './index';
+
+function makeEl(): HTMLElement {
+  const el = document.createElement('div');
+  document.body.append(el);
+  return el;
+}
+
+describe('setStyle / resetStyle', () => {
+  it('applies styles and caches the overwritten values', () => {
+    const el = makeEl();
+    el.style.transform = 'translateY(0px)';
+
+    setStyle(el, { transform: 'translateY(20px)', transition: 'none' });
+    expect(el.style.transform).toBe('translateY(20px)');
+    expect(el.style.transition).toBe('none');
+
+    resetStyle(el);
+    expect(el.style.transform).toBe('translateY(0px)');
+  });
+
+  it('restores a single property when given prop', () => {
+    const el = makeEl();
+    el.style.opacity = '1';
+
+    setStyle(el, { opacity: '0', transform: 'scale(0.9)' });
+    resetStyle(el, 'opacity');
+
+    expect(el.style.opacity).toBe('1');
+    expect(el.style.transform).toBe('scale(0.9)');
+  });
+
+  it('writes custom properties via setProperty', () => {
+    const el = makeEl();
+    setStyle(el, { '--snap-point-height': '120px' });
+    expect(el.style.getPropertyValue('--snap-point-height')).toBe('120px');
+  });
+
+  it('does not cache when ignoreCache is true', () => {
+    const el = makeEl();
+    el.style.opacity = '1';
+
+    setStyle(el, { opacity: '0.5' }, true);
+    resetStyle(el);
+
+    expect(el.style.opacity).toBe('0.5');
+  });
+
+  it('is a no-op for non-elements', () => {
+    expect(() => setStyle(null, { opacity: '0' })).not.toThrow();
+    expect(() => resetStyle(null)).not.toThrow();
+  });
+});
+
+describe('getTranslate', () => {
+  it('returns null when there is no matrix transform', () => {
+    const el = makeEl();
+    expect(getTranslate(el, 'y')).toBeNull();
+  });
+
+  it('reads x and y from a 2D matrix', () => {
+    const el = makeEl();
+    el.style.transform = 'matrix(1, 0, 0, 1, 12, 34)';
+    expect(getTranslate(el, 'x')).toBe(12);
+    expect(getTranslate(el, 'y')).toBe(34);
+  });
+
+  it('reads x and y from a 3D matrix', () => {
+    const el = makeEl();
+    el.style.transform = 'matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 50, 60, 0, 1)';
+    expect(getTranslate(el, 'x')).toBe(50);
+    expect(getTranslate(el, 'y')).toBe(60);
+  });
+});
+
+describe('assignStyle', () => {
+  it('assigns styles and restores the previous cssText on cleanup', () => {
+    const el = makeEl();
+    el.style.cssText = 'color: red;';
+
+    const restore = assignStyle(el, { overflow: 'hidden' });
+    expect(el.style.overflow).toBe('hidden');
+
+    restore();
+    expect(el.style.overflow).toBe('');
+    expect(el.style.color).toBe('red');
+  });
+
+  it('returns a no-op cleanup for a missing element', () => {
+    expect(() => assignStyle(null, { overflow: 'hidden' })()).not.toThrow();
+  });
+});
+
+describe('isInView', () => {
+  it('returns false when visualViewport is unavailable', () => {
+    const el = makeEl();
+    const original = window.visualViewport;
+    Object.defineProperty(globalThis, 'visualViewport', { value: null, configurable: true });
+
+    expect(isInView(el)).toBe(false);
+
+    Object.defineProperty(globalThis, 'visualViewport', { value: original, configurable: true });
+  });
+});
diff --git a/core/platform/src/browsers/domStyle/index.ts b/core/platform/src/browsers/domStyle/index.ts
new file mode 100644
index 0000000..b9adba5
--- /dev/null
+++ b/core/platform/src/browsers/domStyle/index.ts
@@ -0,0 +1,190 @@
+/**
+ * A patch of inline styles — a map of CSS property names to string values.
+ * Keys may be camelCase DOM style properties (`borderRadius`) or `--custom`
+ * properties (set verbatim via `setProperty`).
+ */
+export type StylePatch = Record<string, string>;
+
+/**
+ * The axis a translation is read along: `x` (horizontal) or `y` (vertical).
+ */
+export type TranslateAxis = 'x' | 'y';
+
+// Remembers the styles that {@link setStyle} overwrote, keyed by element, so
+// {@link resetStyle} can put them back. A WeakMap lets the entry be collected
+// once the element is gone.
+const originalStyles = new WeakMap<HTMLElement, StylePatch>();
+
+/**
+ * @name setStyle
+ * @category Browsers
+ * @description Applies a batch of inline styles to an element, remembering the
+ * values it overwrote so {@link resetStyle} can restore them later. `--custom`
+ * properties are written through `setProperty`. Pass `ignoreCache` to apply the
+ * styles without recording the originals (e.g. for transient, per-frame writes
+ * during a drag that you intend to clear wholesale).
+ *
+ * @param {Element | HTMLElement | null} [element] The element to style (ignored if not an `HTMLElement`)
+ * @param {StylePatch} [styles] The property/value pairs to apply
+ * @param {boolean} [ignoreCache] Skip remembering the overwritten values
+ * @returns {void}
+ *
+ * @example
+ * setStyle(el, { transition: 'none', transform: 'translateY(20px)' });
+ * setStyle(el, { opacity: '0.5' }, true); // transient — won't be restored
+ *
+ * @since 0.0.5
+ */
+export function setStyle(element?: Element | HTMLElement | null, styles?: StylePatch, ignoreCache = false): void {
+  if (!element || !(element instanceof HTMLElement) || !styles)
+    return;
+
+  const previous: StylePatch = {};
+
+  for (const [key, value] of Object.entries(styles)) {
+    if (key.startsWith('--')) {
+      element.style.setProperty(key, value);
+      continue;
+    }
+
+    previous[key] = (element.style as unknown as StylePatch)[key];
+    (element.style as unknown as StylePatch)[key] = value;
+  }
+
+  if (ignoreCache)
+    return;
+
+  originalStyles.set(element, previous);
+}
+
+/**
+ * @name resetStyle
+ * @category Browsers
+ * @description Restores the inline styles an element had before the most recent
+ * cached {@link setStyle}. With `prop` it restores a single property; otherwise
+ * it restores every property that was remembered. A no-op if nothing was cached.
+ *
+ * @param {Element | HTMLElement | null} element The element to restore
+ * @param {string} [prop] Restore only this property instead of all of them
+ * @returns {void}
+ *
+ * @example
+ * resetStyle(el); // restore everything setStyle changed
+ * resetStyle(el, 'transform'); // restore just the transform
+ *
+ * @since 0.0.5
+ */
+export function resetStyle(element: Element | HTMLElement | null, prop?: string): void {
+  if (!element || !(element instanceof HTMLElement))
+    return;
+
+  const previous = originalStyles.get(element);
+
+  if (!previous)
+    return;
+
+  if (prop) {
+    (element.style as unknown as StylePatch)[prop] = previous[prop];
+    return;
+  }
+
+  for (const [key, value] of Object.entries(previous))
+    (element.style as unknown as StylePatch)[key] = value;
+}
+
+/**
+ * @name getTranslate
+ * @category Browsers
+ * @description Reads the current translation of an element along one axis from
+ * its computed `transform`, parsing both `matrix(...)` (2D) and `matrix3d(...)`
+ * (3D) forms. Returns `null` when the element has no matrix transform.
+ *
+ * @param {HTMLElement} element The element to measure
+ * @param {TranslateAxis} axis `'x'` for horizontal, `'y'` for vertical
+ * @returns {number | null} The translation in pixels, or `null` if none
+ *
+ * @example
+ * const offset = getTranslate(panel, 'y'); // px the panel is shifted down
+ *
+ * @since 0.0.5
+ */
+export function getTranslate(element: HTMLElement, axis: TranslateAxis): number | null {
+  const style = globalThis.getComputedStyle(element);
+  const transform
+    // @ts-expect-error — vendor-prefixed transforms only exist in some browsers
+    = style.transform || style.webkitTransform || style.mozTransform;
+
+  let match = transform.match(/^matrix3d\((.+)\)$/);
+  if (match) {
+    // matrix3d: the translate components live at indices 12 (x) and 13 (y).
+    // https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix3d
+    return Number.parseFloat(match[1].split(', ')[axis === 'y' ? 13 : 12]);
+  }
+
+  // matrix: the translate components live at indices 4 (x) and 5 (y).
+  // https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix
+  match = transform.match(/^matrix\((.+)\)$/);
+  return match ? Number.parseFloat(match[1].split(', ')[axis === 'y' ? 5 : 4]) : null;
+}
+
+/**
+ * @name assignStyle
+ * @category Browsers
+ * @description Merges a style patch onto an element's inline `style` and returns
+ * a cleanup function that restores the element's entire previous `cssText`.
+ * Unlike {@link setStyle}, the snapshot is the full `cssText`, so the cleanup is
+ * an all-or-nothing revert — handy for scoped effects.
+ *
+ * @param {HTMLElement | null | undefined} element The element to style
+ * @param {Partial<CSSStyleDeclaration>} style The styles to assign
+ * @returns {() => void} A cleanup function that restores the previous `cssText`
+ *
+ * @example
+ * const restore = assignStyle(document.body, { overflow: 'hidden' });
+ * // ...later
+ * restore();
+ *
+ * @since 0.0.5
+ */
+export function assignStyle(element: HTMLElement | null | undefined, style: Partial<CSSStyleDeclaration>): () => void {
+  if (!element)
+    return () => {};
+
+  const previousCssText = element.style.cssText;
+  Object.assign(element.style, style);
+
+  return () => {
+    element.style.cssText = previousCssText;
+  };
+}
+
+/**
+ * @name isInView
+ * @category Browsers
+ * @description Reports whether an element is fully within the visual viewport,
+ * accounting for on-screen keyboards via `window.visualViewport`. A 40px slack
+ * is allowed at the bottom to tolerate Safari's viewport quirks. Returns `false`
+ * when `visualViewport` is unavailable.
+ *
+ * @param {HTMLElement} element The element to test
+ * @returns {boolean} `true` if the element's rect fits inside the visual viewport
+ *
+ * @example
+ * if (!isInView(focusedField)) scrollIntoView(focusedField);
+ *
+ * @since 0.0.5
+ */
+export function isInView(element: HTMLElement): boolean {
+  const rect = element.getBoundingClientRect();
+
+  if (!window.visualViewport)
+    return false;
+
+  return (
+    rect.top >= 0
+    && rect.left >= 0
+    // +40 of slack for Safari's visual-viewport reporting.
+    && rect.bottom <= window.visualViewport.height - 40
+    && rect.right <= window.visualViewport.width
+  );
+}
diff --git a/core/platform/src/browsers/index.ts b/core/platform/src/browsers/index.ts
index d82f88c..4f0ca1f 100644
--- a/core/platform/src/browsers/index.ts
+++ b/core/platform/src/browsers/index.ts
@@ -1,4 +1,7 @@
 export * from './animationLifecycle';
+export * from './domStyle';
 export * from './focusGuard';
 export * from './focusScope';
 export * from './hideOthers';
+export * from './inputState';
+export * from './userAgent';
diff --git a/core/platform/src/browsers/inputState/index.test.ts b/core/platform/src/browsers/inputState/index.test.ts
new file mode 100644
index 0000000..839a2f6
--- /dev/null
+++ b/core/platform/src/browsers/inputState/index.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { readInputState, writeInputState } from './index';
+
+function makeInput(value = ''): HTMLInputElement {
+  const input = document.createElement('input');
+  input.value = value;
+  document.body.append(input);
+  return input;
+}
+
+describe('readInputState', () => {
+  it('reads value and selection', () => {
+    const input = makeInput('hello');
+    input.setSelectionRange(1, 3);
+
+    expect(readInputState(input)).toEqual({ value: 'hello', selection: [1, 3] });
+  });
+
+  it('falls back to a collapsed caret at the end when selection is null', () => {
+    const input = makeInput('abc');
+    // Force a null selection (some input types report null).
+    Object.defineProperty(input, 'selectionStart', { value: null });
+    Object.defineProperty(input, 'selectionEnd', { value: null });
+
+    expect(readInputState(input)).toEqual({ value: 'abc', selection: [3, 3] });
+  });
+});
+
+describe('writeInputState', () => {
+  it('writes the value', () => {
+    const input = makeInput('a');
+    writeInputState(input, { value: '(12)', selection: [4, 4] });
+
+    expect(input.value).toBe('(12)');
+  });
+
+  it('moves the caret only while the element is focused', () => {
+    const input = makeInput('12345');
+    input.focus();
+    writeInputState(input, { value: '12345', selection: [2, 4] });
+
+    expect(input.selectionStart).toBe(2);
+    expect(input.selectionEnd).toBe(4);
+  });
+
+  it('does not reposition the caret when not focused', () => {
+    const input = makeInput('12345');
+    input.setSelectionRange(0, 0);
+    input.blur();
+    writeInputState(input, { value: '12345', selection: [3, 3] });
+
+    // Unfocused: selection is left untouched by setSelectionRange.
+    expect(input.selectionStart).toBe(0);
+  });
+});
diff --git a/core/platform/src/browsers/inputState/index.ts b/core/platform/src/browsers/inputState/index.ts
new file mode 100644
index 0000000..7fbfc9b
--- /dev/null
+++ b/core/platform/src/browsers/inputState/index.ts
@@ -0,0 +1,80 @@
+/**
+ * The editable state of a text field: its current text and selection bounds.
+ * Framework-agnostic and structurally compatible with any `{ value, selection }`
+ * pair (e.g. an input-masking engine's element state).
+ */
+export interface InputState {
+  /**
+   * The element's current `value`.
+   */
+  readonly value: string;
+  /**
+   * The selection as `[from, to]` (collapsed caret when `from === to`).
+   */
+  readonly selection: readonly [from: number, to: number];
+}
+
+/**
+ * A text field whose value and selection can be read and written.
+ */
+export type TextFieldElement = HTMLInputElement | HTMLTextAreaElement;
+
+/**
+ * @name readInputState
+ * @category Browsers
+ * @description Reads the value and current selection of an `<input>`/`<textarea>`
+ * into a plain {@link InputState}. A `null` selection (some input types report it)
+ * falls back to a collapsed caret at the end of the value.
+ *
+ * @param {TextFieldElement} element The input or textarea to read
+ * @returns {InputState} The element's `{ value, selection }`
+ *
+ * @example
+ * const { value, selection } = readInputState(inputEl);
+ *
+ * @since 0.0.5
+ */
+export function readInputState(element: TextFieldElement): InputState {
+  const { value, selectionStart, selectionEnd } = element;
+  const end = value.length;
+
+  return {
+    value,
+    selection: [selectionStart ?? end, selectionEnd ?? end],
+  };
+}
+
+/**
+ * @name writeInputState
+ * @category Browsers
+ * @description Writes value and selection back to an `<input>`/`<textarea>`. The
+ * value is only assigned when it actually changed (avoids spurious cursor jumps),
+ * and the caret is moved **only while the element is focused** so programmatic
+ * updates never steal or reposition focus. `setSelectionRange` is guarded because
+ * some input types (`number`, `email`, `date`) forbid it.
+ *
+ * @param {TextFieldElement} element The input or textarea to update
+ * @param {InputState} state The `{ value, selection }` to apply
+ * @returns {void}
+ *
+ * @example
+ * writeInputState(inputEl, { value: '(123)', selection: [5, 5] });
+ *
+ * @since 0.0.5
+ */
+export function writeInputState(element: TextFieldElement, state: InputState): void {
+  const [from, to] = state.selection;
+
+  if (element.value !== state.value)
+    element.value = state.value;
+
+  if (element.ownerDocument.activeElement !== element)
+    return;
+
+  try {
+    element.setSelectionRange(from, to);
+  }
+  catch {
+    // Input types like number/email/date throw on setSelectionRange — ignore.
+  }
+}
diff --git a/core/platform/src/browsers/userAgent/index.test.ts b/core/platform/src/browsers/userAgent/index.test.ts
new file mode 100644
index 0000000..ecc09ef
--- /dev/null
+++ b/core/platform/src/browsers/userAgent/index.test.ts
@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { isMac, isMobileFirefox, isSafari, testUserAgentPlatform } from './index';
+
+function stubPlatform(platform: string): void {
+  vi.spyOn(globalThis.navigator, 'platform', 'get').mockReturnValue(platform);
+}
+
+function stubUserAgent(ua: string): void {
+  vi.spyOn(globalThis.navigator, 'userAgent', 'get').mockReturnValue(ua);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('testUserAgentPlatform', () => {
+  it('matches against navigator.platform', () => {
+    stubPlatform('MacIntel');
+    expect(testUserAgentPlatform(/^Mac/)).toBe(true);
+    expect(testUserAgentPlatform(/^Win/)).toBe(false);
+  });
+});
+
+describe('isMac', () => {
+  it('is true on a Mac platform', () => {
+    stubPlatform('MacIntel');
+    expect(isMac()).toBe(true);
+  });
+
+  it('is false elsewhere', () => {
+    stubPlatform('Win32');
+    expect(isMac()).toBe(false);
+  });
+});
+
+describe('isSafari', () => {
+  it('is true for a Safari UA', () => {
+    stubUserAgent('Mozilla/5.0 (Macintosh) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15');
+    expect(isSafari()).toBe(true);
+  });
+
+  it('is false for Chrome', () => {
+    stubUserAgent('Mozilla/5.0 (Macintosh) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36');
+    expect(isSafari()).toBe(false);
+  });
+});
+
+describe('isMobileFirefox', () => {
+  it('is true for Android Firefox', () => {
+    stubUserAgent('Mozilla/5.0 (Android 14; Mobile; rv:121.0) Gecko/121.0 Firefox/121.0');
+    expect(isMobileFirefox()).toBe(true);
+  });
+
+  it('is true for iOS Firefox (FxiOS)', () => {
+    stubUserAgent('Mozilla/5.0 (iPhone) AppleWebKit/605.1.15 FxiOS/121.0 Mobile/15E148 Safari/605.1.15');
+    expect(isMobileFirefox()).toBe(true);
+  });
+
+  it('is false for desktop Firefox', () => {
+    stubUserAgent('Mozilla/5.0 (Windows NT 10.0; rv:121.0) Gecko/20100101 Firefox/121.0');
+    expect(isMobileFirefox()).toBe(false);
+  });
+});
diff --git a/core/platform/src/browsers/userAgent/index.ts b/core/platform/src/browsers/userAgent/index.ts
new file mode 100644
index 0000000..650f234
--- /dev/null
+++ b/core/platform/src/browsers/userAgent/index.ts
@@ -0,0 +1,117 @@
+/**
+ * @name testUserAgentPlatform
+ * @category Browsers
+ * @description Tests `navigator.platform` against a regular expression, guarding
+ * for non-browser environments. Returns `undefined` when there is no `navigator`
+ * (e.g. during SSR) so callers can distinguish "no" from "unknown".
+ *
+ * @param {RegExp} re The pattern to test `navigator.platform` against
+ * @returns {boolean | undefined} The match result, or `undefined` outside a browser
+ *
+ * @example
+ * const onMac = testUserAgentPlatform(/^Mac/);
+ *
+ * @since 0.0.5
+ */
+export function testUserAgentPlatform(re: RegExp): boolean | undefined {
+  return globalThis.navigator !== undefined
+    ? re.test(globalThis.navigator.platform)
+    : undefined;
+}
+
+/**
+ * @name isMac
+ * @category Browsers
+ * @description Whether the current platform is macOS (per `navigator.platform`).
+ * Note iPadOS reports as a Mac — combine with {@link isIPad} to disambiguate.
+ *
+ * @returns {boolean | undefined} `true` on macOS, `undefined` outside a browser
+ *
+ * @since 0.0.5
+ */
+export function isMac(): boolean | undefined {
+  return testUserAgentPlatform(/^Mac/);
+}
+
+/**
+ * @name isIPhone
+ * @category Browsers
+ * @description Whether the current platform is an iPhone (per `navigator.platform`).
+ *
+ * @returns {boolean | undefined} `true` on iPhone, `undefined` outside a browser
+ *
+ * @since 0.0.5
+ */
+export function isIPhone(): boolean | undefined {
+  return testUserAgentPlatform(/^iPhone/);
+}
+
+/**
+ * @name isIPad
+ * @category Browsers
+ * @description Whether the current device is an iPad. iPadOS 13+ masquerades as a
+ * Mac, so this also treats a touch-capable Mac (`maxTouchPoints > 1`) as an iPad.
+ *
+ * @returns {boolean | undefined} `true` on iPad, `undefined` outside a browser
+ *
+ * @since 0.0.5
+ */
+export function isIPad(): boolean | undefined {
+  return (
+    testUserAgentPlatform(/^iPad/)
+    // iPadOS 13+ lies and reports as a Mac; touch support gives it away.
+    || (isMac() && navigator.maxTouchPoints > 1)
+  );
+}
+
+/**
+ * @name isIOS
+ * @category Browsers
+ * @description Whether the current device runs iOS/iPadOS (iPhone or iPad).
+ *
+ * @returns {boolean | undefined} `true` on iOS, `undefined` outside a browser
+ *
+ * @since 0.0.5
+ */
+export function isIOS(): boolean | undefined {
+  return isIPhone() || isIPad();
+}
+
+/**
+ * @name isSafari
+ * @category Browsers
+ * @description Whether the current browser is Safari (desktop or iOS), excluding
+ * Chrome and Android browsers that also include "Safari" in their UA string.
+ *
+ * @returns {boolean} `true` if the user agent looks like Safari
+ *
+ * @since 0.0.5
+ */
+export function isSafari(): boolean {
+  if (typeof navigator === 'undefined')
+    return false;
+
+  // eslint-disable-next-line regexp/no-unused-capturing-group
+  return /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+}
+
+/**
+ * @name isMobileFirefox
+ * @category Browsers
+ * @description Whether the current browser is Firefox on a mobile device
+ * (Android Firefox or iOS Firefox / `FxiOS`).
+ *
+ * @returns {boolean} `true` on mobile Firefox
+ *
+ * @since 0.0.5
+ */
+export function isMobileFirefox(): boolean {
+  if (typeof navigator === 'undefined')
+    return false;
+
+  const userAgent = navigator.userAgent;
+  return (
+    (/Firefox/.test(userAgent) && /Mobile/.test(userAgent)) // Android Firefox
+    || /FxiOS/.test(userAgent) // iOS Firefox
+  );
+}
diff --git a/core/platform/src/multi/card/card-brands.ts b/core/platform/src/multi/card/card-brands.ts
new file mode 100644
index 0000000..5dafdf4
--- /dev/null
+++ b/core/platform/src/multi/card/card-brands.ts
@@ -0,0 +1,51 @@
+/**
+ * Payment-card brands: detection patterns (IIN/BIN prefixes and ranges), the
+ * number template (`#` = a digit), valid total lengths, and the security-code
+ * info. Derived from the MIT-licensed `credit-card-type` dataset (Braintree).
+ * The template uses the brand's gap positions; the trailing group is sized to the
+ * longest valid length, so shorter numbers simply leave it partly empty.
+ */
+
+/**
+ * A card brand's prefix pattern: an exact prefix string, or an inclusive numeric
+ * range `[min, max]` whose bounds have the same digit length.
+ */
+export type CardPattern = string | readonly [min: number, max: number];
+
+/**
+ * One payment-card brand.
+ */
+export interface CardBrand {
+  /** Brand id, e.g. `'visa'`. */
+  readonly brand: string;
+  /** Display name, e.g. `'Visa'`. */
+  readonly name: string;
+  /** Number template; `#` is a digit, e.g. `'#### #### #### ####'`. */
+  readonly template: string;
+  /** Valid total digit lengths, e.g. `[16, 18, 19]`. */
+  readonly lengths: readonly number[];
+  /** Security code metadata, e.g. `{ name: 'CVV', size: 3 }`. */
+  readonly code: { readonly name: string; readonly size: number };
+  /** IIN/BIN detection patterns (prefixes and ranges). */
+  readonly patterns: readonly CardPattern[];
+}
+
+/**
+ * Every supported card brand. Resolve a number with `findCardBrand`.
+ */
+export const CARD_BRANDS: readonly CardBrand[] = [
+  { brand: 'visa', name: 'Visa', template: '#### #### #### #######', lengths: [16, 18, 19], code: { name: 'CVV', size: 3 }, patterns: ['4'] },
+  { brand: 'mastercard', name: 'Mastercard', template: '#### #### #### ####', lengths: [16], code: { name: 'CVC', size: 3 }, patterns: [[51, 55], [2221, 2229], [223, 229], [23, 26], [270, 271], '2720'] },
+  { brand: 'american-express', name: 'American Express', template: '#### ###### #####', lengths: [15], code: { name: 'CID', size: 4 }, patterns: ['34', '37'] },
+  { brand: 'diners-club', name: 'Diners Club', template: '#### ###### #########', lengths: [14, 16, 19], code: { name: 'CVV', size: 3 }, patterns: [[300, 305], '36', '38', '39'] },
+  { brand: 'discover', name: 'Discover', template: '#### #### #### #######', lengths: [16, 19], code: { name: 'CID', size: 3 }, patterns: ['6011', [644, 649], '65'] },
+  { brand: 'jcb', name: 'JCB', template: '#### #### #### #######', lengths: [16, 17, 18, 19], code: { name: 'CVV', size: 3 }, patterns: ['2131', '1800', [3528, 3589]] },
+  { brand: 'unionpay', name: 'UnionPay', template: '#### #### #### #######', lengths: [14, 15, 16, 17, 18, 19], code: { name: 'CVN', size: 3 }, patterns: ['620', [62100, 62182], [62184, 62187], [62185, 62197], [62200, 62205], [622010, 622999], '622018', [62207, 62209], [623, 626], '6270', '6272', '6276', [627700, 627779], [627781, 627799], [6282, 6289], '6291', '6292', '810', [8110, 8131], [8132, 8151], [8152, 8163], [8164, 8171]] },
+  { brand: 'maestro', name: 'Maestro', template: '#### #### #### #######', lengths: [12, 13, 14, 15, 16, 17, 18, 19], code: { name: 'CVC', size: 3 }, patterns: ['493698', [500000, 504174], [504176, 506698], [506779, 508999], [56, 59], '63', '67', '6'] },
+  { brand: 'elo', name: 'Elo', template: '#### #### #### ####', lengths: [16], code: { name: 'CVE', size: 3 }, patterns: ['401178', '401179', '438935', '457631', '457632', '431274', '451416', '457393', '504175', [506699, 506778], [509000, 509999], '627780', '636297', '636368', [650031, 650033], [650035, 650051], [650405, 650439], [650485, 650538], [650541, 650598], [650700, 650718], [650720, 650727], [650901, 650978], [651652, 651679], [655000, 655019], [655021, 655058]] },
+  { brand: 'mir', name: 'Mir', template: '#### #### #### #######', lengths: [16, 17, 18, 19], code: { name: 'CVP2', size: 3 }, patterns: [[2200, 2204]] },
+  { brand: 'hiper', name: 'Hiper', template: '#### #### #### ####', lengths: [16], code: { name: 'CVC', size: 3 }, patterns: ['637095', '63737423', '63743358', '637568', '637599', '637609', '637612'] },
+  { brand: 'hipercard', name: 'Hipercard', template: '#### #### #### ####', lengths: [16], code: { name: 'CVC', size: 3 }, patterns: ['606282'] },
+  { brand: 'naranja', name: 'Naranja', template: '#### #### #### ####', lengths: [16], code: { name: 'CVV', size: 3 }, patterns: ['589562', '402918', '527572'] },
+  { brand: 'verve', name: 'Verve', template: '#### #### #### #######', lengths: [16, 18, 19], code: { name: 'CVV', size: 3 }, patterns: [[506099, 506127], '506129', [506133, 506150], [506158, 506163], '506166', '506168', '506170', '506173', [506176, 506180], '506184', [506187, 506188], '506191', '506195', '506197', '507865', '507866', [507868, 507877], [507880, 507888], '507900', '507941'] },
+];
diff --git a/core/platform/src/multi/card/find-card-brand.test.ts b/core/platform/src/multi/card/find-card-brand.test.ts
new file mode 100644
index 0000000..4d33320
--- /dev/null
+++ b/core/platform/src/multi/card/find-card-brand.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { CARD_BRANDS } from './card-brands';
+import { findCardBrand } from './find-card-brand';
+
+describe(findCardBrand, () => {
+  it('detects major brands by IIN', () => {
+    expect(findCardBrand('4111111111111111')?.brand).toBe('visa');
+    expect(findCardBrand('5500005555555559')?.brand).toBe('mastercard');
+    expect(findCardBrand('2221001234567890')?.brand).toBe('mastercard'); // 2-series
+    expect(findCardBrand('371449635398431')?.brand).toBe('american-express');
+    expect(findCardBrand('30569309025904')?.brand).toBe('diners-club');
+    expect(findCardBrand('6011000990139424')?.brand).toBe('discover');
+    expect(findCardBrand('2200123412341234')?.brand).toBe('mir');
+  });
+
+  it('narrows down as digits are typed', () => {
+    expect(findCardBrand('4')?.brand).toBe('visa');
+  });
+
+  it('exposes a template, lengths and security code for every brand', () => {
+    expect(CARD_BRANDS.length).toBeGreaterThan(5);
+    for (const brand of CARD_BRANDS) {
+      expect(brand.template).toMatch(/#/);
+      expect(brand.lengths.length).toBeGreaterThan(0);
+      expect(brand.code.size).toBeGreaterThan(0);
+    }
+  });
+
+  it('returns undefined for empty or unknown input', () => {
+    expect(findCardBrand('')).toBeUndefined();
+    expect(findCardBrand('0000')).toBeUndefined();
+  });
+});
diff --git a/core/platform/src/multi/card/find-card-brand.ts b/core/platform/src/multi/card/find-card-brand.ts
new file mode 100644
index 0000000..b22624b
--- /dev/null
+++ b/core/platform/src/multi/card/find-card-brand.ts
@@ -0,0 +1,85 @@
+import { CARD_BRANDS } from './card-brands';
+import type { CardBrand, CardPattern } from './card-brands';
+
+interface RangeMeta {
+  readonly width: number;
+  readonly minString: string;
+  readonly maxString: string;
+}
+
+// Precompute the constant string forms of every range pattern once, so the
+// per-keystroke scan doesn't re-derive them via String() on each comparison.
+const RANGE_META = new Map<CardPattern, RangeMeta>();
+for (const brand of CARD_BRANDS) {
+  for (const pattern of brand.patterns) {
+    if (typeof pattern !== 'string') {
+      const maxString = String(pattern[1]);
+      RANGE_META.set(pattern, { width: maxString.length, minString: String(pattern[0]), maxString });
+    }
+  }
+}
+
+/**
+ * Score how specifically `digits` matches a pattern: the number of leading digits
+ * that match (higher = more specific), or `0` for no match. Supports partial
+ * input as the user types.
+ */
+function patternScore(digits: string, pattern: CardPattern): number {
+  if (typeof pattern === 'string') {
+    const length = Math.min(pattern.length, digits.length);
+    return digits.slice(0, length) === pattern.slice(0, length) ? length : 0;
+  }
+
+  const meta = RANGE_META.get(pattern);
+  const maxString = meta ? meta.maxString : String(pattern[1]);
+  const minString = meta ? meta.minString : String(pattern[0]);
+  const width = meta ? meta.width : maxString.length;
+
+  const prefix = digits.slice(0, width);
+  const value = Number(prefix);
+  const low = Number(minString.slice(0, prefix.length));
+  const high = Number(maxString.slice(0, prefix.length));
+
+  return value >= low && value <= high ? prefix.length : 0;
+}
+
+/**
+ * @name findCardBrand
+ * @category Multi
+ * @description Detect a payment-card brand from a number's digits by its IIN/BIN
+ * pattern. Returns the brand whose pattern matches the most leading digits (so it
+ * narrows down as the user types), or `undefined` if none match. Pure.
+ *
+ * @param {string} digits The card number's digits (no separators)
+ * @param {readonly CardBrand[]} [brands=CARD_BRANDS] The brand list
+ * @returns {CardBrand | undefined} The detected brand, or `undefined`
+ *
+ * @example
+ * findCardBrand('4111111111111111')?.brand; // 'visa'
+ * findCardBrand('371449635398431')?.brand;   // 'american-express'
+ * findCardBrand('2200123412341234')?.brand;  // 'mir'
+ *
+ * @since 0.0.5
+ */
+export function findCardBrand(
+  digits: string,
+  brands: readonly CardBrand[] = CARD_BRANDS,
+): CardBrand | undefined {
+  if (!digits)
+    return undefined;
+
+  let best: CardBrand | undefined;
+  let bestScore = 0;
+
+  for (const brand of brands) {
+    for (const pattern of brand.patterns) {
+      const score = patternScore(digits, pattern);
+      if (score > bestScore) {
+        best = brand;
+        bestScore = score;
+      }
+    }
+  }
+
+  return best;
+}
diff --git a/core/platform/src/multi/card/index.ts b/core/platform/src/multi/card/index.ts
new file mode 100644
index 0000000..fa2fd54
--- /dev/null
+++ b/core/platform/src/multi/card/index.ts
@@ -0,0 +1,3 @@
+export * from './card-brands';
+export * from './find-card-brand';
+export * from './validate';
diff --git a/core/platform/src/multi/card/validate.test.ts b/core/platform/src/multi/card/validate.test.ts
new file mode 100644
index 0000000..7593ffb
--- /dev/null
+++ b/core/platform/src/multi/card/validate.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { luhn } from '@robonen/encoding';
+import { isValidCardNumber } from './validate';
+
+describe(isValidCardNumber, () => {
+  it('requires a valid checksum and a brand-matching length', () => {
+    expect(isValidCardNumber('4111 1111 1111 1111')).toBe(true); // visa, 16
+    expect(isValidCardNumber('371449635398431')).toBe(true); // amex, 15
+  });
+
+  it('rejects a Luhn-valid number outside the valid length range', () => {
+    expect(luhn('79927398713')).toBe(true); // Luhn-valid…
+    expect(isValidCardNumber('79927398713')).toBe(false); // …but only 11 digits
+  });
+
+  it('rejects a bad checksum', () => {
+    expect(isValidCardNumber('4111 1111 1111 1112')).toBe(false);
+  });
+});
diff --git a/core/platform/src/multi/card/validate.ts b/core/platform/src/multi/card/validate.ts
new file mode 100644
index 0000000..96d59a1
--- /dev/null
+++ b/core/platform/src/multi/card/validate.ts
@@ -0,0 +1,36 @@
+import { luhn } from '@robonen/encoding';
+import { CARD_BRANDS } from './card-brands';
+import type { CardBrand } from './card-brands';
+import { findCardBrand } from './find-card-brand';
+
+const NON_DIGIT = /\D/g;
+
+/**
+ * @name isValidCardNumber
+ * @category Multi
+ * @description Whether `value` is a complete, valid payment-card number: it passes
+ * the Luhn checksum (`luhn` from `@robonen/encoding`) AND its digit length matches
+ * the detected {@link findCardBrand} brand (or the 12–19 digit ISO/IEC 7812 range
+ * when the brand is unknown). For the bare checksum, use `luhn` directly.
+ *
+ * @param {string} value The card number (separators allowed)
+ * @param {readonly CardBrand[]} [brands=CARD_BRANDS] The brand list
+ * @returns {boolean} Whether the number is structurally valid
+ *
+ * @example
+ * isValidCardNumber('4111 1111 1111 1111'); // true
+ * isValidCardNumber('4111 1111 1111');      // false (wrong length)
+ *
+ * @since 0.0.5
+ */
+export function isValidCardNumber(value: string, brands: readonly CardBrand[] = CARD_BRANDS): boolean {
+  if (!luhn(value))
+    return false;
+
+  const digits = value.replaceAll(NON_DIGIT, '');
+  const brand = findCardBrand(digits, brands);
+
+  return brand
+    ? brand.lengths.includes(digits.length)
+    : digits.length >= 12 && digits.length <= 19;
+}
diff --git a/core/platform/src/multi/index.ts b/core/platform/src/multi/index.ts
index 7afcc36..75d09c4 100644
--- a/core/platform/src/multi/index.ts
+++ b/core/platform/src/multi/index.ts
@@ -1 +1,3 @@
+export * from './card';
 export * from './global';
+export * from './intl';
diff --git a/core/platform/src/multi/intl/find-phone-country.test.ts b/core/platform/src/multi/intl/find-phone-country.test.ts
new file mode 100644
index 0000000..895a8c5
--- /dev/null
+++ b/core/platform/src/multi/intl/find-phone-country.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { findPhoneCountry } from './find-phone-country';
+import { PHONE_COUNTRIES } from './phone-countries';
+
+describe(findPhoneCountry, () => {
+  it('every dialing code is prefix-free', () => {
+    const codes = PHONE_COUNTRIES.map(country => country.code);
+    expect(codes.some(a => codes.some(b => a !== b && b.startsWith(a)))).toBe(false);
+  });
+
+  it('returns the primary country for a shared code when no area code matches', () => {
+    expect(findPhoneCountry('12025550123')?.iso2).toBe('us');
+    expect(findPhoneCountry('74951234567')?.iso2).toBe('ru');
+  });
+
+  it('disambiguates a shared code by area code', () => {
+    expect(findPhoneCountry('14165550123')?.iso2).toBe('ca'); // +1 416 → Canada
+    expect(findPhoneCountry('12425550123')?.iso2).toBe('bs'); // +1 242 → Bahamas
+    expect(findPhoneCountry('73101234567')?.iso2).toBe('kz'); // +7 310 → Kazakhstan
+  });
+
+  it('matches a unique long code', () => {
+    expect(findPhoneCountry('380441234567')?.iso2).toBe('ua');
+  });
+
+  it('returns undefined for empty or unknown input', () => {
+    expect(findPhoneCountry('')).toBeUndefined();
+    expect(findPhoneCountry('000')).toBeUndefined();
+  });
+});
diff --git a/core/platform/src/multi/intl/find-phone-country.ts b/core/platform/src/multi/intl/find-phone-country.ts
new file mode 100644
index 0000000..222f651
--- /dev/null
+++ b/core/platform/src/multi/intl/find-phone-country.ts
@@ -0,0 +1,109 @@
+import { PHONE_COUNTRIES } from './phone-countries';
+import type { PhoneCountry } from './phone-countries';
+
+function buildPhoneIndex(countries: readonly PhoneCountry[]): Map<string, PhoneCountry[]> {
+  const index = new Map<string, PhoneCountry[]>();
+
+  for (const country of countries) {
+    let bucket = index.get(country.code);
+    if (!bucket) {
+      bucket = [];
+      index.set(country.code, bucket);
+    }
+    bucket.push(country);
+  }
+
+  return index;
+}
+
+// O(1) lookup over the default dataset, keyed by dialing code. Codes are
+// prefix-free (E.164), so probing the first 3..1 digits finds the unique code —
+// far cheaper than scanning all ~211 countries on every keystroke.
+const PHONE_INDEX = buildPhoneIndex(PHONE_COUNTRIES);
+
+/**
+ * Among countries sharing a dialing code, pick the most specific matching area
+ * code, else the lowest priority (the primary country). `rest` is the digits
+ * after the dialing code.
+ */
+function resolveGroup(group: readonly PhoneCountry[], rest: string): PhoneCountry | undefined {
+  const first = group[0];
+  if (!first)
+    return undefined;
+  if (group.length === 1)
+    return first;
+
+  let best: PhoneCountry | undefined;
+  let bestAreaLength = 0;
+  for (const country of group) {
+    for (const area of country.areaCodes ?? []) {
+      if (area.length > bestAreaLength && rest.startsWith(area)) {
+        best = country;
+        bestAreaLength = area.length;
+      }
+    }
+  }
+  if (best)
+    return best;
+
+  return group.reduce((winner, country) =>
+    (winner.priority ?? 0) <= (country.priority ?? 0) ? winner : country);
+}
+
+/**
+ * @name findPhoneCountry
+ * @category Multi
+ * @description Resolve a digit string to its country among a {@link PhoneCountry}
+ * list. Matches the **longest dialing code** (codes are prefix-free, so this is
+ * unambiguous), then — for countries sharing a code (NANP `+1`, `+7` RU/KZ) — the
+ * most specific **area code**, then the lowest **priority** (the primary country)
+ * when no area code matches. The default dataset is indexed for O(1) lookup; a
+ * custom list falls back to a linear scan.
+ *
+ * @param {string} digits The number's digits (no `+`/separators), e.g. `'14165550123'`
+ * @param {readonly PhoneCountry[]} [countries=PHONE_COUNTRIES] The country list
+ * @returns {PhoneCountry | undefined} The matched country, or `undefined`
+ *
+ * @example
+ * findPhoneCountry('12025550123')?.iso2; // 'us'
+ * findPhoneCountry('14165550123')?.iso2; // 'ca' (area code 416)
+ * findPhoneCountry('12425550123')?.iso2; // 'bs' (area code 242)
+ *
+ * @since 0.0.5
+ */
+export function findPhoneCountry(
+  digits: string,
+  countries: readonly PhoneCountry[] = PHONE_COUNTRIES,
+): PhoneCountry | undefined {
+  if (!digits)
+    return undefined;
+
+  // Fast path: the default dataset is indexed by dialing code.
+  if (countries === PHONE_COUNTRIES) {
+    for (let length = Math.min(3, digits.length); length >= 1; length--) {
+      const bucket = PHONE_INDEX.get(digits.slice(0, length));
+      if (bucket)
+        return resolveGroup(bucket, digits.slice(length));
+    }
+    return undefined;
+  }
+
+  // Fallback (custom list): longest dialing-code prefix via a linear scan.
+  let codeLength = -1;
+  const group: PhoneCountry[] = [];
+  for (const country of countries) {
+    if (!digits.startsWith(country.code))
+      continue;
+
+    if (country.code.length > codeLength) {
+      codeLength = country.code.length;
+      group.length = 0;
+      group.push(country);
+    }
+    else if (country.code.length === codeLength) {
+      group.push(country);
+    }
+  }
+
+  return codeLength === -1 ? undefined : resolveGroup(group, digits.slice(codeLength));
+}
diff --git a/core/platform/src/multi/intl/flag.test.ts b/core/platform/src/multi/intl/flag.test.ts
new file mode 100644
index 0000000..ca00773
--- /dev/null
+++ b/core/platform/src/multi/intl/flag.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { getCountryFlagByCode } from './flag';
+
+describe(getCountryFlagByCode, () => {
+  it('maps alpha-2 codes to flag emoji', () => {
+    expect(getCountryFlagByCode('US')).toBe('🇺🇸');
+    expect(getCountryFlagByCode('UA')).toBe('🇺🇦');
+    expect(getCountryFlagByCode('GB')).toBe('🇬🇧');
+  });
+
+  it('is case-insensitive', () => {
+    expect(getCountryFlagByCode('gb')).toBe(getCountryFlagByCode('GB'));
+  });
+
+  it('returns an empty string for invalid input', () => {
+    expect(getCountryFlagByCode('1')).toBe('');
+    expect(getCountryFlagByCode('USA')).toBe('');
+    expect(getCountryFlagByCode('u')).toBe('');
+    expect(getCountryFlagByCode('')).toBe('');
+  });
+});
diff --git a/core/platform/src/multi/intl/flag.ts b/core/platform/src/multi/intl/flag.ts
new file mode 100644
index 0000000..ab175e2
--- /dev/null
+++ b/core/platform/src/multi/intl/flag.ts
@@ -0,0 +1,34 @@
+// Offset from an ASCII uppercase letter to its Unicode regional indicator
+// symbol: 'A' (U+0041) → 🇦 (U+1F1E6).
+const REGIONAL_INDICATOR_OFFSET = 0x1F1E6 - 'A'.charCodeAt(0);
+const ALPHA2 = /^[a-z]{2}$/i;
+
+/**
+ * @name getCountryFlagByCode
+ * @category Multi
+ * @description Convert an ISO 3166-1 alpha-2 country code (e.g. `'RU'`, `'us'`)
+ * into its flag emoji by mapping each letter to a Unicode regional indicator
+ * symbol. Case-insensitive; returns an empty string for anything that isn't two
+ * ASCII letters. Pure and environment-agnostic.
+ *
+ * @param {string} code The ISO 3166-1 alpha-2 code, e.g. `'US'`
+ * @returns {string} The flag emoji (e.g. `'🇺🇸'`), or `''` when the code is invalid
+ *
+ * @example
+ * getCountryFlagByCode('RU'); // '🇷🇺'
+ * getCountryFlagByCode('us'); // '🇺🇸'
+ * getCountryFlagByCode('123'); // ''
+ *
+ * @since 0.0.5
+ */
+export function getCountryFlagByCode(code: string): string {
+  if (!ALPHA2.test(code))
+    return '';
+
+  const upper = code.toUpperCase();
+
+  return String.fromCodePoint(
+    REGIONAL_INDICATOR_OFFSET + upper.charCodeAt(0),
+    REGIONAL_INDICATOR_OFFSET + upper.charCodeAt(1),
+  );
+}
diff --git a/core/platform/src/multi/intl/index.ts b/core/platform/src/multi/intl/index.ts
new file mode 100644
index 0000000..9817f4b
--- /dev/null
+++ b/core/platform/src/multi/intl/index.ts
@@ -0,0 +1,3 @@
+export * from './flag';
+export * from './find-phone-country';
+export * from './phone-countries';
diff --git a/core/platform/src/multi/intl/phone-countries.ts b/core/platform/src/multi/intl/phone-countries.ts
new file mode 100644
index 0000000..31bb662
--- /dev/null
+++ b/core/platform/src/multi/intl/phone-countries.ts
@@ -0,0 +1,247 @@
+/**
+ * Phone-number formats for every country: an international template with the
+ * dialing-code digits as `#` digit placeholders, plus the `priority`/`areaCodes`
+ * used to disambiguate countries sharing a dialing code (NANP `+1`, `+7` RU/KZ).
+ * NANP territories are normalized to code `'1'` (their 3-digit prefix moved into
+ * `areaCodes`), so every dialing code is prefix-free and the `+1` block shares one
+ * numbering-plan template. Derived from the MIT-licensed `react-phone-input-2`
+ * dataset — display formats, not authoritative validation.
+ */
+
+/**
+ * One country's phone-number format.
+ */
+export interface PhoneCountry {
+  /** Display name, e.g. `'United States'` (omit for custom lists). */
+  readonly name?: string;
+  /** ISO 3166-1 alpha-2 code, lowercase, e.g. `'us'` (omit for custom lists). */
+  readonly iso2?: string;
+  /** International dialing code digits (no `+`), e.g. `'1'`, `'380'`. */
+  readonly code: string;
+  /** International template; `#` is a digit, e.g. `'+# (###) ###-####'`. */
+  readonly template: string;
+  /**
+   * Order among countries sharing `code` — lower wins when no area code matches.
+   * Absent means `0` (the primary country for that code).
+   */
+  readonly priority?: number;
+  /** Area codes (the digits right after `code`) that belong to this country. */
+  readonly areaCodes?: readonly string[];
+}
+
+/**
+ * Every supported country. Resolve a number with `findPhoneCountry`.
+ */
+export const PHONE_COUNTRIES: readonly PhoneCountry[] = [
+  { name: 'Afghanistan', iso2: 'af', code: '93', template: '+## #############' },
+  { name: 'Albania', iso2: 'al', code: '355', template: '+### ############' },
+  { name: 'Algeria', iso2: 'dz', code: '213', template: '+### ############' },
+  { name: 'Andorra', iso2: 'ad', code: '376', template: '+### ############' },
+  { name: 'Angola', iso2: 'ao', code: '244', template: '+### ############' },
+  { name: 'Antigua and Barbuda', iso2: 'ag', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['268'] },
+  { name: 'Argentina', iso2: 'ar', code: '54', template: '+## (##) ########' },
+  { name: 'Armenia', iso2: 'am', code: '374', template: '+### ## ######' },
+  { name: 'Aruba', iso2: 'aw', code: '297', template: '+### ############' },
+  { name: 'Australia', iso2: 'au', code: '61', template: '+## (##) #### ####' },
+  { name: 'Austria', iso2: 'at', code: '43', template: '+## #############' },
+  { name: 'Azerbaijan', iso2: 'az', code: '994', template: '+### (##) ### ## ##' },
+  { name: 'Bahamas', iso2: 'bs', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['242'] },
+  { name: 'Bahrain', iso2: 'bh', code: '973', template: '+### ############' },
+  { name: 'Bangladesh', iso2: 'bd', code: '880', template: '+### ############' },
+  { name: 'Barbados', iso2: 'bb', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['246'] },
+  { name: 'Belarus', iso2: 'by', code: '375', template: '+### (##) ### ## ##' },
+  { name: 'Belgium', iso2: 'be', code: '32', template: '+## ### ## ## ##' },
+  { name: 'Belize', iso2: 'bz', code: '501', template: '+### ############' },
+  { name: 'Benin', iso2: 'bj', code: '229', template: '+### ############' },
+  { name: 'Bhutan', iso2: 'bt', code: '975', template: '+### ############' },
+  { name: 'Bolivia', iso2: 'bo', code: '591', template: '+### ############' },
+  { name: 'Bosnia and Herzegovina', iso2: 'ba', code: '387', template: '+### ############' },
+  { name: 'Botswana', iso2: 'bw', code: '267', template: '+### ############' },
+  { name: 'Brazil', iso2: 'br', code: '55', template: '+## (##) #########' },
+  { name: 'British Indian Ocean Territory', iso2: 'io', code: '246', template: '+### ############' },
+  { name: 'Brunei', iso2: 'bn', code: '673', template: '+### ############' },
+  { name: 'Bulgaria', iso2: 'bg', code: '359', template: '+### ############' },
+  { name: 'Burkina Faso', iso2: 'bf', code: '226', template: '+### ############' },
+  { name: 'Burundi', iso2: 'bi', code: '257', template: '+### ############' },
+  { name: 'Cambodia', iso2: 'kh', code: '855', template: '+### ############' },
+  { name: 'Cameroon', iso2: 'cm', code: '237', template: '+### ############' },
+  { name: 'Canada', iso2: 'ca', code: '1', template: '+# (###) ###-####', priority: 1, areaCodes: ['204', '226', '236', '249', '250', '289', '306', '343', '365', '387', '403', '416', '418', '431', '437', '438', '450', '506', '514', '519', '548', '579', '581', '587', '604', '613', '639', '647', '672', '705', '709', '742', '778', '780', '782', '807', '819', '825', '867', '873', '902', '905'] },
+  { name: 'Cape Verde', iso2: 'cv', code: '238', template: '+### ############' },
+  { name: 'Caribbean Netherlands', iso2: 'bq', code: '599', template: '+### ############', priority: 1 },
+  { name: 'Central African Republic', iso2: 'cf', code: '236', template: '+### ############' },
+  { name: 'Chad', iso2: 'td', code: '235', template: '+### ############' },
+  { name: 'Chile', iso2: 'cl', code: '56', template: '+## #############' },
+  { name: 'China', iso2: 'cn', code: '86', template: '+## ##-#########' },
+  { name: 'Colombia', iso2: 'co', code: '57', template: '+## ### ### ####' },
+  { name: 'Comoros', iso2: 'km', code: '269', template: '+### ############' },
+  { name: 'Congo', iso2: 'cd', code: '243', template: '+### ############' },
+  { name: 'Congo', iso2: 'cg', code: '242', template: '+### ############' },
+  { name: 'Costa Rica', iso2: 'cr', code: '506', template: '+### ####-####' },
+  { name: 'Côte d’Ivoire', iso2: 'ci', code: '225', template: '+### ## ## ## ##' },
+  { name: 'Croatia', iso2: 'hr', code: '385', template: '+### ############' },
+  { name: 'Cuba', iso2: 'cu', code: '53', template: '+## #############' },
+  { name: 'Curaçao', iso2: 'cw', code: '599', template: '+### ############' },
+  { name: 'Cyprus', iso2: 'cy', code: '357', template: '+### ## ######' },
+  { name: 'Czech Republic', iso2: 'cz', code: '420', template: '+### ### ### ###' },
+  { name: 'Denmark', iso2: 'dk', code: '45', template: '+## ## ## ## ##' },
+  { name: 'Djibouti', iso2: 'dj', code: '253', template: '+### ############' },
+  { name: 'Dominica', iso2: 'dm', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['767'] },
+  { name: 'Dominican Republic', iso2: 'do', code: '1', template: '+# (###) ###-####', priority: 2, areaCodes: ['809', '829', '849'] },
+  { name: 'Ecuador', iso2: 'ec', code: '593', template: '+### ############' },
+  { name: 'Egypt', iso2: 'eg', code: '20', template: '+## #############' },
+  { name: 'El Salvador', iso2: 'sv', code: '503', template: '+### ####-####' },
+  { name: 'Equatorial Guinea', iso2: 'gq', code: '240', template: '+### ############' },
+  { name: 'Eritrea', iso2: 'er', code: '291', template: '+### ############' },
+  { name: 'Estonia', iso2: 'ee', code: '372', template: '+### #### ######' },
+  { name: 'Ethiopia', iso2: 'et', code: '251', template: '+### ############' },
+  { name: 'Fiji', iso2: 'fj', code: '679', template: '+### ############' },
+  { name: 'Finland', iso2: 'fi', code: '358', template: '+### ## ### ## ##' },
+  { name: 'France', iso2: 'fr', code: '33', template: '+## # ## ## ## ##' },
+  { name: 'French Guiana', iso2: 'gf', code: '594', template: '+### ############' },
+  { name: 'French Polynesia', iso2: 'pf', code: '689', template: '+### ############' },
+  { name: 'Gabon', iso2: 'ga', code: '241', template: '+### ############' },
+  { name: 'Gambia', iso2: 'gm', code: '220', template: '+### ############' },
+  { name: 'Georgia', iso2: 'ge', code: '995', template: '+### ############' },
+  { name: 'Germany', iso2: 'de', code: '49', template: '+## #### ########' },
+  { name: 'Ghana', iso2: 'gh', code: '233', template: '+### ############' },
+  { name: 'Greece', iso2: 'gr', code: '30', template: '+## #############' },
+  { name: 'Grenada', iso2: 'gd', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['473'] },
+  { name: 'Guadeloupe', iso2: 'gp', code: '590', template: '+### ############' },
+  { name: 'Guam', iso2: 'gu', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['671'] },
+  { name: 'Guatemala', iso2: 'gt', code: '502', template: '+### ####-####' },
+  { name: 'Guinea', iso2: 'gn', code: '224', template: '+### ############' },
+  { name: 'Guinea-Bissau', iso2: 'gw', code: '245', template: '+### ############' },
+  { name: 'Guyana', iso2: 'gy', code: '592', template: '+### ############' },
+  { name: 'Haiti', iso2: 'ht', code: '509', template: '+### ####-####' },
+  { name: 'Honduras', iso2: 'hn', code: '504', template: '+### ############' },
+  { name: 'Hong Kong', iso2: 'hk', code: '852', template: '+### #### ####' },
+  { name: 'Hungary', iso2: 'hu', code: '36', template: '+## #############' },
+  { name: 'Iceland', iso2: 'is', code: '354', template: '+### ### ####' },
+  { name: 'India', iso2: 'in', code: '91', template: '+## #####-#####' },
+  { name: 'Indonesia', iso2: 'id', code: '62', template: '+## #############' },
+  { name: 'Iran', iso2: 'ir', code: '98', template: '+## ### ### ####' },
+  { name: 'Iraq', iso2: 'iq', code: '964', template: '+### ############' },
+  { name: 'Ireland', iso2: 'ie', code: '353', template: '+### ## #######' },
+  { name: 'Israel', iso2: 'il', code: '972', template: '+### ### ### ####' },
+  { name: 'Italy', iso2: 'it', code: '39', template: '+## ### #######' },
+  { name: 'Jamaica', iso2: 'jm', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['876'] },
+  { name: 'Japan', iso2: 'jp', code: '81', template: '+## ## #### ####' },
+  { name: 'Jordan', iso2: 'jo', code: '962', template: '+### ############' },
+  { name: 'Kazakhstan', iso2: 'kz', code: '7', template: '+# (###) ###-##-##', priority: 1, areaCodes: ['310', '311', '312', '313', '315', '318', '321', '324', '325', '326', '327', '336', '7172', '73622'] },
+  { name: 'Kenya', iso2: 'ke', code: '254', template: '+### ############' },
+  { name: 'Kiribati', iso2: 'ki', code: '686', template: '+### ############' },
+  { name: 'Kosovo', iso2: 'xk', code: '383', template: '+### ############' },
+  { name: 'Kuwait', iso2: 'kw', code: '965', template: '+### ############' },
+  { name: 'Kyrgyzstan', iso2: 'kg', code: '996', template: '+### ### ### ###' },
+  { name: 'Laos', iso2: 'la', code: '856', template: '+### ############' },
+  { name: 'Latvia', iso2: 'lv', code: '371', template: '+### ## ### ###' },
+  { name: 'Lebanon', iso2: 'lb', code: '961', template: '+### ############' },
+  { name: 'Lesotho', iso2: 'ls', code: '266', template: '+### ############' },
+  { name: 'Liberia', iso2: 'lr', code: '231', template: '+### ############' },
+  { name: 'Libya', iso2: 'ly', code: '218', template: '+### ############' },
+  { name: 'Liechtenstein', iso2: 'li', code: '423', template: '+### ############' },
+  { name: 'Lithuania', iso2: 'lt', code: '370', template: '+### ############' },
+  { name: 'Luxembourg', iso2: 'lu', code: '352', template: '+### ############' },
+  { name: 'Macau', iso2: 'mo', code: '853', template: '+### ############' },
+  { name: 'Macedonia', iso2: 'mk', code: '389', template: '+### ############' },
+  { name: 'Madagascar', iso2: 'mg', code: '261', template: '+### ############' },
+  { name: 'Malawi', iso2: 'mw', code: '265', template: '+### ############' },
+  { name: 'Malaysia', iso2: 'my', code: '60', template: '+## ##-####-####' },
+  { name: 'Maldives', iso2: 'mv', code: '960', template: '+### ############' },
+  { name: 'Mali', iso2: 'ml', code: '223', template: '+### ############' },
+  { name: 'Malta', iso2: 'mt', code: '356', template: '+### ############' },
+  { name: 'Marshall Islands', iso2: 'mh', code: '692', template: '+### ############' },
+  { name: 'Martinique', iso2: 'mq', code: '596', template: '+### ############' },
+  { name: 'Mauritania', iso2: 'mr', code: '222', template: '+### ############' },
+  { name: 'Mauritius', iso2: 'mu', code: '230', template: '+### ############' },
+  { name: 'Mexico', iso2: 'mx', code: '52', template: '+## ### ### ####' },
+  { name: 'Micronesia', iso2: 'fm', code: '691', template: '+### ############' },
+  { name: 'Moldova', iso2: 'md', code: '373', template: '+### (##) ##-##-##' },
+  { name: 'Monaco', iso2: 'mc', code: '377', template: '+### ############' },
+  { name: 'Mongolia', iso2: 'mn', code: '976', template: '+### ############' },
+  { name: 'Montenegro', iso2: 'me', code: '382', template: '+### ############' },
+  { name: 'Morocco', iso2: 'ma', code: '212', template: '+### ############' },
+  { name: 'Mozambique', iso2: 'mz', code: '258', template: '+### ############' },
+  { name: 'Myanmar', iso2: 'mm', code: '95', template: '+## #############' },
+  { name: 'Namibia', iso2: 'na', code: '264', template: '+### ############' },
+  { name: 'Nauru', iso2: 'nr', code: '674', template: '+### ############' },
+  { name: 'Nepal', iso2: 'np', code: '977', template: '+### ############' },
+  { name: 'Netherlands', iso2: 'nl', code: '31', template: '+## ## ########' },
+  { name: 'New Caledonia', iso2: 'nc', code: '687', template: '+### ############' },
+  { name: 'New Zealand', iso2: 'nz', code: '64', template: '+## ###-###-####' },
+  { name: 'Nicaragua', iso2: 'ni', code: '505', template: '+### ############' },
+  { name: 'Niger', iso2: 'ne', code: '227', template: '+### ############' },
+  { name: 'Nigeria', iso2: 'ng', code: '234', template: '+### ############' },
+  { name: 'North Korea', iso2: 'kp', code: '850', template: '+### ############' },
+  { name: 'Norway', iso2: 'no', code: '47', template: '+## ### ## ###' },
+  { name: 'Oman', iso2: 'om', code: '968', template: '+### ############' },
+  { name: 'Pakistan', iso2: 'pk', code: '92', template: '+## ###-#######' },
+  { name: 'Palau', iso2: 'pw', code: '680', template: '+### ############' },
+  { name: 'Palestine', iso2: 'ps', code: '970', template: '+### ############' },
+  { name: 'Panama', iso2: 'pa', code: '507', template: '+### ############' },
+  { name: 'Papua New Guinea', iso2: 'pg', code: '675', template: '+### ############' },
+  { name: 'Paraguay', iso2: 'py', code: '595', template: '+### ############' },
+  { name: 'Peru', iso2: 'pe', code: '51', template: '+## #############' },
+  { name: 'Philippines', iso2: 'ph', code: '63', template: '+## #### #######' },
+  { name: 'Poland', iso2: 'pl', code: '48', template: '+## ###-###-###' },
+  { name: 'Portugal', iso2: 'pt', code: '351', template: '+### ############' },
+  { name: 'Puerto Rico', iso2: 'pr', code: '1', template: '+# (###) ###-####', priority: 3, areaCodes: ['787', '939'] },
+  { name: 'Qatar', iso2: 'qa', code: '974', template: '+### ############' },
+  { name: 'Réunion', iso2: 're', code: '262', template: '+### ############' },
+  { name: 'Romania', iso2: 'ro', code: '40', template: '+## #############' },
+  { name: 'Russia', iso2: 'ru', code: '7', template: '+# (###) ###-##-##' },
+  { name: 'Rwanda', iso2: 'rw', code: '250', template: '+### ############' },
+  { name: 'Saint Kitts and Nevis', iso2: 'kn', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['869'] },
+  { name: 'Saint Lucia', iso2: 'lc', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['758'] },
+  { name: 'Saint Vincent and the Grenadines', iso2: 'vc', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['784'] },
+  { name: 'Samoa', iso2: 'ws', code: '685', template: '+### ############' },
+  { name: 'San Marino', iso2: 'sm', code: '378', template: '+### ############' },
+  { name: 'São Tomé and Príncipe', iso2: 'st', code: '239', template: '+### ############' },
+  { name: 'Saudi Arabia', iso2: 'sa', code: '966', template: '+### ############' },
+  { name: 'Senegal', iso2: 'sn', code: '221', template: '+### ############' },
+  { name: 'Serbia', iso2: 'rs', code: '381', template: '+### ############' },
+  { name: 'Seychelles', iso2: 'sc', code: '248', template: '+### ############' },
+  { name: 'Sierra Leone', iso2: 'sl', code: '232', template: '+### ############' },
+  { name: 'Singapore', iso2: 'sg', code: '65', template: '+## ####-####' },
+  { name: 'Slovakia', iso2: 'sk', code: '421', template: '+### ############' },
+  { name: 'Slovenia', iso2: 'si', code: '386', template: '+### ############' },
+  { name: 'Solomon Islands', iso2: 'sb', code: '677', template: '+### ############' },
+  { name: 'Somalia', iso2: 'so', code: '252', template: '+### ############' },
+  { name: 'South Africa', iso2: 'za', code: '27', template: '+## #############' },
+  { name: 'South Korea', iso2: 'kr', code: '82', template: '+## ### #### ####' },
+  { name: 'South Sudan', iso2: 'ss', code: '211', template: '+### ############' },
+  { name: 'Spain', iso2: 'es', code: '34', template: '+## ### ### ###' },
+  { name: 'Sri Lanka', iso2: 'lk', code: '94', template: '+## #############' },
+  { name: 'Sudan', iso2: 'sd', code: '249', template: '+### ############' },
+  { name: 'Suriname', iso2: 'sr', code: '597', template: '+### ############' },
+  { name: 'Swaziland', iso2: 'sz', code: '268', template: '+### ############' },
+  { name: 'Sweden', iso2: 'se', code: '46', template: '+## (###) ###-###' },
+  { name: 'Switzerland', iso2: 'ch', code: '41', template: '+## ## ### ## ##' },
+  { name: 'Syria', iso2: 'sy', code: '963', template: '+### ############' },
+  { name: 'Taiwan', iso2: 'tw', code: '886', template: '+### ############' },
+  { name: 'Tajikistan', iso2: 'tj', code: '992', template: '+### ############' },
+  { name: 'Tanzania', iso2: 'tz', code: '255', template: '+### ############' },
+  { name: 'Thailand', iso2: 'th', code: '66', template: '+## #############' },
+  { name: 'Timor-Leste', iso2: 'tl', code: '670', template: '+### ############' },
+  { name: 'Togo', iso2: 'tg', code: '228', template: '+### ############' },
+  { name: 'Tonga', iso2: 'to', code: '676', template: '+### ############' },
+  { name: 'Trinidad and Tobago', iso2: 'tt', code: '1', template: '+# (###) ###-####', priority: 10, areaCodes: ['868'] },
+  { name: 'Tunisia', iso2: 'tn', code: '216', template: '+### ############' },
+  { name: 'Turkey', iso2: 'tr', code: '90', template: '+## ### ### ## ##' },
+  { name: 'Turkmenistan', iso2: 'tm', code: '993', template: '+### ############' },
+  { name: 'Tuvalu', iso2: 'tv', code: '688', template: '+### ############' },
+  { name: 'Uganda', iso2: 'ug', code: '256', template: '+### ############' },
+  { name: 'Ukraine', iso2: 'ua', code: '380', template: '+### (##) ### ## ##' },
+  { name: 'United Arab Emirates', iso2: 'ae', code: '971', template: '+### ############' },
+  { name: 'United Kingdom', iso2: 'gb', code: '44', template: '+## #### ######' },
+  { name: 'United States', iso2: 'us', code: '1', template: '+# (###) ###-####' },
+  { name: 'Uruguay', iso2: 'uy', code: '598', template: '+### ############' },
+  { name: 'Uzbekistan', iso2: 'uz', code: '998', template: '+### ## ### ## ##' },
+  { name: 'Vanuatu', iso2: 'vu', code: '678', template: '+### ############' },
+  { name: 'Vatican City', iso2: 'va', code: '39', template: '+## ### #######', priority: 1 },
+  { name: 'Venezuela', iso2: 've', code: '58', template: '+## #############' },
+  { name: 'Vietnam', iso2: 'vn', code: '84', template: '+## #############' },
+  { name: 'Yemen', iso2: 'ye', code: '967', template: '+### ############' },
+  { name: 'Zambia', iso2: 'zm', code: '260', template: '+### ############' },
+  { name: 'Zimbabwe', iso2: 'zw', code: '263', template: '+### ############' },
+];
diff --git a/docs/app/components/DocsComponentAnatomy.vue b/docs/app/components/DocsComponentAnatomy.vue
index 15977d9..1a2d71d 100644
--- a/docs/app/components/DocsComponentAnatomy.vue
+++ b/docs/app/components/DocsComponentAnatomy.vue
@@ -19,7 +19,10 @@ const anatomyCode = computed(() => {
 
   const imports = `import {\n${names.map(n => `  ${n},`).join('\n')}\n} from '${importPath.value}';`;
 
-  const [root, ...rest] = names;
+  // Wrap the skeleton in the Root part (not whatever the barrel exports first),
+  // with the remaining parts nested inside it.
+  const root = (props.component.parts.find(p => p.role === 'Root') ?? props.component.parts[0]!).name;
+  const rest = names.filter(n => n !== root);
   let tree: string;
   if (rest.length === 0) {
     tree = `<${root} />`;
diff --git a/docs/app/components/DocsDemo.vue b/docs/app/components/DocsDemo.vue
index 8e1962c..69eb50f 100644
--- a/docs/app/components/DocsDemo.vue
+++ b/docs/app/components/DocsDemo.vue
@@ -1,19 +1,25 @@
 <script setup lang="ts">
 import type { Component } from 'vue';
+import { demoSources } from '#docs/demo-sources';
 
 const props = defineProps<{
   component: Component;
-  source: string;
+  /** Key into the lazy demo-source map (`${pkg}/${slug}`). */
+  sourceKey: string;
 }>();
 
 const showSource = ref(false);
+const source = ref('');
 
 const { highlighted, highlightReactive } = useShiki();
 
+// Fetch the raw demo source only when the user first opens it, then highlight.
 watch(showSource, async (show) => {
-  if (show && !highlighted.value) {
-    await highlightReactive(props.source, 'vue');
-  }
+  if (!show) return;
+  if (!source.value)
+    source.value = (await demoSources[props.sourceKey]?.()) ?? '';
+  if (source.value && !highlighted.value)
+    await highlightReactive(source.value, 'vue');
 });
 </script>
 
diff --git a/docs/app/components/DocsMethodsList.vue b/docs/app/components/DocsMethodsList.vue
index 53ed88c..bdf7e08 100644
--- a/docs/app/components/DocsMethodsList.vue
+++ b/docs/app/components/DocsMethodsList.vue
@@ -23,7 +23,7 @@ defineProps<{
       </div>
 
       <p v-if="method.description" class="text-sm text-(--fg-muted) mb-3">
-        {{ method.description }}
+        <DocsText :text="method.description" />
       </p>
 
       <DocsCode
@@ -38,7 +38,7 @@ defineProps<{
       <div v-if="method.returns" class="mt-2 text-sm">
         <span class="text-(--fg-subtle)">Returns</span>
         <code class="ml-1.5 text-xs font-mono bg-(--bg-inset) border border-(--border) px-1.5 py-0.5 rounded">{{ method.returns.type }}</code>
-        <span v-if="method.returns.description" class="ml-2 text-(--fg-muted)">{{ method.returns.description }}</span>
+        <DocsText v-if="method.returns.description" :text="method.returns.description" class="ml-2 text-(--fg-muted)" />
       </div>
     </div>
   </div>
diff --git a/docs/app/components/DocsParamsTable.vue b/docs/app/components/DocsParamsTable.vue
index 3ddae0a..11718be 100644
--- a/docs/app/components/DocsParamsTable.vue
+++ b/docs/app/components/DocsParamsTable.vue
@@ -33,7 +33,8 @@ defineProps<{
             <span v-else class="text-(--fg-subtle)">—</span>
           </td>
           <td class="py-2.5 px-4 text-(--fg-muted) min-w-48">
-            {{ param.description || '—' }}
+            <DocsText v-if="param.description" :text="param.description" />
+            <span v-else>—</span>
           </td>
         </tr>
       </tbody>
diff --git a/docs/app/components/DocsPropsTable.vue b/docs/app/components/DocsPropsTable.vue
index 399e4ee..3949146 100644
--- a/docs/app/components/DocsPropsTable.vue
+++ b/docs/app/components/DocsPropsTable.vue
@@ -36,7 +36,8 @@ defineProps<{
             <span v-else class="text-(--fg-subtle)">—</span>
           </td>
           <td class="py-2.5 px-4 text-(--fg-muted) min-w-48">
-            {{ prop.description || '—' }}
+            <DocsText v-if="prop.description" :text="prop.description" />
+            <span v-else>—</span>
           </td>
         </tr>
       </tbody>
diff --git a/docs/app/components/DocsText.vue b/docs/app/components/DocsText.vue
new file mode 100644
index 0000000..b32a4c8
--- /dev/null
+++ b/docs/app/components/DocsText.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// Renders a short description with inline markdown (bold / `code` / links /
+// {@link}). Content is authored by us (JSDoc), so v-html is safe here.
+const props = defineProps<{ text?: string | null }>();
+
+const html = computed(() => renderInline(props.text ?? ''));
+</script>
+
+<template>
+  <span class="docs-text" v-html="html" />
+</template>
+
+<style scoped>
+.docs-text :deep(code) {
+  font-family: ui-monospace, monospace;
+  font-size: 0.9em;
+  background: var(--bg-inset);
+  border: 1px solid var(--border);
+  border-radius: 0.25rem;
+  padding: 0.05em 0.3em;
+}
+
+.docs-text :deep(a) {
+  color: var(--accent-text);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.docs-text :deep(strong) {
+  font-weight: 600;
+  color: var(--fg);
+}
+</style>
diff --git a/docs/app/composables/useMarkdown.ts b/docs/app/composables/useMarkdown.ts
index c7ac126..f93a1cc 100644
--- a/docs/app/composables/useMarkdown.ts
+++ b/docs/app/composables/useMarkdown.ts
@@ -1,5 +1,9 @@
 import { marked } from 'marked';
 
+// JSDoc `{@link Symbol}` / `{@link Symbol|label}`. The capture starts with a
+// non-space char so the leading `\s+` can't overlap it (no super-linear backtracking).
+const JSDOC_LINK = /\{@link\s+([^\s}|][^}|]*)(?:\|[^}]+)?\}/g;
+
 export interface Heading {
   depth: number;
   text: string;
@@ -46,6 +50,17 @@ export function extractHeadings(markdown: string): Heading[] {
   return headings;
 }
 
+/**
+ * Render a short description as INLINE HTML (bold/code/links, no block wrapping).
+ * Used for API/param/property descriptions, which are authored as one-line
+ * markdown with the occasional JSDoc `{@link X}` (shown as inline code).
+ */
+export function renderInline(text: string): string {
+  if (!text) return '';
+  const withLinks = text.replaceAll(JSDOC_LINK, (_m, name: string) => `\`${name.trim()}\``);
+  return marked.parseInline(withLinks, { async: false }) as string;
+}
+
 /** Render markdown to HTML with stable heading ids (matching extractHeadings). */
 export function renderMarkdown(markdown: string): string {
   const seen = new Map<string, number>();
diff --git a/docs/app/pages/[package]/[utility].vue b/docs/app/pages/[package]/[utility].vue
index 2e53eb9..466d47a 100644
--- a/docs/app/pages/[package]/[utility].vue
+++ b/docs/app/pages/[package]/[utility].vue
@@ -118,10 +118,17 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
             <DocsBadge :kind="entry.item.kind" size="md" />
             <h1 class="min-w-0 break-words text-2xl font-bold font-mono tracking-tight text-(--fg)">{{ entry.item.name }}</h1>
             <DocsTag v-if="entry.item.since" :label="`v${entry.item.since}`" variant="neutral" />
-            <DocsTag v-if="entry.item.hasTests" label="tested" variant="test" />
+            <DocsTag
+              v-if="entry.item.hasTests"
+              :label="typeof entry.item.coverage === 'number' ? `tested · ${entry.item.coverage}%` : 'tested'"
+              variant="test"
+              :title="typeof entry.item.coverage === 'number' ? `${entry.item.coverage}% statement coverage` : undefined"
+            />
             <DocsTag v-if="entry.item.hasDemo" label="demo" variant="demo" />
           </div>
-          <p v-if="entry.item.description" class="text-(--fg-muted) text-[15px] leading-relaxed">{{ entry.item.description }}</p>
+          <p v-if="entry.item.description" class="text-(--fg-muted) text-[15px] leading-relaxed">
+            <DocsText :text="entry.item.description" />
+          </p>
           <div class="flex items-center gap-4 mt-4 text-sm">
             <a :href="ghUrl(entry.item.sourcePath)" target="_blank" rel="noopener noreferrer" class="flex items-center gap-1.5 text-(--fg-subtle) hover:text-(--fg) transition-colors">
               <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4" /><path d="M9 18c-4.51 2-5-2-7-2" /></svg>
@@ -143,7 +150,7 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
 
         <section v-if="entry.item.hasDemo && demoComponent" id="demo" class="mb-8 scroll-mt-20">
           <h2 :class="sectionTitle">Demo</h2>
-          <DocsDemo :component="demoComponent" :source="entry.item.demoSource" />
+          <DocsDemo :component="demoComponent" :source-key="`${packageSlug}/${utilitySlug}`" />
         </section>
 
         <section v-if="entry.item.signatures.length" id="signature" class="mb-8 scroll-mt-20">
@@ -171,10 +178,11 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
 
         <section v-if="entry.item.returns" id="returns" class="mb-8 scroll-mt-20">
           <h2 :class="sectionTitle">Returns</h2>
-          <div class="flex items-baseline gap-2 text-sm flex-wrap">
+          <div class="flex items-baseline gap-2 text-sm flex-wrap" :class="entry.item.returns.properties?.length ? 'mb-3' : ''">
             <code class="font-mono bg-(--bg-inset) border border-(--border) px-2 py-1 rounded text-xs wrap-break-word">{{ entry.item.returns.type }}</code>
-            <span v-if="entry.item.returns.description" class="text-(--fg-muted)">{{ entry.item.returns.description }}</span>
+            <DocsText v-if="entry.item.returns.description" :text="entry.item.returns.description" class="text-(--fg-muted)" />
           </div>
+          <DocsPropsTable v-if="entry.item.returns.properties?.length" :properties="entry.item.returns.properties" />
         </section>
 
         <section v-if="entry.item.properties.length" id="properties" class="mb-8 scroll-mt-20">
@@ -195,7 +203,9 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
                 <DocsBadge :kind="rt.kind" size="sm" />
                 <h3 class="font-mono font-semibold text-sm text-(--fg)">{{ rt.name }}</h3>
               </div>
-              <p v-if="rt.description" class="text-sm text-(--fg-muted) mb-3">{{ rt.description }}</p>
+              <p v-if="rt.description" class="text-sm text-(--fg-muted) mb-3">
+                <DocsText :text="rt.description" />
+              </p>
               <DocsCode v-if="rt.signatures.length" :code="rt.signatures[0]!" />
               <DocsPropsTable v-if="rt.properties.length" :properties="rt.properties" class="mt-3" />
             </div>
@@ -211,7 +221,9 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
             <h1 class="text-2xl font-bold tracking-tight text-(--fg)">{{ entry.component.name }}</h1>
             <DocsTag :label="`${entry.component.parts.length} parts`" variant="neutral" />
           </div>
-          <p v-if="entry.component.description" class="text-(--fg-muted) text-[15px] leading-relaxed">{{ entry.component.description }}</p>
+          <p v-if="entry.component.description" class="text-(--fg-muted) text-[15px] leading-relaxed">
+            <DocsText :text="entry.component.description" />
+          </p>
           <div class="flex items-center gap-4 mt-4 text-sm">
             <a :href="ghUrl(entry.component.sourcePath)" target="_blank" rel="noopener noreferrer" class="flex items-center gap-1.5 text-(--fg-subtle) hover:text-(--fg) transition-colors">
               <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4" /><path d="M9 18c-4.51 2-5-2-7-2" /></svg>
@@ -222,7 +234,7 @@ const sectionTitle = 'text-xs font-semibold uppercase tracking-wider text-(--fg-
 
         <section v-if="entry.component.hasDemo && demoComponent" class="mb-10">
           <h2 :class="sectionTitle">Demo</h2>
-          <DocsDemo :component="demoComponent" :source="entry.component.demoSource" />
+          <DocsDemo :component="demoComponent" :source-key="`${packageSlug}/${utilitySlug}`" />
         </section>
 
         <DocsComponentAnatomy :component="entry.component" :package-name="pkg.name" />
diff --git a/docs/modules/extractor/extract.ts b/docs/modules/extractor/extract.ts
index 810b7c0..8dce030 100644
--- a/docs/modules/extractor/extract.ts
+++ b/docs/modules/extractor/extract.ts
@@ -12,8 +12,8 @@
 
 import { basename, dirname, relative, resolve } from 'node:path';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { Project } from 'ts-morph';
-import type { ClassDeclaration, FunctionDeclaration, InterfaceDeclaration, JSDoc, JSDocTag, MethodDeclaration, PropertyDeclaration, PropertySignature, SourceFile, TypeAliasDeclaration } from 'ts-morph';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import type { ClassDeclaration, FunctionDeclaration, InterfaceDeclaration, JSDoc, JSDocTag, MethodDeclaration, PropertyDeclaration, PropertySignature, SourceFile, TypeAliasDeclaration, VariableDeclaration } from 'ts-morph';
 import type {
   CategoryMeta,
   ComponentMeta,
@@ -36,6 +36,34 @@ import type {
 /** Repository root — docs/modules/extractor → three levels up */
 const ROOT = resolve(import.meta.dirname, '..', '..', '..');
 
+/**
+ * Statement-coverage percentage per source file (repo-relative path), parsed
+ * from Istanbul's `coverage/coverage-final.json` if present. Empty when coverage
+ * hasn't been generated — items then simply omit the coverage badge.
+ */
+function loadCoverage(): Map<string, number> {
+  const map = new Map<string, number>();
+  const file = resolve(ROOT, 'coverage', 'coverage-final.json');
+  if (!existsSync(file)) return map;
+
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf-8')) as Record<string, { s?: Record<string, number> }>;
+    for (const [absPath, entry] of Object.entries(data)) {
+      const counts = Object.values(entry.s ?? {});
+      if (counts.length === 0) continue;
+      const covered = counts.filter(c => c > 0).length;
+      map.set(relative(ROOT, absPath), Math.round((covered / counts.length) * 100));
+    }
+  }
+  catch {
+    // Malformed/partial coverage file — skip rather than fail extraction.
+  }
+
+  return map;
+}
+
+const COVERAGE = loadCoverage();
+
 interface PackageConfig {
   /** Path relative to repo root */
   path: string;
@@ -83,6 +111,18 @@ function slugify(name: string): string {
   return toKebabCase(name);
 }
 
+/**
+ * Clean a type string for display: drop the `import("…").` qualifiers the type
+ * checker emits when resolving types (e.g. `import("vue").Ref<T>` → `Ref<T>`) and
+ * collapse whitespace. Prefer this over raw `.getType().getText()`.
+ */
+function cleanType(text: string): string {
+  return text
+    .replaceAll(/import\((?:"[^"]*"|'[^']*')\)\./g, '')
+    .replaceAll(/\s+/g, ' ')
+    .trim();
+}
+
 function toPascalCase(slug: string): string {
   return slug
     .split(/[-_]/)
@@ -118,8 +158,17 @@ function getExamples(tags: JSDocTag[]): string[] {
   return tags
     .filter(t => t.getTagName() === 'example')
     .map((t) => {
-      const text = t.getCommentText()?.trim() ?? '';
-      return text.replace(/^```(?:ts|typescript)?\n?/, '').replace(/\n?```$/, '').trim();
+      let text = t.getCommentText()?.trim() ?? '';
+      // A leading `<caption>…</caption>` (JSDoc example title) isn't valid code —
+      // turn it into a leading comment so the snippet stays clean & highlightable.
+      let caption = '';
+      const cap = text.match(/^<caption>([\s\S]*?)<\/caption>\s*/i);
+      if (cap) {
+        caption = cap[1]!.trim();
+        text = text.slice(cap[0].length);
+      }
+      text = text.replace(/^```(?:ts|typescript|vue|js|javascript)?\n?/, '').replace(/\n?```$/, '').trim();
+      return caption ? `// ${caption}\n${text}` : text;
     })
     .filter(Boolean);
 }
@@ -130,7 +179,9 @@ function extractParams(tags: JSDocTag[], node: FunctionDeclaration | MethodDecla
 
   for (const param of node.getParameters()) {
     const name = param.getName();
-    const type = param.getType().getText(param);
+    // Prefer the written annotation (`MaybeRefOrGetter<T>`) over the resolved
+    // type, which expands aliases into noise (`T | import("vue").Ref<T> | …`).
+    const type = cleanType(param.getTypeNode()?.getText() ?? param.getType().getText(param));
     const optional = param.isOptional();
     const defaultValue = param.getInitializer()?.getText() ?? null;
 
@@ -156,20 +207,75 @@ function extractParams(tags: JSDocTag[], node: FunctionDeclaration | MethodDecla
 function extractTypeParams(node: FunctionDeclaration | ClassDeclaration | InterfaceDeclaration | TypeAliasDeclaration): TypeParamMeta[] {
   return node.getTypeParameters().map(tp => ({
     name: tp.getName(),
-    constraint: tp.getConstraint()?.getText() ?? null,
-    default: tp.getDefault()?.getText() ?? null,
+    constraint: tp.getConstraint() ? cleanType(tp.getConstraint()!.getText()) : null,
+    default: tp.getDefault() ? cleanType(tp.getDefault()!.getText()) : null,
     description: '',
   }));
 }
 
+/**
+ * When a function returns a plain object — a named interface (`UseXReturn`) OR an
+ * inline object literal (`{ first: HTMLElement | undefined; last: … }`) — expand
+ * its properties so the renderer shows a Name/Type/Description table. Skips
+ * unions/intersections, arrays/tuples, callable (function) types, primitives, and
+ * built-ins (`Ref`/`ComputedRef`/`Promise`/`Map`… whose declaration is in
+ * node_modules) — those keep just the type string.
+ */
+function extractReturnProperties(node: FunctionDeclaration | MethodDeclaration): PropertyMeta[] {
+  const returnType = node.getReturnType();
+
+  if (
+    returnType.isUnion()
+    || returnType.isIntersection()
+    || returnType.isArray()
+    || returnType.isTuple()
+    || returnType.getCallSignatures().length > 0
+    || !returnType.isObject()
+  ) {
+    return [];
+  }
+
+  // A named declaration in node_modules (Ref/Promise/Map…) is a built-in we don't
+  // expand; anonymous object literals have no such declaration → keep going.
+  const symbol = returnType.getAliasSymbol() ?? returnType.getSymbol();
+  const decl = symbol?.getDeclarations()?.[0];
+  if (decl && decl.getSourceFile().isInNodeModules())
+    return [];
+
+  const props: PropertyMeta[] = [];
+  for (const prop of returnType.getProperties()) {
+    const propDecl = prop.getDeclarations()?.[0];
+    if (!propDecl || propDecl.getSourceFile().isInNodeModules())
+      continue;
+
+    // Prefer the written annotation (clean); fall back to the resolved type for
+    // method-style members and inferred object-literal returns.
+    const typeNode = Node.isTyped(propDecl) ? propDecl.getTypeNode() : undefined;
+    const jsdocs = Node.isJSDocable(propDecl) ? propDecl.getJsDocs() : [];
+
+    props.push({
+      name: prop.getName(),
+      type: cleanType(typeNode?.getText() ?? prop.getTypeAtLocation(node).getText(node)),
+      description: getDescription(jsdocs, getJsDocTags(jsdocs)),
+      optional: Node.isQuestionTokenable(propDecl) && propDecl.hasQuestionToken(),
+      defaultValue: null,
+      readonly: false,
+    });
+  }
+
+  return props;
+}
+
 function extractReturnMeta(tags: JSDocTag[], node: FunctionDeclaration | MethodDeclaration): ReturnMeta | null {
-  const returnType = node.getReturnType().getText(node);
+  const returnType = cleanType(node.getReturnTypeNode()?.getText() ?? node.getReturnType().getText(node));
   if (returnType === 'void') return null;
 
   const returnsTag = getTagValue(tags, 'returns') || getTagValue(tags, 'return');
   const description = returnsTag.replace(/^\{[^}]*\}\s*/, '').trim();
 
-  return { type: returnType, description };
+  const properties = extractReturnProperties(node);
+
+  return { type: returnType, description, properties };
 }
 
 function extractMethodMeta(method: MethodDeclaration): MethodMeta {
@@ -192,7 +298,7 @@ function extractPropertyMeta(prop: PropertyDeclaration | PropertySignature): Pro
 
   return {
     name: prop.getName(),
-    type: prop.getType().getText(prop),
+    type: cleanType(prop.getTypeNode?.()?.getText() ?? prop.getType().getText(prop)),
     description: getDescription(jsdocs, tags),
     optional: prop.hasQuestionToken?.() ?? false,
     defaultValue: getTagValue(tags, 'default') || null,
@@ -208,10 +314,11 @@ function hasDemoFile(sourceFilePath: string): boolean {
   return existsSync(resolve(getSourceDir(sourceFilePath), 'demo.vue'));
 }
 
-function readDemoSource(sourceFilePath: string): string {
-  const demoPath = resolve(getSourceDir(sourceFilePath), 'demo.vue');
-  if (!existsSync(demoPath)) return '';
-  return readFileSync(demoPath, 'utf-8');
+// Demo SOURCE is loaded lazily on the client (via `#docs/demo-sources`) only when
+// "View source" is opened, so it is intentionally NOT embedded in the metadata
+// payload (it was ~850KB). `hasDemo`/the lazy map carry what the UI needs.
+function readDemoSource(_sourceFilePath: string): string {
+  return '';
 }
 
 function hasTestFile(sourceFilePath: string): boolean {
@@ -274,7 +381,7 @@ function extractClass(cls: ClassDeclaration, sourceFilePath: string, entryPoint:
     .filter(g => (g.getScope() ?? 'public') === 'public')
     .map(g => ({
       name: g.getName(),
-      type: g.getReturnType().getText(g),
+      type: cleanType(g.getReturnTypeNode()?.getText() ?? g.getReturnType().getText(g)),
       description: getDescription(g.getJsDocs(), getJsDocTags(g.getJsDocs())),
       optional: false,
       defaultValue: null,
@@ -377,6 +484,43 @@ function extractTypeAlias(typeAlias: TypeAliasDeclaration, sourceFilePath: strin
   };
 }
 
+function extractVariable(
+  decl: VariableDeclaration,
+  jsdocs: JSDoc[],
+  tags: JSDocTag[],
+  sourceFilePath: string,
+  entryPoint: string,
+): ItemMeta | null {
+  const name = decl.getName();
+  if (!name || name.startsWith('_')) return null;
+
+  const typeText = cleanType(decl.getTypeNode()?.getText() ?? decl.getType().getText(decl));
+  const keyword = decl.getVariableStatement()?.getDeclarationKind() ?? 'const';
+  // Show the declaration shape, not the (potentially huge) initializer value.
+  const signature = `${keyword} ${name}: ${typeText}`;
+
+  return {
+    name,
+    slug: slugify(name),
+    kind: 'variable',
+    description: getDescription(jsdocs, tags),
+    since: getTagValue(tags, 'since'),
+    signatures: [signature],
+    params: [],
+    returns: null,
+    typeParams: [],
+    examples: getExamples(tags),
+    methods: [],
+    properties: [],
+    hasDemo: hasDemoFile(sourceFilePath),
+    demoSource: readDemoSource(sourceFilePath),
+    hasTests: hasTestFile(sourceFilePath),
+    relatedTypes: [],
+    sourcePath: relative(ROOT, sourceFilePath),
+    entryPoint,
+  };
+}
+
 function collectExportedItems(sourceFile: SourceFile, entryPoint: string, visited = new Set<string>()): ItemMeta[] {
   const filePath = sourceFile.getFilePath();
   if (visited.has(filePath)) return [];
@@ -448,6 +592,21 @@ function collectExportedItems(sourceFile: SourceFile, entryPoint: string, visite
     if (item) items.push(item);
   }
 
+  for (const varStatement of sourceFile.getVariableStatements()) {
+    if (!varStatement.isExported()) continue;
+    const jsdocs = varStatement.getJsDocs();
+    const tags = getJsDocTags(jsdocs);
+    // Gate (like types/interfaces): only documented consts, so we don't surface
+    // every internal constant — desirable but not always.
+    const hasCategory = getTagValue(tags, 'category') !== '';
+    if (!hasCategory && jsdocs.length === 0) continue;
+
+    for (const decl of varStatement.getDeclarations()) {
+      const item = extractVariable(decl, jsdocs, tags, filePath, entryPoint);
+      if (item) items.push(item);
+    }
+  }
+
   for (const exportDecl of sourceFile.getExportDeclarations()) {
     if (!exportDecl.getModuleSpecifierValue()) continue;
     const referencedFile = exportDecl.getModuleSpecifierSourceFile();
@@ -461,13 +620,35 @@ function collectExportedItems(sourceFile: SourceFile, entryPoint: string, visite
  * Groups types/interfaces from `types.ts` files with their sibling
  * class/function items from the same directory as `relatedTypes`.
  */
+/**
+ * A trimmed copy of a type/interface for embedding as a primary's `relatedType`:
+ * keeps the shape (signature/properties/description) but drops the heavy fields
+ * (demo source, examples, nested types, params/returns) that would otherwise be
+ * duplicated into the metadata payload.
+ */
+function slimRelatedType(type: ItemMeta): ItemMeta {
+  return {
+    ...type,
+    examples: [],
+    params: [],
+    returns: null,
+    methods: [],
+    relatedTypes: [],
+    hasDemo: false,
+    demoSource: '',
+  };
+}
+
 function groupCoLocatedTypes(items: ItemMeta[]): ItemMeta[] {
   const typesByDir = new Map<string, ItemMeta[]>();
   const primaryByDir = new Map<string, ItemMeta[]>();
 
   for (const item of items) {
     const dir = dirname(item.sourcePath);
-    const isSecondary = item.sourcePath.endsWith('/types.ts') && (item.kind === 'type' || item.kind === 'interface');
+    // Types/interfaces are documentation-secondary: when a function/class lives
+    // in the same directory they fold into it as `relatedTypes` instead of
+    // competing as standalone pages (keeps the reference to the important items).
+    const isSecondary = item.kind === 'type' || item.kind === 'interface';
 
     const target = isSecondary ? typesByDir : primaryByDir;
     const existing = target.get(dir) ?? [];
@@ -479,8 +660,24 @@ function groupCoLocatedTypes(items: ItemMeta[]): ItemMeta[] {
   for (const [dir, types] of Array.from(typesByDir.entries())) {
     const primaries = primaryByDir.get(dir);
     if (!primaries || primaries.length === 0) continue;
-    for (const primary of primaries) primary.relatedTypes = [...types];
-    for (const t of types) absorbed.add(`${t.entryPoint}:${t.name}`);
+
+    for (const type of types) {
+      // Attach each type to the SINGLE most-relevant primary (longest name-prefix
+      // match, else the first) — never every primary — so it isn't duplicated N×,
+      // and store a slim copy (no demo source / nested types).
+      const typeName = type.name.toLowerCase();
+      let owner = primaries[0]!;
+      let bestLen = -1;
+      for (const primary of primaries) {
+        const primaryName = primary.name.toLowerCase();
+        if (typeName.startsWith(primaryName) && primaryName.length > bestLen) {
+          owner = primary;
+          bestLen = primaryName.length;
+        }
+      }
+      owner.relatedTypes.push(slimRelatedType(type));
+      absorbed.add(`${type.entryPoint}:${type.name}`);
+    }
   }
 
   return items.filter(item => !absorbed.has(`${item.entryPoint}:${item.name}`));
@@ -571,6 +768,28 @@ function buildApiCategories(pkgDir: string): CategoryMeta[] {
 
   const groupedItems = groupCoLocatedTypes(uniqueItems);
 
+  // Per-package slug uniqueness — the [package]/[utility] route keys on slug, so
+  // a function `foo` and interface `Foo` (same kebab slug) would otherwise clash.
+  // Functions/classes keep the base slug; lower-priority kinds get suffixed.
+  const KIND_PRIORITY: Record<string, number> = { function: 0, class: 1, variable: 2, enum: 3, interface: 4, type: 5 };
+  const usedSlugs = new Set<string>();
+  for (const item of [...groupedItems].sort((a, b) => (KIND_PRIORITY[a.kind] ?? 9) - (KIND_PRIORITY[b.kind] ?? 9))) {
+    if (!usedSlugs.has(item.slug)) {
+      usedSlugs.add(item.slug);
+      continue;
+    }
+    let candidate = `${item.slug}-${item.kind}`;
+    let n = 2;
+    while (usedSlugs.has(candidate))
+      candidate = `${item.slug}-${item.kind}-${n++}`;
+    item.slug = candidate;
+    usedSlugs.add(candidate);
+  }
+
+  // Attach statement-coverage % (when coverage data exists) for the test badge.
+  for (const item of groupedItems)
+    item.coverage = COVERAGE.get(item.sourcePath) ?? null;
+
   const categoryMap = new Map<string, ItemMeta[]>();
   for (const item of groupedItems) {
     const cat = inferCategoryFromItem(item);
@@ -621,6 +840,43 @@ function extractEmits(setupScript: string): EmitMeta[] {
 
 let partProjectCounter = 0;
 
+/**
+ * Parse `defineModel(...)` calls from a setup block into the v-model prop(s) +
+ * their `update:*` emit(s) — these don't appear in the `XxxProps` interface or
+ * `defineEmits`, so without this the controlled v-model API is invisible in docs.
+ */
+function extractModels(setupScript: string): { props: PropertyMeta[]; emits: EmitMeta[] } {
+  const props: PropertyMeta[] = [];
+  const emits: EmitMeta[] = [];
+  if (!setupScript.includes('defineModel')) return { props, emits };
+
+  const project = new Project({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true, compilerOptions: { allowJs: true, skipLibCheck: true } });
+  const sf = project.createSourceFile(`__model_${partProjectCounter++}.ts`, setupScript);
+
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (call.getExpression().getText() !== 'defineModel') continue;
+
+    const typeArg = call.getTypeArguments()[0];
+    const type = typeArg ? cleanType(typeArg.getText()) : 'unknown';
+    const firstArg = call.getArguments()[0];
+    const name = firstArg && Node.isStringLiteral(firstArg) ? firstArg.getLiteralValue() : 'modelValue';
+
+    props.push({
+      name,
+      type,
+      description: name === 'modelValue'
+        ? 'Two-way bound value (`v-model`).'
+        : `Two-way bound value (\`v-model:${name}\`).`,
+      optional: true,
+      defaultValue: null,
+      readonly: false,
+    });
+    emits.push({ name: `update:${name}`, payload: `[value: ${type}]`, description: '' });
+  }
+
+  return { props, emits };
+}
+
 /** Parse the `XxxProps` interface from a `.vue` part using ts-morph in-memory. */
 function extractPartProps(plainScript: string): { props: PropertyMeta[]; description: string } {
   if (!plainScript.trim()) return { props: [], description: '' };
@@ -688,12 +944,19 @@ function buildComponents(pkgDir: string): ComponentMeta[] {
     const slug = entry.name;
     const base = toPascalCase(slug);
 
-    // Preserve the anatomy order declared in index.ts; fall back to filenames.
+    // Anatomy = the PUBLIC parts exported from index.ts, in declared order. This
+    // excludes demo.vue and internal parts (*Impl, *Modal/NonModal, *Position, …)
+    // that aren't part of the public API. Fall back to all .vue (minus demo) only
+    // when the barrel exposes no parseable `export { default as X }`.
     const order = readPartOrder(resolve(dir, 'index.ts'));
-    const orderedFiles = [
-      ...order.map(name => `${name}.vue`).filter(f => vueFiles.includes(f)),
-      ...vueFiles.filter(f => !order.includes(f.replace(/\.vue$/, ''))),
-    ];
+    const publicFiles = order.map(name => `${name}.vue`).filter(f => vueFiles.includes(f));
+    const candidates = publicFiles.length > 0
+      ? publicFiles
+      : vueFiles.filter(f => f !== 'demo.vue');
+    // Drop internal implementation/variant parts users never compose directly
+    // (the public part is e.g. `Content`, not `ContentImpl`/`ContentModal`).
+    const INTERNAL_PART = /(?:Impl|ContentModal|ContentNonModal|RootContentModal|RootContentNonModal|Position)\.vue$/;
+    const orderedFiles = candidates.filter(f => !INTERNAL_PART.test(f));
 
     const parts: ComponentPartMeta[] = [];
     let groupDescription = '';
@@ -706,7 +969,17 @@ function buildComponents(pkgDir: string): ComponentMeta[] {
       const name = file.replace(/\.vue$/, '');
       const role = roleFromName(name, base);
       if (role === 'Root' && description && !groupDescription) groupDescription = description;
-      parts.push({ name, role, description, props, emits: extractEmits(setup) });
+
+      // Merge in `defineModel` v-model props/emits (invisible to the interface/
+      // defineEmits parsers), de-duping against any explicitly-declared ones.
+      const models = extractModels(setup);
+      const emits = extractEmits(setup);
+      for (const mp of models.props)
+        if (!props.some(p => p.name === mp.name)) props.push(mp);
+      for (const me of models.emits)
+        if (!emits.some(e => e.name === me.name)) emits.push(me);
+
+      parts.push({ name, role, description, props, emits });
     }
 
     const entryPoint = `./${slug}`;
@@ -720,7 +993,7 @@ function buildComponents(pkgDir: string): ComponentMeta[] {
       entryPoint,
       parts,
       hasDemo,
-      demoSource: hasDemo ? readFileSync(demoPath, 'utf-8') : '',
+      demoSource: '', // loaded lazily client-side via #docs/demo-sources
       sourcePath: relative(ROOT, dir),
     });
   }
diff --git a/docs/modules/extractor/index.ts b/docs/modules/extractor/index.ts
index 47968ea..c98baeb 100644
--- a/docs/modules/extractor/index.ts
+++ b/docs/modules/extractor/index.ts
@@ -50,6 +50,16 @@ export default defineNuxtModule({
     };
 
     nuxt.hook('vite:extendConfig', (config) => {
+      // Workspace SOURCE (e.g. @robonen/primitives) references the `__DEV__`
+      // compile-time flag (each package defines it in its own vitest/tsdown
+      // config). The docs bundle consumes that source directly via the aliases
+      // below, so it must define `__DEV__` too — otherwise it throws
+      // "ReferenceError: __DEV__ is not defined" at runtime (e.g. in the
+      // Primitive `as="template"` / Slot path), silently blanking every demo
+      // that hits it. `import.meta.env.DEV` resolves correctly in dev & prod.
+      config.define ??= {};
+      (config.define as Record<string, unknown>).__DEV__ ??= 'import.meta.env.DEV';
+
       const existing = config.resolve?.alias;
       const sourceAliases = [
         { find: '@/composables', replacement: resolve(vueSrc, 'composables') },
@@ -75,8 +85,9 @@ export default defineNuxtModule({
       filename: 'docs-metadata.ts',
       write: true,
       getContents: () => {
-        const json = JSON.stringify(metadata, null, 2);
-        return `export default ${json} as const;`;
+        // No indentation (smaller module) and no `as const` — a multi-MB literal
+        // type is pathological for tsc, and consumers cast to DocsMetadata anyway.
+        return `export default ${JSON.stringify(metadata)};`;
       },
     });
 
@@ -204,6 +215,50 @@ declare module '#docs/demos' {
 `,
     });
 
+    // Lazy demo SOURCE loaders (raw text) — kept out of the metadata payload and
+    // fetched only when a user opens "View source", so the ~850KB of demo source
+    // never ships in the always-loaded metadata bundle.
+    addTemplate({
+      filename: 'docs-demo-sources.ts',
+      write: true,
+      getContents: () => {
+        const entries: string[] = [];
+        const seen = new Set<string>();
+        const add = (key: string, demoPath: string) => {
+          if (seen.has(key)) return;
+          seen.add(key);
+          entries.push(`  '${key}': () => import('${demoPath}?raw').then(m => m.default),`);
+        };
+
+        for (const pkg of metadata.packages) {
+          for (const cat of pkg.categories)
+            for (const item of cat.items)
+              if (item.hasDemo) add(`${pkg.slug}/${item.slug}`, resolve(ROOT, dirname(item.sourcePath), 'demo.vue'));
+          for (const component of pkg.components)
+            if (component.hasDemo) add(`${pkg.slug}/${component.slug}`, resolve(ROOT, component.sourcePath, 'demo.vue'));
+        }
+
+        return [
+          `export const demoSources: Record<string, () => Promise<string>> = {`,
+          ...entries,
+          `};`,
+          ``,
+        ].join('\n');
+      },
+    });
+
+    nuxt.options.alias['#docs/demo-sources'] = resolve(nuxt.options.buildDir, 'docs-demo-sources');
+
+    addTemplate({
+      filename: 'docs-demo-sources-types.d.ts',
+      write: true,
+      getContents: () => `
+declare module '#docs/demo-sources' {
+  export const demoSources: Record<string, () => Promise<string>>;
+}
+`,
+    });
+
     // Generate hand-authored doc-section import map (`<pkg>/docs/*.vue`)
     addTemplate({
       filename: 'docs-sections.ts',
diff --git a/docs/modules/extractor/types.ts b/docs/modules/extractor/types.ts
index f9f5533..8ee1ae9 100644
--- a/docs/modules/extractor/types.ts
+++ b/docs/modules/extractor/types.ts
@@ -98,6 +98,8 @@ export interface ItemMeta {
   demoSource: string;
   /** Whether an index.test.ts file exists alongside */
   hasTests: boolean;
+  /** Statement-coverage percentage for the source file, if coverage data exists */
+  coverage?: number | null;
   /** Related types/interfaces co-located in the same module directory */
   relatedTypes: ItemMeta[];
   /** Relative path to the source file from repo root */
@@ -188,6 +190,11 @@ export interface ParamMeta {
 export interface ReturnMeta {
   type: string;
   description: string;
+  /**
+   * Properties of the returned object, when the return type is one of the
+   * package's own interfaces — rendered as a table like parameters.
+   */
+  properties?: PropertyMeta[];
 }
 
 export interface TypeParamMeta {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0ed0ee9..773e979 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -201,6 +201,9 @@ importers:
 
   core/platform:
     devDependencies:
+      '@robonen/encoding':
+        specifier: workspace:*
+        version: link:../encoding
       '@robonen/eslint':
         specifier: workspace:*
         version: link:../../configs/eslint
@@ -384,6 +387,9 @@ importers:
       '@floating-ui/vue':
         specifier: ^1.1.11
         version: 1.1.11(vue@3.5.35(typescript@6.0.3))
+      '@robonen/encoding':
+        specifier: workspace:*
+        version: link:../../core/encoding
       '@robonen/platform':
         specifier: workspace:*
         version: link:../../core/platform
diff --git a/vue/primitives/package.json b/vue/primitives/package.json
index 8ecec21..adbc4dc 100644
--- a/vue/primitives/package.json
+++ b/vue/primitives/package.json
@@ -70,6 +70,7 @@
   },
   "dependencies": {
     "@floating-ui/vue": "^1.1.11",
+    "@robonen/encoding": "workspace:*",
     "@robonen/platform": "workspace:*",
     "@robonen/stdlib": "workspace:*",
     "@robonen/vue": "workspace:*",
diff --git a/vue/primitives/src/accordion/AccordionContent.vue b/vue/primitives/src/accordion/AccordionContent.vue
index f2136ec..563f9f0 100644
--- a/vue/primitives/src/accordion/AccordionContent.vue
+++ b/vue/primitives/src/accordion/AccordionContent.vue
@@ -1,6 +1,12 @@
 <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;
diff --git a/vue/primitives/src/accordion/AccordionItem.vue b/vue/primitives/src/accordion/AccordionItem.vue
index 3012b02..c73a0aa 100644
--- a/vue/primitives/src/accordion/AccordionItem.vue
+++ b/vue/primitives/src/accordion/AccordionItem.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A single collapsible section of the accordion, grouping one trigger with
+ * its content. Identified by a unique `value` that the root uses to track
+ * open state; provides item-level context (open, disabled, ids) to its
+ * `AccordionTrigger` and `AccordionContent`.
+ */
 export interface AccordionItemProps extends PrimitiveProps {
   /** Unique value for this item. */
   value: string;
diff --git a/vue/primitives/src/accordion/AccordionRoot.vue b/vue/primitives/src/accordion/AccordionRoot.vue
index db32339..78cc4af 100644
--- a/vue/primitives/src/accordion/AccordionRoot.vue
+++ b/vue/primitives/src/accordion/AccordionRoot.vue
@@ -2,10 +2,16 @@
 import type { PrimitiveProps } from '../primitive';
 import type { RovingDirection } from '../utils/roving-focus';
 
+/**
+ * A vertically (or horizontally) stacked set of headers that each reveal an
+ * associated panel of content. Use it to let users expand and collapse
+ * sections to manage information density — FAQs, settings groups, or any
+ * place a `Collapsible` per item would be repetitive.
+ *
+ * The root owns open state (single or multiple panels), keyboard roving
+ * focus across triggers, and provides context to every `AccordionItem`.
+ */
 export interface AccordionRootProps extends PrimitiveProps {
-  /** Current open value(s) for controlled mode. */
-  modelValue?: string | string[];
-
   /** Initial value(s) for uncontrolled mode. */
   defaultValue?: string | string[];
 
@@ -30,7 +36,7 @@ export interface AccordionRootProps extends PrimitiveProps {
 </script>
 
 <script setup lang="ts">
-import { computed, shallowRef, toRef, watch } from 'vue';
+import { computed, ref, toRef } from 'vue';
 import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
 import { Primitive } from '../primitive';
 import { provideAccordionContext } from './context';
@@ -45,34 +51,25 @@ const {
   orientation = 'vertical',
   dir = 'ltr',
   loop = true,
-  modelValue,
   defaultValue,
   as = 'div',
 } = defineProps<AccordionRootProps>();
 
 const { forwardRef } = useForwardExpose();
 
-const emit = defineEmits<{ 'update:modelValue': [value: string | string[] | undefined] }>();
-
 type RovingAction = NonNullable<ReturnType<typeof rovingKeyToAction>>;
 
-const openSet = shallowRef<Set<string>>(
-  new Set(toArray(modelValue ?? defaultValue)),
-);
+const localValue = ref<string | string[] | undefined>(defaultValue);
 
-function setEqualsArray(set: Set<string>, arr: string[]): boolean {
-  if (arr.length !== set.size) return false;
-  for (let i = 0; i < arr.length; i++) if (!set.has(arr[i]!)) return false;
-  return true;
-}
-
-watch(() => modelValue, (v) => {
-  if (v === undefined) return;
-  const arr = toArray(v);
-  if (setEqualsArray(openSet.value, arr)) return;
-  openSet.value = new Set(arr);
+const model = defineModel<string | string[] | undefined>({
+  get: v => v ?? localValue.value,
+  set: (v) => {
+    localValue.value = v;
+    return v;
+  },
 });
 
+const openSet = computed<Set<string>>(() => new Set(toArray(model.value)));
 
 function nextOpenSet(cur: Set<string>, value: string): Set<string> {
   const present = cur.has(value);
@@ -88,13 +85,12 @@ function nextOpenSet(cur: Set<string>, value: string): Set<string> {
   return next;
 }
 
-function toEmitValue(set: Set<string>): string | string[] | undefined {
+function toModelValue(set: Set<string>): string | string[] | undefined {
   return type === 'single' ? set.values().next().value : [...set];
 }
 
 function commit(next: Set<string>): void {
-  openSet.value = next;
-  emit('update:modelValue', toEmitValue(next));
+  model.value = toModelValue(next);
 }
 
 function isOpen(value: string): boolean {
diff --git a/vue/primitives/src/accordion/AccordionTrigger.vue b/vue/primitives/src/accordion/AccordionTrigger.vue
index b09f9d9..fdfadf3 100644
--- a/vue/primitives/src/accordion/AccordionTrigger.vue
+++ b/vue/primitives/src/accordion/AccordionTrigger.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The interactive header button that toggles its item's content open and
+ * closed. Renders as a `<button>` by default, wires up the correct ARIA
+ * (`aria-expanded`/`aria-controls`) and participates in arrow-key roving
+ * focus across all triggers.
+ */
 export interface AccordionTriggerProps extends PrimitiveProps {
 }
 </script>
diff --git a/vue/primitives/src/accordion/demo.vue b/vue/primitives/src/accordion/demo.vue
new file mode 100644
index 0000000..228b994
--- /dev/null
+++ b/vue/primitives/src/accordion/demo.vue
@@ -0,0 +1,66 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  AccordionContent,
+  AccordionItem,
+  AccordionRoot,
+  AccordionTrigger,
+} from '@robonen/primitives';
+
+const open = ref<string>('shipping');
+
+const items = [
+  {
+    value: 'shipping',
+    question: 'How long does shipping take?',
+    answer: 'Orders ship within 1–2 business days and arrive in 3–5 days with standard delivery. Express options are offered at checkout.',
+  },
+  {
+    value: 'returns',
+    question: 'What is your return policy?',
+    answer: 'Returns are free within 30 days of delivery. Items must be unused and in their original packaging.',
+  },
+  {
+    value: 'support',
+    question: 'How can I reach support?',
+    answer: 'Our team is available 24/7 by email and weekdays 9–5 by live chat. Most tickets are answered within a few hours.',
+  },
+];
+</script>
+
+<template>
+  <AccordionRoot
+    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)"
+  >
+    <AccordionItem
+      v-for="item in items"
+      :key="item.value"
+      :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)"
+      >
+        <span>{{ item.question }}</span>
+        <svg
+          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"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <polyline points="6 9 12 15 18 9" />
+        </svg>
+      </AccordionTrigger>
+      <AccordionContent
+        class="px-4 pb-4 text-sm text-(--fg-muted)"
+      >
+        {{ item.answer }}
+      </AccordionContent>
+    </AccordionItem>
+  </AccordionRoot>
+</template>
diff --git a/vue/primitives/src/alert-dialog/AlertDialogAction.vue b/vue/primitives/src/alert-dialog/AlertDialogAction.vue
index 23f30e3..d3dcc9d 100644
--- a/vue/primitives/src/alert-dialog/AlertDialogAction.vue
+++ b/vue/primitives/src/alert-dialog/AlertDialogAction.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The button that confirms the alert and closes the dialog. Use it for the
+ * action being warned about (e.g. "Delete"); wire your own handler to perform
+ * the work, the part only handles closing.
+ */
 export interface AlertDialogActionProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/alert-dialog/AlertDialogCancel.vue b/vue/primitives/src/alert-dialog/AlertDialogCancel.vue
index cdeb110..594fa50 100644
--- a/vue/primitives/src/alert-dialog/AlertDialogCancel.vue
+++ b/vue/primitives/src/alert-dialog/AlertDialogCancel.vue
@@ -1,6 +1,11 @@
 <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>
 
diff --git a/vue/primitives/src/alert-dialog/AlertDialogContent.vue b/vue/primitives/src/alert-dialog/AlertDialogContent.vue
index f5b7ee0..fd9b886 100644
--- a/vue/primitives/src/alert-dialog/AlertDialogContent.vue
+++ b/vue/primitives/src/alert-dialog/AlertDialogContent.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { DialogContentEmits, DialogContentProps } from '../dialog';
 
+/**
+ * The container for the alert's content, rendered into the portal with
+ * `role="alertdialog"`. Hosts the Title, Description, Cancel, and Action parts,
+ * moves focus to Cancel on open, and disables dismissal via outside clicks or
+ * loss of focus so the alert can only be resolved by an explicit choice.
+ */
 export interface AlertDialogContentProps extends Omit<DialogContentProps, 'role'> {}
 export type AlertDialogContentEmits = DialogContentEmits;
 </script>
diff --git a/vue/primitives/src/alert-dialog/AlertDialogRoot.vue b/vue/primitives/src/alert-dialog/AlertDialogRoot.vue
index af3928c..34de64c 100644
--- a/vue/primitives/src/alert-dialog/AlertDialogRoot.vue
+++ b/vue/primitives/src/alert-dialog/AlertDialogRoot.vue
@@ -1,6 +1,16 @@
 <script lang="ts">
 import type { DialogRootProps } from '../dialog';
 
+/**
+ * A modal dialog that interrupts the user with important content and expects a
+ * deliberate response. Built on top of Dialog, but always modal and rendered
+ * with `role="alertdialog"` — focus moves to the Cancel button on open and
+ * outside clicks are ignored, so the user must explicitly confirm or cancel.
+ *
+ * Use it for destructive or irreversible actions (deleting data, discarding
+ * changes); for non-blocking content prefer Dialog instead. Manages open state
+ * and provides context to all parts. Bind `v-model:open` to control it.
+ */
 export interface AlertDialogRootProps extends Omit<DialogRootProps, 'modal'> {}
 </script>
 
diff --git a/vue/primitives/src/alert-dialog/demo.vue b/vue/primitives/src/alert-dialog/demo.vue
new file mode 100644
index 0000000..7458c62
--- /dev/null
+++ b/vue/primitives/src/alert-dialog/demo.vue
@@ -0,0 +1,86 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogOverlay,
+  AlertDialogPortal,
+  AlertDialogRoot,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@robonen/primitives';
+
+const open = ref(false);
+const deleted = ref(false);
+
+function confirmDelete() {
+  deleted.value = true;
+}
+
+function restore() {
+  deleted.value = false;
+}
+</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.
+    </p>
+    <p
+      v-else
+      class="text-sm text-red-600 dark:text-red-400"
+    >
+      Project deleted.
+      <button
+        type="button"
+        class="ml-1 underline underline-offset-2 hover:text-red-700 dark:hover:text-red-300"
+        @click="restore"
+      >
+        Undo
+      </button>
+    </p>
+
+    <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"
+      >
+        Delete project
+      </AlertDialogTrigger>
+
+      <AlertDialogPortal>
+        <AlertDialogOverlay
+          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"
+        >
+          <AlertDialogTitle class="text-base font-semibold text-(--fg)">
+            Delete this project?
+          </AlertDialogTitle>
+          <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)"
+            >
+              Cancel
+            </AlertDialogCancel>
+            <AlertDialogAction
+              class="inline-flex items-center rounded-md bg-red-600 px-3 py-1.5 text-sm font-medium text-white transition-colors hover:bg-red-500 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-400"
+              @click="confirmDelete"
+            >
+              Delete
+            </AlertDialogAction>
+          </div>
+        </AlertDialogContent>
+      </AlertDialogPortal>
+    </AlertDialogRoot>
+  </div>
+</template>
diff --git a/vue/primitives/src/aspect-ratio/AspectRatio.vue b/vue/primitives/src/aspect-ratio/AspectRatio.vue
index 940ed27..f3227ba 100644
--- a/vue/primitives/src/aspect-ratio/AspectRatio.vue
+++ b/vue/primitives/src/aspect-ratio/AspectRatio.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Displays content within a fixed, responsive width-to-height ratio. The
+ * element grows to fill its container's width and derives its height from the
+ * `ratio`, so the box keeps its proportions at any size. Use it to reserve
+ * layout space for images, video, maps, or embeds and avoid content shift.
+ */
 export interface AspectRatioProps extends PrimitiveProps {
   /**
    * Desired width-to-height ratio (e.g. `16 / 9`, `1`, `4 / 3`).
@@ -14,7 +20,7 @@ export interface AspectRatioProps extends PrimitiveProps {
 import { Primitive } from '../primitive';
 import { useForwardExpose } from '@robonen/vue';
 
-useForwardExpose();
+const { forwardRef } = useForwardExpose();
 
 const { ratio = 1, as = 'div' } = defineProps<AspectRatioProps>();
 
@@ -33,7 +39,7 @@ const INNER_STYLE = {
 </script>
 
 <template>
-  <div :style="wrapperStyle" data-aspect-ratio-wrapper>
+  <div :ref="forwardRef" :style="wrapperStyle" data-aspect-ratio-wrapper>
     <Primitive :as="as" :style="INNER_STYLE" :data-aspect-ratio="true">
       <slot />
     </Primitive>
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/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/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-computes-padding-bottom-from-ratio-1.png differ
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/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/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-places-inner-element-absolutely-covering-the-wrapper-1.png differ
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/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/aspect-ratio/__test__/__screenshots__/AspectRatio.test.ts/AspectRatio-renders-with-default-1-1-ratio-1.png differ
diff --git a/vue/primitives/src/aspect-ratio/demo.vue b/vue/primitives/src/aspect-ratio/demo.vue
new file mode 100644
index 0000000..9e62136
--- /dev/null
+++ b/vue/primitives/src/aspect-ratio/demo.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { AspectRatio } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const ratios = [
+  { label: '16 / 9', value: 16 / 9 },
+  { label: '4 / 3', value: 4 / 3 },
+  { label: '1 / 1', value: 1 },
+] as const;
+
+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">
+      <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)'"
+        @click="ratio = r.value"
+      >
+        {{ r.label }}
+      </button>
+    </div>
+
+    <AspectRatio
+      :ratio="ratio"
+      class="overflow-hidden rounded-xl border border-(--border) bg-(--bg-subtle)"
+    >
+      <img
+        src="https://images.unsplash.com/photo-1535025183041-0991a977e25b?w=800&q=80"
+        alt="Mountain landscape at dusk"
+        class="h-full w-full object-cover"
+      >
+    </AspectRatio>
+
+    <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>
+      proportion as the container resizes, so the image never shifts surrounding layout.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/avatar/AvatarFallback.vue b/vue/primitives/src/avatar/AvatarFallback.vue
index f8e80f7..f65ea9f 100644
--- a/vue/primitives/src/avatar/AvatarFallback.vue
+++ b/vue/primitives/src/avatar/AvatarFallback.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Content shown while the image is loading or when it fails to load — typically
+ * the user's initials or a generic icon. It renders only when the image is not
+ * yet `loaded`, and can be delayed to avoid a flash of fallback on fast
+ * connections.
+ */
 export interface AvatarFallbackProps extends PrimitiveProps {
 
   /** Delay in ms before rendering the fallback (avoids flicker on fast networks). */
diff --git a/vue/primitives/src/avatar/AvatarImage.vue b/vue/primitives/src/avatar/AvatarImage.vue
index 3f8b0f7..83e5564 100644
--- a/vue/primitives/src/avatar/AvatarImage.vue
+++ b/vue/primitives/src/avatar/AvatarImage.vue
@@ -2,11 +2,17 @@
 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;
-  /** Optional hook to reject loaded images by their dimensions/src. */
+  /** Called whenever the image's loading status changes (`idle`/`loading`/`loaded`/`error`). */
   onLoadingStatusChange?: (status: AvatarImageLoadingStatus) => void;
 }
 </script>
diff --git a/vue/primitives/src/avatar/AvatarRoot.vue b/vue/primitives/src/avatar/AvatarRoot.vue
index 4a3bc9a..5050cd3 100644
--- a/vue/primitives/src/avatar/AvatarRoot.vue
+++ b/vue/primitives/src/avatar/AvatarRoot.vue
@@ -1,6 +1,16 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * An image element representing a user, with a graceful text/icon fallback for
+ * when the image is loading or fails to load. Use it for profile pictures in
+ * avatars, comment threads, member lists, or anywhere a user identity is shown
+ * and you need a reliable placeholder.
+ *
+ * The root tracks the image's loading status and provides it via context so
+ * `AvatarImage` and `AvatarFallback` can coordinate which one is rendered. It
+ * exposes the current status on the `data-status` attribute for styling.
+ */
 export interface AvatarRootProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/avatar/demo.vue b/vue/primitives/src/avatar/demo.vue
new file mode 100644
index 0000000..9f5993a
--- /dev/null
+++ b/vue/primitives/src/avatar/demo.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { AvatarFallback, AvatarImage, AvatarRoot } from '@robonen/primitives';
+
+const people = [
+  {
+    name: 'Ada Lovelace',
+    initials: 'AL',
+    src: 'https://i.pravatar.cc/96?img=47',
+  },
+  {
+    name: 'Alan Turing',
+    initials: 'AT',
+    src: 'https://example.com/this-image-does-not-exist.png',
+  },
+  {
+    name: 'Grace Hopper',
+    initials: 'GH',
+    src: '',
+  },
+] as const;
+</script>
+
+<template>
+  <div class="flex items-center gap-4">
+    <div
+      v-for="person in people"
+      :key="person.name"
+      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"
+      >
+        <AvatarImage
+          :src="person.src"
+          :alt="person.name"
+          class="h-full w-full rounded-[inherit] object-cover"
+        />
+        <AvatarFallback
+          :delay-ms="200"
+          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>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/calendar/CalendarCell.vue b/vue/primitives/src/calendar/CalendarCell.vue
index 0ac4c79..084859d 100644
--- a/vue/primitives/src/calendar/CalendarCell.vue
+++ b/vue/primitives/src/calendar/CalendarCell.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A single `role="gridcell"` day container (`<td>`). Reflects the date's state
+ * (selected, disabled, unavailable, outside-view, today) as `data-*`
+ * attributes and `aria-*` for styling, and wraps the focusable
+ * `CalendarCellTrigger`.
+ */
 export interface CalendarCellProps extends PrimitiveProps {
   /** The date this cell represents. */
   date: Date;
diff --git a/vue/primitives/src/calendar/CalendarCellTrigger.vue b/vue/primitives/src/calendar/CalendarCellTrigger.vue
index c8e1fb4..8db9029 100644
--- a/vue/primitives/src/calendar/CalendarCellTrigger.vue
+++ b/vue/primitives/src/calendar/CalendarCellTrigger.vue
@@ -1,6 +1,12 @@
 <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;
diff --git a/vue/primitives/src/calendar/CalendarGrid.vue b/vue/primitives/src/calendar/CalendarGrid.vue
index 57252b2..c3c40c8 100644
--- a/vue/primitives/src/calendar/CalendarGrid.vue
+++ b/vue/primitives/src/calendar/CalendarGrid.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The `role="grid"` table for a single month. Provides grid context (the month
+ * it renders) to its head/body cells; render one per visible month when
+ * `numberOfMonths > 1`.
+ */
 export interface CalendarGridProps extends PrimitiveProps {
   /** The month this grid represents. Defaults to the root placeholder's month. */
   month?: Date;
diff --git a/vue/primitives/src/calendar/CalendarGridBody.vue b/vue/primitives/src/calendar/CalendarGridBody.vue
index ead37d7..ef71645 100644
--- a/vue/primitives/src/calendar/CalendarGridBody.vue
+++ b/vue/primitives/src/calendar/CalendarGridBody.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The grid's `<tbody>` wrapper containing the week rows (`CalendarGridRow`) of
+ * day cells.
+ */
 export interface CalendarGridBodyProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/calendar/CalendarGridHead.vue b/vue/primitives/src/calendar/CalendarGridHead.vue
index 36e3ada..ce273f7 100644
--- a/vue/primitives/src/calendar/CalendarGridHead.vue
+++ b/vue/primitives/src/calendar/CalendarGridHead.vue
@@ -1,6 +1,10 @@
 <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>
 
diff --git a/vue/primitives/src/calendar/CalendarGridRow.vue b/vue/primitives/src/calendar/CalendarGridRow.vue
index efc887a..aebda04 100644
--- a/vue/primitives/src/calendar/CalendarGridRow.vue
+++ b/vue/primitives/src/calendar/CalendarGridRow.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A single table row (`<tr>`) representing one week of the month, or the
+ * weekday-label row inside the grid head.
+ */
 export interface CalendarGridRowProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/calendar/CalendarHeadCell.vue b/vue/primitives/src/calendar/CalendarHeadCell.vue
index 110a3bc..e8d7fc1 100644
--- a/vue/primitives/src/calendar/CalendarHeadCell.vue
+++ b/vue/primitives/src/calendar/CalendarHeadCell.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A `scope="col"` weekday header cell (`<th>`). Renders the localized short
+ * label in its slot while exposing the full weekday name as the `aria-label`
+ * when a `day` is provided.
+ */
 export interface CalendarHeadCellProps extends PrimitiveProps {
   /** The day this header cell represents — used for `aria-label`. */
   day?: Date;
diff --git a/vue/primitives/src/calendar/CalendarHeader.vue b/vue/primitives/src/calendar/CalendarHeader.vue
index 0bea929..a1cca2e 100644
--- a/vue/primitives/src/calendar/CalendarHeader.vue
+++ b/vue/primitives/src/calendar/CalendarHeader.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Layout container for the calendar's top bar. Holds the `CalendarPrev`,
+ * `CalendarHeading`, and `CalendarNext` controls above the month grid(s).
+ */
 export interface CalendarHeaderProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/calendar/CalendarHeading.vue b/vue/primitives/src/calendar/CalendarHeading.vue
index 0849a87..8d99168 100644
--- a/vue/primitives/src/calendar/CalendarHeading.vue
+++ b/vue/primitives/src/calendar/CalendarHeading.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Displays the currently visible month and year (e.g. "June 2026"), or a range
+ * when multiple months are shown. Marked `aria-hidden` since the grid already
+ * carries the full accessible label; expose the value via its default slot to
+ * customize the rendering.
+ */
 export interface CalendarHeadingProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/calendar/CalendarNext.vue b/vue/primitives/src/calendar/CalendarNext.vue
index 6491128..5fb52e8 100644
--- a/vue/primitives/src/calendar/CalendarNext.vue
+++ b/vue/primitives/src/calendar/CalendarNext.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Button that pages the calendar forward (by one month, or by
+ * `numberOfMonths` when paged navigation is enabled). Auto-disables when the
+ * next page would fall after `maxValue` or the calendar is disabled.
+ */
 export interface CalendarNextProps extends PrimitiveProps {
   /** Override the root's `nextPage` for just this button. */
   nextPage?: (placeholder: Date) => Date;
diff --git a/vue/primitives/src/calendar/CalendarPrev.vue b/vue/primitives/src/calendar/CalendarPrev.vue
index f30f463..9d4b881 100644
--- a/vue/primitives/src/calendar/CalendarPrev.vue
+++ b/vue/primitives/src/calendar/CalendarPrev.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Button that pages the calendar backward (by one month, or by
+ * `numberOfMonths` when paged navigation is enabled). Auto-disables when the
+ * previous page would fall before `minValue` or the calendar is disabled.
+ */
 export interface CalendarPrevProps extends PrimitiveProps {
   /** Override the root's `prevPage` for just this button. */
   prevPage?: (placeholder: Date) => Date;
diff --git a/vue/primitives/src/calendar/CalendarRoot.vue b/vue/primitives/src/calendar/CalendarRoot.vue
index dd0e8b0..132c9d7 100644
--- a/vue/primitives/src/calendar/CalendarRoot.vue
+++ b/vue/primitives/src/calendar/CalendarRoot.vue
@@ -2,6 +2,17 @@
 import type { PrimitiveProps } from '../primitive';
 import type { CalendarMonth, WeekDayFormat } from './utils';
 
+/**
+ * A fully accessible, headless date calendar for picking a single day. The
+ * root owns the selected value and the displayed month ("placeholder"), builds
+ * the localized month grid(s), and wires up roving keyboard navigation,
+ * min/max bounds, and disabled/unavailable predicates. Use it to build an
+ * inline date picker or as the body of a popover/`DatePicker`.
+ *
+ * Compose it with `CalendarHeader` (`CalendarPrev` / `CalendarHeading` /
+ * `CalendarNext`) and one `CalendarGrid` per month. Supports `v-model` for the
+ * selected date and `v-model:placeholder` for the visible month.
+ */
 export interface CalendarRootProps extends PrimitiveProps {
   /** Uncontrolled default selected date. */
   defaultValue?: Date;
diff --git a/vue/primitives/src/calendar/demo.vue b/vue/primitives/src/calendar/demo.vue
new file mode 100644
index 0000000..a90eb6b
--- /dev/null
+++ b/vue/primitives/src/calendar/demo.vue
@@ -0,0 +1,110 @@
+<script setup lang="ts">
+import {
+  CalendarCell,
+  CalendarCellTrigger,
+  CalendarGrid,
+  CalendarGridBody,
+  CalendarGridHead,
+  CalendarGridRow,
+  CalendarHeadCell,
+  CalendarHeader,
+  CalendarHeading,
+  CalendarNext,
+  CalendarPrev,
+  CalendarRoot,
+} from '@robonen/primitives';
+import { ref } from 'vue';
+
+const value = ref<Date>(new Date());
+
+function formatSelected(date: Date | undefined) {
+  if (!date) return 'None';
+  return date.toLocaleDateString('en', { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' });
+}
+</script>
+
+<template>
+  <div class="flex w-full max-w-sm flex-col gap-3">
+    <CalendarRoot
+      v-slot="{ grid, weekDays }"
+      v-model="value"
+      class="rounded-xl border border-(--border) bg-(--bg-elevated) 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"
+        >
+          ‹
+        </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"
+        >
+          ›
+        </CalendarNext>
+      </CalendarHeader>
+
+      <CalendarGrid
+        v-for="month in grid"
+        :key="month.value.toString()"
+        :month="month.value"
+        class="w-full border-collapse select-none"
+      >
+        <CalendarGridHead>
+          <CalendarGridRow class="mb-1 flex">
+            <CalendarHeadCell
+              v-for="(weekday, i) in weekDays"
+              :key="weekday + i"
+              class="w-9 text-center text-xs font-medium text-(--fg-subtle)"
+            >
+              {{ weekday }}
+            </CalendarHeadCell>
+          </CalendarGridRow>
+        </CalendarGridHead>
+
+        <CalendarGridBody>
+          <CalendarGridRow
+            v-for="(week, w) in month.weeks"
+            :key="w"
+            class="flex w-full"
+          >
+            <CalendarCell
+              v-for="day in week"
+              :key="day.toString()"
+              :date="day"
+              class="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
+                  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)' : '',
+                  ]"
+                >
+                  {{ dayValue }}
+                </span>
+              </CalendarCellTrigger>
+            </CalendarCell>
+          </CalendarGridRow>
+        </CalendarGridBody>
+      </CalendarGrid>
+    </CalendarRoot>
+
+    <p class="text-xs text-(--fg-muted)">
+      Selected:
+      <span class="font-medium text-(--fg)">{{ formatSelected(value) }}</span>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/checkbox/CheckboxIndicator.vue b/vue/primitives/src/checkbox/CheckboxIndicator.vue
index 14baabd..da85c66 100644
--- a/vue/primitives/src/checkbox/CheckboxIndicator.vue
+++ b/vue/primitives/src/checkbox/CheckboxIndicator.vue
@@ -1,5 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
+/**
+ * Renders its content only when the parent `CheckboxRoot` is checked or
+ * indeterminate, mirroring that state via `data-state`. Place the check/dash
+ * icon inside it; use `forceMount` to keep it mounted for CSS exit animations.
+ */
 export interface CheckboxIndicatorProps extends PrimitiveProps {
   /** Keep mounted even when unchecked (for CSS exit animations). */
   forceMount?: boolean;
diff --git a/vue/primitives/src/checkbox/CheckboxRoot.vue b/vue/primitives/src/checkbox/CheckboxRoot.vue
index 05654e4..16d4613 100644
--- a/vue/primitives/src/checkbox/CheckboxRoot.vue
+++ b/vue/primitives/src/checkbox/CheckboxRoot.vue
@@ -2,6 +2,14 @@
 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;
@@ -22,7 +30,7 @@ export interface CheckboxRootEmits {
 
 <script setup lang="ts">
 import { Primitive } from '../primitive';
-import { ref, toRef, watch } from 'vue';
+import { computed, ref, toRef } from 'vue';
 import { provideCheckboxContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
 
@@ -31,40 +39,51 @@ const { disabled = false, required = false, value = 'on', defaultChecked, name,
 const { forwardRef } = useForwardExpose();
 
 const emit = defineEmits<CheckboxRootEmits>();
-const model = defineModel<CheckedState | undefined>('checked', { default: undefined });
 
-const localChecked = ref<CheckedState>(model.value ?? defaultChecked ?? false);
+const localChecked = ref<CheckedState>(defaultChecked ?? false);
 
-watch(model, (v) => {
-  if (v === undefined) return;
-  if (v !== localChecked.value) localChecked.value = v;
+// `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 {
-  localChecked.value = v;
-  model.value = v;
+  checked.value = v;
   emit('checkedChange', v);
 }
 
 function toggle(): void {
   if (disabled) return;
-  setChecked(localChecked.value !== true);
+  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({
-  // `localChecked` is already a `Ref<CheckedState>`; forward directly without
-  // wrapping in a computed. `toRef(() => disabled)` gives a reactive identity
-  // passthrough without `ReactiveEffect`/cache.
-  checked: localChecked,
+  checked: checkedState,
   disabled: toRef(() => disabled),
 });
-
-// Inlined in template — no need for a cached computed for a single call site.
 </script>
 
 <template>
@@ -72,17 +91,18 @@ provideCheckboxContext({
     :ref="forwardRef"
     :as="as"
     :type="as === 'button' ? 'button' : undefined"
+    :tabindex="as === 'button' ? undefined : (disabled ? -1 : 0)"
     role="checkbox"
-    :aria-checked="localChecked === 'indeterminate' ? 'mixed' : localChecked"
+    :aria-checked="checkedState === 'indeterminate' ? 'mixed' : checkedState"
     :aria-required="required || undefined"
     :aria-disabled="disabled || undefined"
-    :data-state="localChecked === 'indeterminate' ? 'indeterminate' : (localChecked ? 'checked' : 'unchecked')"
+    :data-state="checkedState === 'indeterminate' ? 'indeterminate' : (checkedState ? 'checked' : 'unchecked')"
     :data-disabled="disabled ? '' : undefined"
     :disabled="disabled || undefined"
     @click="toggle"
     @keydown="onKeyDown"
   >
-    <slot :checked="localChecked" />
+    <slot :checked="checkedState" />
     <input
       v-if="name"
       type="checkbox"
@@ -90,7 +110,7 @@ provideCheckboxContext({
       aria-hidden="true"
       :name="name"
       :value="value"
-      :checked="localChecked === true"
+      :checked="checkedState === true"
       :required="required"
       :disabled="disabled"
       style="position: absolute; pointer-events: none; opacity: 0; margin: 0; transform: translateX(-100%);"
diff --git a/vue/primitives/src/checkbox/demo.vue b/vue/primitives/src/checkbox/demo.vue
new file mode 100644
index 0000000..192188d
--- /dev/null
+++ b/vue/primitives/src/checkbox/demo.vue
@@ -0,0 +1,100 @@
+<script setup lang="ts">
+import type { CheckedState } from '@robonen/primitives';
+import { CheckboxIndicator, CheckboxRoot } from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+const ingredients = [
+  { id: 'cheese', label: 'Extra cheese' },
+  { id: 'mushrooms', label: 'Mushrooms' },
+  { id: 'olives', label: 'Olives' },
+];
+
+const selected = ref<Record<string, boolean>>({
+  cheese: true,
+  mushrooms: false,
+  olives: false,
+});
+
+const checkedCount = computed(() => Object.values(selected.value).filter(Boolean).length);
+
+// Parent reflects the children: checked when all, unchecked when none, else indeterminate.
+const allChecked = computed<CheckedState>(() => {
+  if (checkedCount.value === 0) return false;
+  if (checkedCount.value === ingredients.length) return true;
+  return 'indeterminate';
+});
+
+function toggleAll(next: CheckedState) {
+  const value = next === true;
+  for (const item of ingredients) selected.value[item.id] = value;
+}
+
+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">
+    <fieldset class="flex flex-col gap-3 m-0 p-0 border-0">
+      <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)"
+          @checked-change="toggleAll"
+        >
+          <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>
+            <svg v-else 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 font-medium">Select all</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)">
+        <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)"
+          >
+            <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>
+        </label>
+      </div>
+    </fieldset>
+
+    <label class="flex items-start gap-3 cursor-pointer select-none">
+      <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)"
+      >
+        <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>
+    </label>
+
+    <p
+      class="text-xs"
+      :class="acceptedTerms ? 'text-emerald-600 dark:text-emerald-400' : 'text-(--fg-subtle)'"
+    >
+      {{ acceptedTerms ? 'Ready to submit' : 'Please accept the terms to continue' }}
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/collapsible/CollapsibleContent.vue b/vue/primitives/src/collapsible/CollapsibleContent.vue
index 791346f..a5f2d56 100644
--- a/vue/primitives/src/collapsible/CollapsibleContent.vue
+++ b/vue/primitives/src/collapsible/CollapsibleContent.vue
@@ -1,6 +1,11 @@
 <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). */
diff --git a/vue/primitives/src/collapsible/CollapsibleRoot.vue b/vue/primitives/src/collapsible/CollapsibleRoot.vue
index d664ca5..9168d06 100644
--- a/vue/primitives/src/collapsible/CollapsibleRoot.vue
+++ b/vue/primitives/src/collapsible/CollapsibleRoot.vue
@@ -1,6 +1,14 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * An interactive component that expands and collapses a panel of content.
+ *
+ * `CollapsibleRoot` owns the open/closed state (controlled via `v-model:open`
+ * or uncontrolled via `defaultOpen`), provides it to the `Trigger` and
+ * `Content` parts, and reflects it as `data-state`. Use it for show/hide
+ * disclosures such as "read more" sections, FAQ entries, or settings panels.
+ */
 export interface CollapsibleRootProps extends PrimitiveProps {
 
   defaultOpen?: boolean;
diff --git a/vue/primitives/src/collapsible/CollapsibleTrigger.vue b/vue/primitives/src/collapsible/CollapsibleTrigger.vue
index 20d3d91..3ff4d9a 100644
--- a/vue/primitives/src/collapsible/CollapsibleTrigger.vue
+++ b/vue/primitives/src/collapsible/CollapsibleTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The button that toggles the collapsible open and closed. Wires up
+ * `aria-expanded`, `aria-controls`, and the disabled state from the root, and
+ * renders as a `<button>` by default.
+ */
 export interface CollapsibleTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/collapsible/demo.vue b/vue/primitives/src/collapsible/demo.vue
new file mode 100644
index 0000000..fca6628
--- /dev/null
+++ b/vue/primitives/src/collapsible/demo.vue
@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  CollapsibleContent,
+  CollapsibleRoot,
+  CollapsibleTrigger,
+} from '@robonen/primitives';
+
+const open = ref(false);
+
+const commits = [
+  { id: 'a1c3f9', msg: 'Reflect open state via data-state' },
+  { id: 'b7e2d4', msg: 'Wire aria-controls to content id' },
+  { id: 'c0f8a1', msg: 'Unmount content with Presence when closed' },
+];
+</script>
+
+<template>
+  <CollapsibleRoot
+    v-model:open="open"
+    class="w-full max-w-sm rounded-xl border border-(--border) bg-(--bg-elevated) 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>
+
+      <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"
+        :aria-label="open ? 'Collapse commits' : 'Expand commits'"
+      >
+        <svg
+          class="size-4 transition-transform duration-200"
+          :class="open ? 'rotate-180' : ''"
+          viewBox="0 0 24 24" fill="none" stroke="currentColor"
+          stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+        >
+          <path d="m6 9 6 6 6-6" />
+        </svg>
+      </CollapsibleTrigger>
+    </div>
+
+    <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>
+
+    <CollapsibleContent class="mt-1.5 space-y-1.5">
+      <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)"
+      >
+        <span class="text-emerald-600 dark:text-emerald-400">{{ commit.id }}</span>
+        {{ commit.msg }}
+      </div>
+    </CollapsibleContent>
+  </CollapsibleRoot>
+</template>
diff --git a/vue/primitives/src/combobox/ComboboxAnchor.vue b/vue/primitives/src/combobox/ComboboxAnchor.vue
index b64d520..5ba587f 100644
--- a/vue/primitives/src/combobox/ComboboxAnchor.vue
+++ b/vue/primitives/src/combobox/ComboboxAnchor.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PopperAnchorProps } from '../popper';
 
+/**
+ * The element the popup is positioned against, typically wrapping the Input and Trigger.
+ * Acts as the Popper anchor and the boundary used for the blur-to-close heuristic.
+ */
 export interface ComboboxAnchorProps extends PopperAnchorProps {}
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxArrow.vue b/vue/primitives/src/combobox/ComboboxArrow.vue
index 7df8f87..770f601 100644
--- a/vue/primitives/src/combobox/ComboboxArrow.vue
+++ b/vue/primitives/src/combobox/ComboboxArrow.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PopperArrowProps } from '../popper';
 
+/**
+ * An optional arrow that visually points from the popup back to the anchor. Renders only
+ * while the combobox is open. Place inside ComboboxContent.
+ */
 export type ComboboxArrowProps = PopperArrowProps;
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxCancel.vue b/vue/primitives/src/combobox/ComboboxCancel.vue
index 7ae1746..f03cfcc 100644
--- a/vue/primitives/src/combobox/ComboboxCancel.vue
+++ b/vue/primitives/src/combobox/ComboboxCancel.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that clears the current search term and refocuses the input. Typically shown
+ * as an "x" inside the field while the user is typing.
+ */
 export interface ComboboxCancelProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxContent.vue b/vue/primitives/src/combobox/ComboboxContent.vue
index 646cf73..2e7660a 100644
--- a/vue/primitives/src/combobox/ComboboxContent.vue
+++ b/vue/primitives/src/combobox/ComboboxContent.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { ComboboxContentImplEmits, ComboboxContentImplProps } from './ComboboxContentImpl.vue';
 
+/**
+ * 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 type ComboboxContentEmits = ComboboxContentImplEmits;
 </script>
diff --git a/vue/primitives/src/combobox/ComboboxContentImpl.vue b/vue/primitives/src/combobox/ComboboxContentImpl.vue
index 249aa2a..41be878 100644
--- a/vue/primitives/src/combobox/ComboboxContentImpl.vue
+++ b/vue/primitives/src/combobox/ComboboxContentImpl.vue
@@ -4,6 +4,10 @@ import type { FocusScopeEmits } from '../focus-scope';
 import type { PopperContentProps } from '../popper';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Internal implementation of the content popup: wires up focus scoping, dismiss-on-outside,
+ * Popper positioning, and the screen-reader result announcer. Use ComboboxContent instead.
+ */
 export interface ComboboxContentImplProps extends PrimitiveProps, /* @vue-ignore */ Partial<PopperContentProps> {
   /** Position strategy. @default 'popper' */
   position?: 'inline' | 'popper';
diff --git a/vue/primitives/src/combobox/ComboboxEmpty.vue b/vue/primitives/src/combobox/ComboboxEmpty.vue
index f6ee9ea..3306b64 100644
--- a/vue/primitives/src/combobox/ComboboxEmpty.vue
+++ b/vue/primitives/src/combobox/ComboboxEmpty.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Fallback content shown when the current search term matches no items. Renders only when
+ * the filtered count is zero, unless `always` is set.
+ */
 export interface ComboboxEmptyProps extends PrimitiveProps {
   /** Render even when items exist but none are filtered out. */
   always?: boolean;
diff --git a/vue/primitives/src/combobox/ComboboxGroup.vue b/vue/primitives/src/combobox/ComboboxGroup.vue
index be430d0..0a28269 100644
--- a/vue/primitives/src/combobox/ComboboxGroup.vue
+++ b/vue/primitives/src/combobox/ComboboxGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Groups related items under a shared ComboboxLabel. Hides itself automatically when none
+ * of its items survive the current filter.
+ */
 export interface ComboboxGroupProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxInput.vue b/vue/primitives/src/combobox/ComboboxInput.vue
index c73c55e..ecf602b 100644
--- a/vue/primitives/src/combobox/ComboboxInput.vue
+++ b/vue/primitives/src/combobox/ComboboxInput.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The text field users type into to filter options. Owns the search term, ARIA combobox
+ * semantics, and keyboard navigation (arrows, Home/End, Enter to select, Escape to close).
+ */
 export interface ComboboxInputProps extends PrimitiveProps {
   /** Disable the input. */
   disabled?: boolean;
diff --git a/vue/primitives/src/combobox/ComboboxItem.vue b/vue/primitives/src/combobox/ComboboxItem.vue
index 22089b4..26e1e06 100644
--- a/vue/primitives/src/combobox/ComboboxItem.vue
+++ b/vue/primitives/src/combobox/ComboboxItem.vue
@@ -2,6 +2,10 @@
 import type { PrimitiveProps } from '../primitive';
 import type { AcceptableValue } from './utils';
 
+/**
+ * A single selectable option in the list. Registers itself for filtering and keyboard
+ * navigation, toggles selection on click, and highlights on pointer move.
+ */
 export interface ComboboxItemProps<T extends AcceptableValue = AcceptableValue> extends PrimitiveProps {
   /** Item value. Selected/registered identity. */
   value: T;
diff --git a/vue/primitives/src/combobox/ComboboxItemIndicator.vue b/vue/primitives/src/combobox/ComboboxItemIndicator.vue
index ccb9326..eca754b 100644
--- a/vue/primitives/src/combobox/ComboboxItemIndicator.vue
+++ b/vue/primitives/src/combobox/ComboboxItemIndicator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Marks the selected state of its parent ComboboxItem, e.g. a checkmark. Renders only when
+ * that item is selected.
+ */
 export interface ComboboxItemIndicatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxLabel.vue b/vue/primitives/src/combobox/ComboboxLabel.vue
index c5248ed..c720e3b 100644
--- a/vue/primitives/src/combobox/ComboboxLabel.vue
+++ b/vue/primitives/src/combobox/ComboboxLabel.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * An accessible label for a ComboboxGroup. Its id is referenced by the group's
+ * `aria-labelledby`, so place it as a direct child of ComboboxGroup.
+ */
 export interface ComboboxLabelProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxPortal.vue b/vue/primitives/src/combobox/ComboboxPortal.vue
index 9023819..96e392a 100644
--- a/vue/primitives/src/combobox/ComboboxPortal.vue
+++ b/vue/primitives/src/combobox/ComboboxPortal.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PortalProps } from '../teleport';
 
+/**
+ * Teleports the ComboboxContent into another part of the DOM (defaults to `body`) to escape
+ * overflow/stacking-context clipping. Wrap ComboboxContent with it.
+ */
 export interface ComboboxPortalProps extends PortalProps {}
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxRoot.vue b/vue/primitives/src/combobox/ComboboxRoot.vue
index 5b45c9b..da105ab 100644
--- a/vue/primitives/src/combobox/ComboboxRoot.vue
+++ b/vue/primitives/src/combobox/ComboboxRoot.vue
@@ -2,6 +2,13 @@
 import type { Direction } from '../config-provider';
 import type { AcceptableValue, ComboboxFilterFunction, ComboboxFilterItem } from './utils';
 
+/**
+ * An autocomplete / typeahead input that filters a list of options as the user types.
+ * Combine a text input with a popup listbox, supporting single or multiple selection,
+ * custom filtering, and full keyboard navigation. Reach for it when users must pick from
+ * a large or searchable set of options; for a small fixed list a plain Select is simpler.
+ * Wraps everything in a Popper and provides shared state to every other Combobox part.
+ */
 export interface ComboboxRootProps<T extends AcceptableValue = AcceptableValue> {
   /** Controlled selected value. Use `v-model`. */
   modelValue?: T | T[];
@@ -69,8 +76,6 @@ const {
   by,
 } = defineProps<ComboboxRootProps<T>>();
 
-const emit = defineEmits<ComboboxRootEmits<T>>();
-
 const config = useConfig();
 const direction = computed(() => dir ?? config.dir.value);
 
@@ -203,7 +208,6 @@ function isSelected(v: T): boolean {
 
 function commitValue(next: T | T[] | undefined) {
   value.value = next;
-  emit('update:modelValue', next);
 }
 
 function onValueChange(v: T) {
diff --git a/vue/primitives/src/combobox/ComboboxSeparator.vue b/vue/primitives/src/combobox/ComboboxSeparator.vue
index 7ff1fa6..79271cd 100644
--- a/vue/primitives/src/combobox/ComboboxSeparator.vue
+++ b/vue/primitives/src/combobox/ComboboxSeparator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A purely visual divider between items or groups inside the popup. Decorative and hidden
+ * from assistive technology.
+ */
 export interface ComboboxSeparatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/combobox/ComboboxTrigger.vue b/vue/primitives/src/combobox/ComboboxTrigger.vue
index 8b16984..dd37a59 100644
--- a/vue/primitives/src/combobox/ComboboxTrigger.vue
+++ b/vue/primitives/src/combobox/ComboboxTrigger.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button, usually a chevron next to the input, that toggles the popup open and closed.
+ * Optional: typing in the Input also opens the list.
+ */
 export interface ComboboxTriggerProps extends PrimitiveProps {
   /** Disable the trigger independently from the root. */
   disabled?: boolean;
diff --git a/vue/primitives/src/combobox/ComboboxViewport.vue b/vue/primitives/src/combobox/ComboboxViewport.vue
index 0d54883..08fc65f 100644
--- a/vue/primitives/src/combobox/ComboboxViewport.vue
+++ b/vue/primitives/src/combobox/ComboboxViewport.vue
@@ -1,6 +1,10 @@
 <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>
 
diff --git a/vue/primitives/src/combobox/demo.vue b/vue/primitives/src/combobox/demo.vue
new file mode 100644
index 0000000..ff8d441
--- /dev/null
+++ b/vue/primitives/src/combobox/demo.vue
@@ -0,0 +1,119 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+
+import {
+  ComboboxAnchor,
+  ComboboxCancel,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxItemIndicator,
+  ComboboxLabel,
+  ComboboxPortal,
+  ComboboxRoot,
+  ComboboxTrigger,
+  ComboboxViewport,
+} from '@robonen/primitives';
+
+interface Framework {
+  value: string;
+  label: string;
+  group: 'JavaScript' | 'Native';
+}
+
+const frameworks: Framework[] = [
+  { value: 'vue', label: 'Vue', group: 'JavaScript' },
+  { value: 'react', label: 'React', group: 'JavaScript' },
+  { value: 'svelte', label: 'Svelte', group: 'JavaScript' },
+  { value: 'solid', label: 'Solid', group: 'JavaScript' },
+  { value: 'angular', label: 'Angular', group: 'JavaScript' },
+  { value: 'swiftui', label: 'SwiftUI', group: 'Native' },
+  { value: 'compose', label: 'Jetpack Compose', group: 'Native' },
+  { value: 'flutter', label: 'Flutter', group: 'Native' },
+];
+
+const selected = ref<string>();
+
+function labelFor(value: string | undefined) {
+  return frameworks.find(f => f.value === value)?.label ?? '';
+}
+
+const groups = ['JavaScript', 'Native'] as const;
+</script>
+
+<template>
+  <div class="flex w-full max-w-xs flex-col gap-3">
+    <ComboboxRoot
+      v-model="selected"
+      :display-value="labelFor"
+      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)"
+      >
+        <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)"
+        />
+
+        <ComboboxCancel
+          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"
+        >
+          <span aria-hidden="true" class="text-xs">▾</span>
+        </ComboboxTrigger>
+      </ComboboxAnchor>
+
+      <ComboboxPortal>
+        <ComboboxContent
+          :side-offset="6"
+          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)">
+              No frameworks found.
+            </ComboboxEmpty>
+
+            <ComboboxGroup
+              v-for="group in groups"
+              :key="group"
+              class="mb-1 last:mb-0"
+            >
+              <ComboboxLabel
+                class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-(--fg-subtle)"
+              >
+                {{ group }}
+              </ComboboxLabel>
+
+              <ComboboxItem
+                v-for="framework in frameworks.filter(f => f.group === group)"
+                :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"
+              >
+                <span>{{ framework.label }}</span>
+                <ComboboxItemIndicator>
+                  <span aria-hidden="true">✓</span>
+                </ComboboxItemIndicator>
+              </ComboboxItem>
+            </ComboboxGroup>
+          </ComboboxViewport>
+        </ComboboxContent>
+      </ComboboxPortal>
+    </ComboboxRoot>
+
+    <p class="text-sm text-(--fg-muted)">
+      Selected:
+      <span class="font-medium text-(--fg)">{{ selected ? labelFor(selected) : 'none' }}</span>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/command/CommandEmpty.vue b/vue/primitives/src/command/CommandEmpty.vue
index 6de4a4a..ecbb772 100644
--- a/vue/primitives/src/command/CommandEmpty.vue
+++ b/vue/primitives/src/command/CommandEmpty.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Empty-state message shown when the search yields no matching items. By default
+ * it appears only while a search term is active; set `always` to also show it for
+ * an empty list with no query.
+ */
 export interface CommandEmptyProps extends PrimitiveProps {
   /** Render even while there is no active search term. */
   always?: boolean;
diff --git a/vue/primitives/src/command/CommandGroup.vue b/vue/primitives/src/command/CommandGroup.vue
index 935c28a..b8bfdc4 100644
--- a/vue/primitives/src/command/CommandGroup.vue
+++ b/vue/primitives/src/command/CommandGroup.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Labelled section that visually clusters related items under an optional
+ * heading. Hides itself automatically when every item it contains is filtered
+ * out (unless `forceMount`), so empty categories disappear during search.
+ */
 export interface CommandGroupProps extends PrimitiveProps {
   /** Group heading text (rendered when the default slot doesn't override it). */
   heading?: string;
diff --git a/vue/primitives/src/command/CommandInput.vue b/vue/primitives/src/command/CommandInput.vue
index b135fbb..1a3d4f2 100644
--- a/vue/primitives/src/command/CommandInput.vue
+++ b/vue/primitives/src/command/CommandInput.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Search box that drives the command palette: typing updates the root search
+ * term (and re-filters items), while Arrow/Home/End/Enter move the highlight and
+ * commit the selected item. Renders a combobox `<input>` wired up for assistive tech.
+ */
 export interface CommandInputProps extends PrimitiveProps {
   /** Controlled value; falls back to root `searchTerm`. */
   modelValue?: string;
diff --git a/vue/primitives/src/command/CommandItem.vue b/vue/primitives/src/command/CommandItem.vue
index d003845..2e7b4f0 100644
--- a/vue/primitives/src/command/CommandItem.vue
+++ b/vue/primitives/src/command/CommandItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A selectable option in the list. Registers itself with the root (so it can be
+ * filtered, highlighted, and selected), reflects highlight/selection/disabled
+ * 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`. */
   value: string;
diff --git a/vue/primitives/src/command/CommandList.vue b/vue/primitives/src/command/CommandList.vue
index e88f62e..b2086db 100644
--- a/vue/primitives/src/command/CommandList.vue
+++ b/vue/primitives/src/command/CommandList.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Scrollable listbox container that holds the items, groups, and empty/loading
+ * states. Tracks its content height in the `--primitives-command-list-height`
+ * CSS variable so you can animate the palette as results filter in and out.
+ */
 export interface CommandListProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/command/CommandLoading.vue b/vue/primitives/src/command/CommandLoading.vue
index 3cc35fe..84caf92 100644
--- a/vue/primitives/src/command/CommandLoading.vue
+++ b/vue/primitives/src/command/CommandLoading.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Progress indicator for asynchronous results — render it inside the list while
+ * fetching items so screen readers announce the loading state. Exposes an
+ * optional `progress` value as an accessible progressbar.
+ */
 export interface CommandLoadingProps extends PrimitiveProps {
   /** Accessible label describing the loading state. */
   label?: string;
diff --git a/vue/primitives/src/command/CommandRoot.vue b/vue/primitives/src/command/CommandRoot.vue
index ad41aac..46360eb 100644
--- a/vue/primitives/src/command/CommandRoot.vue
+++ b/vue/primitives/src/command/CommandRoot.vue
@@ -2,6 +2,15 @@
 import type { PrimitiveProps } from '../primitive';
 import type { CommandFilterFunction } from './utils';
 
+/**
+ * Root of a command palette / fuzzy-finder menu (cmdk-style): owns the search
+ * term, the registry of items and groups, scoring/filtering, and keyboard-driven
+ * highlight + selection. Compose it with `CommandInput`, `CommandList`,
+ * `CommandGroup`, `CommandItem`, `CommandEmpty`, `CommandLoading`, and
+ * `CommandSeparator`. Reach for it whenever you need a searchable, keyboard-first
+ * list of actions or options — a Spotlight-style launcher, an autocomplete menu,
+ * or a quick-switcher.
+ */
 export interface CommandRootProps extends PrimitiveProps {
   /** Controlled selected value. Use `v-model`. */
   modelValue?: string;
@@ -50,8 +59,6 @@ const {
   label,
 } = defineProps<CommandRootProps>();
 
-const emit = defineEmits<CommandRootEmits>();
-
 const { forwardRef } = useForwardExpose();
 
 const localValue = ref<string | undefined>(defaultValue);
@@ -179,12 +186,10 @@ function getItemId(val: string): string {
 
 function setModelValue(v: string | undefined) {
   value.value = v;
-  emit('update:modelValue', v);
 }
 
 function setSearchTerm(v: string) {
   search.value = v;
-  emit('update:searchTerm', v);
 }
 
 function setSelectedValue(v: string | undefined) {
diff --git a/vue/primitives/src/command/CommandSeparator.vue b/vue/primitives/src/command/CommandSeparator.vue
index 8c1de49..221e7e9 100644
--- a/vue/primitives/src/command/CommandSeparator.vue
+++ b/vue/primitives/src/command/CommandSeparator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Visual divider between groups or items. Hidden automatically while a search
+ * term is active (since filtering collapses the list) unless `alwaysRender` is set.
+ */
 export interface CommandSeparatorProps extends PrimitiveProps {
   /** Render the separator even while the search term is active. */
   alwaysRender?: boolean;
diff --git a/vue/primitives/src/command/demo.vue b/vue/primitives/src/command/demo.vue
new file mode 100644
index 0000000..0473790
--- /dev/null
+++ b/vue/primitives/src/command/demo.vue
@@ -0,0 +1,134 @@
+<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/context-menu/ContextMenuArrow.vue b/vue/primitives/src/context-menu/ContextMenuArrow.vue
index bbc7866..38c3ad6 100644
--- a/vue/primitives/src/context-menu/ContextMenuArrow.vue
+++ b/vue/primitives/src/context-menu/ContextMenuArrow.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuArrowProps } from '../menu';
 
+/**
+ * An optional arrow that visually points from the content back toward its
+ * anchor. Render it inside the content.
+ */
 export interface ContextMenuArrowProps extends MenuArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuCheckboxItem.vue b/vue/primitives/src/context-menu/ContextMenuCheckboxItem.vue
index c3e6eba..db6ed9f 100644
--- a/vue/primitives/src/context-menu/ContextMenuCheckboxItem.vue
+++ b/vue/primitives/src/context-menu/ContextMenuCheckboxItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuCheckboxItemEmits, MenuCheckboxItemProps } from '../menu';
 
+/**
+ * An item that toggles an on/off (or indeterminate) state, exposing
+ * `aria-checked` for assistive tech. Bind `v-model:checked` and pair it with a
+ * `ContextMenuItemIndicator` to render the checkmark.
+ */
 export interface ContextMenuCheckboxItemProps extends MenuCheckboxItemProps {}
 export type ContextMenuCheckboxItemEmits = MenuCheckboxItemEmits;
 </script>
diff --git a/vue/primitives/src/context-menu/ContextMenuContent.vue b/vue/primitives/src/context-menu/ContextMenuContent.vue
index c996faa..be97fde 100644
--- a/vue/primitives/src/context-menu/ContextMenuContent.vue
+++ b/vue/primitives/src/context-menu/ContextMenuContent.vue
@@ -1,6 +1,11 @@
 <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>
diff --git a/vue/primitives/src/context-menu/ContextMenuGroup.vue b/vue/primitives/src/context-menu/ContextMenuGroup.vue
index 00b6c90..d34b05f 100644
--- a/vue/primitives/src/context-menu/ContextMenuGroup.vue
+++ b/vue/primitives/src/context-menu/ContextMenuGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuGroupProps } from '../menu';
 
+/**
+ * Groups a set of related items under one accessible `role="group"`, optionally
+ * labelled by a `ContextMenuLabel`. Use it to organize the menu into sections.
+ */
 export interface ContextMenuGroupProps extends MenuGroupProps {}
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuItem.vue b/vue/primitives/src/context-menu/ContextMenuItem.vue
index cddf23b..854bc8c 100644
--- a/vue/primitives/src/context-menu/ContextMenuItem.vue
+++ b/vue/primitives/src/context-menu/ContextMenuItem.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuItemEmits, MenuItemProps } from '../menu';
 
+/**
+ * A single actionable command in the menu. Emits `select` on click or Enter
+ * and closes the menu by default; can be `disabled` for unavailable actions.
+ */
 export interface ContextMenuItemProps extends MenuItemProps {}
 export type ContextMenuItemEmits = MenuItemEmits;
 </script>
diff --git a/vue/primitives/src/context-menu/ContextMenuItemIndicator.vue b/vue/primitives/src/context-menu/ContextMenuItemIndicator.vue
index 422c63c..83fe88a 100644
--- a/vue/primitives/src/context-menu/ContextMenuItemIndicator.vue
+++ b/vue/primitives/src/context-menu/ContextMenuItemIndicator.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuItemIndicatorProps } from '../menu';
 
+/**
+ * Renders its content only when the parent checkbox or radio item is checked.
+ * Place it inside a `ContextMenuCheckboxItem` or `ContextMenuRadioItem` to show
+ * the check or dot.
+ */
 export interface ContextMenuItemIndicatorProps extends MenuItemIndicatorProps {}
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuLabel.vue b/vue/primitives/src/context-menu/ContextMenuLabel.vue
index 6bf59b7..e223102 100644
--- a/vue/primitives/src/context-menu/ContextMenuLabel.vue
+++ b/vue/primitives/src/context-menu/ContextMenuLabel.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuLabelProps } from '../menu';
 
+/**
+ * A non-interactive caption for a group of items. Skipped by keyboard
+ * navigation; use it to title a section within the menu.
+ */
 export interface ContextMenuLabelProps extends MenuLabelProps {}
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuPortal.vue b/vue/primitives/src/context-menu/ContextMenuPortal.vue
index eed0027..f2a1d9c 100644
--- a/vue/primitives/src/context-menu/ContextMenuPortal.vue
+++ b/vue/primitives/src/context-menu/ContextMenuPortal.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuPortalProps } from '../menu';
 
+/**
+ * Teleports the menu content into `document.body` (or a custom target) so it
+ * escapes parent overflow and stacking contexts. Place it between the trigger
+ * and the content.
+ */
 export interface ContextMenuPortalProps extends MenuPortalProps {}
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuRadioGroup.vue b/vue/primitives/src/context-menu/ContextMenuRadioGroup.vue
index 0761c76..faa751f 100644
--- a/vue/primitives/src/context-menu/ContextMenuRadioGroup.vue
+++ b/vue/primitives/src/context-menu/ContextMenuRadioGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuRadioGroupEmits, MenuRadioGroupProps } from '../menu';
 
+/**
+ * A group of mutually exclusive `ContextMenuRadioItem`s sharing a single
+ * selected value. Bind `v-model` to track the active choice.
+ */
 export interface ContextMenuRadioGroupProps extends MenuRadioGroupProps {}
 export type ContextMenuRadioGroupEmits = MenuRadioGroupEmits;
 </script>
diff --git a/vue/primitives/src/context-menu/ContextMenuRadioItem.vue b/vue/primitives/src/context-menu/ContextMenuRadioItem.vue
index 3206fec..74766b6 100644
--- a/vue/primitives/src/context-menu/ContextMenuRadioItem.vue
+++ b/vue/primitives/src/context-menu/ContextMenuRadioItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuRadioItemEmits, MenuRadioItemProps } from '../menu';
 
+/**
+ * One option within a `ContextMenuRadioGroup`, identified by its `value`.
+ * Selecting it sets the group's value; pair it with a `ContextMenuItemIndicator`
+ * to render the selected dot.
+ */
 export interface ContextMenuRadioItemProps extends MenuRadioItemProps {}
 export type ContextMenuRadioItemEmits = MenuRadioItemEmits;
 </script>
diff --git a/vue/primitives/src/context-menu/ContextMenuRoot.vue b/vue/primitives/src/context-menu/ContextMenuRoot.vue
index 8448d1e..fe23009 100644
--- a/vue/primitives/src/context-menu/ContextMenuRoot.vue
+++ b/vue/primitives/src/context-menu/ContextMenuRoot.vue
@@ -1,43 +1,46 @@
 <script lang="ts">
 import type { Direction } from '../config-provider';
 
+/**
+ * A menu that opens at the pointer on right-click (or a long-press on touch),
+ * replacing the platform's native context menu with your own styled actions.
+ * Built on top of Menu, so it inherits keyboard navigation, typeahead, nested
+ * submenus, and checkbox/radio items.
+ *
+ * Use it for contextual actions tied to a region or element — cut/copy/paste,
+ * row actions in a table, canvas tools — when there is no persistent button to
+ * click. The root owns open state and provides context to every part; listen
+ * to `update:open` to react when the menu opens or closes.
+ */
 export interface ContextMenuRootProps {
   dir?: Direction;
   modal?: boolean;
 }
-export interface ContextMenuRootEmits {
-  'update:open': [value: boolean];
-}
 </script>
 
 <script setup lang="ts">
-import { ref, toRef } from 'vue';
+import { toRef } from 'vue';
 
 import { MenuRoot } from '../menu';
 import { provideContextMenuRootContext } from './context';
 
 const { dir, modal = true } = defineProps<ContextMenuRootProps>();
-const emit = defineEmits<ContextMenuRootEmits>();
 defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
 
-const open = ref(false);
+const open = defineModel<boolean>('open', { default: false });
 
 provideContextMenuRootContext({
   open,
-  onOpenChange: (v) => {
-    open.value = v;
-    emit('update:open', v);
-  },
+  onOpenChange: (v) => { open.value = v; },
   modal: toRef(() => modal),
 });
 </script>
 
 <template>
   <MenuRoot
-    :open="open"
+    v-model:open="open"
     :dir="dir"
     :modal="modal"
-    @update:open="open = $event"
   >
     <slot :open="open" />
   </MenuRoot>
diff --git a/vue/primitives/src/context-menu/ContextMenuSeparator.vue b/vue/primitives/src/context-menu/ContextMenuSeparator.vue
index f5e2f6c..f19f3bb 100644
--- a/vue/primitives/src/context-menu/ContextMenuSeparator.vue
+++ b/vue/primitives/src/context-menu/ContextMenuSeparator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuSeparatorProps } from '../menu';
 
+/**
+ * A visual divider between groups of items, exposed as `role="separator"` and
+ * skipped by keyboard navigation.
+ */
 export interface ContextMenuSeparatorProps extends MenuSeparatorProps {}
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuSub.vue b/vue/primitives/src/context-menu/ContextMenuSub.vue
index f7c9203..a60605e 100644
--- a/vue/primitives/src/context-menu/ContextMenuSub.vue
+++ b/vue/primitives/src/context-menu/ContextMenuSub.vue
@@ -1,6 +1,11 @@
 <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>
diff --git a/vue/primitives/src/context-menu/ContextMenuSubContent.vue b/vue/primitives/src/context-menu/ContextMenuSubContent.vue
index 210cb63..e313d4a 100644
--- a/vue/primitives/src/context-menu/ContextMenuSubContent.vue
+++ b/vue/primitives/src/context-menu/ContextMenuSubContent.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuSubContentEmits, MenuSubContentProps } from '../menu';
 
+/**
+ * The floating panel of a nested submenu, positioned alongside its
+ * `ContextMenuSubTrigger`. Render it inside a `ContextMenuSub`.
+ */
 export interface ContextMenuSubContentProps extends MenuSubContentProps {}
 export type ContextMenuSubContentEmits = MenuSubContentEmits;
 </script>
diff --git a/vue/primitives/src/context-menu/ContextMenuSubTrigger.vue b/vue/primitives/src/context-menu/ContextMenuSubTrigger.vue
index 58b8bec..da3fc4b 100644
--- a/vue/primitives/src/context-menu/ContextMenuSubTrigger.vue
+++ b/vue/primitives/src/context-menu/ContextMenuSubTrigger.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuSubTriggerProps } from '../menu';
 
+/**
+ * The item that opens a nested submenu on hover or arrow-key, anchoring its
+ * `ContextMenuSubContent`. Place it as the first child of a `ContextMenuSub`.
+ */
 export interface ContextMenuSubTriggerProps extends MenuSubTriggerProps {}
 </script>
 
diff --git a/vue/primitives/src/context-menu/ContextMenuTrigger.vue b/vue/primitives/src/context-menu/ContextMenuTrigger.vue
index 17ccb9b..efca476 100644
--- a/vue/primitives/src/context-menu/ContextMenuTrigger.vue
+++ b/vue/primitives/src/context-menu/ContextMenuTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The region that captures right-click (and touch 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;
 }
diff --git a/vue/primitives/src/context-menu/demo.vue b/vue/primitives/src/context-menu/demo.vue
new file mode 100644
index 0000000..0bd4eee
--- /dev/null
+++ b/vue/primitives/src/context-menu/demo.vue
@@ -0,0 +1,183 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  ContextMenuCheckboxItem,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuItemIndicator,
+  ContextMenuLabel,
+  ContextMenuPortal,
+  ContextMenuRadioGroup,
+  ContextMenuRadioItem,
+  ContextMenuRoot,
+  ContextMenuSeparator,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuTrigger,
+} from '@robonen/primitives';
+
+const showGrid = ref(true);
+const showRulers = ref(false);
+const zoom = ref('100');
+const lastAction = ref('Right-click the canvas to open the menu.');
+
+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';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-3">
+    <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"
+      >
+        Right-click anywhere in this area
+      </ContextMenuTrigger>
+
+      <ContextMenuPortal>
+        <ContextMenuContent :class="contentClass">
+          <ContextMenuItem
+            :class="itemClass"
+            @select="run('Cut')"
+          >
+            Cut
+            <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>
+          </ContextMenuItem>
+          <ContextMenuItem
+            :class="itemClass"
+            disabled
+          >
+            Paste
+            <span class="text-xs text-(--fg-subtle)">⌘V</span>
+          </ContextMenuItem>
+
+          <ContextMenuSeparator class="my-1 h-px bg-(--border)" />
+
+          <ContextMenuLabel class="px-2 py-1 text-xs font-medium text-(--fg-subtle)">
+            View
+          </ContextMenuLabel>
+
+          <ContextMenuCheckboxItem
+            v-model:checked="showGrid"
+            :class="itemClass"
+          >
+            <span class="flex items-center gap-2">
+              <span class="flex size-4 items-center justify-center">
+                <ContextMenuItemIndicator>
+                  <svg
+                    class="size-3.5"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="3"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  >
+                    <polyline points="20 6 9 17 4 12" />
+                  </svg>
+                </ContextMenuItemIndicator>
+              </span>
+              Show grid
+            </span>
+          </ContextMenuCheckboxItem>
+
+          <ContextMenuCheckboxItem
+            v-model:checked="showRulers"
+            :class="itemClass"
+          >
+            <span class="flex items-center gap-2">
+              <span class="flex size-4 items-center justify-center">
+                <ContextMenuItemIndicator>
+                  <svg
+                    class="size-3.5"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="3"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  >
+                    <polyline points="20 6 9 17 4 12" />
+                  </svg>
+                </ContextMenuItemIndicator>
+              </span>
+              Show rulers
+            </span>
+          </ContextMenuCheckboxItem>
+
+          <ContextMenuSub>
+            <ContextMenuSubTrigger
+              :class="itemClass"
+              class="data-[state=open]:bg-(--bg-subtle)"
+            >
+              Zoom
+              <svg
+                class="size-4 text-(--fg-subtle)"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <polyline points="9 18 15 12 9 6" />
+              </svg>
+            </ContextMenuSubTrigger>
+            <ContextMenuPortal>
+              <ContextMenuSubContent
+                :class="contentClass"
+                class="min-w-32"
+              >
+                <ContextMenuRadioGroup v-model="zoom">
+                  <ContextMenuRadioItem
+                    v-for="level in ['50', '100', '200']"
+                    :key="level"
+                    :value="level"
+                    :class="itemClass"
+                  >
+                    <span class="flex items-center gap-2">
+                      <span class="flex size-4 items-center justify-center">
+                        <ContextMenuItemIndicator>
+                          <span class="size-1.5 rounded-full bg-current" />
+                        </ContextMenuItemIndicator>
+                      </span>
+                      {{ level }}%
+                    </span>
+                  </ContextMenuRadioItem>
+                </ContextMenuRadioGroup>
+              </ContextMenuSubContent>
+            </ContextMenuPortal>
+          </ContextMenuSub>
+
+          <ContextMenuSeparator class="my-1 h-px bg-(--border)" />
+
+          <ContextMenuItem
+            :class="itemClass"
+            class="text-red-600 data-[highlighted]:bg-red-600 data-[highlighted]:text-white dark:text-red-400"
+            @select="run('Delete')"
+          >
+            Delete
+            <span class="text-xs opacity-70">⌫</span>
+          </ContextMenuItem>
+        </ContextMenuContent>
+      </ContextMenuPortal>
+    </ContextMenuRoot>
+
+    <p class="text-xs text-(--fg-muted)">
+      {{ lastAction }} · grid {{ showGrid ? 'on' : 'off' }} · zoom {{ zoom }}%
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/context-menu/index.ts b/vue/primitives/src/context-menu/index.ts
index b0153f3..816949f 100644
--- a/vue/primitives/src/context-menu/index.ts
+++ b/vue/primitives/src/context-menu/index.ts
@@ -9,7 +9,7 @@ export { default as ContextMenuLabel, type ContextMenuLabelProps } from './Conte
 export { default as ContextMenuPortal, type ContextMenuPortalProps } from './ContextMenuPortal.vue';
 export { default as ContextMenuRadioGroup, type ContextMenuRadioGroupEmits, type ContextMenuRadioGroupProps } from './ContextMenuRadioGroup.vue';
 export { default as ContextMenuRadioItem, type ContextMenuRadioItemEmits, type ContextMenuRadioItemProps } from './ContextMenuRadioItem.vue';
-export { default as ContextMenuRoot, type ContextMenuRootEmits, type ContextMenuRootProps } from './ContextMenuRoot.vue';
+export { default as ContextMenuRoot, type ContextMenuRootProps } from './ContextMenuRoot.vue';
 export { default as ContextMenuSeparator, type ContextMenuSeparatorProps } from './ContextMenuSeparator.vue';
 export { default as ContextMenuSub, type ContextMenuSubEmits, type ContextMenuSubProps } from './ContextMenuSub.vue';
 export { default as ContextMenuSubContent, type ContextMenuSubContentEmits, type ContextMenuSubContentProps } from './ContextMenuSubContent.vue';
diff --git a/vue/primitives/src/date-picker/DatePickerAnchor.vue b/vue/primitives/src/date-picker/DatePickerAnchor.vue
index 95dd4f0..ab6f8ea 100644
--- a/vue/primitives/src/date-picker/DatePickerAnchor.vue
+++ b/vue/primitives/src/date-picker/DatePickerAnchor.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PopperAnchorProps } from '../popper';
 
+/**
+ * Optional custom anchor for positioning the popover against an element other
+ * than the trigger (e.g. a field or input group). When present, the trigger
+ * stops acting as the anchor and the content is positioned relative to this.
+ */
 export interface DatePickerAnchorProps extends PopperAnchorProps {}
 </script>
 
diff --git a/vue/primitives/src/date-picker/DatePickerArrow.vue b/vue/primitives/src/date-picker/DatePickerArrow.vue
index c7cb296..a1ff962 100644
--- a/vue/primitives/src/date-picker/DatePickerArrow.vue
+++ b/vue/primitives/src/date-picker/DatePickerArrow.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PopperArrowProps } from '../popper';
 
+/**
+ * An optional arrow rendered inside `DatePickerContent` that points back at the
+ * trigger/anchor. Purely decorative; place it as a child of the content.
+ */
 export interface DatePickerArrowProps extends PopperArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/date-picker/DatePickerCalendar.vue b/vue/primitives/src/date-picker/DatePickerCalendar.vue
index 830099a..38d14f6 100644
--- a/vue/primitives/src/date-picker/DatePickerCalendar.vue
+++ b/vue/primitives/src/date-picker/DatePickerCalendar.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A styling wrapper for the calendar grid rendered inside the popover. The
+ * calendar subparts (`DatePickerGrid`, `DatePickerCell`, etc.) consume the
+ * calendar context provided by `DatePickerRoot`; this element just groups and
+ * labels them with a `data-primitives-date-picker-calendar` hook.
+ */
 export interface DatePickerCalendarProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/date-picker/DatePickerClose.vue b/vue/primitives/src/date-picker/DatePickerClose.vue
index b4e02f5..c5c3ccc 100644
--- a/vue/primitives/src/date-picker/DatePickerClose.vue
+++ b/vue/primitives/src/date-picker/DatePickerClose.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that closes the picker popover when clicked. Render it inside
+ * `DatePickerContent` (e.g. a "Done" or dismiss action).
+ */
 export interface DatePickerCloseProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/date-picker/DatePickerContent.vue b/vue/primitives/src/date-picker/DatePickerContent.vue
index 240c4da..a699381 100644
--- a/vue/primitives/src/date-picker/DatePickerContent.vue
+++ b/vue/primitives/src/date-picker/DatePickerContent.vue
@@ -3,6 +3,12 @@ import type { DismissableLayerEmits } from '../dismissable-layer';
 import type { FocusScopeEmits } from '../focus-scope';
 import type { PopperContentProps } from '../popper';
 
+/**
+ * The popover panel that holds the calendar. Handles Popper positioning,
+ * presence (mount/unmount on open), focus trapping/restoration, and dismissal
+ * via Escape or outside interaction. Renders only while open unless `forceMount`
+ * is set.
+ */
 export interface DatePickerContentProps extends PopperContentProps {
   /** Keep mounted for CSS exit animations. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/date-picker/DatePickerField.vue b/vue/primitives/src/date-picker/DatePickerField.vue
index 4df614f..e8f6049 100644
--- a/vue/primitives/src/date-picker/DatePickerField.vue
+++ b/vue/primitives/src/date-picker/DatePickerField.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A text input that renders the selected date and, when `editable`, lets users
+ * type a date that is parsed and committed back to the picker on blur/Enter.
+ * Aliased as `DatePickerInput`; defaults to a read-only display of the value.
+ */
 export interface DatePickerFieldProps extends PrimitiveProps {
   /** Allow typing into the field. @default false (read-only display) */
   editable?: boolean;
diff --git a/vue/primitives/src/date-picker/DatePickerPortal.vue b/vue/primitives/src/date-picker/DatePickerPortal.vue
index 0cbb882..67b0c23 100644
--- a/vue/primitives/src/date-picker/DatePickerPortal.vue
+++ b/vue/primitives/src/date-picker/DatePickerPortal.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { TeleportPrimitiveProps } from '../teleport';
 
+/**
+ * Teleports the popover content into a different part of the DOM (the body by
+ * default) so it escapes overflow/stacking-context clipping. Wrap
+ * `DatePickerContent` with it when the picker lives inside a scrolled or
+ * transformed container.
+ */
 export interface DatePickerPortalProps extends TeleportPrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/date-picker/DatePickerRoot.vue b/vue/primitives/src/date-picker/DatePickerRoot.vue
index 26a1ea3..67d1a80 100644
--- a/vue/primitives/src/date-picker/DatePickerRoot.vue
+++ b/vue/primitives/src/date-picker/DatePickerRoot.vue
@@ -2,6 +2,13 @@
 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. */
diff --git a/vue/primitives/src/date-picker/DatePickerTrigger.vue b/vue/primitives/src/date-picker/DatePickerTrigger.vue
index 989826c..711323f 100644
--- a/vue/primitives/src/date-picker/DatePickerTrigger.vue
+++ b/vue/primitives/src/date-picker/DatePickerTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The button that toggles the picker popover open and closed. Acts as the
+ * Popper anchor (unless a custom `DatePickerAnchor` is present) and carries the
+ * dialog-related ARIA wiring (`aria-haspopup`, `aria-expanded`, `aria-controls`).
+ */
 export interface DatePickerTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/date-picker/demo.vue b/vue/primitives/src/date-picker/demo.vue
new file mode 100644
index 0000000..d2b9e1d
--- /dev/null
+++ b/vue/primitives/src/date-picker/demo.vue
@@ -0,0 +1,158 @@
+<script lang="ts">
+import { defineComponent, h } from 'vue';
+import {
+  DatePickerCell,
+  DatePickerCellTrigger,
+  DatePickerGrid,
+  DatePickerGridBody,
+  DatePickerGridHead,
+  DatePickerGridRow,
+  DatePickerHeadCell,
+  useCalendarRootContext,
+} from '@robonen/primitives';
+
+// Reads the calendar context provided by DatePickerRoot. Defined as a child so
+// the injection resolves (the demo's own <script setup> is the Root's parent).
+const CalendarBody = defineComponent({
+  name: 'CalendarBody',
+  setup() {
+    const ctx = useCalendarRootContext();
+
+    return () => ctx.grid.value.map(month => h(
+      DatePickerGrid,
+      { key: month.value.toString(), month: month.value, class: 'w-full border-collapse select-none' },
+      () => [
+        h(DatePickerGridHead, null, () => h(
+          DatePickerGridRow,
+          { 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)' },
+            () => weekday,
+          )),
+        )),
+        h(DatePickerGridBody, null, () => month.weeks.map((week, w) => h(
+          DatePickerGridRow,
+          { key: w, class: 'flex w-full' },
+          () => week.map(day => h(
+            DatePickerCell,
+            { key: day.toString(), date: day, class: 'p-0.5' },
+            () => h(
+              DatePickerCellTrigger,
+              {
+                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
+                  data-[disabled]:cursor-not-allowed data-[disabled]:opacity-30`,
+              },
+            ),
+          )),
+        ))),
+      ],
+    ));
+  },
+});
+
+export default CalendarBody;
+</script>
+
+<script setup lang="ts">
+import {
+  DatePickerCalendar,
+  DatePickerClose,
+  DatePickerContent,
+  DatePickerField,
+  DatePickerHeading,
+  DatePickerNext,
+  DatePickerPrev,
+  DatePickerRoot,
+  DatePickerTrigger,
+} from '@robonen/primitives';
+import { ref } from 'vue';
+
+const value = ref<Date>();
+</script>
+
+<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>
+
+    <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)"
+        />
+        <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)"
+        >
+          <svg
+            class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+            stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+          >
+            <rect x="3" y="4" width="18" height="18" rx="2" />
+            <path d="M16 2v4M8 2v4M3 10h18" />
+          </svg>
+        </DatePickerTrigger>
+      </div>
+
+      <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"
+      >
+        <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"
+            >
+              ‹
+            </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"
+            >
+              ›
+            </DatePickerNext>
+          </div>
+
+          <CalendarBody />
+        </DatePickerCalendar>
+
+        <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"
+            @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"
+          >
+            Done
+          </DatePickerClose>
+        </div>
+      </DatePickerContent>
+
+      <p v-if="false">{{ open }}</p>
+    </DatePickerRoot>
+
+    <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>
+      </template>
+      <template v-else>
+        No date selected yet
+      </template>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/dialog/DialogClose.vue b/vue/primitives/src/dialog/DialogClose.vue
index bb04b75..482eaf1 100644
--- a/vue/primitives/src/dialog/DialogClose.vue
+++ b/vue/primitives/src/dialog/DialogClose.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that closes the dialog when activated. Place inside Content for an
+ * explicit dismiss control (e.g. an "X" in the corner or a "Cancel" button).
+ */
 export interface DialogCloseProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/dialog/DialogContent.vue b/vue/primitives/src/dialog/DialogContent.vue
index 0bc656c..bd9d150 100644
--- a/vue/primitives/src/dialog/DialogContent.vue
+++ b/vue/primitives/src/dialog/DialogContent.vue
@@ -1,6 +1,13 @@
 <script lang="ts">
 import type { DialogContentImplEmits, DialogContentImplProps } from './DialogContentImpl.vue';
 
+/**
+ * The dialog panel itself — the container for Title, Description, and the body.
+ * Renders only while open and picks a modal or non-modal implementation from
+ * the Root's `modal` setting: modal traps focus, locks body scroll, and hides
+ * the rest of the page from assistive tech; non-modal does none of these. Emits
+ * focus and dismissal events so consumers can guard against closing.
+ */
 export interface DialogContentProps extends Omit<DialogContentImplProps, 'trapFocus' | 'disableOutsidePointerEvents'> {
   /** Keep mounted for CSS exit animations. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/dialog/DialogContentImpl.vue b/vue/primitives/src/dialog/DialogContentImpl.vue
index 3358bad..c0e9a21 100644
--- a/vue/primitives/src/dialog/DialogContentImpl.vue
+++ b/vue/primitives/src/dialog/DialogContentImpl.vue
@@ -3,6 +3,11 @@ import type { DismissableLayerEmits } from '../dismissable-layer';
 import type { FocusScopeEmits } from '../focus-scope';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Internal shared implementation behind DialogContent — wraps a FocusScope and
+ * a DismissableLayer and applies the dialog ARIA wiring. Not exported; the modal
+ * and non-modal Content variants render this with the appropriate flags.
+ */
 export interface DialogContentImplProps extends PrimitiveProps {
   /** Trap focus inside the content (modal dialogs). */
   trapFocus?: boolean;
diff --git a/vue/primitives/src/dialog/DialogDescription.vue b/vue/primitives/src/dialog/DialogDescription.vue
index 3b07310..af0496c 100644
--- a/vue/primitives/src/dialog/DialogDescription.vue
+++ b/vue/primitives/src/dialog/DialogDescription.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * An optional supporting description for the dialog. Its id is wired to the
+ * Content's `aria-describedby` so screen readers announce it after the title.
+ */
 export interface DialogDescriptionProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/dialog/DialogOverlay.vue b/vue/primitives/src/dialog/DialogOverlay.vue
index 55d1e4b..cc49914 100644
--- a/vue/primitives/src/dialog/DialogOverlay.vue
+++ b/vue/primitives/src/dialog/DialogOverlay.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A full-screen layer rendered behind the Content that dims and covers the page
+ * while a modal dialog is open. Only renders in modal mode; omit it for
+ * non-modal dialogs.
+ */
 export interface DialogOverlayProps extends PrimitiveProps {
   /**
    * Keep overlay mounted even when the dialog is closed — useful for CSS
diff --git a/vue/primitives/src/dialog/DialogPortal.vue b/vue/primitives/src/dialog/DialogPortal.vue
index 38b9b49..2db8ee1 100644
--- a/vue/primitives/src/dialog/DialogPortal.vue
+++ b/vue/primitives/src/dialog/DialogPortal.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { TeleportPrimitiveProps } from '../teleport';
 
+/**
+ * Teleports the Overlay and Content out of the normal DOM flow (by default into
+ * `body`) so they render above the rest of the page and escape `overflow`/
+ * stacking contexts. Mounts its children only while the dialog is open.
+ */
 export interface DialogPortalProps extends TeleportPrimitiveProps {
   /**
    * When true the Portal (and its descendants) remain mounted even when the
diff --git a/vue/primitives/src/dialog/DialogRoot.vue b/vue/primitives/src/dialog/DialogRoot.vue
index e3a8ddb..894f175 100644
--- a/vue/primitives/src/dialog/DialogRoot.vue
+++ b/vue/primitives/src/dialog/DialogRoot.vue
@@ -1,4 +1,16 @@
 <script lang="ts">
+/**
+ * A window overlaid on the page that interrupts the rest of the app while it is
+ * open — used for tasks like forms, confirmations, or detail views that should
+ * sit above the current context. Composed from a Trigger, a Portal, an Overlay,
+ * and Content (with Title, Description, and Close).
+ *
+ * Root manages the open state and provides context to every part. Bind
+ * `v-model:open` to control it, or rely on the Trigger/Close for uncontrolled
+ * use. Modal by default (traps focus, locks scroll, marks the rest of the
+ * document inert); set `modal="false"` for a non-blocking dialog. For
+ * destructive confirmations that demand an explicit choice, prefer AlertDialog.
+ */
 export interface DialogRootProps {
   /** Uncontrolled initial open state. Ignored once `v-model:open` is bound. */
   defaultOpen?: boolean;
diff --git a/vue/primitives/src/dialog/DialogTitle.vue b/vue/primitives/src/dialog/DialogTitle.vue
index 6559807..df06a6c 100644
--- a/vue/primitives/src/dialog/DialogTitle.vue
+++ b/vue/primitives/src/dialog/DialogTitle.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * An accessible title for the dialog. Its id is wired to the Content's
+ * `aria-labelledby`, so render one inside every dialog (visually hide it if you
+ * do not want it shown).
+ */
 export interface DialogTitleProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/dialog/DialogTrigger.vue b/vue/primitives/src/dialog/DialogTrigger.vue
index c76de89..13572c9 100644
--- a/vue/primitives/src/dialog/DialogTrigger.vue
+++ b/vue/primitives/src/dialog/DialogTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The button that toggles the dialog open. Wires up `aria-haspopup`,
+ * `aria-expanded`, and `aria-controls`, and is the element focus returns to
+ * when the dialog closes.
+ */
 export interface DialogTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/dialog/demo.vue b/vue/primitives/src/dialog/demo.vue
new file mode 100644
index 0000000..6224e10
--- /dev/null
+++ b/vue/primitives/src/dialog/demo.vue
@@ -0,0 +1,125 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogOverlay,
+  DialogPortal,
+  DialogRoot,
+  DialogTitle,
+  DialogTrigger,
+} from '@robonen/primitives';
+
+const open = ref(false);
+
+const name = ref('Ada Lovelace');
+const email = ref('ada@example.com');
+const saved = ref('');
+
+const draftName = ref(name.value);
+const draftEmail = ref(email.value);
+
+function onOpenAutoFocus() {
+  // Start from the current values each time the dialog opens.
+  draftName.value = name.value;
+  draftEmail.value = email.value;
+}
+
+function save() {
+  name.value = draftName.value;
+  email.value = draftEmail.value;
+  saved.value = `${name.value} · ${email.value}`;
+  open.value = false;
+}
+</script>
+
+<template>
+  <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)">
+        {{ name.charAt(0) }}
+      </div>
+      <div class="text-sm leading-tight">
+        <div class="font-medium">{{ name }}</div>
+        <div class="text-(--fg-muted)">{{ email }}</div>
+      </div>
+    </div>
+
+    <p v-if="saved" class="text-xs text-emerald-600 dark:text-emerald-400">
+      Saved: {{ saved }}
+    </p>
+
+    <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)"
+      >
+        Edit profile
+      </DialogTrigger>
+
+      <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"
+          @open-auto-focus="onOpenAutoFocus"
+        >
+          <div class="flex items-start justify-between gap-4">
+            <div>
+              <DialogTitle class="text-base font-semibold text-(--fg)">
+                Edit profile
+              </DialogTitle>
+              <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)"
+            >
+              <svg
+                class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+                stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+              >
+                <path d="M18 6 6 18M6 6l12 12" />
+              </svg>
+            </DialogClose>
+          </div>
+
+          <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>
+              <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)"
+              >
+            </label>
+            <label class="flex flex-col gap-1 text-sm">
+              <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)"
+              >
+            </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)"
+              >
+                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)"
+              >
+                Save changes
+              </button>
+            </div>
+          </form>
+        </DialogContent>
+      </DialogPortal>
+    </DialogRoot>
+  </div>
+</template>
diff --git a/vue/primitives/src/dismissable-layer/DismissableLayer.vue b/vue/primitives/src/dismissable-layer/DismissableLayer.vue
index 1f8e324..38e740f 100644
--- a/vue/primitives/src/dismissable-layer/DismissableLayer.vue
+++ b/vue/primitives/src/dismissable-layer/DismissableLayer.vue
@@ -1,6 +1,14 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A low-level building block that detects when the user interacts away from its
+ * content — pressing Escape, clicking/pointing outside, or moving focus out — and
+ * emits a `dismiss` event so the consumer can close the layer. Layers are tracked
+ * in a global stack so only the topmost one responds, letting dialogs, popovers,
+ * menus, and tooltips nest correctly. Use it to wrap any transient overlay whose
+ * lifecycle you want driven by outside-interaction; it renders no UI of its own.
+ */
 export interface DismissableLayerProps extends PrimitiveProps {
   /**
    * When enabled, outside pointer events are blocked — the rest of the
diff --git a/vue/primitives/src/drawer/DrawerContent.vue b/vue/primitives/src/drawer/DrawerContent.vue
new file mode 100644
index 0000000..193a0e9
--- /dev/null
+++ b/vue/primitives/src/drawer/DrawerContent.vue
@@ -0,0 +1,120 @@
+<script lang="ts">
+import type { DialogContentEmits, DialogContentProps } from '../dialog';
+
+/**
+ * The draggable drawer panel. Wraps Dialog's Content (so it keeps focus
+ * trapping, scroll locking, and dismissal) and adds the pointer-drag gesture,
+ * snap-point positioning, and the `data-drawer-*` hooks the CSS animates.
+ * Bring your own size/colour/padding via `class`/`style`.
+ */
+export interface DrawerContentProps extends DialogContentProps {}
+
+export type DrawerContentEmits = DialogContentEmits;
+</script>
+
+<script setup lang="ts">
+import { computed, ref, watch, watchEffect } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { DialogContent } from '../dialog';
+import { injectDrawerRootContext } from './context';
+import { useScaleBackground } from './useScaleBackground';
+
+defineProps<DrawerContentProps>();
+const emit = defineEmits<DrawerContentEmits>();
+
+const {
+  isOpen,
+  snapPointsOffset,
+  hasSnapPoints,
+  drawerRef,
+  onPress,
+  onDrag,
+  onRelease,
+  modal,
+  dismissible,
+  keyboardIsOpen,
+  direction,
+  handleOnly,
+} = injectDrawerRootContext();
+
+const { forwardRef, currentElement } = useForwardExpose();
+
+// Track the content element for the drag math (undefined while closed/unmounted).
+watch(currentElement, (el) => {
+  drawerRef.value = el as HTMLElement | undefined;
+}, { immediate: true, flush: 'post' });
+
+useScaleBackground();
+
+const delayedSnapPoints = ref(false);
+
+const snapPointHeight = computed(() => {
+  if (snapPointsOffset.value && snapPointsOffset.value.length > 0)
+    return `${snapPointsOffset.value[0]}px`;
+
+  return '0';
+});
+
+function handlePointerDownOutside(event: Event) {
+  if (!modal.value || event.defaultPrevented) {
+    event.preventDefault();
+    return;
+  }
+
+  if (keyboardIsOpen.value)
+    keyboardIsOpen.value = false;
+
+  // Let the underlying DismissableLayer close a dismissible modal drawer;
+  // otherwise hold it open.
+  if (!dismissible.value)
+    event.preventDefault();
+}
+
+function handleEscapeKeyDown(event: KeyboardEvent) {
+  if (!dismissible.value)
+    event.preventDefault();
+}
+
+function handlePointerDown(event: PointerEvent) {
+  if (handleOnly.value)
+    return;
+  onPress(event);
+}
+
+function handlePointerMove(event: PointerEvent) {
+  if (handleOnly.value)
+    return;
+  onDrag(event);
+}
+
+watchEffect(() => {
+  if (hasSnapPoints.value) {
+    globalThis.requestAnimationFrame(() => {
+      delayedSnapPoints.value = true;
+    });
+  }
+});
+</script>
+
+<template>
+  <DialogContent
+    :ref="forwardRef"
+    data-drawer
+    :data-drawer-direction="direction"
+    :data-drawer-delayed-snap-points="delayedSnapPoints ? 'true' : 'false'"
+    :data-drawer-snap-points="isOpen && hasSnapPoints ? 'true' : 'false'"
+    :style="{ '--snap-point-height': snapPointHeight }"
+    @pointerdown="handlePointerDown"
+    @pointermove="handlePointerMove"
+    @pointerup="onRelease"
+    @open-auto-focus.prevent
+    @pointer-down-outside="handlePointerDownOutside"
+    @escape-key-down="handleEscapeKeyDown"
+    @close-auto-focus="emit('closeAutoFocus', $event)"
+    @focus-outside="emit('focusOutside', $event)"
+    @interact-outside="emit('interactOutside', $event)"
+    @dismiss="emit('dismiss')"
+  >
+    <slot />
+  </DialogContent>
+</template>
diff --git a/vue/primitives/src/drawer/DrawerHandle.vue b/vue/primitives/src/drawer/DrawerHandle.vue
new file mode 100644
index 0000000..c42965c
--- /dev/null
+++ b/vue/primitives/src/drawer/DrawerHandle.vue
@@ -0,0 +1,123 @@
+<script lang="ts">
+import type { DrawerHandleProps } from './controls';
+
+export type { DrawerHandleProps } from './controls';
+
+/**
+ * The grab handle at the edge of the drawer. Dragging it always moves the
+ * drawer (even when the root is `handleOnly`), and a tap cycles through snap
+ * points — or closes a dismissible drawer once past the last one.
+ */
+</script>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { injectDrawerRootContext } from './context';
+
+const props = withDefaults(defineProps<DrawerHandleProps>(), {
+  preventCycle: false,
+});
+
+const LONG_HANDLE_PRESS_TIMEOUT = 250;
+const DOUBLE_TAP_TIMEOUT = 120;
+
+const { onPress, onDrag, handleRef, handleOnly, isOpen, snapPoints, activeSnapPoint, isDragging, dismissible, closeDrawer }
+  = injectDrawerRootContext();
+
+// 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 closeTimeoutId = ref<number | null>(null);
+const shouldCancelInteraction = ref(false);
+
+function handleStartCycle() {
+  // Ignore the second tap of a double-tap.
+  if (shouldCancelInteraction.value) {
+    handleCancelInteraction();
+    return;
+  }
+
+  globalThis.setTimeout(() => {
+    handleCycleSnapPoints();
+  }, DOUBLE_TAP_TIMEOUT);
+}
+
+function handleCycleSnapPoints() {
+  // Don't treat an accidental tap during a resize as a cycle.
+  if (isDragging.value || props.preventCycle || shouldCancelInteraction.value) {
+    handleCancelInteraction();
+    return;
+  }
+
+  handleCancelInteraction();
+
+  if (!snapPoints.value || snapPoints.value.length === 0) {
+    if (!dismissible.value)
+      closeDrawer();
+
+    return;
+  }
+
+  const isLastSnapPoint = activeSnapPoint.value === snapPoints.value[snapPoints.value.length - 1];
+
+  if (isLastSnapPoint && dismissible.value) {
+    closeDrawer();
+    return;
+  }
+
+  const currentSnapIndex = snapPoints.value.indexOf(activeSnapPoint.value);
+
+  if (currentSnapIndex === -1)
+    return; // activeSnapPoint not in snapPoints
+
+  const nextSnapPointIndex = isLastSnapPoint ? 0 : currentSnapIndex + 1;
+  activeSnapPoint.value = snapPoints.value[nextSnapPointIndex];
+}
+
+function handleStartInteraction() {
+  closeTimeoutId.value = globalThis.setTimeout(() => {
+    // A long press cancels the tap-to-cycle.
+    shouldCancelInteraction.value = true;
+  }, LONG_HANDLE_PRESS_TIMEOUT);
+}
+
+function handleCancelInteraction() {
+  if (closeTimeoutId.value)
+    globalThis.clearTimeout(closeTimeoutId.value);
+
+  shouldCancelInteraction.value = false;
+}
+
+function handlePointerDown(event: PointerEvent) {
+  if (handleOnly.value)
+    onPress(event);
+  handleStartInteraction();
+}
+
+function handlePointerMove(event: PointerEvent) {
+  if (handleOnly.value)
+    onDrag(event);
+}
+</script>
+
+<template>
+  <div
+    ref="handleElement"
+    :data-drawer-visible="isOpen ? 'true' : 'false'"
+    data-drawer-handle
+    aria-hidden="true"
+    @click="handleStartCycle"
+    @pointercancel="handleCancelInteraction"
+    @pointerdown="handlePointerDown"
+    @pointermove="handlePointerMove"
+  >
+    <span data-drawer-handle-hitarea aria-hidden="true">
+      <slot />
+    </span>
+  </div>
+</template>
diff --git a/vue/primitives/src/drawer/DrawerOverlay.vue b/vue/primitives/src/drawer/DrawerOverlay.vue
new file mode 100644
index 0000000..319cf9f
--- /dev/null
+++ b/vue/primitives/src/drawer/DrawerOverlay.vue
@@ -0,0 +1,37 @@
+<script lang="ts">
+import type { DialogOverlayProps } from '../dialog';
+
+/**
+ * The dimming layer behind the drawer. Wraps Dialog's Overlay and exposes the
+ * `data-drawer-overlay` hooks so its opacity can fade in step with the drag and
+ * with snap points. Only renders for modal drawers.
+ */
+export interface DrawerOverlayProps extends DialogOverlayProps {}
+</script>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { DialogOverlay } from '../dialog';
+import { injectDrawerRootContext } from './context';
+
+defineProps<DrawerOverlayProps>();
+
+const { overlayRef, hasSnapPoints, isOpen, shouldFade } = injectDrawerRootContext();
+const { forwardRef, currentElement } = useForwardExpose();
+
+watch(currentElement, (el) => {
+  overlayRef.value = el as HTMLElement | undefined;
+}, { immediate: true, flush: 'post' });
+</script>
+
+<template>
+  <DialogOverlay
+    :ref="forwardRef"
+    data-drawer-overlay
+    :data-drawer-snap-points="isOpen && hasSnapPoints ? 'true' : 'false'"
+    :data-drawer-snap-points-overlay="isOpen && shouldFade ? 'true' : 'false'"
+  >
+    <slot />
+  </DialogOverlay>
+</template>
diff --git a/vue/primitives/src/drawer/DrawerRoot.vue b/vue/primitives/src/drawer/DrawerRoot.vue
new file mode 100644
index 0000000..5ec7ea1
--- /dev/null
+++ b/vue/primitives/src/drawer/DrawerRoot.vue
@@ -0,0 +1,115 @@
+<script lang="ts">
+import type { DrawerRootEmits, DrawerRootProps } from './controls';
+
+export type { DrawerRootEmits, DrawerRootProps } from './controls';
+
+/**
+ * A panel that slides in from an edge of the screen and can be dragged to
+ * dismiss — the Vaul-style drawer, rebuilt on top of this library's Dialog so it
+ * inherits focus trapping, scroll locking, and dismissal behaviour. Compose it
+ * from a Trigger, a Portal, an Overlay, and Content (optionally with a Handle,
+ * Title, Description, and Close).
+ *
+ * Bind `v-model:open` to control it, or rely on the Trigger/Close for
+ * uncontrolled use. Supports snap points (`v-model:active-snap-point`), four
+ * `direction`s, an optional scaled background, and nesting via DrawerRootNested.
+ */
+</script>
+
+<script setup lang="ts">
+import { computed, ref, toRefs, watch } from 'vue';
+import { useStyleTag } from '@robonen/vue';
+import { DialogRoot } from '../dialog';
+import { provideDrawerRootContext } from './context';
+import { useDrawer } from './controls';
+import { CLOSE_THRESHOLD, SCROLL_LOCK_TIMEOUT, TRANSITIONS } from './constants';
+import { DRAWER_STYLES, DRAWER_STYLE_ID } from './style';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(defineProps<DrawerRootProps>(), {
+  open: undefined,
+  defaultOpen: false,
+  fixed: undefined,
+  dismissible: true,
+  activeSnapPoint: undefined,
+  snapPoints: undefined,
+  shouldScaleBackground: undefined,
+  setBackgroundColorOnScale: true,
+  closeThreshold: CLOSE_THRESHOLD,
+  fadeFromIndex: undefined,
+  nested: false,
+  modal: true,
+  scrollLockTimeout: SCROLL_LOCK_TIMEOUT,
+  direction: 'bottom',
+  noBodyStyles: false,
+  handleOnly: false,
+  preventScrollRestoration: false,
+});
+
+const emit = defineEmits<DrawerRootEmits>();
+
+// Inject the critical drawer CSS once (reference-counted across every drawer).
+useStyleTag(DRAWER_STYLES, { id: DRAWER_STYLE_ID });
+
+const fadeFromIndex = computed(() => props.fadeFromIndex ?? (props.snapPoints && props.snapPoints.length - 1));
+
+// `isOpen` is the single source of truth for the open state. It's seeded from the
+// controlled `open` prop (or `defaultOpen`), kept in sync with the prop while
+// controlled, and is the ref the engine and the underlying Dialog both read.
+const isOpen = ref<boolean>(props.open ?? props.defaultOpen);
+
+watch(() => props.open, (value) => {
+  if (value !== undefined)
+    isOpen.value = value;
+});
+
+// Every change to `isOpen` (from any source) notifies the consumer's `v-model`
+// once and schedules `animationEnd`. Close-specific effects (`close`, snap reset)
+// live in the engine's own watch on the same ref.
+watch(isOpen, (o) => {
+  emit('update:open', o);
+  setTimeout(() => emit('animationEnd', o), TRANSITIONS.DURATION * 1000);
+});
+
+const localActiveSnapPoint = ref<number | string | null | undefined>(
+  props.activeSnapPoint ?? props.snapPoints?.[0] ?? null,
+);
+const activeSnapPoint = computed<number | string | null | undefined>({
+  get: () => (props.activeSnapPoint !== undefined ? props.activeSnapPoint : localActiveSnapPoint.value),
+  set: (value) => {
+    if (props.activeSnapPoint === undefined)
+      localActiveSnapPoint.value = value;
+    if (value !== null && value !== undefined)
+      emit('update:activeSnapPoint', value);
+  },
+});
+
+const emitHandlers = {
+  emitDrag: (percentageDragged: number) => emit('drag', percentageDragged),
+  emitRelease: (o: boolean) => emit('release', o),
+  emitClose: () => emit('close'),
+};
+
+const { modal } = provideDrawerRootContext(
+  useDrawer({
+    ...emitHandlers,
+    ...toRefs(props),
+    activeSnapPoint,
+    fadeFromIndex,
+    open: isOpen,
+  }),
+);
+
+// The Dialog reports its own dismissals (trigger, close button, escape, outside
+// click) here; mirror them into `isOpen` and let the watchers do the rest.
+function handleOpenChange(o: boolean) {
+  isOpen.value = o;
+}
+</script>
+
+<template>
+  <DialogRoot :open="isOpen" :modal="modal" @update:open="handleOpenChange">
+    <slot :open="isOpen" />
+  </DialogRoot>
+</template>
diff --git a/vue/primitives/src/drawer/DrawerRootNested.vue b/vue/primitives/src/drawer/DrawerRootNested.vue
new file mode 100644
index 0000000..72c9a0c
--- /dev/null
+++ b/vue/primitives/src/drawer/DrawerRootNested.vue
@@ -0,0 +1,54 @@
+<script lang="ts">
+/**
+ * A drawer nested inside another drawer. Behaves like DrawerRoot but reports its
+ * drag/open state to the parent so the parent visibly recedes as this one opens.
+ * Place it inside a parent DrawerRoot's content.
+ */
+</script>
+
+<script setup lang="ts">
+import DrawerRoot from './DrawerRoot.vue';
+import type { DrawerRootEmits, DrawerRootProps } from './controls';
+import { injectDrawerRootContext } from './context';
+
+const props = defineProps<DrawerRootProps>();
+const emit = defineEmits<DrawerRootEmits>();
+
+const { onNestedDrag, onNestedOpenChange, onNestedRelease } = injectDrawerRootContext();
+
+function onClose() {
+  onNestedOpenChange(false);
+  emit('close');
+}
+
+function onDrag(percentageDragged: number) {
+  onNestedDrag(percentageDragged);
+  emit('drag', percentageDragged);
+}
+
+function onRelease(open: boolean) {
+  onNestedRelease(open);
+  emit('release', open);
+}
+
+function onOpenChange(open: boolean) {
+  if (open)
+    onNestedOpenChange(open);
+  emit('update:open', open);
+}
+</script>
+
+<template>
+  <DrawerRoot
+    v-bind="props"
+    nested
+    @close="onClose"
+    @drag="onDrag"
+    @release="onRelease"
+    @update:open="onOpenChange"
+    @update:active-snap-point="emit('update:activeSnapPoint', $event)"
+    @animation-end="emit('animationEnd', $event)"
+  >
+    <slot />
+  </DrawerRoot>
+</template>
diff --git a/vue/primitives/src/drawer/__test__/Drawer.test.ts b/vue/primitives/src/drawer/__test__/Drawer.test.ts
new file mode 100644
index 0000000..773a070
--- /dev/null
+++ b/vue/primitives/src/drawer/__test__/Drawer.test.ts
@@ -0,0 +1,221 @@
+import type { VueWrapper } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import {
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHandle,
+  DrawerOverlay,
+  DrawerPortal,
+  DrawerRoot,
+  DrawerTitle,
+  DrawerTrigger,
+} from '../index';
+
+const wrappers: Array<VueWrapper<any>> = [];
+
+afterEach(() => {
+  while (wrappers.length) wrappers.pop()!.unmount();
+  document.body.innerHTML = '';
+  document.body.removeAttribute('style');
+  document.getElementById('robonen-drawer')?.remove();
+});
+
+function track<T extends VueWrapper<any>>(w: T): T {
+  wrappers.push(w);
+  return w;
+}
+
+/** Drains Vue's scheduler (including `flush: 'post'` watchers). */
+async function flush(): Promise<void> {
+  await nextTick();
+  await nextTick();
+  await nextTick();
+}
+
+function $<T extends Element = HTMLElement>(selector: string): T | null {
+  return document.querySelector<T>(selector);
+}
+
+function $content(): HTMLElement | null {
+  return $('[data-drawer]');
+}
+
+function $trigger(): HTMLElement {
+  return $<HTMLElement>('[aria-haspopup="dialog"]')!;
+}
+
+function $close(): HTMLButtonElement | undefined {
+  return [...document.querySelectorAll('button')].find(b => b.textContent === 'Close');
+}
+
+interface MountOptions {
+  open?: boolean;
+  defaultOpen?: boolean;
+  modal?: boolean;
+  dismissible?: boolean;
+  direction?: 'top' | 'bottom' | 'left' | 'right';
+  withHandle?: boolean;
+  onUpdateOpen?: (v: boolean) => void;
+  onClose?: () => void;
+}
+
+function mountDrawer(options: MountOptions = {}) {
+  const { withHandle = true } = options;
+
+  const Wrapper = defineComponent({
+    setup() {
+      return () => h(
+        DrawerRoot,
+        {
+          open: options.open,
+          defaultOpen: options.defaultOpen,
+          modal: options.modal ?? true,
+          dismissible: options.dismissible ?? true,
+          direction: options.direction ?? 'bottom',
+          'onUpdate:open': options.onUpdateOpen,
+          onClose: options.onClose,
+        },
+        {
+          default: () => [
+            h(DrawerTrigger, null, { default: () => 'Open' }),
+            h(DrawerPortal, null, {
+              default: () => [
+                h(DrawerOverlay, { 'data-testid': 'overlay' }),
+                h(DrawerContent, null, {
+                  default: () => [
+                    withHandle ? h(DrawerHandle) : null,
+                    h(DrawerTitle, null, { default: () => 'Title' }),
+                    h(DrawerDescription, null, { default: () => 'Desc' }),
+                    h(DrawerClose, null, { default: () => 'Close' }),
+                  ],
+                }),
+              ],
+            }),
+          ],
+        },
+      );
+    },
+  });
+
+  return track(mount(Wrapper, { attachTo: document.body }));
+}
+
+describe('Drawer / markup', () => {
+  it('renders closed by default', () => {
+    mountDrawer();
+    expect($trigger().getAttribute('data-state')).toBe('closed');
+    expect($content()).toBeNull();
+  });
+
+  it('injects the critical drawer stylesheet once', async () => {
+    mountDrawer({ defaultOpen: true });
+    await flush();
+    const tags = document.querySelectorAll('#robonen-drawer');
+    expect(tags.length).toBe(1);
+    expect(tags[0]!.textContent).toContain('@keyframes slideFromBottom');
+  });
+
+  it('exposes drawer data attributes on the content when open', async () => {
+    mountDrawer({ defaultOpen: true, direction: 'right' });
+    await flush();
+    const content = $content()!;
+    expect(content.getAttribute('data-state')).toBe('open');
+    expect(content.getAttribute('data-drawer-direction')).toBe('right');
+    expect(content.hasAttribute('data-drawer')).toBe(true);
+  });
+
+  it('renders the handle without throwing (handleRef wiring)', async () => {
+    mountDrawer({ defaultOpen: true, withHandle: true });
+    await flush();
+    expect($('[data-drawer-handle]')).toBeTruthy();
+    expect($('[data-drawer-handle-hitarea]')).toBeTruthy();
+  });
+});
+
+describe('Drawer / open state', () => {
+  it('opens when the trigger is clicked (uncontrolled)', async () => {
+    mountDrawer();
+    $trigger().click();
+    await flush();
+    expect($content()).toBeTruthy();
+  });
+
+  it('closes when DrawerClose is clicked', async () => {
+    mountDrawer({ defaultOpen: true });
+    await flush();
+    $close()!.click();
+    await flush();
+    // Presence keeps the node for the exit animation; data-state flips to closed.
+    expect($content()?.getAttribute('data-state') ?? 'closed').toBe('closed');
+  });
+
+  it('emits update:open when the trigger is clicked (controlled)', async () => {
+    const onUpdateOpen = vi.fn();
+    mountDrawer({ open: false, onUpdateOpen });
+
+    $trigger().click();
+    await flush();
+    expect(onUpdateOpen).toHaveBeenCalledWith(true);
+  });
+
+  it('emits close exactly once when dismissed via DrawerClose', async () => {
+    const onClose = vi.fn();
+    mountDrawer({ defaultOpen: true, onClose });
+    await flush();
+
+    $close()!.click();
+    await flush();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('emits close when a controlled drawer is closed by flipping v-model:open', async () => {
+    // Regression: closing purely by setting the bound `open` prop to false (not
+    // via a dialog dismissal) must still run the close side effects.
+    const onClose = vi.fn();
+    const state = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(
+          DrawerRoot,
+          {
+            open: state.value,
+            'onUpdate:open': (v: boolean) => { state.value = v; },
+            onClose,
+          },
+          {
+            default: () => h(DrawerPortal, null, {
+              default: () => h(DrawerContent, null, {
+                default: () => h(DrawerTitle, null, { default: () => 'Title' }),
+              }),
+            }),
+          },
+        );
+      },
+    });
+
+    track(mount(Wrapper, { attachTo: document.body }));
+    await flush();
+    expect($content()).toBeTruthy();
+
+    state.value = false;
+    await flush();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('Drawer / overlay', () => {
+  it('renders an overlay for modal drawers', async () => {
+    mountDrawer({ defaultOpen: true, modal: true });
+    await flush();
+    expect($('[data-drawer-overlay]')).toBeTruthy();
+  });
+
+  it('omits the overlay for non-modal drawers', async () => {
+    mountDrawer({ defaultOpen: true, modal: false });
+    await flush();
+    expect($('[data-drawer-overlay]')).toBeNull();
+  });
+});
diff --git a/vue/primitives/src/drawer/constants.ts b/vue/primitives/src/drawer/constants.ts
new file mode 100644
index 0000000..2ed9705
--- /dev/null
+++ b/vue/primitives/src/drawer/constants.ts
@@ -0,0 +1,26 @@
+/** Open/close animation timing, shared by the CSS keyframes and the JS transitions. */
+export const TRANSITIONS = {
+  DURATION: 0.5,
+  EASE: [0.32, 0.72, 0, 1],
+} as const;
+
+/** Drag speed (px/ms) above which a flick closes the drawer regardless of distance. */
+export const VELOCITY_THRESHOLD = 0.4;
+
+/** Default fraction of the drawer that must be swiped away before it closes. */
+export const CLOSE_THRESHOLD = 0.25;
+
+/** How long (ms) dragging stays disabled after scrolling content inside the drawer. */
+export const SCROLL_LOCK_TIMEOUT = 100;
+
+/** Corner radius (px) applied to the scaled background wrapper while open. */
+export const BORDER_RADIUS = 8;
+
+/** Pixels a parent drawer is displaced when a nested drawer opens. */
+export const NESTED_DISPLACEMENT = 16;
+
+/** Top inset (px) used when scaling the background, mimicking a stacked-card look. */
+export const WINDOW_TOP_OFFSET = 26;
+
+/** Class applied to the drawer element while a drag is in progress. */
+export const DRAG_CLASS = 'drawer-dragging';
diff --git a/vue/primitives/src/drawer/context.ts b/vue/primitives/src/drawer/context.ts
new file mode 100644
index 0000000..18c9502
--- /dev/null
+++ b/vue/primitives/src/drawer/context.ts
@@ -0,0 +1,83 @@
+import type { Ref } from 'vue';
+import { useContextFactory } from '@robonen/vue';
+import type { DrawerDirection } from './types';
+
+export interface DrawerRootContext {
+  /** Source-of-truth open state (also bound to the underlying Dialog). */
+  open: Ref<boolean>;
+  /** Alias of {@link open}; kept for parity with consumers reading `isOpen`. */
+  isOpen: Ref<boolean>;
+  /** Whether the drawer blocks the rest of the page (focus trap, scroll lock). */
+  modal: Ref<boolean>;
+  /** Becomes `true` the first time the drawer opens; gates Safari position fixes. */
+  hasBeenOpened: Ref<boolean>;
+  /** DOM node of the drawer content (DialogContent), tracked for drag math. */
+  drawerRef: Ref<HTMLElement | undefined>;
+  /** DOM node of the overlay, faded in sync with the drag. */
+  overlayRef: Ref<HTMLElement | undefined>;
+  /** DOM node of the drag handle. */
+  handleRef: Ref<HTMLElement | undefined>;
+  /** Whether a pointer drag is currently in progress. */
+  isDragging: Ref<boolean>;
+  /** Timestamp the active drag started, for velocity calculations. */
+  dragStartTime: Ref<Date | null>;
+  /** Latched once a drag is permitted, so it can't be cancelled mid-gesture. */
+  isAllowedToDrag: Ref<boolean>;
+  /** Configured snap points (fractions of the screen or px strings). */
+  snapPoints: Ref<Array<number | string> | undefined>;
+  /** Whether any snap points are configured. */
+  hasSnapPoints: Ref<boolean>;
+  /** Whether the on-screen keyboard is currently considered open. */
+  keyboardIsOpen: Ref<boolean>;
+  /** The currently active snap point value (px string, fraction, or null). */
+  activeSnapPoint: Ref<number | string | null | undefined>;
+  /** Pointer coordinate (clientX/clientY) captured at drag start. */
+  pointerStart: Ref<number>;
+  /** Whether dragging/clicking outside/escape closes the drawer. */
+  dismissible: Ref<boolean>;
+  /** Measured height of the drawer content in px. */
+  drawerHeightRef: Ref<number>;
+  /** Pixel offset of each snap point along the drag axis. */
+  snapPointsOffset: Ref<number[]>;
+  /** The edge the drawer is anchored to. */
+  direction: Ref<DrawerDirection>;
+  /** Begin a drag gesture. */
+  onPress: (event: PointerEvent) => void;
+  /** Update the drawer position during a drag. */
+  onDrag: (event: PointerEvent) => void;
+  /** Settle the drawer (snap, close, or reset) when the pointer is released. */
+  onRelease: (event: PointerEvent) => void;
+  /** Programmatically close the drawer. */
+  closeDrawer: () => void;
+  /** Whether the overlay should fade with the drag at the current snap point. */
+  shouldFade: Ref<boolean>;
+  /** Snap point index from which the overlay starts fading. */
+  fadeFromIndex: Ref<number | undefined>;
+  /** Whether the page background scales back while the drawer is open. */
+  shouldScaleBackground: Ref<boolean | undefined>;
+  /** Whether to set the body background to black during the scale effect. */
+  setBackgroundColorOnScale: Ref<boolean | undefined>;
+  /** Drive the parent drawer's transform as a nested child drawer is dragged. */
+  onNestedDrag: (percentageDragged: number) => void;
+  /** Settle the parent drawer when a nested child drawer is released. */
+  onNestedRelease: (o: boolean) => void;
+  /** React to a nested child drawer opening/closing. */
+  onNestedOpenChange: (o: boolean) => void;
+  /** Emit the root's `close` event. */
+  emitClose: () => void;
+  /** Emit the root's `drag` event with the drag percentage. */
+  emitDrag: (percentageDragged: number) => void;
+  /** Emit the root's `release` event. */
+  emitRelease: (open: boolean) => void;
+  /** Whether this drawer is nested inside another drawer. */
+  nested: Ref<boolean>;
+  /** Whether dragging is only permitted from the handle. */
+  handleOnly: Ref<boolean>;
+  /** Whether to skip Vaul-style body styling entirely. */
+  noBodyStyles: Ref<boolean>;
+}
+
+const ctx = useContextFactory<DrawerRootContext>('DrawerRootContext');
+
+export const provideDrawerRootContext = ctx.provide;
+export const injectDrawerRootContext = ctx.inject;
diff --git a/vue/primitives/src/drawer/controls.ts b/vue/primitives/src/drawer/controls.ts
new file mode 100644
index 0000000..d0557b6
--- /dev/null
+++ b/vue/primitives/src/drawer/controls.ts
@@ -0,0 +1,632 @@
+import type { Ref } from 'vue';
+import { computed, ref, watch, watchEffect } from 'vue';
+import { isClient } from '@robonen/platform/multi';
+import { getTranslate, resetStyle, setStyle } from '@robonen/platform/browsers';
+import { dampenValue, getDrawerWrapper, isVertical } from './helpers';
+import { BORDER_RADIUS, DRAG_CLASS, NESTED_DISPLACEMENT, TRANSITIONS, VELOCITY_THRESHOLD, WINDOW_TOP_OFFSET } from './constants';
+import { useSnapPoints } from './useSnapPoints';
+import { usePositionFixed } from './usePositionFixed';
+import type { DrawerRootContext } from './context';
+import type { DrawerDirection } from './types';
+
+export interface WithoutFadeFromProps {
+  /**
+   * Fractions (0–1) of the screen each snap point occupies, ordered from least
+   * to most visible — e.g. `[0.2, 0.5, 0.8]`. Px strings (e.g. `'200px'`) are
+   * also accepted and ignore screen height.
+   */
+  snapPoints?: Array<number | string>;
+  /** Index of the snap point from which the overlay fade begins. Defaults to the last. */
+  fadeFromIndex?: never;
+}
+
+export type DrawerRootProps = {
+  /** The active snap point (two-way bindable via `v-model:active-snap-point`). */
+  activeSnapPoint?: number | string | null;
+  /**
+   * Fraction (0–1) of the drawer that must be swiped away before it closes.
+   * @default 0.25
+   */
+  closeThreshold?: number;
+  /** Scale the page background down while the drawer is open (stacked-card look). */
+  shouldScaleBackground?: boolean;
+  /**
+   * Set the body background to black during the scale effect.
+   * @default true
+   */
+  setBackgroundColorOnScale?: boolean;
+  /**
+   * How long (ms) dragging is disabled after scrolling content inside the drawer.
+   * @default 100
+   */
+  scrollLockTimeout?: number;
+  /**
+   * Keep the drawer in place when the keyboard opens, resizing it to stay
+   * scrollable instead of translating it upward.
+   */
+  fixed?: boolean;
+  /**
+   * When `false`, dragging, clicking outside, and pressing escape will not close
+   * the drawer. Pair with `v-model:open` so you can still control it.
+   * @default true
+   */
+  dismissible?: boolean;
+  /**
+   * When `false`, the rest of the page stays interactive while the drawer is open.
+   * @default true
+   */
+  modal?: boolean;
+  /** Controlled open state (`v-model:open`). */
+  open?: boolean;
+  /**
+   * Start opened, skipping the initial enter animation. Still reacts to `open`.
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /** Marks this drawer as nested inside another (set automatically by DrawerRootNested). */
+  nested?: boolean;
+  /**
+   * The edge the drawer is anchored to.
+   * @default 'bottom'
+   */
+  direction?: DrawerDirection;
+  /** Skip all body styling that the drawer would otherwise apply. */
+  noBodyStyles?: boolean;
+  /**
+   * Only allow dragging via the DrawerHandle.
+   * @default false
+   */
+  handleOnly?: boolean;
+  /** Don't restore scroll position when the drawer closes after a navigation. */
+  preventScrollRestoration?: boolean;
+} & WithoutFadeFromProps;
+
+export interface UseDrawerProps {
+  open: Ref<boolean>;
+  snapPoints: Ref<Array<number | string> | undefined>;
+  dismissible: Ref<boolean>;
+  nested: Ref<boolean>;
+  fixed: Ref<boolean | undefined>;
+  modal: Ref<boolean>;
+  shouldScaleBackground: Ref<boolean | undefined>;
+  setBackgroundColorOnScale: Ref<boolean | undefined>;
+  activeSnapPoint: Ref<number | string | null | undefined>;
+  fadeFromIndex: Ref<number | undefined>;
+  closeThreshold: Ref<number>;
+  scrollLockTimeout: Ref<number>;
+  direction: Ref<DrawerDirection>;
+  noBodyStyles: Ref<boolean>;
+  preventScrollRestoration: Ref<boolean>;
+  handleOnly: Ref<boolean>;
+}
+
+export interface DrawerRootEmits {
+  /** Fired continuously during a drag with the fraction (0–1) dragged. */
+  (e: 'drag', percentageDragged: number): void;
+  /** Fired when the pointer is released, with whether the drawer stays open. */
+  (e: 'release', open: boolean): void;
+  /** Fired when the drawer begins closing. */
+  (e: 'close'): void;
+  /** Two-way binding for the open state. */
+  (e: 'update:open', open: boolean): void;
+  /** Two-way binding for the active snap point. */
+  (e: 'update:activeSnapPoint', val: string | number): void;
+  /** Fired after the open/close animation ends, with the open state at that time. */
+  (e: 'animationEnd', open: boolean): void;
+}
+
+export interface DialogEmitHandlers {
+  emitDrag: (percentageDragged: number) => void;
+  emitRelease: (open: boolean) => void;
+  emitClose: () => void;
+}
+
+export interface DrawerHandleProps {
+  /** Prevent the handle tap from cycling through snap points. */
+  preventCycle?: boolean;
+}
+
+function usePropOrDefaultRef<T>(prop: Ref<T | undefined> | undefined, defaultRef: Ref<T>): Ref<T> {
+  return prop && !!prop.value ? (prop as Ref<T>) : defaultRef;
+}
+
+/**
+ * The drawer engine: owns the drag gesture, snap-point settling, background
+ * scaling, and nested-drawer coordination. Returns the value provided as
+ * {@link DrawerRootContext} to the drawer parts.
+ */
+export function useDrawer(props: UseDrawerProps & DialogEmitHandlers): DrawerRootContext {
+  const {
+    emitDrag,
+    emitRelease,
+    emitClose,
+    open,
+    dismissible,
+    nested,
+    modal,
+    shouldScaleBackground,
+    setBackgroundColorOnScale,
+    scrollLockTimeout,
+    closeThreshold,
+    activeSnapPoint,
+    fadeFromIndex,
+    direction,
+    noBodyStyles,
+    handleOnly,
+    preventScrollRestoration,
+  } = props;
+
+  const hasBeenOpened = ref(open.value);
+  const isDragging = ref(false);
+  const justReleased = ref(false);
+
+  const overlayRef = ref<HTMLElement | undefined>(undefined);
+
+  const openTime = ref<Date | null>(null);
+  const dragStartTime = ref<Date | null>(null);
+  const dragEndTime = ref<Date | null>(null);
+  const lastTimeDragPrevented = ref<Date | null>(null);
+  const isAllowedToDrag = ref(false);
+
+  const nestedOpenChangeTimer = ref<number | null>(null);
+
+  const pointerStart = ref(0);
+  const keyboardIsOpen = ref(false);
+
+  const drawerRef = ref<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 {
+    activeSnapPointIndex,
+    onRelease: onReleaseSnapPoints,
+    snapPointsOffset,
+    onDrag: onDragSnapPoints,
+    shouldFade,
+    getPercentageDragged: getSnapPointsPercentageDragged,
+  } = useSnapPoints({
+    snapPoints,
+    activeSnapPoint,
+    drawerRef,
+    fadeFromIndex,
+    overlayRef,
+    onSnapPointChange,
+    direction,
+  });
+
+  function onSnapPointChange(activeSnapPointIndex: number, snapPointsOffset: number[]) {
+    // Refresh openTime when we reach the last snap point so scrollable content
+    // there isn't immediately draggable.
+    if (snapPoints.value && activeSnapPointIndex === snapPointsOffset.length - 1)
+      openTime.value = new Date();
+  }
+
+  usePositionFixed({
+    isOpen: open,
+    modal,
+    nested,
+    hasBeenOpened,
+    noBodyStyles,
+    preventScrollRestoration,
+  });
+
+  function getScale() {
+    return (window.innerWidth - WINDOW_TOP_OFFSET) / window.innerWidth;
+  }
+
+  function shouldDrag(el: EventTarget | null, isDraggingInDirection: boolean) {
+    if (!el)
+      return false;
+    let element = el as HTMLElement;
+    const highlightedText = globalThis.getSelection()?.toString();
+    const swipeAmount = drawerRef.value ? getTranslate(drawerRef.value, isVertical(direction.value) ? 'y' : 'x') : null;
+    const date = new Date();
+
+    if (element.hasAttribute('data-drawer-no-drag') || element.closest('[data-drawer-no-drag]'))
+      return false;
+
+    if (direction.value === 'right' || direction.value === 'left')
+      return true;
+
+    // Allow scrolling during the open animation.
+    if (openTime.value && date.getTime() - openTime.value.getTime() < 500)
+      return false;
+
+    if (swipeAmount !== null) {
+      if (direction.value === 'bottom' ? swipeAmount > 0 : swipeAmount < 0)
+        return true;
+    }
+
+    // Don't drag when text is selected.
+    if (highlightedText && highlightedText.length > 0)
+      return false;
+
+    // Don't drag right after scrolling inside the drawer.
+    if (
+      lastTimeDragPrevented.value
+      && date.getTime() - lastTimeDragPrevented.value.getTime() < scrollLockTimeout.value
+      && swipeAmount === 0
+    ) {
+      lastTimeDragPrevented.value = date;
+      return false;
+    }
+
+    if (isDraggingInDirection) {
+      lastTimeDragPrevented.value = date;
+      // Dragging in the open direction → allow scrolling instead.
+      return false;
+    }
+
+    // Walk up the tree; if a scrollable ancestor isn't at the top, scroll it instead of dragging.
+    while (element) {
+      if (element.scrollHeight > element.clientHeight) {
+        if (element.scrollTop !== 0) {
+          lastTimeDragPrevented.value = new Date();
+          return false;
+        }
+
+        if (element.getAttribute('role') === 'dialog')
+          return true;
+      }
+
+      element = element.parentNode as HTMLElement;
+    }
+
+    return true;
+  }
+
+  function onPress(event: PointerEvent) {
+    if (!dismissible.value && !snapPoints.value)
+      return;
+    if (drawerRef.value && !drawerRef.value.contains(event.target as Node))
+      return;
+    isDragging.value = true;
+    dragStartTime.value = new Date();
+
+    (event.target as HTMLElement).setPointerCapture(event.pointerId);
+    pointerStart.value = isVertical(direction.value) ? event.clientY : event.clientX;
+  }
+
+  function onDrag(event: PointerEvent) {
+    if (!drawerRef.value)
+      return;
+
+    if (isDragging.value) {
+      const directionMultiplier = direction.value === 'bottom' || direction.value === 'right' ? 1 : -1;
+      const draggedDistance
+        = (pointerStart.value - (isVertical(direction.value) ? event.clientY : event.clientX)) * directionMultiplier;
+      const isDraggingInDirection = draggedDistance > 0;
+
+      // Don't allow dragging toward close past the first snap point when not dismissible.
+      const noCloseSnapPointsPreCondition = snapPoints.value && !dismissible.value && !isDraggingInDirection;
+
+      if (noCloseSnapPointsPreCondition && activeSnapPointIndex.value === 0)
+        return;
+
+      const absDraggedDistance = Math.abs(draggedDistance);
+      const wrapper = getDrawerWrapper();
+
+      // 1 means the closed position.
+      let percentageDragged = absDraggedDistance / drawerHeightRef.value;
+      const snapPointPercentageDragged = getSnapPointsPercentageDragged(absDraggedDistance, isDraggingInDirection);
+
+      if (snapPointPercentageDragged !== null)
+        percentageDragged = snapPointPercentageDragged;
+
+      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' });
+
+      if (snapPoints.value)
+        onDragSnapPoints({ draggedDistance });
+
+      // Rubber-band past the open position when there are no snap points.
+      if (isDraggingInDirection && !snapPoints.value) {
+        const dampenedDraggedDistance = dampenValue(draggedDistance);
+
+        const translateValue = Math.min(dampenedDraggedDistance * -1, 0) * directionMultiplier;
+        setStyle(drawerRef.value, {
+          transform: isVertical(direction.value)
+            ? `translate3d(0, ${translateValue}px, 0)`
+            : `translate3d(${translateValue}px, 0, 0)`,
+        });
+        return;
+      }
+
+      const opacityValue = 1 - percentageDragged;
+
+      if (shouldFade.value || (fadeFromIndex.value && activeSnapPointIndex.value === fadeFromIndex.value - 1)) {
+        emitDrag(percentageDragged);
+
+        setStyle(overlayRef.value, { opacity: `${opacityValue}`, transition: 'none' }, true);
+      }
+
+      if (wrapper && overlayRef.value && shouldScaleBackground.value) {
+        const scaleValue = Math.min(getScale() + percentageDragged * (1 - getScale()), 1);
+        const borderRadiusValue = 8 - percentageDragged * 8;
+        const translateValue = Math.max(0, 14 - percentageDragged * 14);
+
+        setStyle(
+          wrapper,
+          {
+            borderRadius: `${borderRadiusValue}px`,
+            transform: isVertical(direction.value)
+              ? `scale(${scaleValue}) translate3d(0, ${translateValue}px, 0)`
+              : `scale(${scaleValue}) translate3d(${translateValue}px, 0, 0)`,
+            transition: 'none',
+          },
+          true,
+        );
+      }
+
+      if (!snapPoints.value) {
+        const translateValue = absDraggedDistance * directionMultiplier;
+
+        setStyle(drawerRef.value, {
+          transform: isVertical(direction.value)
+            ? `translate3d(0, ${translateValue}px, 0)`
+            : `translate3d(${translateValue}px, 0, 0)`,
+        });
+      }
+    }
+  }
+
+  function resetDrawer() {
+    if (!drawerRef.value)
+      return;
+    const wrapper = getDrawerWrapper();
+    const currentSwipeAmount = getTranslate(drawerRef.value, isVertical(direction.value) ? 'y' : 'x');
+
+    setStyle(drawerRef.value, {
+      transform: 'translate3d(0, 0, 0)',
+      transition: `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+    });
+
+    setStyle(overlayRef.value, {
+      transition: `opacity ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+      opacity: '1',
+    });
+
+    // Keep the background scaled if we didn't swipe back down.
+    if (shouldScaleBackground.value && currentSwipeAmount && currentSwipeAmount > 0 && open.value) {
+      setStyle(
+        wrapper,
+        {
+          borderRadius: `${BORDER_RADIUS}px`,
+          overflow: 'hidden',
+          ...(isVertical(direction.value)
+            ? {
+                transform: `scale(${getScale()}) translate3d(0, calc(env(safe-area-inset-top) + 14px), 0)`,
+                transformOrigin: 'top',
+              }
+            : {
+                transform: `scale(${getScale()}) translate3d(calc(env(safe-area-inset-top) + 14px), 0, 0)`,
+                transformOrigin: 'left',
+              }),
+          transitionProperty: 'transform, border-radius',
+          transitionDuration: `${TRANSITIONS.DURATION}s`,
+          transitionTimingFunction: `cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+        },
+        true,
+      );
+    }
+  }
+
+  // Flip the shared open state to false; every close side effect (emitClose, the
+  // snap-point reset, update:open) is driven off the `open` transition below, so
+  // this stays the single place that closes — whatever the trigger (drag, handle,
+  // dialog dismissal, or a controlled `v-model:open` flip).
+  function closeDrawer() {
+    if (!drawerRef.value)
+      return;
+
+    open.value = false;
+  }
+
+  watchEffect(() => {
+    if (!open.value && shouldScaleBackground.value && isClient) {
+      // The component is invisible by the time onAnimationEnd would fire, so use a timeout.
+      const id = setTimeout(() => {
+        resetStyle(document.body);
+      }, 200);
+
+      return () => clearTimeout(id);
+    }
+
+    return undefined;
+  });
+
+  function onRelease(event: PointerEvent) {
+    if (!isDragging.value || !drawerRef.value)
+      return;
+
+    drawerRef.value.classList.remove(DRAG_CLASS);
+    isAllowedToDrag.value = false;
+    isDragging.value = false;
+    dragEndTime.value = new Date();
+    const swipeAmount = getTranslate(drawerRef.value, isVertical(direction.value) ? 'y' : 'x');
+
+    if (!shouldDrag(event.target, false) || !swipeAmount || Number.isNaN(swipeAmount))
+      return;
+
+    if (dragStartTime.value === null)
+      return;
+
+    const timeTaken = dragEndTime.value.getTime() - dragStartTime.value.getTime();
+    const distMoved = pointerStart.value - (isVertical(direction.value) ? event.clientY : event.clientX);
+    const velocity = Math.abs(distMoved) / timeTaken;
+
+    if (velocity > 0.05) {
+      // Prevents the drawer from focusing an input as the drag ends.
+      justReleased.value = true;
+
+      globalThis.setTimeout(() => {
+        justReleased.value = false;
+      }, 200);
+    }
+
+    if (snapPoints.value) {
+      const directionMultiplier = direction.value === 'bottom' || direction.value === 'right' ? 1 : -1;
+
+      onReleaseSnapPoints({
+        draggedDistance: distMoved * directionMultiplier,
+        closeDrawer,
+        velocity,
+        dismissible: dismissible.value,
+      });
+      emitRelease(true);
+      return;
+    }
+
+    // Moved in the open direction → settle back.
+    if (direction.value === 'bottom' || direction.value === 'right' ? distMoved > 0 : distMoved < 0) {
+      resetDrawer();
+      emitRelease(true);
+      return;
+    }
+
+    if (velocity > VELOCITY_THRESHOLD) {
+      closeDrawer();
+      emitRelease(false);
+      return;
+    }
+
+    const visibleDrawerHeight = Math.min(drawerRef.value.getBoundingClientRect().height ?? 0, window.innerHeight);
+
+    if (swipeAmount >= visibleDrawerHeight * closeThreshold.value) {
+      closeDrawer();
+      emitRelease(false);
+      return;
+    }
+
+    emitRelease(true);
+    resetDrawer();
+  }
+
+  // Single owner of open/close side effects. Reacts to every source that writes
+  // the shared `open` ref: the drag/handle paths (closeDrawer), the dialog's
+  // dismissals (DrawerRoot.handleOpenChange), and a controlled `v-model:open`
+  // flip (DrawerRoot's prop watch). `update:open`/`animationEnd` are emitted by
+  // DrawerRoot's own watch on the same ref.
+  watch(open, (o) => {
+    if (o) {
+      openTime.value = new Date();
+      hasBeenOpened.value = true;
+    }
+    else {
+      emitClose();
+      globalThis.setTimeout(() => {
+        if (snapPoints.value)
+          activeSnapPoint.value = snapPoints.value[0];
+      }, TRANSITIONS.DURATION * 1000);
+    }
+  });
+
+  function onNestedOpenChange(o: boolean) {
+    const scale = o ? (window.innerWidth - NESTED_DISPLACEMENT) / window.innerWidth : 1;
+    const y = o ? -NESTED_DISPLACEMENT : 0;
+
+    if (nestedOpenChangeTimer.value)
+      globalThis.clearTimeout(nestedOpenChangeTimer.value);
+
+    setStyle(drawerRef.value, {
+      transition: `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+      transform: `scale(${scale}) translate3d(0, ${y}px, 0)`,
+    });
+
+    if (!o && drawerRef.value) {
+      nestedOpenChangeTimer.value = globalThis.setTimeout(() => {
+        const translateValue = getTranslate(drawerRef.value!, isVertical(direction.value) ? 'y' : 'x');
+        setStyle(drawerRef.value, {
+          transition: 'none',
+          transform: isVertical(direction.value)
+            ? `translate3d(0, ${translateValue}px, 0)`
+            : `translate3d(${translateValue}px, 0, 0)`,
+        });
+      }, 500);
+    }
+  }
+
+  function onNestedDrag(percentageDragged: number) {
+    if (percentageDragged < 0)
+      return;
+
+    const initialDim = isVertical(direction.value) ? window.innerHeight : window.innerWidth;
+    const initialScale = (initialDim - NESTED_DISPLACEMENT) / initialDim;
+    const newScale = initialScale + percentageDragged * (1 - initialScale);
+    const newTranslate = -NESTED_DISPLACEMENT + percentageDragged * NESTED_DISPLACEMENT;
+
+    setStyle(drawerRef.value, {
+      transform: isVertical(direction.value)
+        ? `scale(${newScale}) translate3d(0, ${newTranslate}px, 0)`
+        : `scale(${newScale}) translate3d(${newTranslate}px, 0, 0)`,
+      transition: 'none',
+    });
+  }
+
+  function onNestedRelease(o: boolean) {
+    const dim = isVertical(direction.value) ? window.innerHeight : window.innerWidth;
+    const scale = o ? (dim - NESTED_DISPLACEMENT) / dim : 1;
+    const translate = o ? -NESTED_DISPLACEMENT : 0;
+
+    if (o) {
+      setStyle(drawerRef.value, {
+        transition: `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+        transform: isVertical(direction.value)
+          ? `scale(${scale}) translate3d(0, ${translate}px, 0)`
+          : `scale(${scale}) translate3d(${translate}px, 0, 0)`,
+      });
+    }
+  }
+
+  return {
+    open,
+    isOpen: open,
+    modal,
+    keyboardIsOpen,
+    hasBeenOpened,
+    drawerRef,
+    drawerHeightRef,
+    overlayRef,
+    handleRef,
+    isDragging,
+    dragStartTime,
+    isAllowedToDrag,
+    snapPoints,
+    activeSnapPoint,
+    hasSnapPoints,
+    pointerStart,
+    dismissible,
+    snapPointsOffset,
+    direction,
+    shouldFade,
+    fadeFromIndex,
+    shouldScaleBackground,
+    setBackgroundColorOnScale,
+    onPress,
+    onDrag,
+    onRelease,
+    closeDrawer,
+    onNestedDrag,
+    onNestedRelease,
+    onNestedOpenChange,
+    emitClose,
+    emitDrag,
+    emitRelease,
+    nested,
+    handleOnly,
+    noBodyStyles,
+  };
+}
diff --git a/vue/primitives/src/drawer/demo.vue b/vue/primitives/src/drawer/demo.vue
new file mode 100644
index 0000000..d948258
--- /dev/null
+++ b/vue/primitives/src/drawer/demo.vue
@@ -0,0 +1,94 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHandle,
+  DrawerOverlay,
+  DrawerPortal,
+  DrawerRoot,
+  DrawerTitle,
+  DrawerTrigger,
+} from '@robonen/primitives';
+
+const open = ref(false);
+
+const goals = [
+  { id: 'focus', label: 'Deep focus', detail: '90 min, no notifications' },
+  { id: 'move', label: 'Move', detail: 'A short walk after lunch' },
+  { id: 'read', label: 'Read', detail: '20 pages before bed' },
+];
+const selected = ref(goals[0]!.id);
+</script>
+
+<template>
+  <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)"
+      >
+        Set today's goal
+      </DrawerTrigger>
+
+      <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"
+        >
+          <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)">
+              Set today's goal
+            </DrawerTitle>
+            <DrawerDescription class="mt-1 text-sm text-(--fg-muted)">
+              Pick one thing to focus on. Drag the handle down to dismiss.
+            </DrawerDescription>
+
+            <div class="mt-4 flex flex-col gap-2">
+              <button
+                v-for="goal in goals"
+                :key="goal.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)'"
+                @click="selected = goal.id"
+              >
+                <span>
+                  <span class="font-medium">{{ goal.label }}</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)"
+                >
+                  <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" />
+                  </svg>
+                </span>
+              </button>
+            </div>
+
+            <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)"
+              >
+                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)"
+                @click="open = false"
+              >
+                Save goal
+              </button>
+            </div>
+          </div>
+        </DrawerContent>
+      </DrawerPortal>
+    </DrawerRoot>
+  </div>
+</template>
diff --git a/vue/primitives/src/drawer/helpers.ts b/vue/primitives/src/drawer/helpers.ts
new file mode 100644
index 0000000..24892d5
--- /dev/null
+++ b/vue/primitives/src/drawer/helpers.ts
@@ -0,0 +1,27 @@
+import type { DrawerDirection } from './types';
+
+/**
+ * Whether a direction runs along the vertical axis (`top`/`bottom`) as opposed
+ * to the horizontal axis (`left`/`right`). Used to pick the axis for translation
+ * reads/writes and window dimension.
+ */
+export function isVertical(direction: DrawerDirection): boolean {
+  return direction === 'top' || direction === 'bottom';
+}
+
+/**
+ * Logarithmic resistance applied when dragging the drawer past its open
+ * position, so it follows the pointer with diminishing returns (rubber-band).
+ */
+export function dampenValue(v: number): number {
+  return 8 * (Math.log(v + 1) - 2);
+}
+
+/**
+ * Resolves the app wrapper that the background-scale effect transforms. Consumers
+ * opt in by adding `data-drawer-wrapper` to the element that holds their page
+ * content (sibling to the portalled drawer).
+ */
+export function getDrawerWrapper(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('[data-drawer-wrapper]');
+}
diff --git a/vue/primitives/src/drawer/index.ts b/vue/primitives/src/drawer/index.ts
new file mode 100644
index 0000000..0038646
--- /dev/null
+++ b/vue/primitives/src/drawer/index.ts
@@ -0,0 +1,31 @@
+export { default as DrawerRoot } from './DrawerRoot.vue';
+export { default as DrawerRootNested } from './DrawerRootNested.vue';
+export { default as DrawerContent } from './DrawerContent.vue';
+export { default as DrawerOverlay } from './DrawerOverlay.vue';
+export { default as DrawerHandle } from './DrawerHandle.vue';
+
+export type { DrawerRootEmits, DrawerRootProps, DrawerHandleProps } from './controls';
+export type { DrawerContentEmits, DrawerContentProps } from './DrawerContent.vue';
+export type { DrawerOverlayProps } from './DrawerOverlay.vue';
+export type { DrawerDirection, SnapPoint } from './types';
+
+export { injectDrawerRootContext, provideDrawerRootContext } from './context';
+export type { DrawerRootContext } from './context';
+
+// Parts with no drawer-specific behaviour reuse Dialog directly, re-exported
+// under Drawer names so consumers stay within one namespace.
+export {
+  DialogClose as DrawerClose,
+  DialogDescription as DrawerDescription,
+  DialogPortal as DrawerPortal,
+  DialogTitle as DrawerTitle,
+  DialogTrigger as DrawerTrigger,
+} from '../dialog';
+
+export type {
+  DialogCloseProps as DrawerCloseProps,
+  DialogDescriptionProps as DrawerDescriptionProps,
+  DialogPortalProps as DrawerPortalProps,
+  DialogTitleProps as DrawerTitleProps,
+  DialogTriggerProps as DrawerTriggerProps,
+} from '../dialog';
diff --git a/vue/primitives/src/drawer/style.ts b/vue/primitives/src/drawer/style.ts
new file mode 100644
index 0000000..45a9b80
--- /dev/null
+++ b/vue/primitives/src/drawer/style.ts
@@ -0,0 +1,270 @@
+/**
+ * Critical drawer styles — the slide keyframes plus the data-attribute-driven
+ * transforms that the drag engine toggles. Injected once at runtime via
+ * `useStyleTag` from DrawerRoot, so the headless primitive stays self-contained
+ * (no separate CSS file to import). Consumers still bring their own visual
+ * styling (size, colour, padding) on DrawerContent/DrawerOverlay.
+ *
+ * The selectors here mirror the `data-drawer-*` attributes set in the component
+ * templates and {@link ./controls} — keep them in sync.
+ */
+export const DRAWER_STYLE_ID = 'robonen-drawer';
+
+export const DRAWER_STYLES = `
+[data-drawer] {
+  touch-action: none;
+  will-change: transform;
+  transition: transform 0.5s cubic-bezier(0.32, 0.72, 0, 1);
+  animation-duration: 0.5s;
+  animation-timing-function: cubic-bezier(0.32, 0.72, 0, 1);
+}
+
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='bottom'][data-state='open'] {
+  animation-name: slideFromBottom;
+}
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='bottom'][data-state='closed'] {
+  animation-name: slideToBottom;
+}
+
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='top'][data-state='open'] {
+  animation-name: slideFromTop;
+}
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='top'][data-state='closed'] {
+  animation-name: slideToTop;
+}
+
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='left'][data-state='open'] {
+  animation-name: slideFromLeft;
+}
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='left'][data-state='closed'] {
+  animation-name: slideToLeft;
+}
+
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='right'][data-state='open'] {
+  animation-name: slideFromRight;
+}
+[data-drawer][data-drawer-snap-points='false'][data-drawer-direction='right'][data-state='closed'] {
+  animation-name: slideToRight;
+}
+
+[data-drawer][data-drawer-snap-points='true'][data-drawer-direction='bottom'] {
+  transform: translate3d(0, var(--initial-transform, 100%), 0);
+}
+
+[data-drawer][data-drawer-snap-points='true'][data-drawer-direction='top'] {
+  transform: translate3d(0, calc(var(--initial-transform, 100%) * -1), 0);
+}
+
+[data-drawer][data-drawer-snap-points='true'][data-drawer-direction='left'] {
+  transform: translate3d(calc(var(--initial-transform, 100%) * -1), 0, 0);
+}
+
+[data-drawer][data-drawer-snap-points='true'][data-drawer-direction='right'] {
+  transform: translate3d(var(--initial-transform, 100%), 0, 0);
+}
+
+[data-drawer][data-drawer-delayed-snap-points='true'][data-drawer-direction='top'] {
+  transform: translate3d(0, var(--snap-point-height, 0), 0);
+}
+
+[data-drawer][data-drawer-delayed-snap-points='true'][data-drawer-direction='bottom'] {
+  transform: translate3d(0, var(--snap-point-height, 0), 0);
+}
+
+[data-drawer][data-drawer-delayed-snap-points='true'][data-drawer-direction='left'] {
+  transform: translate3d(var(--snap-point-height, 0), 0, 0);
+}
+
+[data-drawer][data-drawer-delayed-snap-points='true'][data-drawer-direction='right'] {
+  transform: translate3d(var(--snap-point-height, 0), 0, 0);
+}
+
+[data-drawer-overlay][data-drawer-snap-points='false'] {
+  animation-duration: 0.5s;
+  animation-timing-function: cubic-bezier(0.32, 0.72, 0, 1);
+}
+[data-drawer-overlay][data-drawer-snap-points='false'][data-state='open'] {
+  animation-name: fadeIn;
+}
+[data-drawer-overlay][data-state='closed'] {
+  animation-name: fadeOut;
+}
+
+[data-drawer-animate='false'] {
+  animation: none !important;
+}
+
+[data-drawer-overlay][data-drawer-snap-points='true'] {
+  opacity: 0;
+  transition: opacity 0.5s cubic-bezier(0.32, 0.72, 0, 1);
+}
+
+[data-drawer-overlay][data-drawer-snap-points='true'] {
+  opacity: 1;
+}
+
+[data-drawer]:not([data-drawer-custom-container='true'])::after {
+  content: '';
+  position: absolute;
+  background: inherit;
+  background-color: inherit;
+}
+
+[data-drawer][data-drawer-direction='top']::after {
+  top: initial;
+  bottom: 100%;
+  left: 0;
+  right: 0;
+  height: 200%;
+}
+
+[data-drawer][data-drawer-direction='bottom']::after {
+  top: 100%;
+  bottom: initial;
+  left: 0;
+  right: 0;
+  height: 200%;
+}
+
+[data-drawer][data-drawer-direction='left']::after {
+  left: initial;
+  right: 100%;
+  top: 0;
+  bottom: 0;
+  width: 200%;
+}
+
+[data-drawer][data-drawer-direction='right']::after {
+  left: 100%;
+  right: initial;
+  top: 0;
+  bottom: 0;
+  width: 200%;
+}
+
+[data-drawer-overlay][data-drawer-snap-points='true']:not([data-drawer-snap-points-overlay='true']):not(
+    [data-state='closed']
+  ) {
+  opacity: 0;
+}
+
+[data-drawer-overlay][data-drawer-snap-points-overlay='true'] {
+  opacity: 1;
+}
+
+[data-drawer-handle] {
+  display: block;
+  position: relative;
+  opacity: 0.7;
+  background: #e2e2e4;
+  margin-left: auto;
+  margin-right: auto;
+  height: 5px;
+  width: 32px;
+  border-radius: 1rem;
+  touch-action: pan-y;
+}
+
+[data-drawer-handle]:hover,
+[data-drawer-handle]:active {
+  opacity: 1;
+}
+
+[data-drawer-handle-hitarea] {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  width: max(100%, 2.75rem); /* 44px */
+  height: max(100%, 2.75rem); /* 44px */
+  touch-action: inherit;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  [data-drawer] {
+    user-select: none;
+  }
+}
+
+@media (pointer: fine) {
+  [data-drawer-handle-hitarea] {
+    width: 100%;
+    height: 100%;
+  }
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes fadeOut {
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes slideFromBottom {
+  from {
+    transform: translate3d(0, var(--initial-transform, 100%), 0);
+  }
+  to {
+    transform: translate3d(0, 0, 0);
+  }
+}
+
+@keyframes slideToBottom {
+  to {
+    transform: translate3d(0, var(--initial-transform, 100%), 0);
+  }
+}
+
+@keyframes slideFromTop {
+  from {
+    transform: translate3d(0, calc(var(--initial-transform, 100%) * -1), 0);
+  }
+  to {
+    transform: translate3d(0, 0, 0);
+  }
+}
+
+@keyframes slideToTop {
+  to {
+    transform: translate3d(0, calc(var(--initial-transform, 100%) * -1), 0);
+  }
+}
+
+@keyframes slideFromLeft {
+  from {
+    transform: translate3d(calc(var(--initial-transform, 100%) * -1), 0, 0);
+  }
+  to {
+    transform: translate3d(0, 0, 0);
+  }
+}
+
+@keyframes slideToLeft {
+  to {
+    transform: translate3d(calc(var(--initial-transform, 100%) * -1), 0, 0);
+  }
+}
+
+@keyframes slideFromRight {
+  from {
+    transform: translate3d(var(--initial-transform, 100%), 0, 0);
+  }
+  to {
+    transform: translate3d(0, 0, 0);
+  }
+}
+
+@keyframes slideToRight {
+  to {
+    transform: translate3d(var(--initial-transform, 100%), 0, 0);
+  }
+}
+`;
diff --git a/vue/primitives/src/drawer/types.ts b/vue/primitives/src/drawer/types.ts
new file mode 100644
index 0000000..c7b46a7
--- /dev/null
+++ b/vue/primitives/src/drawer/types.ts
@@ -0,0 +1,13 @@
+/**
+ * The edge the drawer is anchored to and slides in from.
+ */
+export type DrawerDirection = 'top' | 'bottom' | 'left' | 'right';
+
+/**
+ * A resolved snap point: the original `fraction` (0–1 of the screen, or a raw
+ * px value) paired with its computed pixel `height`.
+ */
+export interface SnapPoint {
+  fraction: number;
+  height: number;
+}
diff --git a/vue/primitives/src/drawer/usePositionFixed.ts b/vue/primitives/src/drawer/usePositionFixed.ts
new file mode 100644
index 0000000..ff03a60
--- /dev/null
+++ b/vue/primitives/src/drawer/usePositionFixed.ts
@@ -0,0 +1,127 @@
+import type { Ref } from 'vue';
+import { onMounted, onUnmounted, ref, watch } from 'vue';
+import { isSafari } from '@robonen/platform/browsers';
+
+interface BodyPosition {
+  position: string;
+  top: string;
+  left: string;
+  height: string;
+}
+
+interface PositionFixedOptions {
+  isOpen: Ref<boolean>;
+  modal: Ref<boolean>;
+  nested: Ref<boolean>;
+  hasBeenOpened: Ref<boolean>;
+  preventScrollRestoration: Ref<boolean>;
+  noBodyStyles: Ref<boolean>;
+}
+
+// Module-level so a single restoration survives across nested drawers that each
+// run this composable — only the outermost open/close should touch the body.
+let previousBodyPosition: BodyPosition | null = null;
+
+/**
+ * Pins `document.body` with `position: fixed` while the drawer is open on iOS
+ * Safari, where the address bar otherwise causes a jarring viewport shift. A
+ * no-op on every other browser. Restores the scroll position on close.
+ */
+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);
+
+  function setPositionFixed(): void {
+    if (!isSafari())
+      return;
+
+    if (previousBodyPosition === null && isOpen.value && !noBodyStyles.value) {
+      previousBodyPosition = {
+        position: document.body.style.position,
+        top: document.body.style.top,
+        left: document.body.style.left,
+        height: document.body.style.height,
+      };
+
+      const { scrollX, innerHeight } = globalThis;
+
+      document.body.style.setProperty('position', 'fixed', 'important');
+      Object.assign(document.body.style, {
+        top: `${-scrollPos.value}px`,
+        left: `${-scrollX}px`,
+        right: '0px',
+        height: 'auto',
+      });
+
+      setTimeout(() => {
+        requestAnimationFrame(() => {
+          // If a bottom bar appeared after pinning, nudge the content up so it
+          // isn't hidden behind it.
+          const bottomBarHeight = innerHeight - window.innerHeight;
+          if (bottomBarHeight && scrollPos.value >= innerHeight)
+            document.body.style.top = `-${scrollPos.value + bottomBarHeight}px`;
+        });
+      }, 300);
+    }
+  }
+
+  function restorePositionSetting(): void {
+    if (!isSafari())
+      return;
+
+    if (previousBodyPosition !== null && !noBodyStyles.value) {
+      const y = -Number.parseInt(document.body.style.top, 10);
+      const x = -Number.parseInt(document.body.style.left, 10);
+
+      Object.assign(document.body.style, previousBodyPosition);
+
+      globalThis.requestAnimationFrame(() => {
+        if (preventScrollRestoration.value && activeUrl.value !== globalThis.location.href) {
+          activeUrl.value = globalThis.location.href;
+          return;
+        }
+
+        window.scrollTo(x, y);
+      });
+
+      previousBodyPosition = null;
+    }
+  }
+
+  onMounted(() => {
+    function onScroll() {
+      scrollPos.value = window.scrollY;
+    }
+
+    onScroll();
+    window.addEventListener('scroll', onScroll);
+
+    onUnmounted(() => {
+      window.removeEventListener('scroll', onScroll);
+    });
+  });
+
+  watch([isOpen, hasBeenOpened, activeUrl], () => {
+    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)
+        setPositionFixed();
+
+      if (!modal.value) {
+        setTimeout(() => {
+          restorePositionSetting();
+        }, 500);
+      }
+    }
+    else {
+      restorePositionSetting();
+    }
+  });
+
+  return { restorePositionSetting };
+}
diff --git a/vue/primitives/src/drawer/useScaleBackground.ts b/vue/primitives/src/drawer/useScaleBackground.ts
new file mode 100644
index 0000000..93f870d
--- /dev/null
+++ b/vue/primitives/src/drawer/useScaleBackground.ts
@@ -0,0 +1,64 @@
+import { ref, watchEffect } from 'vue';
+import { isClient } from '@robonen/platform/multi';
+import { assignStyle } from '@robonen/platform/browsers';
+import { injectDrawerRootContext } from './context';
+import { getDrawerWrapper, isVertical } from './helpers';
+import { BORDER_RADIUS, TRANSITIONS, WINDOW_TOP_OFFSET } from './constants';
+
+/**
+ * Scales the page background down behind the drawer (the stacked-card effect),
+ * transforming the element marked `data-drawer-wrapper`. Restores everything,
+ * including the body background, when the drawer closes. No-op unless
+ * `shouldScaleBackground` is enabled on the root.
+ */
+export function useScaleBackground() {
+  const { direction, isOpen, shouldScaleBackground, setBackgroundColorOnScale, noBodyStyles } = injectDrawerRootContext();
+  const timeoutIdRef = ref<number | null>(null);
+  const initialBackgroundColor = ref(typeof document !== 'undefined' ? document.body.style.backgroundColor : '');
+
+  function getScale() {
+    return (window.innerWidth - WINDOW_TOP_OFFSET) / window.innerWidth;
+  }
+
+  watchEffect((onCleanup) => {
+    // `flush: 'pre'` watchers run during SSR; this effect touches document/window,
+    // so it must stay client-only.
+    if (isClient && isOpen.value && shouldScaleBackground.value) {
+      if (timeoutIdRef.value)
+        clearTimeout(timeoutIdRef.value);
+
+      const wrapper = getDrawerWrapper();
+
+      if (!wrapper)
+        return;
+
+      if (setBackgroundColorOnScale.value && !noBodyStyles.value)
+        assignStyle(document.body, { background: 'black' });
+
+      assignStyle(wrapper, {
+        transformOrigin: isVertical(direction.value) ? 'top' : 'left',
+        transitionProperty: 'transform, border-radius',
+        transitionDuration: `${TRANSITIONS.DURATION}s`,
+        transitionTimingFunction: `cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+      });
+
+      const wrapperStylesCleanup = assignStyle(wrapper, {
+        borderRadius: `${BORDER_RADIUS}px`,
+        overflow: 'hidden',
+        ...(isVertical(direction.value)
+          ? { transform: `scale(${getScale()}) translate3d(0, calc(env(safe-area-inset-top) + 14px), 0)` }
+          : { transform: `scale(${getScale()}) translate3d(calc(env(safe-area-inset-top) + 14px), 0, 0)` }),
+      });
+
+      onCleanup(() => {
+        wrapperStylesCleanup();
+        timeoutIdRef.value = globalThis.setTimeout(() => {
+          if (initialBackgroundColor.value)
+            document.body.style.background = initialBackgroundColor.value;
+          else
+            document.body.style.removeProperty('background');
+        }, TRANSITIONS.DURATION * 1000);
+      });
+    }
+  }, { flush: 'pre' });
+}
diff --git a/vue/primitives/src/drawer/useSnapPoints.ts b/vue/primitives/src/drawer/useSnapPoints.ts
new file mode 100644
index 0000000..6cdd821
--- /dev/null
+++ b/vue/primitives/src/drawer/useSnapPoints.ts
@@ -0,0 +1,283 @@
+import type { Ref } from 'vue';
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { setStyle } from '@robonen/platform/browsers';
+import { isVertical } from './helpers';
+import { TRANSITIONS, VELOCITY_THRESHOLD } from './constants';
+import type { DrawerDirection } from './types';
+
+interface UseSnapPointsProps {
+  activeSnapPoint: Ref<number | string | null | undefined>;
+  snapPoints: Ref<Array<number | string> | undefined>;
+  fadeFromIndex: Ref<number | undefined>;
+  drawerRef: Ref<HTMLElement | undefined>;
+  overlayRef: Ref<HTMLElement | undefined>;
+  onSnapPointChange: (activeSnapPointIndex: number, snapPointsOffset: number[]) => void;
+  direction: Ref<DrawerDirection>;
+}
+
+const transition = (property: 'transform' | 'opacity') =>
+  `${property} ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`;
+
+/**
+ * Drag/release maths for drawers configured with snap points: resolves each
+ * snap point to a pixel offset, animates the drawer between them, and decides
+ * which point to settle on (or whether to close) based on drag distance and
+ * velocity.
+ */
+export function useSnapPoints({
+  activeSnapPoint,
+  snapPoints,
+  drawerRef,
+  overlayRef,
+  fadeFromIndex,
+  onSnapPointChange,
+  direction,
+}: UseSnapPointsProps) {
+  const windowDimensions = ref(globalThis.window !== undefined
+    ? { innerWidth: window.innerWidth, innerHeight: window.innerHeight }
+    : undefined);
+
+  function onResize() {
+    windowDimensions.value = { innerWidth: window.innerWidth, innerHeight: window.innerHeight };
+  }
+
+  onMounted(() => {
+    if (globalThis.window !== undefined)
+      window.addEventListener('resize', onResize);
+  });
+
+  onBeforeUnmount(() => {
+    if (globalThis.window !== undefined)
+      window.removeEventListener('resize', onResize);
+  });
+
+  const isLastSnapPoint = computed(
+    () => (snapPoints.value && activeSnapPoint.value === snapPoints.value[snapPoints.value.length - 1]) ?? null,
+  );
+
+  const shouldFade = computed(
+    () =>
+      (snapPoints.value
+        && snapPoints.value.length > 0
+        && (fadeFromIndex?.value || fadeFromIndex?.value === 0)
+        && !Number.isNaN(fadeFromIndex?.value)
+        && snapPoints.value[fadeFromIndex?.value ?? -1] === activeSnapPoint.value)
+      || !snapPoints.value,
+  );
+
+  const activeSnapPointIndex = computed(
+    () => snapPoints.value?.indexOf(activeSnapPoint.value) ?? null,
+  );
+
+  const snapPointsOffset = computed(
+    () =>
+      snapPoints.value?.map((snapPoint) => {
+        const isPx = typeof snapPoint === 'string';
+        let snapPointAsNumber = 0;
+
+        if (isPx)
+          snapPointAsNumber = Number.parseInt(snapPoint, 10);
+
+        if (isVertical(direction.value)) {
+          const height = isPx
+            ? snapPointAsNumber
+            : windowDimensions.value
+              ? (snapPoint as number) * windowDimensions.value.innerHeight
+              : 0;
+
+          if (windowDimensions.value)
+            return direction.value === 'bottom' ? windowDimensions.value.innerHeight - height : -windowDimensions.value.innerHeight + height;
+
+          return height;
+        }
+
+        const width = isPx
+          ? snapPointAsNumber
+          : windowDimensions.value
+            ? (snapPoint as number) * windowDimensions.value.innerWidth
+            : 0;
+
+        if (windowDimensions.value)
+          return direction.value === 'right' ? windowDimensions.value.innerWidth - width : -windowDimensions.value.innerWidth + width;
+
+        return width;
+      }) ?? [],
+  );
+
+  const activeSnapPointOffset = computed(() =>
+    activeSnapPointIndex.value !== null ? snapPointsOffset.value?.[activeSnapPointIndex.value] : null,
+  );
+
+  function snapToPoint(dimension: number) {
+    const newSnapPointIndex = snapPointsOffset.value?.indexOf(dimension) ?? null;
+
+    // Wait for the element to be mounted before transforming it.
+    nextTick(() => {
+      onSnapPointChange(newSnapPointIndex, snapPointsOffset.value);
+      setStyle(drawerRef.value, {
+        transition: transition('transform'),
+        transform: isVertical(direction.value) ? `translate3d(0, ${dimension}px, 0)` : `translate3d(${dimension}px, 0, 0)`,
+      });
+    });
+
+    if (
+      snapPointsOffset.value
+      && newSnapPointIndex !== snapPointsOffset.value.length - 1
+      && newSnapPointIndex !== fadeFromIndex?.value
+    ) {
+      setStyle(overlayRef.value, { transition: transition('opacity'), opacity: '0' });
+    }
+    else {
+      setStyle(overlayRef.value, { transition: transition('opacity'), opacity: '1' });
+    }
+
+    activeSnapPoint.value = newSnapPointIndex !== null ? snapPoints.value?.[newSnapPointIndex] ?? null : null;
+  }
+
+  watch(
+    [activeSnapPoint, snapPointsOffset, snapPoints],
+    () => {
+      if (activeSnapPoint.value) {
+        const newIndex = snapPoints.value?.indexOf(activeSnapPoint.value) ?? -1;
+
+        if (snapPointsOffset.value && newIndex !== -1 && typeof snapPointsOffset.value[newIndex] === 'number')
+          snapToPoint(snapPointsOffset.value[newIndex]);
+      }
+    },
+    { immediate: true },
+  );
+
+  function onRelease({
+    draggedDistance,
+    closeDrawer,
+    velocity,
+    dismissible,
+  }: {
+    draggedDistance: number;
+    closeDrawer: () => void;
+    velocity: number;
+    dismissible: boolean;
+  }) {
+    if (fadeFromIndex.value === undefined)
+      return;
+
+    const currentPosition
+      = direction.value === 'bottom' || direction.value === 'right'
+        ? (activeSnapPointOffset.value ?? 0) - draggedDistance
+        : (activeSnapPointOffset.value ?? 0) + draggedDistance;
+    const isOverlaySnapPoint = activeSnapPointIndex.value === fadeFromIndex.value - 1;
+    const isFirst = activeSnapPointIndex.value === 0;
+    const hasDraggedUp = draggedDistance > 0;
+
+    if (isOverlaySnapPoint)
+      setStyle(overlayRef.value, { transition: transition('opacity') });
+
+    if (velocity > 2 && !hasDraggedUp) {
+      if (dismissible)
+        closeDrawer();
+      else
+        snapToPoint(snapPointsOffset.value[0]); // snap to initial point
+      return;
+    }
+
+    if (velocity > 2 && hasDraggedUp && snapPointsOffset.value && snapPoints.value) {
+      snapToPoint(snapPointsOffset.value[snapPoints.value.length - 1]);
+      return;
+    }
+
+    // Settle on the snap point closest to where the drag ended.
+    const closestSnapPoint = snapPointsOffset.value?.reduce((prev, curr) => {
+      if (typeof prev !== 'number' || typeof curr !== 'number')
+        return prev;
+
+      return Math.abs(curr - currentPosition) < Math.abs(prev - currentPosition) ? curr : prev;
+    });
+
+    const dim = isVertical(direction.value) ? window.innerHeight : window.innerWidth;
+    if (velocity > VELOCITY_THRESHOLD && Math.abs(draggedDistance) < dim * 0.4) {
+      const dragDirection = hasDraggedUp ? 1 : -1; // 1 = up, -1 = down
+
+      // Ignore an upward flick while already on the last snap point.
+      if (dragDirection > 0 && isLastSnapPoint.value) {
+        snapToPoint(snapPointsOffset.value[(snapPoints.value?.length ?? 0) - 1]);
+        return;
+      }
+
+      if (isFirst && dragDirection < 0 && dismissible)
+        closeDrawer();
+
+      if (activeSnapPointIndex.value === null)
+        return;
+
+      snapToPoint(snapPointsOffset.value[activeSnapPointIndex.value + dragDirection]);
+      return;
+    }
+
+    snapToPoint(closestSnapPoint);
+  }
+
+  function onDrag({ draggedDistance }: { draggedDistance: number }) {
+    if (activeSnapPointOffset.value === null)
+      return;
+
+    const newValue
+      = direction.value === 'bottom' || direction.value === 'right'
+        ? (activeSnapPointOffset.value ?? 0) - draggedDistance
+        : (activeSnapPointOffset.value ?? 0) + draggedDistance;
+
+    // Don't drag past the last (largest) snap point.
+    if ((direction.value === 'bottom' || direction.value === 'right') && newValue < snapPointsOffset.value[snapPointsOffset.value.length - 1])
+      return;
+
+    if ((direction.value === 'top' || direction.value === 'left') && newValue > snapPointsOffset.value[snapPointsOffset.value.length - 1])
+      return;
+
+    setStyle(drawerRef.value, {
+      transform: isVertical(direction.value) ? `translate3d(0, ${newValue}px, 0)` : `translate3d(${newValue}px, 0, 0)`,
+    });
+  }
+
+  function getPercentageDragged(absDraggedDistance: number, isDraggingDown: boolean) {
+    if (
+      !snapPoints.value
+      || typeof activeSnapPointIndex.value !== 'number'
+      || !snapPointsOffset.value
+      || fadeFromIndex.value === undefined
+    )
+      return null;
+
+    // Whether we're dragging toward a snap point that should show the overlay.
+    const isOverlaySnapPoint = activeSnapPointIndex.value === fadeFromIndex.value - 1;
+    const isOverlaySnapPointOrHigher = activeSnapPointIndex.value >= fadeFromIndex.value;
+
+    if (isOverlaySnapPointOrHigher && isDraggingDown)
+      return 0;
+
+    // Don't animate, but still use this one when dragging away from the overlay snap point.
+    if (isOverlaySnapPoint && !isDraggingDown)
+      return 1;
+    if (!shouldFade.value && !isOverlaySnapPoint)
+      return null;
+
+    const targetSnapPointIndex = isOverlaySnapPoint ? activeSnapPointIndex.value + 1 : activeSnapPointIndex.value - 1;
+
+    // Distance between the overlay snap point and its neighbour, used to scale opacity.
+    const snapPointDistance = isOverlaySnapPoint
+      ? snapPointsOffset.value[targetSnapPointIndex] - snapPointsOffset.value[targetSnapPointIndex - 1]
+      : snapPointsOffset.value[targetSnapPointIndex + 1] - snapPointsOffset.value[targetSnapPointIndex];
+
+    const percentageDragged = absDraggedDistance / Math.abs(snapPointDistance);
+
+    return isOverlaySnapPoint ? 1 - percentageDragged : percentageDragged;
+  }
+
+  return {
+    isLastSnapPoint,
+    shouldFade,
+    getPercentageDragged,
+    activeSnapPointIndex,
+    onRelease,
+    onDrag,
+    snapPointsOffset,
+  };
+}
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuArrow.vue b/vue/primitives/src/dropdown-menu/DropdownMenuArrow.vue
index 98b2a80..0c2d8fd 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuArrow.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuArrow.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuArrowProps } from '../menu';
 
+/**
+ * An optional arrow that points from the content back toward the trigger.
+ * Render it inside the content; it tracks the trigger as the menu repositions.
+ */
 export interface DropdownMenuArrowProps extends MenuArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuCheckboxItem.vue b/vue/primitives/src/dropdown-menu/DropdownMenuCheckboxItem.vue
index d2ecbf9..563ff26 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuCheckboxItem.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuCheckboxItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuCheckboxItemEmits, MenuCheckboxItemProps } from '../menu';
 
+/**
+ * A menu item that toggles a boolean (or indeterminate) state. Bind
+ * `v-model:checked` to track the value; pair it with DropdownMenuItemIndicator
+ * to render a check mark when active.
+ */
 export interface DropdownMenuCheckboxItemProps extends MenuCheckboxItemProps {}
 export type DropdownMenuCheckboxItemEmits = MenuCheckboxItemEmits;
 </script>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuContent.vue b/vue/primitives/src/dropdown-menu/DropdownMenuContent.vue
index 1d5f622..6e985b6 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuContent.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuContent.vue
@@ -1,6 +1,11 @@
 <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>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuGroup.vue b/vue/primitives/src/dropdown-menu/DropdownMenuGroup.vue
index 355961e..e011888 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuGroup.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuGroupProps } from '../menu';
 
+/**
+ * Groups related items so assistive tech announces them together. Pair it with
+ * a DropdownMenuLabel to give the group an accessible name.
+ */
 export interface DropdownMenuGroupProps extends MenuGroupProps {}
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuItem.vue b/vue/primitives/src/dropdown-menu/DropdownMenuItem.vue
index db12231..91fa67a 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuItem.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuItem.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuItemEmits, MenuItemProps } from '../menu';
 
+/**
+ * A single actionable row in the menu. Emits `select` on click or
+ * Enter/Space and closes the menu afterwards unless the event is prevented.
+ */
 export interface DropdownMenuItemProps extends MenuItemProps {}
 export type DropdownMenuItemEmits = MenuItemEmits;
 </script>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuItemIndicator.vue b/vue/primitives/src/dropdown-menu/DropdownMenuItemIndicator.vue
index bdab714..74db411 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuItemIndicator.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuItemIndicator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuItemIndicatorProps } from '../menu';
 
+/**
+ * Renders its content only when the enclosing checkbox or radio item is
+ * checked. Put a check mark or dot inside it as the selection marker.
+ */
 export interface DropdownMenuItemIndicatorProps extends MenuItemIndicatorProps {}
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuLabel.vue b/vue/primitives/src/dropdown-menu/DropdownMenuLabel.vue
index 82a917a..98b27f1 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuLabel.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuLabel.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuLabelProps } from '../menu';
 
+/**
+ * A non-interactive heading that titles a section of the menu. It is skipped
+ * by keyboard navigation and is not selectable.
+ */
 export interface DropdownMenuLabelProps extends MenuLabelProps {}
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuPortal.vue b/vue/primitives/src/dropdown-menu/DropdownMenuPortal.vue
index 7506f63..b3de55b 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuPortal.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuPortal.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuPortalProps } from '../menu';
 
+/**
+ * Teleports the menu content into the document body (or a chosen target) so it
+ * renders above other content and escapes any `overflow: hidden` ancestor.
+ */
 export interface DropdownMenuPortalProps extends MenuPortalProps {}
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuRadioGroup.vue b/vue/primitives/src/dropdown-menu/DropdownMenuRadioGroup.vue
index 63a431e..639d777 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuRadioGroup.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuRadioGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuRadioGroupEmits, MenuRadioGroupProps } from '../menu';
 
+/**
+ * Groups DropdownMenuRadioItems into a single-choice set. Bind `v-model` to
+ * track the selected item's value across the group.
+ */
 export interface DropdownMenuRadioGroupProps extends MenuRadioGroupProps {}
 export type DropdownMenuRadioGroupEmits = MenuRadioGroupEmits;
 </script>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuRadioItem.vue b/vue/primitives/src/dropdown-menu/DropdownMenuRadioItem.vue
index 1c98568..8682404 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuRadioItem.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuRadioItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuRadioItemEmits, MenuRadioItemProps } from '../menu';
 
+/**
+ * One option within a DropdownMenuRadioGroup. Selecting it sets the group's
+ * value to this item's `value`; pair it with DropdownMenuItemIndicator to show
+ * which option is active.
+ */
 export interface DropdownMenuRadioItemProps extends MenuRadioItemProps {}
 export type DropdownMenuRadioItemEmits = MenuRadioItemEmits;
 </script>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuRoot.vue b/vue/primitives/src/dropdown-menu/DropdownMenuRoot.vue
index e5d7686..0a61f0c 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuRoot.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuRoot.vue
@@ -1,42 +1,48 @@
 <script lang="ts">
 import type { Direction } from '../config-provider';
 
+/**
+ * A button-triggered menu of actions, opened on click and built on top of Menu,
+ * so it inherits keyboard navigation, typeahead, nested submenus, and
+ * checkbox/radio items. Unlike a context menu, it is anchored to a persistent
+ * trigger button rather than the pointer.
+ *
+ * Use it for action menus on a toolbar, an avatar, or a "more" button — settings,
+ * row actions, account menus, and the like. The root owns open state and provides
+ * context to every part; bind `v-model:open` (or listen to `update:open`) to
+ * control or observe whether the menu is open.
+ */
 export interface DropdownMenuRootProps {
-  open?: boolean;
   defaultOpen?: boolean;
   dir?: Direction;
   modal?: boolean;
 }
-export interface DropdownMenuRootEmits {
-  'update:open': [value: boolean];
-}
 </script>
 
 <script setup lang="ts">
-import { computed, ref, shallowRef } from 'vue';
+import { ref, shallowRef } from 'vue';
 
 import { useId } from '../config-provider';
 import { MenuRoot } from '../menu';
 import { provideDropdownMenuRootContext } from './context';
 
 const {
-  open: openProp,
   defaultOpen = false,
   dir,
   modal = true,
 } = defineProps<DropdownMenuRootProps>();
 
-const emit = defineEmits<DropdownMenuRootEmits>();
-defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
+const localOpen = ref<boolean>(defaultOpen);
 
-const local = ref(defaultOpen);
-const open = computed({
-  get: () => openProp !== undefined ? openProp : local.value,
+const open = defineModel<boolean>('open', {
+  default: undefined,
+  get: v => v ?? localOpen.value,
   set: (v) => {
-    local.value = v;
-    emit('update:open', v);
+    localOpen.value = v;
+    return v;
   },
 });
+defineSlots<{ default?: (props: { open: boolean }) => unknown }>();
 
 const triggerRef = shallowRef<HTMLElement | null>(null);
 const triggerId = useId(undefined, 'dropdown-trigger');
@@ -54,10 +60,9 @@ provideDropdownMenuRootContext({
 
 <template>
   <MenuRoot
-    :open="open"
+    v-model:open="open"
     :dir="dir"
     :modal="modal"
-    @update:open="open = $event"
   >
     <slot :open="open" />
   </MenuRoot>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSeparator.vue b/vue/primitives/src/dropdown-menu/DropdownMenuSeparator.vue
index 4930a23..4d59044 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSeparator.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuSeparator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuSeparatorProps } from '../menu';
 
+/**
+ * A horizontal divider used to visually separate groups of items. Decorative
+ * and skipped by keyboard navigation.
+ */
 export interface DropdownMenuSeparatorProps extends MenuSeparatorProps {}
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSub.vue b/vue/primitives/src/dropdown-menu/DropdownMenuSub.vue
index 62648f6..61c8408 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSub.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuSub.vue
@@ -1,6 +1,11 @@
 <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>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSubContent.vue b/vue/primitives/src/dropdown-menu/DropdownMenuSubContent.vue
index 891d270..91d8486 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSubContent.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuSubContent.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuSubContentEmits, MenuSubContentProps } from '../menu';
 
+/**
+ * The floating surface for a submenu's items, positioned alongside its
+ * DropdownMenuSubTrigger. Place it inside a DropdownMenuSub.
+ */
 export interface DropdownMenuSubContentProps extends MenuSubContentProps {}
 export type DropdownMenuSubContentEmits = MenuSubContentEmits;
 </script>
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuSubTrigger.vue b/vue/primitives/src/dropdown-menu/DropdownMenuSubTrigger.vue
index ae0e888..dd2c2d0 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuSubTrigger.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuSubTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuSubTriggerProps } from '../menu';
 
+/**
+ * The item that opens its submenu on hover or ArrowRight and closes it on
+ * ArrowLeft. Renders like a regular item but opens DropdownMenuSubContent
+ * instead of emitting `select`.
+ */
 export interface DropdownMenuSubTriggerProps extends MenuSubTriggerProps {}
 </script>
 
diff --git a/vue/primitives/src/dropdown-menu/DropdownMenuTrigger.vue b/vue/primitives/src/dropdown-menu/DropdownMenuTrigger.vue
index ea50ba9..ef85841 100644
--- a/vue/primitives/src/dropdown-menu/DropdownMenuTrigger.vue
+++ b/vue/primitives/src/dropdown-menu/DropdownMenuTrigger.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The button that toggles the menu open on click, Enter, Space, or the arrow
+ * keys, and serves as the anchor the content is positioned against. Renders a
+ * `<button>` by default and wires up the `aria-haspopup`/`aria-expanded`
+ * accessibility attributes.
+ */
 export interface DropdownMenuTriggerProps extends PrimitiveProps {
   disabled?: boolean;
 }
diff --git a/vue/primitives/src/dropdown-menu/demo.vue b/vue/primitives/src/dropdown-menu/demo.vue
new file mode 100644
index 0000000..3e20c19
--- /dev/null
+++ b/vue/primitives/src/dropdown-menu/demo.vue
@@ -0,0 +1,131 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuItemIndicator,
+  DropdownMenuLabel,
+  DropdownMenuPortal,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuRoot,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@robonen/primitives';
+
+const open = ref(false);
+const showStatusBar = ref(true);
+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 checkItemClass = `${itemClass} pl-7 relative`;
+
+function run(action: string) {
+  lastAction.value = action;
+}
+</script>
+
+<template>
+  <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)"
+      >
+        Options
+        <span
+          class="i-carbon-chevron-down text-(--fg-muted) transition-transform duration-150 group-data-[state=open]:rotate-180"
+          aria-hidden="true"
+        />
+      </DropdownMenuTrigger>
+
+      <DropdownMenuPortal>
+        <DropdownMenuContent
+          :side-offset="6"
+          align="start"
+          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)">
+            My account
+          </DropdownMenuLabel>
+
+          <DropdownMenuItem :class="itemClass" @select="run('Profile')">
+            <span class="i-carbon-user" aria-hidden="true" />
+            Profile
+          </DropdownMenuItem>
+          <DropdownMenuItem :class="itemClass" @select="run('Settings')">
+            <span class="i-carbon-settings" aria-hidden="true" />
+            Settings
+          </DropdownMenuItem>
+
+          <DropdownMenuSeparator class="my-1 h-px bg-(--border)" />
+
+          <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" />
+            </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" />
+            </DropdownMenuItemIndicator>
+            Activity bar
+          </DropdownMenuCheckboxItem>
+
+          <DropdownMenuSeparator class="my-1 h-px bg-(--border)" />
+
+          <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" />
+              </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" />
+              </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" />
+              </DropdownMenuItemIndicator>
+              System
+            </DropdownMenuRadioItem>
+          </DropdownMenuRadioGroup>
+
+          <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"
+            @select="run('Sign out')"
+          >
+            <span class="i-carbon-logout" aria-hidden="true" />
+            Sign out
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </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>
+      <template v-if="lastAction">
+        &middot; Last action: <span class="font-medium text-(--fg)">{{ lastAction }}</span>
+      </template>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/dropdown-menu/index.ts b/vue/primitives/src/dropdown-menu/index.ts
index 2b9989a..b5f9b14 100644
--- a/vue/primitives/src/dropdown-menu/index.ts
+++ b/vue/primitives/src/dropdown-menu/index.ts
@@ -9,7 +9,7 @@ export { default as DropdownMenuLabel, type DropdownMenuLabelProps } from './Dro
 export { default as DropdownMenuPortal, type DropdownMenuPortalProps } from './DropdownMenuPortal.vue';
 export { default as DropdownMenuRadioGroup, type DropdownMenuRadioGroupEmits, type DropdownMenuRadioGroupProps } from './DropdownMenuRadioGroup.vue';
 export { default as DropdownMenuRadioItem, type DropdownMenuRadioItemEmits, type DropdownMenuRadioItemProps } from './DropdownMenuRadioItem.vue';
-export { default as DropdownMenuRoot, type DropdownMenuRootEmits, type DropdownMenuRootProps } from './DropdownMenuRoot.vue';
+export { default as DropdownMenuRoot, type DropdownMenuRootProps } from './DropdownMenuRoot.vue';
 export { default as DropdownMenuSeparator, type DropdownMenuSeparatorProps } from './DropdownMenuSeparator.vue';
 export { default as DropdownMenuSub, type DropdownMenuSubEmits, type DropdownMenuSubProps } from './DropdownMenuSub.vue';
 export { default as DropdownMenuSubContent, type DropdownMenuSubContentEmits, type DropdownMenuSubContentProps } from './DropdownMenuSubContent.vue';
diff --git a/vue/primitives/src/editable/EditableArea.vue b/vue/primitives/src/editable/EditableArea.vue
index 76f5b44..3e4e962 100644
--- a/vue/primitives/src/editable/EditableArea.vue
+++ b/vue/primitives/src/editable/EditableArea.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Wrapper that groups the preview and input. It mirrors edit/empty/disabled
+ * state via data attributes and, when `autoResize` is set, becomes the grid that
+ * sizes the input to match the preview text.
+ */
 export interface EditableAreaProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/editable/EditableCancelTrigger.vue b/vue/primitives/src/editable/EditableCancelTrigger.vue
index ccd5672..a6565ff 100644
--- a/vue/primitives/src/editable/EditableCancelTrigger.vue
+++ b/vue/primitives/src/editable/EditableCancelTrigger.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Button that discards the draft, restores the committed value, and leaves edit
+ * mode. It is only shown while editing.
+ */
 export interface EditableCancelTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/editable/EditableEditTrigger.vue b/vue/primitives/src/editable/EditableEditTrigger.vue
index d43f4cb..8ff62c9 100644
--- a/vue/primitives/src/editable/EditableEditTrigger.vue
+++ b/vue/primitives/src/editable/EditableEditTrigger.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Button that enters edit mode. It is hidden while editing and disabled when the
+ * Root is disabled.
+ */
 export interface EditableEditTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/editable/EditableInput.vue b/vue/primitives/src/editable/EditableInput.vue
index 3046607..58f9f5b 100644
--- a/vue/primitives/src/editable/EditableInput.vue
+++ b/vue/primitives/src/editable/EditableInput.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The text input shown while editing. It binds the draft value, auto-focuses
+ * (and optionally selects) when edit mode begins, and handles Enter to submit /
+ * Escape to cancel per the Root's `submitMode`.
+ */
 export interface EditableInputProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/editable/EditablePreview.vue b/vue/primitives/src/editable/EditablePreview.vue
index 7eb7708..f20d060 100644
--- a/vue/primitives/src/editable/EditablePreview.vue
+++ b/vue/primitives/src/editable/EditablePreview.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Read-only display of the current value (or the preview placeholder when
+ * empty). It is focusable and, depending on `activationMode`, enters edit mode
+ * on focus or double-click.
+ */
 export interface EditablePreviewProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/editable/EditableRoot.vue b/vue/primitives/src/editable/EditableRoot.vue
index 2568059..90da246 100644
--- a/vue/primitives/src/editable/EditableRoot.vue
+++ b/vue/primitives/src/editable/EditableRoot.vue
@@ -2,9 +2,13 @@
 import type { EditableActivationMode, EditablePlaceholder, EditableSubmitMode } from './context';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Inline-editable text field that toggles between a read-only preview and an
+ * editable input. Root owns the value (via `v-model`), edit state, and submit /
+ * cancel behavior, providing them to its parts. Use it for click-to-edit labels,
+ * titles, and table cells where a full form input would be heavy.
+ */
 export interface EditableRootProps extends PrimitiveProps {
-  /** Controlled value. Use `v-model`. */
-  modelValue?: string;
   /** Uncontrolled initial value. @default '' */
   defaultValue?: string;
   /** Placeholder for edit / preview. A single string applies to both. */
@@ -28,7 +32,6 @@ export interface EditableRootProps extends PrimitiveProps {
 }
 
 export interface EditableRootEmits {
-  'update:modelValue': [value: string];
   'update:state': [state: 'edit' | 'submit' | 'cancel'];
   submit: [value: string];
 }
@@ -44,7 +47,6 @@ defineOptions({ inheritAttrs: false });
 
 const {
   as = 'div',
-  modelValue,
   defaultValue = '',
   placeholder = 'Enter text…',
   activationMode = 'focus',
@@ -61,19 +63,24 @@ const emit = defineEmits<EditableRootEmits>();
 
 const { forwardRef, currentElement } = useForwardExpose();
 
-const localValue = ref<string>(modelValue ?? defaultValue);
+// Uncontrolled fallback, seeded from `defaultValue`. In controlled mode the
+// `get` reads the live prop, so local state can never go stale.
+const localValue = ref<string>(defaultValue);
 
-watch(() => modelValue, (v) => {
-  if (v === undefined || v === localValue.value) return;
-  localValue.value = v;
+const model = defineModel<string>({
+  get: v => v ?? localValue.value,
+  set: (v) => {
+    localValue.value = v;
+    return v;
+  },
 });
 
-const inputValue = ref<string>(localValue.value);
+const inputValue = ref<string>(model.value);
 const isEditing = ref<boolean>(startWithEditMode);
 const inputRef = shallowRef<HTMLInputElement | undefined>();
 
-// Keep the draft in sync when modelValue changes from outside.
-watch(localValue, (v) => {
+// Keep the draft in sync when the committed value changes from outside.
+watch(model, (v) => {
   inputValue.value = v;
 });
 
@@ -83,24 +90,23 @@ const resolvedPlaceholder = computed<EditablePlaceholder>(() =>
     : placeholder,
 );
 
-const isEmpty = computed(() => localValue.value === '');
+const isEmpty = computed(() => model.value === '');
 
 function commitModel(v: string): void {
-  if (v === localValue.value) return;
-  localValue.value = v;
-  emit('update:modelValue', v);
+  if (v === model.value) return;
+  model.value = v;
 }
 
 function edit(): void {
   if (disabled || readonly) return;
-  inputValue.value = localValue.value;
+  inputValue.value = model.value;
   isEditing.value = true;
   emit('update:state', 'edit');
 }
 
 function cancel(): void {
   isEditing.value = false;
-  inputValue.value = localValue.value;
+  inputValue.value = model.value;
   emit('update:state', 'cancel');
 }
 
@@ -121,7 +127,7 @@ function onFocusOutCapture(event: FocusEvent): void {
 }
 
 provideEditableContext({
-  modelValue: localValue,
+  modelValue: model,
   inputValue,
   isEditing,
   placeholder: resolvedPlaceholder,
@@ -153,7 +159,7 @@ provideEditableContext({
     @focusout.capture="onFocusOutCapture"
   >
     <slot
-      :model-value="localValue"
+      :model-value="model"
       :is-editing="isEditing"
       :is-empty="isEmpty"
       :edit="edit"
diff --git a/vue/primitives/src/editable/EditableSubmitTrigger.vue b/vue/primitives/src/editable/EditableSubmitTrigger.vue
index 266cdb6..a875bf0 100644
--- a/vue/primitives/src/editable/EditableSubmitTrigger.vue
+++ b/vue/primitives/src/editable/EditableSubmitTrigger.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Button that commits the draft value and leaves edit mode. It is only shown
+ * while editing.
+ */
 export interface EditableSubmitTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/editable/demo.vue b/vue/primitives/src/editable/demo.vue
new file mode 100644
index 0000000..4c89074
--- /dev/null
+++ b/vue/primitives/src/editable/demo.vue
@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  EditableArea,
+  EditableCancelTrigger,
+  EditableEditTrigger,
+  EditableInput,
+  EditablePreview,
+  EditableRoot,
+  EditableSubmitTrigger,
+} from '@robonen/primitives';
+
+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>
+
+    <EditableRoot
+      v-model="name"
+      submit-mode="both"
+      select-on-focus
+      activation-mode="dblclick"
+      placeholder="Add your name…"
+      class="flex items-center gap-2"
+    >
+      <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)"
+        />
+        <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)"
+        />
+      </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"
+      >
+        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"
+      >
+        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"
+      >
+        Cancel
+      </EditableCancelTrigger>
+    </EditableRoot>
+
+    <p class="mt-3 text-xs text-(--fg-subtle)">
+      Double-click the name to edit. Enter or blur saves, Escape cancels.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/focus-scope/FocusScope.vue b/vue/primitives/src/focus-scope/FocusScope.vue
index cf9bc1b..49eac2d 100644
--- a/vue/primitives/src/focus-scope/FocusScope.vue
+++ b/vue/primitives/src/focus-scope/FocusScope.vue
@@ -8,6 +8,17 @@ export interface FocusScopeEmits {
   unmountAutoFocus: [event: Event];
 }
 
+/**
+ * A low-level building block that manages keyboard focus for its contents. On
+ * mount it can move focus inside (autofocus), on unmount it restores focus to
+ * the previously focused element, and while active it can loop Tab/Shift+Tab at
+ * the edges and/or trap focus so it cannot leave the container. Scopes are
+ * tracked in a global stack so nested scopes (e.g. a dialog opening over a
+ * popover) hand focus management back and forth correctly. Use it to wrap any
+ * overlay or modal surface that needs accessible focus containment; it renders
+ * no UI of its own. Emits `mountAutoFocus`/`unmountAutoFocus` so the consumer
+ * can override the default focus target.
+ */
 export interface FocusScopeProps extends PrimitiveProps {
   /**
    * Зациклить Tab/Shift+Tab: с последнего элемента — на первый и наоборот.
diff --git a/vue/primitives/src/hover-card/HoverCardArrow.vue b/vue/primitives/src/hover-card/HoverCardArrow.vue
index 2cde95b..adb4599 100644
--- a/vue/primitives/src/hover-card/HoverCardArrow.vue
+++ b/vue/primitives/src/hover-card/HoverCardArrow.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PopperArrowProps } from '../popper';
 
+/**
+ * An optional arrow that points from the hover card content back toward the
+ * trigger. Place it inside `HoverCardContent`; it tracks the resolved side and
+ * alignment automatically.
+ */
 export interface HoverCardArrowProps extends PopperArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/hover-card/HoverCardContent.vue b/vue/primitives/src/hover-card/HoverCardContent.vue
index e4dd274..6a29725 100644
--- a/vue/primitives/src/hover-card/HoverCardContent.vue
+++ b/vue/primitives/src/hover-card/HoverCardContent.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { HoverCardContentImplEmits, HoverCardContentImplProps } from './HoverCardContentImpl.vue';
 
+/**
+ * The floating panel that holds the previewed content. It is positioned against
+ * the trigger and is mounted only while the card is open (gated by `Presence`),
+ * unless `forceMount` is set so you can drive enter/exit animations yourself.
+ */
 export interface HoverCardContentProps extends HoverCardContentImplProps {
   /** Keep mounted for CSS exit animations. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/hover-card/HoverCardContentImpl.vue b/vue/primitives/src/hover-card/HoverCardContentImpl.vue
index 9d591ae..e8c1294 100644
--- a/vue/primitives/src/hover-card/HoverCardContentImpl.vue
+++ b/vue/primitives/src/hover-card/HoverCardContentImpl.vue
@@ -2,6 +2,12 @@
 import type { PopperContentProps } from '../popper';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Internal implementation of the hover card panel: it wires up Popper
+ * positioning, the dismissable layer, the trigger-to-content grace area, and
+ * selection handling. Rendered by `HoverCardContent`; not exported for direct
+ * use.
+ */
 export interface HoverCardContentImplProps extends PrimitiveProps, Pick<
   PopperContentProps,
   | 'side'
diff --git a/vue/primitives/src/hover-card/HoverCardPortal.vue b/vue/primitives/src/hover-card/HoverCardPortal.vue
index 1ca353c..8ed53c3 100644
--- a/vue/primitives/src/hover-card/HoverCardPortal.vue
+++ b/vue/primitives/src/hover-card/HoverCardPortal.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { TeleportPrimitiveProps } from '../teleport';
 
+/**
+ * Teleports the hover card content into a different part of the DOM (the body by
+ * default) so it escapes parent overflow and stacking-context clipping. Wrap the
+ * content in it to keep the floating card above the rest of the page.
+ */
 export interface HoverCardPortalProps extends TeleportPrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/hover-card/HoverCardRoot.vue b/vue/primitives/src/hover-card/HoverCardRoot.vue
index 402c063..2d758fc 100644
--- a/vue/primitives/src/hover-card/HoverCardRoot.vue
+++ b/vue/primitives/src/hover-card/HoverCardRoot.vue
@@ -1,4 +1,16 @@
 <script lang="ts">
+/**
+ * A rich, floating card that previews related content when the pointer hovers
+ * (or keyboard focus lands) on a trigger, after a short open delay. Built on
+ * Popper for collision-aware positioning, with a grace area so the pointer can
+ * travel from the trigger to the card without it closing.
+ *
+ * Use it for sighted-user preview affordances — a user profile on an @mention,
+ * a link preview, or a glance at a record — never for essential information,
+ * since it is not exposed to touch or assistive technology the way a tooltip is.
+ * The root owns open state and provides context to every part; bind
+ * `v-model:open` (or listen to `update:open`) to observe or control it.
+ */
 export interface HoverCardRootProps {
   /** Controlled open state. Bind with `v-model:open`. */
   open?: boolean;
diff --git a/vue/primitives/src/hover-card/HoverCardTrigger.vue b/vue/primitives/src/hover-card/HoverCardTrigger.vue
index 3c70ca9..c963aa9 100644
--- a/vue/primitives/src/hover-card/HoverCardTrigger.vue
+++ b/vue/primitives/src/hover-card/HoverCardTrigger.vue
@@ -2,6 +2,11 @@
 import type { PopperAnchorProps } from '../popper';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The element that opens the hover card on pointer enter or focus and anchors
+ * the floating content to it. Renders as an `<a>` by default; pass a custom
+ * `reference` to position the card against a different element.
+ */
 export interface HoverCardTriggerProps extends PrimitiveProps, Pick<PopperAnchorProps, 'reference'> {}
 </script>
 
diff --git a/vue/primitives/src/hover-card/demo.vue b/vue/primitives/src/hover-card/demo.vue
new file mode 100644
index 0000000..59203ff
--- /dev/null
+++ b/vue/primitives/src/hover-card/demo.vue
@@ -0,0 +1,62 @@
+<script setup lang="ts">
+import {
+  HoverCardArrow,
+  HoverCardContent,
+  HoverCardPortal,
+  HoverCardRoot,
+  HoverCardTrigger,
+} from '@robonen/primitives';
+
+const user = {
+  handle: '@robonen',
+  name: 'Andrew Robonen',
+  bio: 'Building headless Vue primitives. Coffee, types, and small bundles.',
+  following: 182,
+  followers: '4.1k',
+};
+</script>
+
+<template>
+  <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)"
+      >
+        {{ user.handle }}
+      </HoverCardTrigger>
+
+      <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"
+        >
+          <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)">
+              {{ 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>
+          </div>
+
+          <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>
+
+          <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" />
+            </svg>
+          </HoverCardArrow>
+        </HoverCardContent>
+      </HoverCardPortal>
+    </HoverCardRoot>
+    — hover the handle to preview.
+  </p>
+</template>
diff --git a/vue/primitives/src/index.ts b/vue/primitives/src/index.ts
index a5ead48..4b002a0 100644
--- a/vue/primitives/src/index.ts
+++ b/vue/primitives/src/index.ts
@@ -10,6 +10,7 @@ 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';
@@ -53,3 +54,5 @@ export * from './command';
 
 export * from './calendar';
 export * from './date-picker';
+
+export * from './qr-code';
diff --git a/vue/primitives/src/label/Label.vue b/vue/primitives/src/label/Label.vue
index b17f57c..ac0cecb 100644
--- a/vue/primitives/src/label/Label.vue
+++ b/vue/primitives/src/label/Label.vue
@@ -1,6 +1,13 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A caption associated with a form control. Renders a native `<label>` and,
+ * when `for` matches a control's id, lets clicks focus or toggle that control
+ * while announcing the text to assistive technology. Double-click text
+ * selection is suppressed so labels stay clickable. Use it to label inputs,
+ * checkboxes, switches, and other custom controls.
+ */
 export interface LabelProps extends PrimitiveProps {
   /** The id of the element the label is associated with (renders as `for`). */
   for?: string;
@@ -11,7 +18,7 @@ export interface LabelProps extends PrimitiveProps {
 import { Primitive } from '../primitive';
 import { useForwardExpose } from '@robonen/vue';
 
-useForwardExpose();
+const { forwardRef } = useForwardExpose();
 
 const { as = 'label', for: htmlFor } = defineProps<LabelProps>();
 
@@ -22,7 +29,7 @@ function onMouseDown(event: MouseEvent) {
 </script>
 
 <template>
-  <Primitive :as="as" :for="htmlFor" @mousedown="onMouseDown">
+  <Primitive :ref="forwardRef" :as="as" :for="htmlFor" @mousedown="onMouseDown">
     <slot />
   </Primitive>
 </template>
diff --git a/vue/primitives/src/label/demo.vue b/vue/primitives/src/label/demo.vue
new file mode 100644
index 0000000..400dbe1
--- /dev/null
+++ b/vue/primitives/src/label/demo.vue
@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import { Label } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const email = ref('');
+const notify = ref(true);
+</script>
+
+<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)"
+    @submit.prevent
+  >
+    <div class="flex flex-col gap-1.5">
+      <Label
+        for="demo-email"
+        class="text-sm font-medium select-none"
+      >
+        Email address
+      </Label>
+      <input
+        id="demo-email"
+        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)"
+      >
+      <p class="text-xs text-(--fg-subtle)">
+        Click the label above to focus the field.
+      </p>
+    </div>
+
+    <Label
+      for="demo-notify"
+      class="flex cursor-pointer items-center gap-2.5 text-sm select-none"
+    >
+      <input
+        id="demo-notify"
+        v-model="notify"
+        type="checkbox"
+        class="size-4 accent-(--accent)"
+      >
+      Email me about product updates
+    </Label>
+
+    <p
+      class="text-sm"
+      :class="notify
+        ? 'text-emerald-600 dark:text-emerald-400'
+        : 'text-(--fg-muted)'"
+    >
+      {{ notify ? 'You will receive updates.' : 'Updates are off.' }}
+    </p>
+  </form>
+</template>
diff --git a/vue/primitives/src/listbox/ListboxContent.vue b/vue/primitives/src/listbox/ListboxContent.vue
index 68a425c..75334ef 100644
--- a/vue/primitives/src/listbox/ListboxContent.vue
+++ b/vue/primitives/src/listbox/ListboxContent.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The scrollable list container (`role="listbox"`) that wraps the items. It
+ * receives focus, owns the keyboard handlers (navigation, enter, type-ahead),
+ * and exposes the collection of items to the root.
+ */
 export interface ListboxContentProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/listbox/ListboxFilter.vue b/vue/primitives/src/listbox/ListboxFilter.vue
index da86783..479f2f0 100644
--- a/vue/primitives/src/listbox/ListboxFilter.vue
+++ b/vue/primitives/src/listbox/ListboxFilter.vue
@@ -1,6 +1,13 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * An optional text input for filtering the list. While mounted it takes over
+ * focus from the content (driving the list via `aria-activedescendant`),
+ * resets the highlight to the first item on each keystroke, and forwards
+ * Enter / arrow / Home / End keys to the listbox. Filtering of the items
+ * themselves is left to the consumer via `v-model`.
+ */
 export interface ListboxFilterProps extends PrimitiveProps {
   /** Controlled input value. */
   modelValue?: string;
diff --git a/vue/primitives/src/listbox/ListboxGroup.vue b/vue/primitives/src/listbox/ListboxGroup.vue
index a41650b..6cf9256 100644
--- a/vue/primitives/src/listbox/ListboxGroup.vue
+++ b/vue/primitives/src/listbox/ListboxGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Groups related items under a shared label (`role="group"`). Wraps a set of
+ * `ListboxItem`s and is labelled by its `ListboxGroupLabel` via `aria-labelledby`.
+ */
 export interface ListboxGroupProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/listbox/ListboxGroupLabel.vue b/vue/primitives/src/listbox/ListboxGroupLabel.vue
index 82c7304..afa71e3 100644
--- a/vue/primitives/src/listbox/ListboxGroupLabel.vue
+++ b/vue/primitives/src/listbox/ListboxGroupLabel.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The accessible label for a `ListboxGroup`. Its id is wired to the group's
+ * `aria-labelledby`, so place it inside the group to name the set of items.
+ */
 export interface ListboxGroupLabelProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/listbox/ListboxItem.vue b/vue/primitives/src/listbox/ListboxItem.vue
index 7fd2351..31333a0 100644
--- a/vue/primitives/src/listbox/ListboxItem.vue
+++ b/vue/primitives/src/listbox/ListboxItem.vue
@@ -2,6 +2,11 @@
 import type { ListboxValue } from './utils';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A single selectable option (`role="option"`). Clicking, pressing Space, or
+ * pressing Enter while highlighted toggles its selection and emits `select`.
+ * Exposes `isSelected` / `isHighlighted` to its default slot.
+ */
 export interface ListboxItemProps<U extends ListboxValue = ListboxValue> extends PrimitiveProps {
   /** The value of the item. */
   value: U;
diff --git a/vue/primitives/src/listbox/ListboxItemIndicator.vue b/vue/primitives/src/listbox/ListboxItemIndicator.vue
index c0f065f..350d50b 100644
--- a/vue/primitives/src/listbox/ListboxItemIndicator.vue
+++ b/vue/primitives/src/listbox/ListboxItemIndicator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Renders its content only when the parent `ListboxItem` is selected. Use it
+ * to show a checkmark or other selected-state marker; it is `aria-hidden`.
+ */
 export interface ListboxItemIndicatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/listbox/ListboxRoot.vue b/vue/primitives/src/listbox/ListboxRoot.vue
index bf8d80f..ddeb58f 100644
--- a/vue/primitives/src/listbox/ListboxRoot.vue
+++ b/vue/primitives/src/listbox/ListboxRoot.vue
@@ -3,9 +3,18 @@ import type { ListboxDirection, ListboxOrientation, ListboxSelectionBehavior } f
 import type { ListboxValue } from './utils';
 import type { PrimitiveProps } from '../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.
+ *
+ * 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.
+ */
 export interface ListboxRootProps<U extends ListboxValue = ListboxValue> extends PrimitiveProps {
-  /** Controlled value. Use `v-model`. */
-  modelValue?: U | U[];
   /** Uncontrolled initial value. */
   defaultValue?: U | U[];
   /** Allow multiple selection. */
@@ -25,7 +34,6 @@ export interface ListboxRootProps<U extends ListboxValue = ListboxValue> extends
 }
 
 export interface ListboxRootEmits<U extends ListboxValue = ListboxValue> {
-  'update:modelValue': [value: U | U[] | undefined];
   highlight: [payload: { ref: HTMLElement; value: U } | undefined];
   entryFocus: [event: CustomEvent];
   leave: [event: Event];
@@ -45,7 +53,6 @@ import { useForwardExpose } from '@robonen/vue';
 
 const {
   as = 'div',
-  modelValue,
   defaultValue,
   multiple = false,
   orientation = 'vertical',
@@ -58,11 +65,13 @@ const {
 
 const emit = defineEmits<ListboxRootEmits<T>>();
 
+const model = defineModel<T | T[] | undefined>();
+
 const { forwardRef, currentElement } = useForwardExpose();
 const config = useConfig();
 const direction = computed(() => dir ?? config.dir.value);
 
-const initial = (modelValue ?? defaultValue) as T | T[] | undefined;
+const initial = (model.value ?? defaultValue) as T | T[] | undefined;
 // shallowRef: value is always replaced on commit, never mutated in place.
 const localValue = shallowRef<T | T[] | undefined>(
   multiple
@@ -70,7 +79,7 @@ const localValue = shallowRef<T | T[] | undefined>(
     : (Array.isArray(initial) ? initial[0] : initial),
 ) as Ref<T | T[] | undefined>;
 
-watch(() => modelValue, (v) => {
+watch(model, (v) => {
   if (v === undefined) return;
   const cur = localValue.value;
   if (Array.isArray(v)) {
@@ -116,7 +125,7 @@ function isSelected(value: T): boolean {
 
 function commit(next: T | T[] | undefined): void {
   localValue.value = next;
-  emit('update:modelValue', next);
+  model.value = next;
 }
 
 function onValueChange(val: T): void {
diff --git a/vue/primitives/src/listbox/demo.vue b/vue/primitives/src/listbox/demo.vue
new file mode 100644
index 0000000..a2f0a09
--- /dev/null
+++ b/vue/primitives/src/listbox/demo.vue
@@ -0,0 +1,106 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+
+import {
+  ListboxContent,
+  ListboxFilter,
+  ListboxGroup,
+  ListboxGroupLabel,
+  ListboxItem,
+  ListboxItemIndicator,
+  ListboxRoot,
+} from '@robonen/primitives';
+
+interface Fruit {
+  value: string;
+  label: string;
+  group: 'Citrus' | 'Berries';
+}
+
+const fruits: Fruit[] = [
+  { value: 'orange', label: 'Orange', group: 'Citrus' },
+  { value: 'lemon', label: 'Lemon', group: 'Citrus' },
+  { value: 'lime', label: 'Lime', group: 'Citrus' },
+  { value: 'strawberry', label: 'Strawberry', group: 'Berries' },
+  { value: 'blueberry', label: 'Blueberry', group: 'Berries' },
+  { value: 'raspberry', label: 'Raspberry', group: 'Berries' },
+];
+
+const selected = ref<string[]>(['lemon']);
+const query = ref('');
+
+const groups = ['Citrus', 'Berries'] as const;
+
+const filtered = computed(() => {
+  const q = query.value.trim().toLowerCase();
+  return q ? fruits.filter(f => f.label.toLowerCase().includes(q)) : fruits;
+});
+
+function itemsFor(group: (typeof groups)[number]) {
+  return filtered.value.filter(f => f.group === group);
+}
+
+function labelFor(value: string) {
+  return fruits.find(f => f.value === value)?.label ?? value;
+}
+</script>
+
+<template>
+  <div class="flex w-full max-w-xs flex-col gap-3">
+    <ListboxRoot
+      v-model="selected"
+      multiple
+      highlight-on-hover
+      class="overflow-hidden rounded-lg border border-(--border) bg-(--bg-elevated)"
+    >
+      <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)"
+        />
+      </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)"
+        >
+          No fruit found.
+        </p>
+
+        <ListboxGroup
+          v-for="group in groups"
+          v-show="itemsFor(group).length"
+          :key="group"
+          class="mb-1 last:mb-0"
+        >
+          <ListboxGroupLabel
+            class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-(--fg-subtle)"
+          >
+            {{ group }}
+          </ListboxGroupLabel>
+
+          <ListboxItem
+            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"
+          >
+            <span>{{ fruit.label }}</span>
+            <ListboxItemIndicator class="text-(--accent)">
+              <span aria-hidden="true">✓</span>
+            </ListboxItemIndicator>
+          </ListboxItem>
+        </ListboxGroup>
+      </ListboxContent>
+    </ListboxRoot>
+
+    <p class="text-sm text-(--fg-muted)">
+      Selected:
+      <span class="font-medium text-(--fg)">
+        {{ selected.length ? selected.map(labelFor).join(', ') : 'none' }}
+      </span>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/menu/MenuAnchor.vue b/vue/primitives/src/menu/MenuAnchor.vue
index 0a3f9ae..b396a26 100644
--- a/vue/primitives/src/menu/MenuAnchor.vue
+++ b/vue/primitives/src/menu/MenuAnchor.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PopperAnchorProps } from '../popper';
 
+/**
+ * An optional positioning anchor for the menu content. Render it around the
+ * element the menu should attach to when the open trigger is not itself the
+ * anchor (for example, anchoring a dropdown to a virtual element or the
+ * pointer). When omitted, content is positioned relative to its trigger.
+ */
 export interface MenuAnchorProps extends PopperAnchorProps {}
 </script>
 
diff --git a/vue/primitives/src/menu/MenuArrow.vue b/vue/primitives/src/menu/MenuArrow.vue
index 13d62f7..cb87088 100644
--- a/vue/primitives/src/menu/MenuArrow.vue
+++ b/vue/primitives/src/menu/MenuArrow.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PopperArrowProps } from '../popper';
 
+/**
+ * An optional arrow that renders inside the menu content and points back toward
+ * the anchor, visually tying the floating menu to its trigger. Place it as a
+ * child of the content.
+ */
 export interface MenuArrowProps extends PopperArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/menu/MenuCheckboxItem.vue b/vue/primitives/src/menu/MenuCheckboxItem.vue
index a91cfc8..fd34e4e 100644
--- a/vue/primitives/src/menu/MenuCheckboxItem.vue
+++ b/vue/primitives/src/menu/MenuCheckboxItem.vue
@@ -2,8 +2,16 @@
 import type { MenuItemImplEmits, MenuItemImplProps } from './MenuItemImpl.vue';
 import type { CheckedState } from './types';
 
+/**
+ * A menu item that toggles a boolean (or indeterminate) state when selected,
+ * rendering with `role="menuitemcheckbox"`. Pair it with MenuItemIndicator to
+ * show a check mark. Bind `v-model:checked` to control its state, or leave it
+ * uncontrolled with `defaultChecked`.
+ */
 export interface MenuCheckboxItemProps extends MenuItemImplProps {
+  /** The controlled checked state. Use together with `update:checked`; may be `'indeterminate'`. */
   checked?: CheckedState;
+  /** The checked state when uncontrolled. */
   defaultChecked?: CheckedState;
 }
 export interface MenuCheckboxItemEmits extends MenuItemImplEmits {
diff --git a/vue/primitives/src/menu/MenuContent.vue b/vue/primitives/src/menu/MenuContent.vue
index 1ff4dd6..acbef88 100644
--- a/vue/primitives/src/menu/MenuContent.vue
+++ b/vue/primitives/src/menu/MenuContent.vue
@@ -1,7 +1,17 @@
 <script lang="ts">
 import type { MenuContentImplEmits, MenuContentImplProps } from './MenuContentImpl.vue';
 
+/**
+ * The popup surface that holds the menu items. It mounts only while the menu is
+ * open (gated by Presence), positions itself via Popper, and switches between
+ * modal and non-modal behaviour based on the root's `modal` prop. Place items,
+ * groups, labels, separators, and submenus inside it.
+ *
+ * Set `forceMount` to keep it in the DOM when open state is driven externally
+ * (for example, to run exit animations).
+ */
 export interface MenuContentProps extends MenuContentImplProps {
+  /** Force mounting the content even when closed, e.g. to control presence with an external animation library. */
   forceMount?: boolean;
 }
 export type MenuContentEmits = MenuContentImplEmits;
diff --git a/vue/primitives/src/menu/MenuContentImpl.vue b/vue/primitives/src/menu/MenuContentImpl.vue
index 74cca31..2ea96ed 100644
--- a/vue/primitives/src/menu/MenuContentImpl.vue
+++ b/vue/primitives/src/menu/MenuContentImpl.vue
@@ -2,14 +2,23 @@
 import type { PopperContentProps } from '../popper';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Internal shared implementation behind MenuContent and MenuSubContent. It
+ * composes Popper positioning, FocusScope, DismissableLayer, and a vertical
+ * RovingFocusGroup, and adds typeahead search and pointer grace-area handling.
+ * Not meant to be used directly — render MenuContent (or MenuSubContent) instead.
+ */
 export interface MenuContentImplProps extends PrimitiveProps, Pick<PopperContentProps,
   | 'side' | 'sideOffset' | 'sideFlip' | 'align' | 'alignOffset' | 'alignFlip'
   | 'avoidCollisions' | 'collisionBoundary' | 'collisionPadding' | 'arrowPadding'
   | 'sticky' | 'hideWhenDetached' | 'positionStrategy' | 'updatePositionStrategy'
   | 'reference' | 'prioritizePosition'
 > {
+  /** Whether keyboard focus should wrap from the last item back to the first (and vice versa). */
   loop?: boolean;
+  /** Whether to trap focus inside the content while open (used for modal menus). */
   trapFocus?: boolean;
+  /** Whether to block pointer events on everything outside the content (used for modal menus). */
   disableOutsidePointerEvents?: boolean;
 }
 
diff --git a/vue/primitives/src/menu/MenuGroup.vue b/vue/primitives/src/menu/MenuGroup.vue
index c7e636b..e6ab474 100644
--- a/vue/primitives/src/menu/MenuGroup.vue
+++ b/vue/primitives/src/menu/MenuGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Groups a set of related menu items under `role="group"` for accessibility.
+ * Combine it with a MenuLabel to give the group an accessible name.
+ */
 export interface MenuGroupProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/menu/MenuItem.vue b/vue/primitives/src/menu/MenuItem.vue
index 97bc355..e46abb1 100644
--- a/vue/primitives/src/menu/MenuItem.vue
+++ b/vue/primitives/src/menu/MenuItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuItemImplEmits, MenuItemImplProps } from './MenuItemImpl.vue';
 
+/**
+ * A single actionable menu item that emits `select` and closes the menu when
+ * activated by click, Enter, or Space. Use it for ordinary commands; call
+ * `event.preventDefault()` in `select` to keep the menu open after selection.
+ */
 export interface MenuItemProps extends MenuItemImplProps {}
 export type MenuItemEmits = MenuItemImplEmits;
 </script>
diff --git a/vue/primitives/src/menu/MenuItemImpl.vue b/vue/primitives/src/menu/MenuItemImpl.vue
index 61383c7..3e0979a 100644
--- a/vue/primitives/src/menu/MenuItemImpl.vue
+++ b/vue/primitives/src/menu/MenuItemImpl.vue
@@ -1,8 +1,16 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Internal base for every selectable menu item (MenuItem, MenuCheckboxItem,
+ * MenuRadioItem, MenuSubTrigger). It wires up roving-focus, pointer
+ * highlighting, disabled state, and typeahead `textValue`, and emits `select`.
+ * Not used directly — render one of the public item parts instead.
+ */
 export interface MenuItemImplProps extends PrimitiveProps {
+  /** Whether the item is disabled, removing it from focus and selection. */
   disabled?: boolean;
+  /** Optional text used to match the item during typeahead; defaults to the item's trimmed text content. */
   textValue?: string;
 }
 export interface MenuItemImplEmits {
diff --git a/vue/primitives/src/menu/MenuItemIndicator.vue b/vue/primitives/src/menu/MenuItemIndicator.vue
index e92c4d0..e23f871 100644
--- a/vue/primitives/src/menu/MenuItemIndicator.vue
+++ b/vue/primitives/src/menu/MenuItemIndicator.vue
@@ -1,7 +1,13 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Renders only while its parent MenuCheckboxItem or MenuRadioItem is checked (or
+ * indeterminate), giving you a place to show a check or dot icon. Must be nested
+ * inside a checkbox or radio item, which provides its state via context.
+ */
 export interface MenuItemIndicatorProps extends PrimitiveProps {
+  /** Force mounting the indicator even when unchecked, e.g. to control presence with an external animation library. */
   forceMount?: boolean;
 }
 </script>
diff --git a/vue/primitives/src/menu/MenuLabel.vue b/vue/primitives/src/menu/MenuLabel.vue
index cefc532..281ac5b 100644
--- a/vue/primitives/src/menu/MenuLabel.vue
+++ b/vue/primitives/src/menu/MenuLabel.vue
@@ -1,6 +1,11 @@
 <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>
 
diff --git a/vue/primitives/src/menu/MenuPortal.vue b/vue/primitives/src/menu/MenuPortal.vue
index f27d2d6..084d850 100644
--- a/vue/primitives/src/menu/MenuPortal.vue
+++ b/vue/primitives/src/menu/MenuPortal.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PortalProps } from '../teleport';
 
+/**
+ * Teleports the menu content into a different part of the DOM (the document body
+ * by default) so it escapes ancestor `overflow` and stacking-context clipping.
+ * Wrap the content in this part to render it as a top-level overlay.
+ */
 export interface MenuPortalProps extends PortalProps {}
 </script>
 
diff --git a/vue/primitives/src/menu/MenuRadioGroup.vue b/vue/primitives/src/menu/MenuRadioGroup.vue
index 07b5793..4d61d89 100644
--- a/vue/primitives/src/menu/MenuRadioGroup.vue
+++ b/vue/primitives/src/menu/MenuRadioGroup.vue
@@ -1,8 +1,15 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * 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.
+ */
 export interface MenuRadioGroupProps extends PrimitiveProps {
+  /** The controlled selected value. Use together with `update:modelValue`. */
   modelValue?: string;
+  /** The selected value when uncontrolled. */
   defaultValue?: string;
 }
 export interface MenuRadioGroupEmits {
diff --git a/vue/primitives/src/menu/MenuRadioItem.vue b/vue/primitives/src/menu/MenuRadioItem.vue
index 89f258e..b80aaea 100644
--- a/vue/primitives/src/menu/MenuRadioItem.vue
+++ b/vue/primitives/src/menu/MenuRadioItem.vue
@@ -1,7 +1,14 @@
 <script lang="ts">
 import type { MenuItemImplEmits, MenuItemImplProps } from './MenuItemImpl.vue';
 
+/**
+ * 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.
+ */
 export interface MenuRadioItemProps extends MenuItemImplProps {
+  /** The unique value this item represents within its MenuRadioGroup. */
   value: string;
 }
 export type MenuRadioItemEmits = MenuItemImplEmits;
diff --git a/vue/primitives/src/menu/MenuRoot.vue b/vue/primitives/src/menu/MenuRoot.vue
index f845355..39c6178 100644
--- a/vue/primitives/src/menu/MenuRoot.vue
+++ b/vue/primitives/src/menu/MenuRoot.vue
@@ -1,14 +1,22 @@
 <script lang="ts">
 import type { Direction } from '../config-provider';
 
+/**
+ * The unstyled, low-level menu engine that powers DropdownMenu, ContextMenu, and
+ * Menubar. It is built on Popper and wires up roving-focus keyboard navigation,
+ * typeahead, nested submenus, checkbox/radio items, and modal vs. non-modal
+ * dismissal — but it is deliberately trigger-agnostic, so consumers supply their
+ * own anchor and open logic.
+ *
+ * Use this directly only when composing a new menu-like primitive; for ordinary
+ * app menus reach for DropdownMenu or ContextMenu instead. MenuRoot owns open
+ * state and provides context to every part; bind `v-model:open` (or listen to
+ * `update:open`) to control or observe whether the menu is open.
+ */
 export interface MenuRootProps {
-  open?: boolean;
   dir?: Direction;
   modal?: boolean;
 }
-export interface MenuRootEmits {
-  'update:open': [value: boolean];
-}
 </script>
 
 <script setup lang="ts">
@@ -20,12 +28,11 @@ import { provideMenuContext, provideMenuRootContext } from './context';
 import { useIsUsingKeyboard } from './useIsUsingKeyboard';
 
 const {
-  open = false,
   dir: dirProp,
   modal = true,
 } = defineProps<MenuRootProps>();
 
-const emit = defineEmits<MenuRootEmits>();
+const open = defineModel<boolean>('open', { default: false });
 
 defineSlots<{ default?: () => unknown }>();
 
@@ -33,17 +40,16 @@ const config = useConfig();
 const dirRef = toRef(() => dirProp ?? config.dir.value);
 const isUsingKeyboardRef = useIsUsingKeyboard();
 const content = shallowRef<HTMLElement | null>(null);
-const openRef = toRef(() => open);
 
 provideMenuContext({
-  open: openRef,
-  onOpenChange: v => emit('update:open', v),
+  open,
+  onOpenChange: (v) => { open.value = v; },
   content,
   onContentChange: (el) => { content.value = el; },
 });
 
 provideMenuRootContext({
-  onClose: () => emit('update:open', false),
+  onClose: () => { open.value = false; },
   dir: dirRef,
   isUsingKeyboardRef,
   modal: toRef(() => modal),
diff --git a/vue/primitives/src/menu/MenuRootContentModal.vue b/vue/primitives/src/menu/MenuRootContentModal.vue
index 140203b..1ac212e 100644
--- a/vue/primitives/src/menu/MenuRootContentModal.vue
+++ b/vue/primitives/src/menu/MenuRootContentModal.vue
@@ -1,4 +1,7 @@
 <script setup lang="ts">
+// Internal modal variant of the menu content: traps focus, disables outside
+// pointer events, locks body scroll, and hides sibling content from assistive
+// tech. Selected by MenuContent when the root's `modal` prop is true.
 import type { MenuContentImplEmits, MenuContentImplProps } from './MenuContentImpl.vue';
 
 import { shallowRef, watchEffect } from 'vue';
diff --git a/vue/primitives/src/menu/MenuRootContentNonModal.vue b/vue/primitives/src/menu/MenuRootContentNonModal.vue
index 24bf5f2..c4cf633 100644
--- a/vue/primitives/src/menu/MenuRootContentNonModal.vue
+++ b/vue/primitives/src/menu/MenuRootContentNonModal.vue
@@ -1,4 +1,8 @@
 <script setup lang="ts">
+// Internal non-modal variant of the menu content: leaves focus untrapped and
+// outside pointer events enabled, so the rest of the page stays interactive
+// while the menu is open. Selected by MenuContent when the root's `modal` prop
+// is false.
 import type { MenuContentImplEmits, MenuContentImplProps } from './MenuContentImpl.vue';
 
 import { shallowRef, watchEffect } from 'vue';
diff --git a/vue/primitives/src/menu/MenuSeparator.vue b/vue/primitives/src/menu/MenuSeparator.vue
index ef40b82..3ebfe77 100644
--- a/vue/primitives/src/menu/MenuSeparator.vue
+++ b/vue/primitives/src/menu/MenuSeparator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A visual and semantic divider (`role="separator"`) between groups of menu
+ * items. It is purely decorative for navigation and is skipped by keyboard focus.
+ */
 export interface MenuSeparatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/menu/MenuSub.vue b/vue/primitives/src/menu/MenuSub.vue
index 5f7c732..e22d229 100644
--- a/vue/primitives/src/menu/MenuSub.vue
+++ b/vue/primitives/src/menu/MenuSub.vue
@@ -1,5 +1,12 @@
 <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 {
diff --git a/vue/primitives/src/menu/MenuSubContent.vue b/vue/primitives/src/menu/MenuSubContent.vue
index 889887d..f5b0ee2 100644
--- a/vue/primitives/src/menu/MenuSubContent.vue
+++ b/vue/primitives/src/menu/MenuSubContent.vue
@@ -1,7 +1,14 @@
 <script lang="ts">
 import type { MenuContentImplEmits, MenuContentImplProps } from './MenuContentImpl.vue';
 
+/**
+ * The popup surface for a submenu's items. It mounts while the submenu is open,
+ * positions itself to the side of its MenuSubTrigger (flipping for RTL), and
+ * always renders non-modally so the parent menu stays interactive. Must be used
+ * inside a MenuSub.
+ */
 export interface MenuSubContentProps extends MenuContentImplProps {
+  /** Force mounting the content even when closed, e.g. to control presence with an external animation library. */
   forceMount?: boolean;
 }
 export type MenuSubContentEmits = MenuContentImplEmits;
diff --git a/vue/primitives/src/menu/MenuSubTrigger.vue b/vue/primitives/src/menu/MenuSubTrigger.vue
index 96ab83f..daf735e 100644
--- a/vue/primitives/src/menu/MenuSubTrigger.vue
+++ b/vue/primitives/src/menu/MenuSubTrigger.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { MenuItemImplProps } from './MenuItemImpl.vue';
 
+/**
+ * A menu item that opens its parent MenuSub's submenu. It acts as both the
+ * positioning anchor and the trigger, opening on hover (with a grace delay) or
+ * via the directional arrow key and closing on the opposite arrow. Must be used
+ * inside a MenuSub, alongside a MenuSubContent.
+ */
 export interface MenuSubTriggerProps extends MenuItemImplProps {}
 </script>
 
diff --git a/vue/primitives/src/menu/index.ts b/vue/primitives/src/menu/index.ts
index d3078e9..e8b3a78 100644
--- a/vue/primitives/src/menu/index.ts
+++ b/vue/primitives/src/menu/index.ts
@@ -13,7 +13,7 @@ export { default as MenuLabel, type MenuLabelProps } from './MenuLabel.vue';
 export { default as MenuPortal, type MenuPortalProps } from './MenuPortal.vue';
 export { default as MenuRadioGroup, type MenuRadioGroupEmits, type MenuRadioGroupProps } from './MenuRadioGroup.vue';
 export { default as MenuRadioItem, type MenuRadioItemEmits, type MenuRadioItemProps } from './MenuRadioItem.vue';
-export { default as MenuRoot, type MenuRootEmits, type MenuRootProps } from './MenuRoot.vue';
+export { default as MenuRoot, type MenuRootProps } from './MenuRoot.vue';
 export { default as MenuSeparator, type MenuSeparatorProps } from './MenuSeparator.vue';
 export { default as MenuSub, type MenuSubEmits, type MenuSubProps } from './MenuSub.vue';
 export { default as MenuSubContent, type MenuSubContentEmits, type MenuSubContentProps } from './MenuSubContent.vue';
diff --git a/vue/primitives/src/menubar/MenubarArrow.vue b/vue/primitives/src/menubar/MenubarArrow.vue
index eb82864..dfc869b 100644
--- a/vue/primitives/src/menubar/MenubarArrow.vue
+++ b/vue/primitives/src/menubar/MenubarArrow.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuArrowProps } from '../menu';
 
+/**
+ * An optional arrow that points from a menu's content back toward its trigger.
+ * Render it inside the content; it tracks the trigger as the menu repositions.
+ */
 export interface MenubarArrowProps extends MenuArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/menubar/MenubarCheckboxItem.vue b/vue/primitives/src/menubar/MenubarCheckboxItem.vue
index bd8fce4..57b3bc4 100644
--- a/vue/primitives/src/menubar/MenubarCheckboxItem.vue
+++ b/vue/primitives/src/menubar/MenubarCheckboxItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuCheckboxItemEmits, MenuCheckboxItemProps } from '../menu';
 
+/**
+ * A menu item that toggles a boolean (or indeterminate) state. Bind
+ * `v-model:checked` to track the value; pair it with MenubarItemIndicator to
+ * render a check mark when active.
+ */
 export interface MenubarCheckboxItemProps extends MenuCheckboxItemProps {}
 export type MenubarCheckboxItemEmits = MenuCheckboxItemEmits;
 </script>
diff --git a/vue/primitives/src/menubar/MenubarContent.vue b/vue/primitives/src/menubar/MenubarContent.vue
index 19fc7e6..bb38c4a 100644
--- a/vue/primitives/src/menubar/MenubarContent.vue
+++ b/vue/primitives/src/menubar/MenubarContent.vue
@@ -1,6 +1,12 @@
 <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>
diff --git a/vue/primitives/src/menubar/MenubarGroup.vue b/vue/primitives/src/menubar/MenubarGroup.vue
index aec69d7..0cdf195 100644
--- a/vue/primitives/src/menubar/MenubarGroup.vue
+++ b/vue/primitives/src/menubar/MenubarGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuGroupProps } from '../menu';
 
+/**
+ * Groups related items within a menu so assistive tech announces them together.
+ * Pair it with a MenubarLabel to give the group an accessible name.
+ */
 export interface MenubarGroupProps extends MenuGroupProps {}
 </script>
 
diff --git a/vue/primitives/src/menubar/MenubarItem.vue b/vue/primitives/src/menubar/MenubarItem.vue
index 671cd8e..f8ce1ba 100644
--- a/vue/primitives/src/menubar/MenubarItem.vue
+++ b/vue/primitives/src/menubar/MenubarItem.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuItemEmits, MenuItemProps } from '../menu';
 
+/**
+ * A single actionable row in a menu. Emits `select` on click or Enter/Space and
+ * closes the menu afterwards unless the event is prevented.
+ */
 export interface MenubarItemProps extends MenuItemProps {}
 export type MenubarItemEmits = MenuItemEmits;
 </script>
diff --git a/vue/primitives/src/menubar/MenubarItemIndicator.vue b/vue/primitives/src/menubar/MenubarItemIndicator.vue
index dce9565..15b353d 100644
--- a/vue/primitives/src/menubar/MenubarItemIndicator.vue
+++ b/vue/primitives/src/menubar/MenubarItemIndicator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuItemIndicatorProps } from '../menu';
 
+/**
+ * Renders its content only when the enclosing checkbox or radio item is checked.
+ * Put a check mark or dot inside it as the selection marker.
+ */
 export interface MenubarItemIndicatorProps extends MenuItemIndicatorProps {}
 </script>
 
diff --git a/vue/primitives/src/menubar/MenubarLabel.vue b/vue/primitives/src/menubar/MenubarLabel.vue
index d15ec5f..c88e2a7 100644
--- a/vue/primitives/src/menubar/MenubarLabel.vue
+++ b/vue/primitives/src/menubar/MenubarLabel.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuLabelProps } from '../menu';
 
+/**
+ * A non-interactive heading that titles a section of a menu. It is skipped by
+ * keyboard navigation and is not selectable.
+ */
 export interface MenubarLabelProps extends MenuLabelProps {}
 </script>
 
diff --git a/vue/primitives/src/menubar/MenubarMenu.vue b/vue/primitives/src/menubar/MenubarMenu.vue
index 80f29a3..cd9b043 100644
--- a/vue/primitives/src/menubar/MenubarMenu.vue
+++ b/vue/primitives/src/menubar/MenubarMenu.vue
@@ -1,4 +1,9 @@
 <script lang="ts">
+/**
+ * A single menu within the menubar, pairing one MenubarTrigger with its
+ * MenubarContent. Its `value` identifies the menu to the root so it can track
+ * which one is open; if omitted, a stable id is generated automatically.
+ */
 export interface MenubarMenuProps {
   value?: string;
 }
diff --git a/vue/primitives/src/menubar/MenubarPortal.vue b/vue/primitives/src/menubar/MenubarPortal.vue
index b2eb31a..aa99d56 100644
--- a/vue/primitives/src/menubar/MenubarPortal.vue
+++ b/vue/primitives/src/menubar/MenubarPortal.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuPortalProps } from '../menu';
 
+/**
+ * Teleports a menu's content into the document body (or a chosen target) so it
+ * renders above other content and escapes any `overflow: hidden` ancestor.
+ */
 export interface MenubarPortalProps extends MenuPortalProps {}
 </script>
 
diff --git a/vue/primitives/src/menubar/MenubarRadioGroup.vue b/vue/primitives/src/menubar/MenubarRadioGroup.vue
index a82fe52..b84ec70 100644
--- a/vue/primitives/src/menubar/MenubarRadioGroup.vue
+++ b/vue/primitives/src/menubar/MenubarRadioGroup.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuRadioGroupEmits, MenuRadioGroupProps } from '../menu';
 
+/**
+ * Groups MenubarRadioItems into a single-choice set. Bind `v-model` to track the
+ * selected item's value across the group.
+ */
 export interface MenubarRadioGroupProps extends MenuRadioGroupProps {}
 export type MenubarRadioGroupEmits = MenuRadioGroupEmits;
 </script>
diff --git a/vue/primitives/src/menubar/MenubarRadioItem.vue b/vue/primitives/src/menubar/MenubarRadioItem.vue
index c206501..1169b1e 100644
--- a/vue/primitives/src/menubar/MenubarRadioItem.vue
+++ b/vue/primitives/src/menubar/MenubarRadioItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuRadioItemEmits, MenuRadioItemProps } from '../menu';
 
+/**
+ * One option within a MenubarRadioGroup. Selecting it sets the group's value to
+ * this item's `value`; pair it with MenubarItemIndicator to show which option is
+ * active.
+ */
 export interface MenubarRadioItemProps extends MenuRadioItemProps {}
 export type MenubarRadioItemEmits = MenuRadioItemEmits;
 </script>
diff --git a/vue/primitives/src/menubar/MenubarRoot.vue b/vue/primitives/src/menubar/MenubarRoot.vue
index f6dec19..e868ec8 100644
--- a/vue/primitives/src/menubar/MenubarRoot.vue
+++ b/vue/primitives/src/menubar/MenubarRoot.vue
@@ -2,19 +2,26 @@
 import type { Direction } from '../config-provider';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A horizontal bar of menus, like the File / Edit / View row in a desktop app.
+ * Each MenubarMenu owns a trigger and its dropdown; the root coordinates them so
+ * only one is open at a time, arrow keys move between triggers, and typeahead
+ * jumps to a trigger by name. Built on top of Menu, so every menu inherits
+ * keyboard navigation, nested submenus, and checkbox/radio items.
+ *
+ * Use it for application-style menu bars in editors, dashboards, and tools. The
+ * root holds which menu is open; bind `v-model` (or listen to
+ * `update:modelValue`) to control or observe the active menu's value.
+ */
 export interface MenubarRootProps extends PrimitiveProps {
-  modelValue?: string;
   defaultValue?: string;
   dir?: Direction;
   loop?: boolean;
 }
-export interface MenubarRootEmits {
-  'update:modelValue': [value: string | undefined];
-}
 </script>
 
 <script setup lang="ts">
-import { computed, onScopeDispose, ref, toRef } from 'vue';
+import { onScopeDispose, ref, toRef } from 'vue';
 
 import { Primitive } from '../primitive';
 import { provideMenubarRootContext } from './context';
@@ -23,13 +30,22 @@ import { useConfig } from '../config-provider';
 import { useForwardExpose } from '@robonen/vue';
 
 const {
-  modelValue,
   defaultValue,
   dir: dirProp,
   loop = true,
   as = 'div',
 } = defineProps<MenubarRootProps>();
-const emit = defineEmits<MenubarRootEmits>();
+
+const localValue = ref<string | undefined>(defaultValue);
+
+const value = defineModel<string | undefined>('modelValue', {
+  default: undefined,
+  get: v => v ?? localValue.value,
+  set: (v) => {
+    localValue.value = v;
+    return v;
+  },
+});
 
 const config = useConfig();
 const dirRef = toRef(() => dirProp ?? config.dir.value);
@@ -37,15 +53,6 @@ const { forwardRef } = useForwardExpose();
 
 const { getItems, CollectionSlot } = useCollectionProvider<string>();
 
-const local = ref<string | undefined>(defaultValue);
-const value = computed({
-  get: () => modelValue !== undefined ? modelValue : local.value,
-  set: (v) => {
-    local.value = v;
-    emit('update:modelValue', v);
-  },
-});
-
 const searchRef = ref('');
 let searchTimer: ReturnType<typeof setTimeout> | undefined;
 
diff --git a/vue/primitives/src/menubar/MenubarSeparator.vue b/vue/primitives/src/menubar/MenubarSeparator.vue
index 103e646..870cab7 100644
--- a/vue/primitives/src/menubar/MenubarSeparator.vue
+++ b/vue/primitives/src/menubar/MenubarSeparator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { MenuSeparatorProps } from '../menu';
 
+/**
+ * A horizontal divider used to visually separate groups of items within a menu.
+ * Decorative and skipped by keyboard navigation.
+ */
 export interface MenubarSeparatorProps extends MenuSeparatorProps {}
 </script>
 
diff --git a/vue/primitives/src/menubar/MenubarSub.vue b/vue/primitives/src/menubar/MenubarSub.vue
index d140014..8b49363 100644
--- a/vue/primitives/src/menubar/MenubarSub.vue
+++ b/vue/primitives/src/menubar/MenubarSub.vue
@@ -1,6 +1,11 @@
 <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>
diff --git a/vue/primitives/src/menubar/MenubarSubContent.vue b/vue/primitives/src/menubar/MenubarSubContent.vue
index daf1e27..5938920 100644
--- a/vue/primitives/src/menubar/MenubarSubContent.vue
+++ b/vue/primitives/src/menubar/MenubarSubContent.vue
@@ -1,6 +1,10 @@
 <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>
diff --git a/vue/primitives/src/menubar/MenubarSubTrigger.vue b/vue/primitives/src/menubar/MenubarSubTrigger.vue
index 2536df4..f10fb36 100644
--- a/vue/primitives/src/menubar/MenubarSubTrigger.vue
+++ b/vue/primitives/src/menubar/MenubarSubTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { MenuSubTriggerProps } from '../menu';
 
+/**
+ * The item that opens its submenu on hover or ArrowRight and closes it on
+ * ArrowLeft. Renders like a regular item but opens MenubarSubContent instead of
+ * emitting `select`.
+ */
 export interface MenubarSubTriggerProps extends MenuSubTriggerProps {}
 </script>
 
diff --git a/vue/primitives/src/menubar/MenubarTrigger.vue b/vue/primitives/src/menubar/MenubarTrigger.vue
index 732b2de..dc9e19d 100644
--- a/vue/primitives/src/menubar/MenubarTrigger.vue
+++ b/vue/primitives/src/menubar/MenubarTrigger.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The button in the menubar that opens its menu and anchors the content.
+ * Toggles on click, opens on Enter / Space / ArrowDown / ArrowUp, and — once any
+ * menu is open — switches to this menu on hover. Arrow keys, Home/End, and
+ * typeahead move focus between sibling triggers.
+ */
 export interface MenubarTriggerProps extends PrimitiveProps {
   disabled?: boolean;
 }
diff --git a/vue/primitives/src/menubar/demo.vue b/vue/primitives/src/menubar/demo.vue
new file mode 100644
index 0000000..3541812
--- /dev/null
+++ b/vue/primitives/src/menubar/demo.vue
@@ -0,0 +1,162 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  MenubarCheckboxItem,
+  MenubarContent,
+  MenubarItem,
+  MenubarItemIndicator,
+  MenubarLabel,
+  MenubarMenu,
+  MenubarPortal,
+  MenubarRadioGroup,
+  MenubarRadioItem,
+  MenubarRoot,
+  MenubarSeparator,
+  MenubarSub,
+  MenubarSubContent,
+  MenubarSubTrigger,
+  MenubarTrigger,
+} from '@robonen/primitives';
+
+const active = ref<string>();
+const showStatusBar = ref(true);
+const showMinimap = ref(false);
+const layout = ref('comfortable');
+const lastAction = ref('');
+
+const triggerClass = 'rounded-md px-3 py-1.5 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-(--accent) data-[state=open]:text-(--accent-fg)';
+const contentClass = 'z-50 min-w-52 rounded-lg border border-(--border) bg-(--bg-elevated) p-1 shadow-lg';
+const itemClass = 'flex cursor-default select-none items-center justify-between gap-4 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} relative pl-7`;
+const labelClass = 'px-2 py-1.5 text-xs font-medium text-(--fg-subtle)';
+const shortcutClass = 'text-xs text-(--fg-muted) group-data-[highlighted]:text-(--accent-fg)';
+
+function run(action: string) {
+  lastAction.value = action;
+}
+</script>
+
+<template>
+  <div class="flex flex-col items-start gap-3 text-(--fg)">
+    <MenubarRoot
+      v-model="active"
+      class="flex items-center gap-1 rounded-lg border border-(--border) bg-(--bg) p-1"
+    >
+      <MenubarMenu value="file">
+        <MenubarTrigger :class="triggerClass">
+          File
+        </MenubarTrigger>
+        <MenubarPortal>
+          <MenubarContent :side-offset="6" :class="contentClass">
+            <MenubarItem class="group" :class="itemClass" @select="run('New File')">
+              New file <span :class="shortcutClass">Cmd N</span>
+            </MenubarItem>
+            <MenubarItem class="group" :class="itemClass" @select="run('Open')">
+              Open... <span :class="shortcutClass">Cmd O</span>
+            </MenubarItem>
+
+            <MenubarSub>
+              <MenubarSubTrigger class="group" :class="itemClass">
+                Share
+                <span class="i-carbon-chevron-right text-(--fg-muted) group-data-[highlighted]:text-(--accent-fg)" aria-hidden="true" />
+              </MenubarSubTrigger>
+              <MenubarPortal>
+                <MenubarSubContent :class="contentClass">
+                  <MenubarItem :class="itemClass" @select="run('Copy link')">
+                    Copy link
+                  </MenubarItem>
+                  <MenubarItem :class="itemClass" @select="run('Email')">
+                    Email
+                  </MenubarItem>
+                </MenubarSubContent>
+              </MenubarPortal>
+            </MenubarSub>
+
+            <MenubarSeparator class="my-1 h-px bg-(--border)" />
+
+            <MenubarItem class="group" :class="itemClass" @select="run('Save')">
+              Save <span :class="shortcutClass">Cmd S</span>
+            </MenubarItem>
+          </MenubarContent>
+        </MenubarPortal>
+      </MenubarMenu>
+
+      <MenubarMenu value="edit">
+        <MenubarTrigger :class="triggerClass">
+          Edit
+        </MenubarTrigger>
+        <MenubarPortal>
+          <MenubarContent :side-offset="6" :class="contentClass">
+            <MenubarItem class="group" :class="itemClass" @select="run('Undo')">
+              Undo <span :class="shortcutClass">Cmd Z</span>
+            </MenubarItem>
+            <MenubarItem class="group" :class="itemClass" disabled>
+              Redo <span :class="shortcutClass">Cmd Shift Z</span>
+            </MenubarItem>
+            <MenubarSeparator class="my-1 h-px bg-(--border)" />
+            <MenubarItem :class="itemClass" @select="run('Cut')">
+              Cut
+            </MenubarItem>
+            <MenubarItem :class="itemClass" @select="run('Copy')">
+              Copy
+            </MenubarItem>
+            <MenubarItem :class="itemClass" @select="run('Paste')">
+              Paste
+            </MenubarItem>
+          </MenubarContent>
+        </MenubarPortal>
+      </MenubarMenu>
+
+      <MenubarMenu value="view">
+        <MenubarTrigger :class="triggerClass">
+          View
+        </MenubarTrigger>
+        <MenubarPortal>
+          <MenubarContent :side-offset="6" :class="contentClass">
+            <MenubarCheckboxItem v-model:checked="showStatusBar" :class="checkItemClass">
+              <MenubarItemIndicator class="absolute left-1.5 inline-flex">
+                <span class="i-carbon-checkmark text-(--accent)" aria-hidden="true" />
+              </MenubarItemIndicator>
+              Status bar
+            </MenubarCheckboxItem>
+            <MenubarCheckboxItem v-model:checked="showMinimap" :class="checkItemClass">
+              <MenubarItemIndicator class="absolute left-1.5 inline-flex">
+                <span class="i-carbon-checkmark text-(--accent)" aria-hidden="true" />
+              </MenubarItemIndicator>
+              Minimap
+            </MenubarCheckboxItem>
+
+            <MenubarSeparator class="my-1 h-px bg-(--border)" />
+            <MenubarLabel :class="labelClass">
+              Layout
+            </MenubarLabel>
+
+            <MenubarRadioGroup v-model="layout">
+              <MenubarRadioItem value="compact" :class="checkItemClass">
+                <MenubarItemIndicator class="absolute left-1.5 inline-flex">
+                  <span class="i-carbon-dot-mark text-(--accent)" aria-hidden="true" />
+                </MenubarItemIndicator>
+                Compact
+              </MenubarRadioItem>
+              <MenubarRadioItem value="comfortable" :class="checkItemClass">
+                <MenubarItemIndicator class="absolute left-1.5 inline-flex">
+                  <span class="i-carbon-dot-mark text-(--accent)" aria-hidden="true" />
+                </MenubarItemIndicator>
+                Comfortable
+              </MenubarRadioItem>
+            </MenubarRadioGroup>
+          </MenubarContent>
+        </MenubarPortal>
+      </MenubarMenu>
+    </MenubarRoot>
+
+    <p class="text-xs text-(--fg-muted)">
+      Status bar: <span class="font-medium text-(--fg)">{{ showStatusBar ? 'on' : 'off' }}</span>
+      &middot; Minimap: <span class="font-medium text-(--fg)">{{ showMinimap ? 'on' : 'off' }}</span>
+      &middot; Layout: <span class="font-medium text-(--fg)">{{ layout }}</span>
+      <template v-if="lastAction">
+        &middot; Last action: <span class="font-medium text-(--fg)">{{ lastAction }}</span>
+      </template>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/menubar/index.ts b/vue/primitives/src/menubar/index.ts
index 490f39e..b409fbb 100644
--- a/vue/primitives/src/menubar/index.ts
+++ b/vue/primitives/src/menubar/index.ts
@@ -1,5 +1,5 @@
 export { default as MenubarRoot } from './MenubarRoot.vue';
-export type { MenubarRootProps, MenubarRootEmits } from './MenubarRoot.vue';
+export type { MenubarRootProps } from './MenubarRoot.vue';
 
 export { default as MenubarMenu } from './MenubarMenu.vue';
 export type { MenubarMenuProps } from './MenubarMenu.vue';
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuContent.vue b/vue/primitives/src/navigation-menu/NavigationMenuContent.vue
index 708ccf2..ec48fda 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuContent.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuContent.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { NavigationMenuContentImplEmits, NavigationMenuContentImplProps } from './NavigationMenuContentImpl.vue';
 
+/**
+ * The panel revealed when its item's trigger is active. Handles mount/unmount via
+ * `Presence`, teleports into the shared `NavigationMenuViewport` when one is present
+ * (otherwise renders inline), and keeps content alive briefly during viewport
+ * transitions. Place one per `NavigationMenuItem` that has a trigger.
+ */
 export interface NavigationMenuContentProps extends NavigationMenuContentImplProps {
   /** Keep mounted regardless of `present`. Useful for transition libraries. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuContentImpl.vue b/vue/primitives/src/navigation-menu/NavigationMenuContentImpl.vue
index f46cb91..6a160cf 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuContentImpl.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuContentImpl.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { DismissableLayerEmits, DismissableLayerProps } from '../dismissable-layer';
 
+/**
+ * Internal rendering body for `NavigationMenuContent`. Wraps the panel in a
+ * `FocusScope` and `DismissableLayer`, implementing arrow-key/Tab navigation between
+ * links, escape-to-dismiss, outside-interaction handling, and the `data-motion`
+ * transition attribute. Not part of the public anatomy; use `NavigationMenuContent`.
+ */
 export interface NavigationMenuContentImplProps extends DismissableLayerProps {}
 
 export type NavigationMenuContentImplEmits = DismissableLayerEmits & {
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuIndicator.vue b/vue/primitives/src/navigation-menu/NavigationMenuIndicator.vue
index e982065..86c57a0 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuIndicator.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuIndicator.vue
@@ -1,4 +1,9 @@
 <script lang="ts">
+/**
+ * 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 {
   forceMount?: boolean;
 }
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuItem.vue b/vue/primitives/src/navigation-menu/NavigationMenuItem.vue
index 9326998..d3ba217 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuItem.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuItem.vue
@@ -1,4 +1,9 @@
 <script lang="ts">
+/**
+ * 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 {
   /**
    * Unique value associating this item with the active state. Generated
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuLink.vue b/vue/primitives/src/navigation-menu/NavigationMenuLink.vue
index 96c641d..5c27247 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuLink.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuLink.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A navigable link, rendered as an `<a>` by default, usable as a top-level menu item
+ * or inside a content panel. Selecting it dismisses the open menu (unless the `select`
+ * event is prevented) and marks itself with `aria-current` when `active`.
+ */
 export interface NavigationMenuLinkProps extends PrimitiveProps {
   /** Marks the link as active for styling and aria-current. */
   active?: boolean;
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuList.vue b/vue/primitives/src/navigation-menu/NavigationMenuList.vue
index 381d372..ebf0ea4 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuList.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuList.vue
@@ -1,4 +1,10 @@
 <script lang="ts">
+/**
+ * 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
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuRoot.vue b/vue/primitives/src/navigation-menu/NavigationMenuRoot.vue
index c4f56b4..724ca1e 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuRoot.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuRoot.vue
@@ -2,6 +2,14 @@
 import type { Direction } from '../config-provider';
 import type { Orientation } from '../roving-focus';
 
+/**
+ * A collection of navigation links and disclosure menus, typically used for the
+ * primary site header. `NavigationMenuRoot` owns the open state and hover/click
+ * timing for the whole menu, rendering as a `<nav>` landmark and providing context
+ * to every list, item, trigger, content, viewport, and indicator beneath it. Reach
+ * for it over a generic dropdown when you need keyboard-accessible, animatable
+ * mega-menu panels that share a single active state.
+ */
 export interface NavigationMenuRootProps {
   /** Uncontrolled initial value. */
   defaultValue?: string;
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuSub.vue b/vue/primitives/src/navigation-menu/NavigationMenuSub.vue
index 29ded50..0b59360 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuSub.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuSub.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { Orientation } from '../roving-focus';
 
+/**
+ * Nests a second navigation menu inside a `NavigationMenuContent` panel, with its
+ * own independent active value while inheriting the parent's timing and direction.
+ * Use it to build multi-level menus where a content panel itself contains a list of
+ * triggers and sub-panels.
+ */
 export interface NavigationMenuSubProps {
   /** Uncontrolled initial value. */
   defaultValue?: string;
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuTrigger.vue b/vue/primitives/src/navigation-menu/NavigationMenuTrigger.vue
index 0bd716c..bfaaaa1 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuTrigger.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuTrigger.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { ComponentPublicInstance } from 'vue';
 
+/**
+ * The button that opens its item's `NavigationMenuContent` on hover, click, or keyboard.
+ * Reflects open state via `data-state` and `aria-expanded`, and manages the hover/click
+ * 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 {
   /** Disables interaction with this trigger. */
   disabled?: boolean;
diff --git a/vue/primitives/src/navigation-menu/NavigationMenuViewport.vue b/vue/primitives/src/navigation-menu/NavigationMenuViewport.vue
index 6d674ac..9eb4cd2 100644
--- a/vue/primitives/src/navigation-menu/NavigationMenuViewport.vue
+++ b/vue/primitives/src/navigation-menu/NavigationMenuViewport.vue
@@ -1,4 +1,10 @@
 <script lang="ts">
+/**
+ * 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 {
   /** Keep mounted regardless of open state. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/navigation-menu/demo.vue b/vue/primitives/src/navigation-menu/demo.vue
new file mode 100644
index 0000000..a1e4205
--- /dev/null
+++ b/vue/primitives/src/navigation-menu/demo.vue
@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  NavigationMenuContent,
+  NavigationMenuIndicator,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuRoot,
+  NavigationMenuTrigger,
+  NavigationMenuViewport,
+} from '@robonen/primitives';
+
+const value = ref('');
+
+const products = [
+  { title: 'Analytics', desc: 'Real-time dashboards for every metric.', icon: 'i-carbon-chart-line' },
+  { title: 'Automation', desc: 'Workflows that run themselves.', icon: 'i-carbon-flow' },
+  { title: 'Reports', desc: 'Share insights with your team.', icon: 'i-carbon-document' },
+  { title: 'Integrations', desc: 'Connect the tools you already use.', icon: 'i-carbon-plug' },
+];
+
+const resources = [
+  { title: 'Documentation', desc: 'Guides and API reference.' },
+  { title: 'Changelog', desc: 'What shipped this week.' },
+  { 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)';
+</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"
+  >
+    <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"
+            aria-hidden="true"
+          />
+        </NavigationMenuTrigger>
+        <NavigationMenuContent
+          class="grid w-[28rem] grid-cols-2 gap-1 p-3 outline-none data-[motion=from-start]:animate-in data-[motion=from-end]:animate-in"
+        >
+          <NavigationMenuLink
+            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)"
+          >
+            <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>
+          </NavigationMenuLink>
+        </NavigationMenuContent>
+      </NavigationMenuItem>
+
+      <NavigationMenuItem value="resources">
+        <NavigationMenuTrigger :class="triggerClass">
+          Resources
+          <span
+            class="i-carbon-chevron-down text-(--fg-muted) transition-transform duration-200 group-data-[state=open]:rotate-180"
+            aria-hidden="true"
+          />
+        </NavigationMenuTrigger>
+        <NavigationMenuContent class="flex w-64 flex-col gap-1 p-3 outline-none">
+          <NavigationMenuLink
+            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)"
+          >
+            <span class="text-sm font-medium text-(--fg)">{{ item.title }}</span>
+            <span class="text-xs text-(--fg-muted)">{{ item.desc }}</span>
+          </NavigationMenuLink>
+        </NavigationMenuContent>
+      </NavigationMenuItem>
+
+      <NavigationMenuItem value="pricing">
+        <NavigationMenuLink href="#" active :class="linkClass">
+          Pricing
+        </NavigationMenuLink>
+      </NavigationMenuItem>
+
+      <NavigationMenuIndicator
+        class="absolute top-full left-0 z-10 flex h-2 items-end justify-center overflow-hidden transition-[width,transform] duration-200 data-[state=hidden]:opacity-0 data-[state=visible]:opacity-100"
+        :style="{
+          width: 'var(--primitives-navigation-menu-indicator-size)',
+          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)" />
+      </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"
+      :style="{
+        left: 'var(--primitives-navigation-menu-viewport-left)',
+        top: 'var(--primitives-navigation-menu-viewport-top)',
+        width: 'var(--primitives-navigation-menu-viewport-width)',
+        height: 'var(--primitives-navigation-menu-viewport-height)',
+      }"
+    />
+  </NavigationMenuRoot>
+</template>
diff --git a/vue/primitives/src/number-field/NumberFieldDecrement.vue b/vue/primitives/src/number-field/NumberFieldDecrement.vue
index fa7e10f..2bbf4ad 100644
--- a/vue/primitives/src/number-field/NumberFieldDecrement.vue
+++ b/vue/primitives/src/number-field/NumberFieldDecrement.vue
@@ -1,5 +1,12 @@
 <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>
 
diff --git a/vue/primitives/src/number-field/NumberFieldIncrement.vue b/vue/primitives/src/number-field/NumberFieldIncrement.vue
index 6bca85d..c656ffb 100644
--- a/vue/primitives/src/number-field/NumberFieldIncrement.vue
+++ b/vue/primitives/src/number-field/NumberFieldIncrement.vue
@@ -1,5 +1,12 @@
 <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>
 
diff --git a/vue/primitives/src/number-field/NumberFieldInput.vue b/vue/primitives/src/number-field/NumberFieldInput.vue
index 8a80e45..b09b999 100644
--- a/vue/primitives/src/number-field/NumberFieldInput.vue
+++ b/vue/primitives/src/number-field/NumberFieldInput.vue
@@ -1,5 +1,12 @@
 <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;
diff --git a/vue/primitives/src/number-field/NumberFieldRoot.vue b/vue/primitives/src/number-field/NumberFieldRoot.vue
index a598fc5..f5a5e0b 100644
--- a/vue/primitives/src/number-field/NumberFieldRoot.vue
+++ b/vue/primitives/src/number-field/NumberFieldRoot.vue
@@ -1,7 +1,15 @@
 <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 {
-  modelValue?: number | null;
   defaultValue?: number | null;
   min?: number;
   max?: number;
@@ -12,7 +20,6 @@ export interface NumberFieldRootProps extends PrimitiveProps {
 }
 
 export interface NumberFieldRootEmits {
-  'update:modelValue': [value: number | null];
   valueChange: [value: number | null];
 }
 </script>
@@ -25,17 +32,23 @@ import { useForwardExpose } from '@robonen/vue';
 import { clamp } from '@robonen/stdlib';
 import { useId } from '../config-provider';
 
-const { step = 1, disabled = false, readonly = false, min, max, modelValue, defaultValue, as = 'div' } = defineProps<NumberFieldRootProps>();
+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>(
-  modelValue !== undefined ? modelValue : (defaultValue ?? null),
+  model.value !== undefined ? model.value : (defaultValue ?? null),
 );
 
-watch(() => modelValue, (v) => {
+watch(model, (v) => {
   if (v === undefined) return;
   if (v === localValue.value) return;
   localValue.value = v;
@@ -46,7 +59,8 @@ function setValue(v: number | null): void {
   const next = v === null ? null : clamp(v, min ?? -Infinity, max ?? Infinity);
   if (next === localValue.value) return;
   localValue.value = next;
-  emit('update:modelValue', next);
+  // `defineModel` emits `update:modelValue` on write — no manual emit needed.
+  model.value = next;
   emit('valueChange', next);
 }
 
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/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-ArrowUp---ArrowDown-step--clamped-by-min-max-1.png
new file mode 100644
index 0000000..bd43ea0
Binary files /dev/null and b/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-ArrowUp---ArrowDown-step--clamped-by-min-max-1.png differ
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/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-Home-End-jump-to-min-max-when-defined-1.png
new file mode 100644
index 0000000..ee5236a
Binary files /dev/null and b/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-Home-End-jump-to-min-max-when-defined-1.png differ
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/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-PageUp-PageDown-step-by-10--1.png
new file mode 100644
index 0000000..c3b6d70
Binary files /dev/null and b/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-PageUp-PageDown-step-by-10--1.png differ
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/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-typing-updates-value--invalid---null-1.png
new file mode 100644
index 0000000..08cf08b
Binary files /dev/null and b/vue/primitives/src/number-field/__test__/__screenshots__/NumberField.test.ts/NumberField-typing-updates-value--invalid---null-1.png differ
diff --git a/vue/primitives/src/number-field/demo.vue b/vue/primitives/src/number-field/demo.vue
new file mode 100644
index 0000000..e407470
--- /dev/null
+++ b/vue/primitives/src/number-field/demo.vue
@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import { NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput, NumberFieldRoot } from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+const UNIT_PRICE = 12;
+const MAX = 10;
+
+const quantity = ref<number | null>(2);
+
+const total = computed(() => (quantity.value ?? 0) * UNIT_PRICE);
+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-1">
+      <span class="text-sm font-semibold">Espresso blend</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>
+
+      <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"
+      >
+        <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"
+        >
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+            <path d="M3 7h8" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+          </svg>
+        </NumberFieldDecrement>
+
+        <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"
+        />
+
+        <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"
+        >
+          <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" />
+          </svg>
+        </NumberFieldIncrement>
+      </NumberFieldRoot>
+    </label>
+
+    <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)'"
+    >
+      {{ atMax ? `Maximum of ${MAX} bags per order` : 'Use the arrow keys or buttons to adjust' }}
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/pagination/PaginationEllipsis.vue b/vue/primitives/src/pagination/PaginationEllipsis.vue
index d131ff9..a89f754 100644
--- a/vue/primitives/src/pagination/PaginationEllipsis.vue
+++ b/vue/primitives/src/pagination/PaginationEllipsis.vue
@@ -1,11 +1,16 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A non-interactive placeholder shown where page links are collapsed into a
+ * gap. Render one for each ellipsis entry in the list's `items`; defaults to an
+ * ellipsis character but accepts custom content via the default slot.
+ */
 export interface PaginationEllipsisProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '@/primitive';
+import { Primitive } from '../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/pagination/PaginationFirst.vue
index 888defe..133a6b3 100644
--- a/vue/primitives/src/pagination/PaginationFirst.vue
+++ b/vue/primitives/src/pagination/PaginationFirst.vue
@@ -1,11 +1,16 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that jumps to the first page. Renders as a `<button>`, is
+ * automatically disabled when already on the first page (or the pagination is
+ * disabled), and is labelled "First Page" for assistive technology.
+ */
 export interface PaginationFirstProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '@/primitive';
+import { Primitive } from '../primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
diff --git a/vue/primitives/src/pagination/PaginationLast.vue b/vue/primitives/src/pagination/PaginationLast.vue
index f74324a..78dfeeb 100644
--- a/vue/primitives/src/pagination/PaginationLast.vue
+++ b/vue/primitives/src/pagination/PaginationLast.vue
@@ -1,11 +1,16 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that jumps to the last page. Renders as a `<button>`, is
+ * automatically disabled when already on the last page (or the pagination is
+ * disabled), and is labelled "Last Page" for assistive technology.
+ */
 export interface PaginationLastProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '@/primitive';
+import { Primitive } from '../primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
diff --git a/vue/primitives/src/pagination/PaginationList.vue b/vue/primitives/src/pagination/PaginationList.vue
index 5878bdb..a94a1b8 100644
--- a/vue/primitives/src/pagination/PaginationList.vue
+++ b/vue/primitives/src/pagination/PaginationList.vue
@@ -1,12 +1,18 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The container that computes the visible page sequence (page numbers and
+ * ellipsis placeholders) from the root context. Its default slot exposes the
+ * resolved `items` array so you can render a `PaginationListItem` per page and
+ * a `PaginationEllipsis` per gap.
+ */
 export interface PaginationListProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
 import type { PaginationItem } from './utils';
-import { Primitive } from '@/primitive';
+import { Primitive } from '../primitive';
 import { computed } from 'vue';
 import { getRange } from './utils';
 import { injectPaginationContext } from './context';
diff --git a/vue/primitives/src/pagination/PaginationListItem.vue b/vue/primitives/src/pagination/PaginationListItem.vue
index 9333373..fbb46d8 100644
--- a/vue/primitives/src/pagination/PaginationListItem.vue
+++ b/vue/primitives/src/pagination/PaginationListItem.vue
@@ -1,13 +1,19 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A single page link. Renders as a `<button>` that selects its `value` page on
+ * click, marks itself with `aria-current="page"` and `data-selected` when it is
+ * the current page, and is disabled while the pagination is disabled.
+ */
 export interface PaginationListItemProps extends PrimitiveProps {
+  /** The page number this item navigates to. */
   value: number;
 }
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '@/primitive';
+import { Primitive } from '../primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
diff --git a/vue/primitives/src/pagination/PaginationNext.vue b/vue/primitives/src/pagination/PaginationNext.vue
index 6f4c438..8d056df 100644
--- a/vue/primitives/src/pagination/PaginationNext.vue
+++ b/vue/primitives/src/pagination/PaginationNext.vue
@@ -1,11 +1,16 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that moves to the next page. Renders as a `<button>`, is
+ * automatically disabled on the last page (or while the pagination is
+ * disabled), and is labelled "Next Page" for assistive technology.
+ */
 export interface PaginationNextProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '@/primitive';
+import { Primitive } from '../primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
diff --git a/vue/primitives/src/pagination/PaginationPrev.vue b/vue/primitives/src/pagination/PaginationPrev.vue
index 87b4082..7a0d2d2 100644
--- a/vue/primitives/src/pagination/PaginationPrev.vue
+++ b/vue/primitives/src/pagination/PaginationPrev.vue
@@ -1,11 +1,16 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that moves to the previous page. Renders as a `<button>`, is
+ * automatically disabled on the first page (or while the pagination is
+ * disabled), and is labelled "Previous Page" for assistive technology.
+ */
 export interface PaginationPrevProps extends PrimitiveProps {}
 </script>
 
 <script setup lang="ts">
-import { Primitive } from '@/primitive';
+import { Primitive } from '../primitive';
 import { computed } from 'vue';
 import { injectPaginationContext } from './context';
 import { useForwardExpose } from '@robonen/vue';
diff --git a/vue/primitives/src/pagination/PaginationRoot.vue b/vue/primitives/src/pagination/PaginationRoot.vue
index 36feb45..f17a7f6 100644
--- a/vue/primitives/src/pagination/PaginationRoot.vue
+++ b/vue/primitives/src/pagination/PaginationRoot.vue
@@ -1,19 +1,42 @@
 <script lang="ts">
-import type { PrimitiveProps } from '@/primitive';
+import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Splits a large collection into discrete pages and lets users move between
+ * them. Use it for paged tables, search results, or any list too long to show
+ * at once — pair it with server- or client-side data fetching keyed off the
+ * current page.
+ *
+ * The root owns the current page (controlled via `v-model:page` or uncontrolled
+ * via `defaultPage`), derives the total page count from `total` and `pageSize`,
+ * and provides context to every child part (list, items, ellipsis, and the
+ * first/prev/next/last controls). The default slot exposes `page` and
+ * `pageCount`.
+ */
 export interface PaginationRootProps extends PrimitiveProps {
+  /** Total number of items across all pages. */
   total: number;
+
+  /** Number of items per page; combined with `total` to derive the page count. @default 10 */
   pageSize?: number;
+
+  /** Number of page links to show on each side of the current page. @default 1 */
   siblingCount?: number;
+
+  /** Always render the first and last page links, even when ellipses are shown. @default false */
   showEdges?: boolean;
+
+  /** Disable the whole pagination, including every control. @default false */
   disabled?: boolean;
+
+  /** Initial page for uncontrolled usage (when `v-model:page` is not bound). @default 1 */
   defaultPage?: number;
 }
 </script>
 
 <script setup lang="ts">
 import { useForwardExpose, useOffsetPagination } from '@robonen/vue';
-import { Primitive } from '@/primitive';
+import { Primitive } from '../primitive';
 import { providePaginationContext } from './context';
 import { toRef } from 'vue';
 
diff --git a/vue/primitives/src/pagination/demo.vue b/vue/primitives/src/pagination/demo.vue
new file mode 100644
index 0000000..7ecc4af
--- /dev/null
+++ b/vue/primitives/src/pagination/demo.vue
@@ -0,0 +1,104 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import {
+  PaginationEllipsis,
+  PaginationFirst,
+  PaginationLast,
+  PaginationList,
+  PaginationListItem,
+  PaginationNext,
+  PaginationPrev,
+  PaginationRoot,
+} from '@robonen/primitives';
+
+const total = 96;
+const pageSize = 10;
+const page = ref(3);
+
+const range = computed(() => {
+  const start = (page.value - 1) * pageSize + 1;
+  const end = Math.min(page.value * pageSize, total);
+  return { start, end };
+});
+</script>
+
+<template>
+  <PaginationRoot
+    v-slot="{ pageCount }"
+    v-model:page="page"
+    :total="total"
+    :page-size="pageSize"
+    :sibling-count="1"
+    show-edges
+    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>
+
+    <PaginationList
+      v-slot="{ items }"
+      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"
+        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">
+          <polyline points="11 17 6 12 11 7" />
+          <polyline points="18 17 13 12 18 7" />
+        </svg>
+      </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"
+        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">
+          <polyline points="15 18 9 12 15 6" />
+        </svg>
+      </PaginationPrev>
+
+      <template
+        v-for="(item, index) in items"
+        :key="index"
+      >
+        <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)"
+        >
+          {{ item.value }}
+        </PaginationListItem>
+        <PaginationEllipsis
+          v-else
+          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"
+        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">
+          <polyline points="9 18 15 12 9 6" />
+        </svg>
+      </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"
+        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">
+          <polyline points="13 17 18 12 13 7" />
+          <polyline points="6 17 11 12 6 7" />
+        </svg>
+      </PaginationLast>
+    </PaginationList>
+
+    <p class="text-xs text-(--fg-subtle)">
+      Page {{ page }} of {{ pageCount }}
+    </p>
+  </PaginationRoot>
+</template>
diff --git a/vue/primitives/src/pin-input/PinInputInput.vue b/vue/primitives/src/pin-input/PinInputInput.vue
index 814d8a5..5957f2e 100644
--- a/vue/primitives/src/pin-input/PinInputInput.vue
+++ b/vue/primitives/src/pin-input/PinInputInput.vue
@@ -1,17 +1,24 @@
 <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';
 
-interface Props {
-  index: number;
-}
-
-const props = defineProps<Props>();
+const props = defineProps<PinInputInputProps>();
 const ctx = usePinInputContext();
 const el = useTemplateRef<HTMLInputElement>('el');
 
diff --git a/vue/primitives/src/pin-input/PinInputRoot.vue b/vue/primitives/src/pin-input/PinInputRoot.vue
index bdf54b2..bcbebe8 100644
--- a/vue/primitives/src/pin-input/PinInputRoot.vue
+++ b/vue/primitives/src/pin-input/PinInputRoot.vue
@@ -1,12 +1,17 @@
-<script setup lang="ts">
+<script lang="ts">
 import type { PrimitiveProps } from '../primitive';
-import { Primitive } from '../primitive';
-import { computed, ref, toRef, watch } from 'vue';
-import { providePinInputContext } from './context';
-import { useForwardExpose } from '@robonen/vue';
 
-interface Props extends PrimitiveProps {
-  modelValue?: string[];
+/**
+ * A segmented input for short codes — OTP / one-time passwords, 2FA tokens, or
+ * PINs split across one box per character. The interactive root: it owns the
+ * value as a per-cell `string[]` (controlled via `v-model` / `update:modelValue`
+ * or uncontrolled via `defaultValue`), sizes the field to `length`, enforces the
+ * `type` ('text' | 'number') and `mask`, and provides context to each
+ * `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.
+ */
+export interface PinInputRootProps extends PrimitiveProps {
   defaultValue?: string[];
   length?: number;
   mask?: boolean;
@@ -16,9 +21,15 @@ interface Props extends PrimitiveProps {
   placeholder?: string;
 
 }
+</script>
+
+<script setup lang="ts">
+import { Primitive } from '../primitive';
+import { computed, ref, toRef, watch } from 'vue';
+import { providePinInputContext } from './context';
+import { useForwardExpose } from '@robonen/vue';
 
 const {
-  modelValue,
   defaultValue,
   length = 4,
   mask = false,
@@ -27,13 +38,12 @@ const {
   disabled = false,
   placeholder = '',
   as = 'div',
-} = defineProps<Props>();
+} = defineProps<PinInputRootProps>();
 
 const { forwardRef } = useForwardExpose();
 
 const emit = defineEmits<{
-  (e: 'update:modelValue', v: string[]): void;
-  (e: 'complete', v: string): void;
+  complete: [value: string];
 }>();
 
 const lengthRef = computed(() => Math.max(1, length | 0));
@@ -47,9 +57,17 @@ function normalize(v: readonly string[] | undefined): string[] {
   return out;
 }
 
-const value = ref<string[]>(normalize(modelValue ?? defaultValue));
+// `defineModel` owns the `modelValue` prop in both modes: controlled (parent
+// `v-model`) and uncontrolled (its own internal store). Writing `model.value`
+// emits `update:modelValue`, so no manual emit is needed. `value` is the
+// normalized, per-cell `string[]` source of truth read by the inputs — kept as
+// a local ref so synchronous bursts (e.g. paste) always read the latest write
+// rather than a not-yet-propagated controlled prop.
+const model = defineModel<string[]>();
 
-watch(() => modelValue, (v) => {
+const value = ref<string[]>(normalize(model.value ?? defaultValue));
+
+watch(model, (v) => {
   if (v === undefined)
     return;
   const nv = normalize(v);
@@ -78,8 +96,11 @@ function unregister(el: HTMLInputElement): void {
     inputs.value.splice(i, 1);
 }
 
-function emitValue(v: string[]): void {
-  emit('update:modelValue', v);
+function commit(v: string[]): void {
+  // `value` is the synchronous source of truth; `model.value` mirrors it and,
+  // via `defineModel`, emits `update:modelValue`. No manual emit needed.
+  value.value = v;
+  model.value = v;
   if (v.every(ch => ch.length === 1))
     emit('complete', v.join(''));
 }
@@ -92,8 +113,7 @@ function setAt(index: number, char: string): void {
     return;
   const next = value.value.slice();
   next[index] = ch;
-  value.value = next;
-  emitValue(next);
+  commit(next);
 }
 
 function clearAt(index: number): void {
@@ -101,8 +121,7 @@ function clearAt(index: number): void {
     return;
   const next = value.value.slice();
   next[index] = '';
-  value.value = next;
-  emitValue(next);
+  commit(next);
 }
 
 function focusIndex(index: number): void {
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/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-Backspace-on-empty-moves-to-previous-and-clears-1.png
new file mode 100644
index 0000000..6e59a3c
Binary files /dev/null and b/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-Backspace-on-empty-moves-to-previous-and-clears-1.png differ
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/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-mask-renders-password-type-for-each-input-1.png
new file mode 100644
index 0000000..43be2ab
Binary files /dev/null and b/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-mask-renders-password-type-for-each-input-1.png differ
diff --git a/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-paste-fills-across-inputs-1.png b/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-paste-fills-across-inputs-1.png
new file mode 100644
index 0000000..2bc5cbf
Binary files /dev/null and b/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-paste-fills-across-inputs-1.png differ
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/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-type-number-rejects-non-digit-input-1.png
new file mode 100644
index 0000000..1d7df86
Binary files /dev/null and b/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-type-number-rejects-non-digit-input-1.png differ
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/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-typing-auto-advances-focus-and-fires-complete-1.png
new file mode 100644
index 0000000..4be90f7
Binary files /dev/null and b/vue/primitives/src/pin-input/__test__/__screenshots__/PinInput.test.ts/PinInput-typing-auto-advances-focus-and-fires-complete-1.png differ
diff --git a/vue/primitives/src/pin-input/demo.vue b/vue/primitives/src/pin-input/demo.vue
new file mode 100644
index 0000000..b6c905b
--- /dev/null
+++ b/vue/primitives/src/pin-input/demo.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import { PinInputInput, PinInputRoot } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const LENGTH = 6;
+
+const code = ref<string[]>([]);
+const status = ref<'idle' | 'verifying' | 'ok' | 'error'>('idle');
+
+function onComplete(value: string) {
+  status.value = 'verifying';
+  // Pretend to call an API; "123456" is the happy path.
+  window.setTimeout(() => {
+    status.value = value === '123456' ? 'ok' : 'error';
+  }, 600);
+}
+
+function reset() {
+  code.value = [];
+  status.value = 'idle';
+}
+</script>
+
+<template>
+  <div class="w-full max-w-sm rounded-xl border border-(--border) bg-(--bg-elevated) p-6 text-(--fg)">
+    <h3 class="text-base font-semibold">
+      Verify your email
+    </h3>
+    <p class="mt-1 text-sm text-(--fg-muted)">
+      Enter the 6-digit code we sent to your inbox.
+    </p>
+
+    <PinInputRoot
+      v-slot="{ isComplete }"
+      v-model="code"
+      :length="LENGTH"
+      type="number"
+      otp
+      :disabled="status === 'verifying' || status === 'ok'"
+      class="mt-5 flex items-center gap-2 data-[disabled]:opacity-60"
+      @complete="onComplete"
+    >
+      <PinInputInput
+        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="status === 'error'
+          ? 'border-red-500 dark:border-red-400'
+          : isComplete && status === 'ok'
+            ? 'border-emerald-500 dark:border-emerald-400'
+            : 'border-(--border)'"
+      />
+    </PinInputRoot>
+
+    <div class="mt-4 flex min-h-5 items-center justify-between text-sm">
+      <p
+        class="font-medium"
+        :class="{
+          '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',
+        }"
+      >
+        <span v-if="status === 'verifying'">Verifying…</span>
+        <span v-else-if="status === 'ok'">Code accepted</span>
+        <span v-else-if="status === 'error'">Invalid code — try again</span>
+        <span v-else>Tip: try 123456</span>
+      </p>
+
+      <button
+        type="button"
+        class="rounded-md px-2 py-1 text-sm text-(--accent) transition-colors hover:bg-(--bg-inset)"
+        @click="reset"
+      >
+        Reset
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/pin-input/index.ts b/vue/primitives/src/pin-input/index.ts
index 51f8601..f99d4ab 100644
--- a/vue/primitives/src/pin-input/index.ts
+++ b/vue/primitives/src/pin-input/index.ts
@@ -1,3 +1,5 @@
 export { default as PinInputInput } from './PinInputInput.vue';
 export { default as PinInputRoot } from './PinInputRoot.vue';
+export type { PinInputInputProps } from './PinInputInput.vue';
+export type { PinInputRootProps } from './PinInputRoot.vue';
 export * from './context';
diff --git a/vue/primitives/src/popover/PopoverAnchor.vue b/vue/primitives/src/popover/PopoverAnchor.vue
index 6542f0a..1525f02 100644
--- a/vue/primitives/src/popover/PopoverAnchor.vue
+++ b/vue/primitives/src/popover/PopoverAnchor.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PopperAnchorProps } from '../popper';
 
+/**
+ * An optional alternate element to position Content against. Place it anywhere
+ * inside Root to anchor the popover to something other than the Trigger — the
+ * Trigger then only toggles open state and no longer drives positioning.
+ */
 export interface PopoverAnchorProps extends PopperAnchorProps {}
 </script>
 
diff --git a/vue/primitives/src/popover/PopoverArrow.vue b/vue/primitives/src/popover/PopoverArrow.vue
index 5517e9c..fd95e5f 100644
--- a/vue/primitives/src/popover/PopoverArrow.vue
+++ b/vue/primitives/src/popover/PopoverArrow.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PopperArrowProps } from '../popper';
 
+/**
+ * An optional arrow that points from Content back toward the Trigger or Anchor,
+ * tracking the popover's resolved side and alignment. Place inside Content;
+ * pass custom SVG via the default slot to match your panel's styling.
+ */
 export interface PopoverArrowProps extends PopperArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/popover/PopoverClose.vue b/vue/primitives/src/popover/PopoverClose.vue
index 2d2d564..558c4ec 100644
--- a/vue/primitives/src/popover/PopoverClose.vue
+++ b/vue/primitives/src/popover/PopoverClose.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that closes the popover when activated. Place inside Content for an
+ * explicit dismiss control, such as an "X" in the corner or a "Done" button.
+ */
 export interface PopoverCloseProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/popover/PopoverContent.vue b/vue/primitives/src/popover/PopoverContent.vue
index 2520b54..54f0a5b 100644
--- a/vue/primitives/src/popover/PopoverContent.vue
+++ b/vue/primitives/src/popover/PopoverContent.vue
@@ -1,6 +1,13 @@
 <script lang="ts">
 import type { PopoverContentImplEmits, PopoverContentImplProps } from './PopoverContentImpl.vue';
 
+/**
+ * The floating panel itself — the positioned container for the popover's body.
+ * Renders only while open and picks a modal or non-modal implementation from
+ * the Root's `modal` setting: modal traps focus, locks body scroll, and blocks
+ * outside pointer events; non-modal does none of these. Emits focus and
+ * dismissal events so consumers can guard against closing.
+ */
 export interface PopoverContentProps extends PopoverContentImplProps {
   /** Keep mounted for CSS exit animations. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/popover/PopoverContentImpl.vue b/vue/primitives/src/popover/PopoverContentImpl.vue
index 7912c93..b9c5975 100644
--- a/vue/primitives/src/popover/PopoverContentImpl.vue
+++ b/vue/primitives/src/popover/PopoverContentImpl.vue
@@ -3,6 +3,12 @@ import type { DismissableLayerEmits } from '../dismissable-layer';
 import type { FocusScopeEmits } from '../focus-scope';
 import type { PopperContentProps } from '../popper';
 
+/**
+ * Internal shared implementation behind PopoverContent — wraps a FocusScope, a
+ * DismissableLayer, and a PopperContent and applies the popover ARIA wiring and
+ * `--popover-*` style variables. Not exported; the modal and non-modal Content
+ * variants render this with the appropriate flags.
+ */
 export interface PopoverContentImplProps extends PopperContentProps {
   /** Trap focus inside the content (modal popovers). */
   trapFocus?: boolean;
diff --git a/vue/primitives/src/popover/PopoverPortal.vue b/vue/primitives/src/popover/PopoverPortal.vue
index 2ef8a8e..6e1cfc0 100644
--- a/vue/primitives/src/popover/PopoverPortal.vue
+++ b/vue/primitives/src/popover/PopoverPortal.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { TeleportPrimitiveProps } from '../teleport';
 
+/**
+ * Teleports Content out of the normal DOM flow (by default into `body`) so the
+ * popover renders above the rest of the page and escapes `overflow` and
+ * stacking contexts. Mounts its children only while the popover is open.
+ */
 export interface PopoverPortalProps extends TeleportPrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/popover/PopoverRoot.vue b/vue/primitives/src/popover/PopoverRoot.vue
index ee92449..e735985 100644
--- a/vue/primitives/src/popover/PopoverRoot.vue
+++ b/vue/primitives/src/popover/PopoverRoot.vue
@@ -1,4 +1,17 @@
 <script lang="ts">
+/**
+ * A floating panel anchored to a trigger, used for rich, interactive content
+ * such as forms, settings, or detail cards that can hold focusable elements.
+ * Composed from a Trigger, an optional Anchor, a Portal, and Content (with an
+ * optional Arrow and Close). Positioning is handled by the underlying Popper.
+ *
+ * Root manages the open state and provides context to every part. Bind
+ * `v-model:open` to control it, or rely on the Trigger/Close for uncontrolled
+ * use. Non-modal by default; set `modal` to trap focus, lock scroll, and block
+ * outside pointer events. Reach for a Popover when you need interactive
+ * overlay content; use Tooltip for hover-only labels and Dialog for blocking,
+ * page-level tasks.
+ */
 export interface PopoverRootProps {
   /** Uncontrolled initial open state. Ignored once `v-model:open` is bound. */
   defaultOpen?: boolean;
diff --git a/vue/primitives/src/popover/PopoverTrigger.vue b/vue/primitives/src/popover/PopoverTrigger.vue
index 8e87221..ff0f61d 100644
--- a/vue/primitives/src/popover/PopoverTrigger.vue
+++ b/vue/primitives/src/popover/PopoverTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The button that toggles the popover open and closed. Wires up
+ * `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls`, and (unless a
+ * custom Anchor is present) acts as the element Content is positioned against.
+ */
 export interface PopoverTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/popover/demo.vue b/vue/primitives/src/popover/demo.vue
new file mode 100644
index 0000000..4f8b3c7
--- /dev/null
+++ b/vue/primitives/src/popover/demo.vue
@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import { reactive } from 'vue';
+import {
+  PopoverArrow,
+  PopoverClose,
+  PopoverContent,
+  PopoverPortal,
+  PopoverRoot,
+  PopoverTrigger,
+} from '@robonen/primitives';
+
+const dimensions = reactive({
+  width: 320,
+  height: 180,
+  maxWidth: 480,
+  maxHeight: 280,
+});
+
+const fields = [
+  { key: 'width', label: 'Width' },
+  { key: 'height', label: 'Height' },
+  { key: 'maxWidth', label: 'Max. width' },
+  { key: 'maxHeight', label: 'Max. height' },
+] as const;
+</script>
+
+<template>
+  <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)"
+      :style="{ width: `${dimensions.width}px`, height: `${dimensions.height}px` }"
+    >
+      <span class="block px-2 py-1">{{ dimensions.width }} × {{ dimensions.height }}</span>
+    </div>
+
+    <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)"
+      >
+        <svg
+          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" />
+          <circle cx="12" cy="12" r="3" />
+        </svg>
+        Dimensions
+      </PopoverTrigger>
+
+      <PopoverPortal>
+        <PopoverContent
+          :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"
+        >
+          <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>
+            </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)"
+            >
+              <svg
+                class="size-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+                stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+              >
+                <path d="M18 6 6 18M6 6l12 12" />
+              </svg>
+            </PopoverClose>
+          </div>
+
+          <div class="mt-3 flex flex-col gap-2">
+            <label
+              v-for="field in fields"
+              :key="field.key"
+              class="grid grid-cols-[1fr_auto] items-center gap-3 text-sm"
+            >
+              <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)"
+              >
+            </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" />
+            </svg>
+          </PopoverArrow>
+        </PopoverContent>
+      </PopoverPortal>
+    </PopoverRoot>
+  </div>
+</template>
diff --git a/vue/primitives/src/popper/PopperAnchor.vue b/vue/primitives/src/popper/PopperAnchor.vue
index 18ca7d2..90e24a6 100644
--- a/vue/primitives/src/popper/PopperAnchor.vue
+++ b/vue/primitives/src/popper/PopperAnchor.vue
@@ -2,6 +2,13 @@
 import type { PrimitiveProps } from '../primitive';
 import type { ReferenceElement } from '@floating-ui/vue';
 
+/**
+ * Marks the element that `PopperContent` positions itself against. Renders its
+ * child and registers it with the `PopperRoot` as the positioning reference;
+ * pass `reference` to anchor to a virtual or external element instead of the
+ * rendered DOM node. Optional — when omitted, the content falls back to its own
+ * `reference` prop or the nearest registered anchor.
+ */
 export interface PopperAnchorProps extends PrimitiveProps {
   /** Custom reference element for positioning. If not provided, uses the rendered element. */
   reference?: ReferenceElement;
diff --git a/vue/primitives/src/popper/PopperArrow.vue b/vue/primitives/src/popper/PopperArrow.vue
index 8fb2a49..af8e403 100644
--- a/vue/primitives/src/popper/PopperArrow.vue
+++ b/vue/primitives/src/popper/PopperArrow.vue
@@ -25,6 +25,12 @@ const TRANSFORM: Record<Side, string> = {
   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;
diff --git a/vue/primitives/src/popper/PopperContent.vue b/vue/primitives/src/popper/PopperContent.vue
index 62695f9..9347e10 100644
--- a/vue/primitives/src/popper/PopperContent.vue
+++ b/vue/primitives/src/popper/PopperContent.vue
@@ -3,6 +3,18 @@ import type { Align, Side } from './utils';
 import type { Middleware, Placement, ReferenceElement } from '@floating-ui/vue';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The floating element positioned against the anchor. This is the workhorse of
+ * the Popper building block: it runs Floating UI (offset, flip, shift, size,
+ * arrow, hide) to place itself on the chosen side/alignment, keeps the position
+ * updated on scroll/resize/layout shift, avoids collisions with the viewport or
+ * a custom boundary, and exposes `--popper-*` CSS variables plus `data-side` /
+ * `data-align` attributes for styling and transform-origin. Use the Popper parts
+ * to build any anchored overlay — tooltips, popovers, menus, selects — where
+ * content must follow a trigger and stay on-screen. Place it inside a
+ * `PopperRoot` (so it can read the registered anchor) and emit `placed` once the
+ * first position settles.
+ */
 export interface PopperContentProps extends PrimitiveProps {
   /** Preferred side of the anchor. @default 'bottom' */
   side?: Side;
diff --git a/vue/primitives/src/popper/PopperRoot.vue b/vue/primitives/src/popper/PopperRoot.vue
index 174a148..a546eee 100644
--- a/vue/primitives/src/popper/PopperRoot.vue
+++ b/vue/primitives/src/popper/PopperRoot.vue
@@ -1,3 +1,17 @@
+<script lang="ts">
+/**
+ * The context provider for a popper. It coordinates positioning between
+ * `PopperAnchor` (the reference element), `PopperContent` (the floating
+ * element placed against it), and `PopperArrow`, sharing the registered anchor
+ * via context. It renders only its slot and adds no DOM of its own, so wrap
+ * the anchor and content in it to build tooltips, popovers, dropdown menus, and
+ * other floating UI.
+ */
+// PopperRoot is a context-only provider that renders just its slot — it takes no props.
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface PopperRootProps {}
+</script>
+
 <script setup lang="ts">
 import type { ReferenceElement } from '@floating-ui/vue';
 import { providePopperRootContext } from './context';
@@ -5,6 +19,8 @@ import { ref } from 'vue';
 
 defineOptions({ inheritAttrs: false });
 
+defineProps<PopperRootProps>();
+
 const anchor = ref<ReferenceElement>();
 
 providePopperRootContext({
diff --git a/vue/primitives/src/popper/index.ts b/vue/primitives/src/popper/index.ts
index c49ffca..1c66308 100644
--- a/vue/primitives/src/popper/index.ts
+++ b/vue/primitives/src/popper/index.ts
@@ -6,6 +6,7 @@ export { default as PopperArrow } from './PopperArrow.vue';
 export { usePopperRootContext, usePopperContentContext } from './context';
 
 export type { PopperRootContext, PopperContentContext } from './context';
+export type { PopperRootProps } from './PopperRoot.vue';
 export type { PopperAnchorProps } from './PopperAnchor.vue';
 export type { PopperContentEmits, PopperContentProps } from './PopperContent.vue';
 export type { PopperArrowProps } from './PopperArrow.vue';
diff --git a/vue/primitives/src/presence/Presence.vue b/vue/primitives/src/presence/Presence.vue
index 9ff0fd4..ee3e74c 100644
--- a/vue/primitives/src/presence/Presence.vue
+++ b/vue/primitives/src/presence/Presence.vue
@@ -1,6 +1,22 @@
 <script lang="ts">
+/**
+ * Controls the mount/unmount lifecycle of a single child while respecting CSS
+ * enter/leave animations, keeping it in the DOM until any exit animation has
+ * finished. Use it as the foundation for show/hide parts (dialog content,
+ * tooltips, collapsible panels) so they animate out before being removed,
+ * rather than disappearing instantly when their `present` state flips to false.
+ *
+ * `Presence` is a headless building block: it renders its child via `Slot`
+ * (merging attributes onto it), wires up animation tracking, and exposes the
+ * resolved presence to the default slot so children can reflect it (e.g. as a
+ * `data-state`). The same logic is available standalone through `usePresence`.
+ */
 export interface PresenceProps {
+
+  /** Whether the child should be present. While `false`, the child stays mounted until any leave animation completes. */
   present: boolean;
+
+  /** Keep the child mounted regardless of `present` (useful for animation control or measuring while hidden). */
   forceMount?: boolean;
 }
 
diff --git a/vue/primitives/src/progress/ProgressIndicator.vue b/vue/primitives/src/progress/ProgressIndicator.vue
index a9724eb..1bb98ee 100644
--- a/vue/primitives/src/progress/ProgressIndicator.vue
+++ b/vue/primitives/src/progress/ProgressIndicator.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The visual fill of the progress bar, rendered inside `ProgressRoot`. It reads
+ * the value, max, and state from context and exposes them via `data-state`,
+ * `data-value`, and `data-max` (plus matching slot props) so you can size and
+ * style the fill — e.g. translating it by the completion percentage.
+ */
 export interface ProgressIndicatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/progress/ProgressRoot.vue b/vue/primitives/src/progress/ProgressRoot.vue
index d1eb04a..f0772ef 100644
--- a/vue/primitives/src/progress/ProgressRoot.vue
+++ b/vue/primitives/src/progress/ProgressRoot.vue
@@ -2,6 +2,18 @@
 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;
diff --git a/vue/primitives/src/progress/demo.vue b/vue/primitives/src/progress/demo.vue
new file mode 100644
index 0000000..6886727
--- /dev/null
+++ b/vue/primitives/src/progress/demo.vue
@@ -0,0 +1,72 @@
+<script setup lang="ts">
+import { onBeforeUnmount, ref } from 'vue';
+import { ProgressIndicator, ProgressRoot } from '@robonen/primitives';
+
+const value = ref(0);
+let timer: ReturnType<typeof setInterval> | undefined;
+
+function start() {
+  stop();
+  value.value = 0;
+  timer = setInterval(() => {
+    value.value = Math.min(100, value.value + Math.round(8 + Math.random() * 14));
+    if (value.value >= 100)
+      stop();
+  }, 600);
+}
+
+function stop() {
+  if (timer) {
+    clearInterval(timer);
+    timer = undefined;
+  }
+}
+
+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)">
+    <!-- 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>
+      </div>
+
+      <ProgressRoot
+        v-slot="{ state }"
+        :model-value="value"
+        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)'"
+          :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"
+        @click="start"
+      >
+        {{ value === 0 ? 'Start upload' : 'Restart' }}
+      </button>
+    </div>
+
+    <!-- Indeterminate: value is null -->
+    <div class="space-y-2">
+      <span class="text-sm font-medium">Syncing changes…</span>
+
+      <ProgressRoot
+        :model-value="null"
+        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)" />
+      </ProgressRoot>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/qr-code/QrCodeBackground.vue b/vue/primitives/src/qr-code/QrCodeBackground.vue
new file mode 100644
index 0000000..b3b8156
--- /dev/null
+++ b/vue/primitives/src/qr-code/QrCodeBackground.vue
@@ -0,0 +1,52 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../primitive';
+
+/**
+ * A rectangle covering the entire code, quiet zone included. Use it for a solid
+ * backdrop or a gradient/pattern fill behind the modules. Defaults to
+ * `fill="none"` so the page background shows through unless you style it.
+ */
+export interface QrCodeBackgroundProps extends PrimitiveProps {
+  /** Fill applied to the rectangle. Default `'none'` (transparent). Overridable via CSS. */
+  fill?: string;
+  /** Corner radius in module units. Default `0`. */
+  radius?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../primitive';
+import { useQrCodeContext } from './context';
+
+const { as = 'rect', fill = 'none', radius = 0 } = defineProps<QrCodeBackgroundProps>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useQrCodeContext();
+
+const rect = computed(() => {
+  const m = ctx.margin.value;
+  return {
+    x: -m.left,
+    y: -m.top,
+    width: m.left + ctx.size.value + m.right,
+    height: m.top + ctx.size.value + m.bottom,
+  };
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :x="rect.x"
+    :y="rect.y"
+    :width="rect.width"
+    :height="rect.height"
+    :rx="radius || undefined"
+    :ry="radius || undefined"
+    :fill="fill"
+    data-qr-background
+  />
+</template>
diff --git a/vue/primitives/src/qr-code/QrCodeCells.vue b/vue/primitives/src/qr-code/QrCodeCells.vue
new file mode 100644
index 0000000..18f8dde
--- /dev/null
+++ b/vue/primitives/src/qr-code/QrCodeCells.vue
@@ -0,0 +1,76 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../primitive';
+import type { QrCellPattern } from './utils';
+
+/**
+ * Renders the data modules of the code. The `pattern` prop switches between
+ * pixel styles; `fluid` is neighbour-aware and merges adjacent modules into
+ * smooth blobs. By default the three finder patterns are skipped so that
+ * `QrCodeMarker`/`QrCodeMarkers` can style them independently — set
+ * `includeMarkers` to draw a complete code from cells alone.
+ *
+ * For total control, provide a `#cell` slot: it is rendered once per dark
+ * module with its grid position and center, and you emit whatever SVG you like.
+ */
+export interface QrCodeCellsProps extends PrimitiveProps {
+  /** Module shape: `square` (default), `dot`, `rounded`, or `fluid` (connected). */
+  pattern?: QrCellPattern;
+  /** Corner roundness in `[0, 1]` for `rounded`/`fluid`. Default `0.5`. */
+  radius?: number;
+  /** Gap between modules in `[0, 1)`, as a fraction of cell size. Ignored by `fluid`. Default `0`. */
+  gap?: number;
+  /** Also render the finder-pattern modules (use when not composing `QrCodeMarkers`). Default `false`. */
+  includeMarkers?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, useSlots } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../primitive';
+import { useQrCodeContext } from './context';
+import { cellList, cellsPath } from './utils';
+
+const {
+  as = 'path',
+  pattern = 'square',
+  radius = 0.5,
+  gap = 0,
+  includeMarkers = false,
+} = defineProps<QrCodeCellsProps>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useQrCodeContext();
+const slots = useSlots();
+
+const d = computed(() =>
+  cellsPath(ctx.qr.value, { pattern, radius, gap, includeMarkers, isReserved: ctx.isReserved }),
+);
+
+const cells = computed(() =>
+  cellList(ctx.qr.value, { includeMarkers, isReserved: ctx.isReserved }),
+);
+</script>
+
+<template>
+  <Primitive
+    v-if="slots.cell"
+    :ref="forwardRef"
+    :as="as === 'path' ? 'g' : as"
+    data-qr-cells
+  >
+    <slot
+      v-for="cell in cells"
+      :key="`${cell.x}-${cell.y}`"
+      name="cell"
+      v-bind="cell"
+    />
+  </Primitive>
+  <Primitive
+    v-else
+    :ref="forwardRef"
+    :as="as"
+    :d="d"
+    data-qr-cells
+  />
+</template>
diff --git a/vue/primitives/src/qr-code/QrCodeLogo.vue b/vue/primitives/src/qr-code/QrCodeLogo.vue
new file mode 100644
index 0000000..5e8fc39
--- /dev/null
+++ b/vue/primitives/src/qr-code/QrCodeLogo.vue
@@ -0,0 +1,94 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../primitive';
+
+/**
+ * Overlays a logo at the center of the code (or anywhere via `x`/`y`). Pass an
+ * image `src`, or use the default slot for arbitrary SVG content — the slot
+ * receives the computed placement so you can size and position freely.
+ *
+ * With `knockout` (the default) the modules behind the logo are cleared so it
+ * sits in clean space; pair it with a high `errorCorrection` level on the root
+ * to keep the code scannable.
+ */
+export interface QrCodeLogoProps extends PrimitiveProps {
+  /** Image URL to render via an SVG `<image>`. Optional when using the default slot. */
+  src?: string;
+  /** Logo extent as a fraction of the code size, in `[0, 1]`. Default `0.25`. */
+  size?: number;
+  /** Center X in module units. Defaults to the code's horizontal center. */
+  x?: number;
+  /** Center Y in module units. Defaults to the code's vertical center. */
+  y?: number;
+  /** Extra cleared padding around the logo, in modules. Default `1`. */
+  padding?: number;
+  /** Clear the modules behind the logo so it has clean space. Default `true`. */
+  knockout?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, onScopeDispose, watchEffect } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../primitive';
+import { useQrCodeContext } from './context';
+
+const {
+  as = 'g',
+  src,
+  size = 0.25,
+  x,
+  y,
+  padding = 1,
+  knockout = true,
+} = defineProps<QrCodeLogoProps>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useQrCodeContext();
+
+const area = computed(() => {
+  const extent = Math.max(0, size) * ctx.size.value;
+  const cx = x ?? ctx.size.value / 2;
+  const cy = y ?? ctx.size.value / 2;
+  return {
+    x: cx - extent / 2,
+    y: cy - extent / 2,
+    width: extent,
+    height: extent,
+    cx,
+    cy,
+  };
+});
+
+const owner = Symbol('qr-logo');
+
+watchEffect(() => {
+  if (!knockout) {
+    ctx.release(owner);
+    return;
+  }
+  const a = area.value;
+  ctx.reserve(owner, {
+    x: a.x - padding,
+    y: a.y - padding,
+    width: a.width + padding * 2,
+    height: a.height + padding * 2,
+  });
+});
+
+onScopeDispose(() => ctx.release(owner));
+</script>
+
+<template>
+  <Primitive :ref="forwardRef" :as="as" data-qr-logo>
+    <image
+      v-if="src"
+      :href="src"
+      :x="area.x"
+      :y="area.y"
+      :width="area.width"
+      :height="area.height"
+      preserveAspectRatio="xMidYMid meet"
+    />
+    <slot v-bind="area" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/qr-code/QrCodeMarker.vue b/vue/primitives/src/qr-code/QrCodeMarker.vue
new file mode 100644
index 0000000..91926f2
--- /dev/null
+++ b/vue/primitives/src/qr-code/QrCodeMarker.vue
@@ -0,0 +1,76 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../primitive';
+import type { MarkerCorner, QrMarkerBall, QrMarkerFrame } from './utils';
+
+/**
+ * A single finder ("eye") pattern, made of an outer `frame` ring and an inner
+ * `ball`. Position it by `corner` (resolved from the matrix size) or pin it with
+ * explicit `x`/`y` module coordinates. Override the `#frame` / `#ball` slots to
+ * draw arbitrary shapes; each receives the 7×7 region's origin and center.
+ */
+export interface QrCodeMarkerProps extends PrimitiveProps {
+  /** Which finder to render. Ignored when both `x` and `y` are given. Default `'top-left'`. */
+  corner?: MarkerCorner;
+  /** Explicit X of the finder's top-left module (overrides `corner`). */
+  x?: number;
+  /** Explicit Y of the finder's top-left module (overrides `corner`). */
+  y?: number;
+  /** Outer ring shape: `square` (default), `rounded`, or `circle`. */
+  frame?: QrMarkerFrame;
+  /** Inner ball shape: `square` (default), `rounded`, `circle`, or `diamond`. */
+  ball?: QrMarkerBall;
+  /** Roundness in `[0, 1]` for `rounded` frames/balls. Default `0.5`. */
+  radius?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../primitive';
+import { useQrCodeContext } from './context';
+import { markerBallPath, markerFramePath } from './utils';
+
+const {
+  as = 'g',
+  corner = 'top-left',
+  x,
+  y,
+  frame = 'square',
+  ball = 'square',
+  radius = 0.5,
+} = defineProps<QrCodeMarkerProps>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useQrCodeContext();
+
+const placement = computed(() => {
+  if (x !== undefined && y !== undefined)
+    return { x, y };
+  return ctx.markers.value.find(m => m.corner === corner) ?? { x: 0, y: 0 };
+});
+
+const origin = computed(() => {
+  const p = placement.value;
+  return { x: p.x, y: p.y, cx: p.x + 3.5, cy: p.y + 3.5 };
+});
+
+const framePath = computed(() => markerFramePath(placement.value.x, placement.value.y, frame, radius));
+const ballPath = computed(() => markerBallPath(placement.value.x, placement.value.y, ball, radius));
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :data-corner="corner"
+    data-qr-marker
+  >
+    <slot name="frame" v-bind="origin">
+      <path :d="framePath" fill-rule="evenodd" data-qr-marker-frame />
+    </slot>
+    <slot name="ball" v-bind="origin">
+      <path :d="ballPath" data-qr-marker-ball />
+    </slot>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/qr-code/QrCodeMarkers.vue b/vue/primitives/src/qr-code/QrCodeMarkers.vue
new file mode 100644
index 0000000..ac2764b
--- /dev/null
+++ b/vue/primitives/src/qr-code/QrCodeMarkers.vue
@@ -0,0 +1,61 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../primitive';
+import type { QrMarkerBall, QrMarkerFrame } from './utils';
+
+/**
+ * Convenience wrapper that renders all three finder patterns with a shared
+ * style. Forwards `frame`/`ball`/`radius` to each `QrCodeMarker` and re-exposes
+ * their `#frame` / `#ball` slots (augmented with the `corner` being drawn). For
+ * fully bespoke per-corner rendering, use the `#default` slot — it is invoked
+ * once per marker with its placement.
+ */
+export interface QrCodeMarkersProps extends PrimitiveProps {
+  /** Outer ring shape for every marker. Default `square`. */
+  frame?: QrMarkerFrame;
+  /** Inner ball shape for every marker. Default `square`. */
+  ball?: QrMarkerBall;
+  /** Roundness in `[0, 1]` for `rounded` frames/balls. Default `0.5`. */
+  radius?: number;
+}
+</script>
+
+<script setup lang="ts">
+import { useForwardExpose } from '@robonen/vue';
+import { Primitive } from '../primitive';
+import QrCodeMarker from './QrCodeMarker.vue';
+import { useQrCodeContext } from './context';
+
+const { as = 'g', frame = 'square', ball = 'square', radius = 0.5 } = defineProps<QrCodeMarkersProps>();
+
+const { forwardRef } = useForwardExpose();
+const ctx = useQrCodeContext();
+</script>
+
+<template>
+  <Primitive :ref="forwardRef" :as="as" data-qr-markers>
+    <template v-for="marker in ctx.markers.value" :key="marker.corner">
+      <slot
+        v-if="$slots.default"
+        :corner="marker.corner"
+        :x="marker.x"
+        :y="marker.y"
+        :cx="marker.x + 3.5"
+        :cy="marker.y + 3.5"
+      />
+      <QrCodeMarker
+        v-else
+        :corner="marker.corner"
+        :frame="frame"
+        :ball="ball"
+        :radius="radius"
+      >
+        <template v-if="$slots.frame" #frame="scope">
+          <slot name="frame" v-bind="scope" :corner="marker.corner" />
+        </template>
+        <template v-if="$slots.ball" #ball="scope">
+          <slot name="ball" v-bind="scope" :corner="marker.corner" />
+        </template>
+      </QrCodeMarker>
+    </template>
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/qr-code/QrCodeRoot.vue b/vue/primitives/src/qr-code/QrCodeRoot.vue
new file mode 100644
index 0000000..8e21d5b
--- /dev/null
+++ b/vue/primitives/src/qr-code/QrCodeRoot.vue
@@ -0,0 +1,134 @@
+<script lang="ts">
+import type { PrimitiveProps } from '../primitive';
+import type { QrCodeErrorCorrection, QrCodeMargin } from './context';
+
+/**
+ * The root of a QR code. Encodes `value` into a matrix (via `@robonen/encoding`)
+ * and renders an `<svg>` whose viewBox is laid out in module units, so every
+ * child part draws in the same resolution-independent coordinate space and the
+ * whole code scales with the SVG's CSS width/height.
+ *
+ * It is fully headless: compose `QrCodeBackground`, `QrCodeCells`,
+ * `QrCodeMarkers`/`QrCodeMarker` and `QrCodeLogo` inside it and style them with
+ * CSS (`fill`, gradients, `<defs>`) — patterns, marker shapes and logos are all
+ * controlled by props or slots on those parts.
+ *
+ * @example
+ * ```vue
+ * <QrCodeRoot value="https://example.com" class="size-48">
+ *   <QrCodeCells pattern="fluid" />
+ *   <QrCodeMarkers frame="rounded" ball="circle" />
+ * </QrCodeRoot>
+ * ```
+ */
+export interface QrCodeRootProps extends PrimitiveProps {
+  /** The text to encode. Re-encodes reactively when it changes. */
+  value: string;
+  /** Error-correction level — higher levels survive more damage (and logos) at the cost of density. Default `'M'`. */
+  errorCorrection?: QrCodeErrorCorrection;
+  /** Quiet-zone width in modules, uniform or per-side. Default `4` (the spec minimum). */
+  margin?: number | Partial<QrCodeMargin>;
+  /** Smallest QR version (1–40) to consider. Default `1`. */
+  minVersion?: number;
+  /** Largest QR version (1–40) to consider. Default `40`. */
+  maxVersion?: number;
+  /** Mask pattern (0–7), or `-1` to auto-select the lowest-penalty mask. Default `-1`. */
+  mask?: number;
+  /** Whether to automatically raise the error-correction level if the data still fits. Default `true`. */
+  boostEcc?: boolean;
+}
+</script>
+
+<script setup lang="ts">
+import { computed, reactive } from 'vue';
+import { EccMap, QrCodeDataType, encodeSegments, makeSegments } from '@robonen/encoding';
+import { useForwardExpose, useId } from '@robonen/vue';
+import { Primitive } from '../primitive';
+import { provideQrCodeContext } from './context';
+import type { QrCodeRegion } from './utils';
+import { markerPlacements } from './utils';
+
+const {
+  as = 'svg',
+  value,
+  errorCorrection = 'M',
+  margin = 4,
+  minVersion = 1,
+  maxVersion = 40,
+  mask = -1,
+  boostEcc = true,
+} = defineProps<QrCodeRootProps>();
+
+const { forwardRef } = useForwardExpose();
+const id = useId(undefined, 'qr');
+
+const qr = computed(() =>
+  encodeSegments(makeSegments(value), EccMap[errorCorrection], minVersion, maxVersion, mask, boostEcc),
+);
+
+const size = computed(() => qr.value.size);
+
+const resolvedMargin = computed<QrCodeMargin>(() => {
+  if (typeof margin === 'number')
+    return { top: margin, right: margin, bottom: margin, left: margin };
+  return { top: margin.top ?? 0, right: margin.right ?? 0, bottom: margin.bottom ?? 0, left: margin.left ?? 0 };
+});
+
+const markers = computed(() => markerPlacements(size.value));
+
+const viewBox = computed(() => {
+  const m = resolvedMargin.value;
+  const width = m.left + size.value + m.right;
+  const height = m.top + size.value + m.bottom;
+  return `${-m.left} ${-m.top} ${width} ${height}`;
+});
+
+const reserved = reactive(new Map<symbol, QrCodeRegion>());
+
+function reserve(owner: symbol, region: QrCodeRegion | null): void {
+  if (region)
+    reserved.set(owner, region);
+  else
+    reserved.delete(owner);
+}
+
+function release(owner: symbol): void {
+  reserved.delete(owner);
+}
+
+function isReserved(x: number, y: number): boolean {
+  const cx = x + 0.5;
+  const cy = y + 0.5;
+  for (const r of reserved.values()) {
+    if (cx >= r.x && cx < r.x + r.width && cy >= r.y && cy < r.y + r.height)
+      return true;
+  }
+  return false;
+}
+
+provideQrCodeContext({
+  qr,
+  size,
+  margin: resolvedMargin,
+  markers,
+  isDark: (x, y) => qr.value.getModule(x, y),
+  getModuleType: (x, y) => (x >= 0 && y >= 0 && x < size.value && y < size.value ? qr.value.getType(x, y) : QrCodeDataType.Border),
+  isReserved,
+  reserve,
+  release,
+  id,
+});
+</script>
+
+<template>
+  <Primitive
+    :ref="forwardRef"
+    :as="as"
+    :viewBox="viewBox"
+    role="img"
+    :data-qr-size="size"
+    :data-qr-version="qr.version"
+  >
+    <slot :qr="qr" :size="size" :markers="markers" />
+  </Primitive>
+</template>
diff --git a/vue/primitives/src/qr-code/__test__/QrCode.test.ts b/vue/primitives/src/qr-code/__test__/QrCode.test.ts
new file mode 100644
index 0000000..bbf3c66
--- /dev/null
+++ b/vue/primitives/src/qr-code/__test__/QrCode.test.ts
@@ -0,0 +1,190 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, nextTick } from 'vue';
+import { MEDIUM, QrCodeDataType, encodeText } from '@robonen/encoding';
+import {
+  QrCodeCells,
+  QrCodeLogo,
+  QrCodeMarker,
+  QrCodeMarkers,
+  QrCodeRoot,
+  cellsPath,
+  circlePath,
+  markerFramePath,
+  markerPlacements,
+  roundedRectPath,
+} from '../index';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+function mountQr(rootProps: Record<string, unknown>, children: () => unknown) {
+  return mount(defineComponent({
+    setup: () => () => h(QrCodeRoot, rootProps, { default: children }),
+  }), { attachTo: document.body });
+}
+
+describe('qr-code geometry utils', () => {
+  it('roundedRectPath emits a sharp rect when all radii are zero', () => {
+    const d = roundedRectPath(0, 0, 1, 1, 0, 0, 0, 0);
+    expect(d).not.toContain('A');
+    expect(d.startsWith('M')).toBe(true);
+    expect(d.endsWith('Z')).toBe(true);
+  });
+
+  it('roundedRectPath adds arc commands for non-zero radii', () => {
+    expect(roundedRectPath(0, 0, 1, 1, 0.5, 0.5, 0.5, 0.5)).toContain('A');
+  });
+
+  it('circlePath produces two arcs centered on the point', () => {
+    const d = circlePath(5, 5, 2);
+    expect((d.match(/A/g) ?? []).length).toBe(2);
+  });
+
+  it('markerPlacements returns the three finder corners for a v1 code', () => {
+    const placements = markerPlacements(21);
+    expect(placements.map(p => p.corner)).toEqual(['top-left', 'top-right', 'bottom-left']);
+    expect(placements.find(p => p.corner === 'top-right')).toMatchObject({ x: 14, y: 0 });
+    expect(placements.find(p => p.corner === 'bottom-left')).toMatchObject({ x: 0, y: 14 });
+  });
+
+  it('cellsPath excludes finder modules by default and includes them on request', () => {
+    const qr = encodeText('hello', MEDIUM);
+    const base = { pattern: 'square' as const, radius: 0, gap: 0, isReserved: () => false };
+    const withoutMarkers = cellsPath(qr, { ...base, includeMarkers: false });
+    const withMarkers = cellsPath(qr, { ...base, includeMarkers: true });
+    expect(withMarkers.length).toBeGreaterThan(withoutMarkers.length);
+  });
+
+  it('cellsPath skips reserved modules', () => {
+    const qr = encodeText('hello world', MEDIUM);
+    const base = { pattern: 'square' as const, radius: 0, gap: 0, includeMarkers: true };
+    const full = cellsPath(qr, { ...base, isReserved: () => false });
+    const knocked = cellsPath(qr, { ...base, isReserved: () => true });
+    expect(knocked).toBe('');
+    expect(full.length).toBeGreaterThan(0);
+  });
+
+  it('markerFramePath uses an annulus (no straight edges) for the circle frame', () => {
+    expect(markerFramePath(0, 0, 'circle', 0.5)).toContain('A');
+    expect(markerFramePath(0, 0, 'square', 0)).not.toContain('A');
+  });
+});
+
+describe('QrCodeRoot rendering', () => {
+  it('renders an SVG element in the SVG namespace with a viewBox', () => {
+    const w = mountQr({ value: 'hello' }, () => h(QrCodeCells));
+    const svg = w.element as unknown as SVGSVGElement;
+    expect(svg.tagName.toLowerCase()).toBe('svg');
+    expect(svg.namespaceURI).toBe(SVG_NS);
+    // default margin 4, v1 size 21 → 4 + 21 + 4 = 29
+    expect(svg.getAttribute('viewBox')).toBe('-4 -4 29 29');
+    expect(svg.getAttribute('role')).toBe('img');
+    expect(svg.getAttribute('data-qr-size')).toBe('21');
+    w.unmount();
+  });
+
+  it('renders cells as a namespaced <path> with a non-empty d', () => {
+    const w = mountQr({ value: 'hello' }, () => h(QrCodeCells));
+    const path = w.element.querySelector('[data-qr-cells]') as SVGPathElement;
+    expect(path).toBeTruthy();
+    expect(path.namespaceURI).toBe(SVG_NS);
+    expect(path.getAttribute('d')!.length).toBeGreaterThan(0);
+    w.unmount();
+  });
+
+  it('square and dot patterns produce different geometry', () => {
+    const sq = mountQr({ value: 'pattern' }, () => h(QrCodeCells, { pattern: 'square' }));
+    const dot = mountQr({ value: 'pattern' }, () => h(QrCodeCells, { pattern: 'dot' }));
+    const sqD = sq.element.querySelector('[data-qr-cells]')!.getAttribute('d')!;
+    const dotD = dot.element.querySelector('[data-qr-cells]')!.getAttribute('d')!;
+    expect(sqD).not.toBe(dotD);
+    expect(sqD).not.toContain('A');
+    expect(dotD).toContain('A');
+    sq.unmount();
+    dot.unmount();
+  });
+});
+
+describe('QrCodeMarkers', () => {
+  it('renders three finder groups, each with a frame and a ball', () => {
+    const w = mountQr({ value: 'markers' }, () => [
+      h(QrCodeCells),
+      h(QrCodeMarkers, { frame: 'rounded', ball: 'circle' }),
+    ]);
+    expect(w.element.querySelectorAll('[data-qr-marker]').length).toBe(3);
+    expect(w.element.querySelectorAll('[data-qr-marker-frame]').length).toBe(3);
+    expect(w.element.querySelectorAll('[data-qr-marker-ball]').length).toBe(3);
+    w.unmount();
+  });
+
+  it('a single QrCodemarker resolves its corner placement and tags it', () => {
+    const w = mountQr({ value: 'corner' }, () => h(QrCodeMarker, { corner: 'top-right' }));
+    const g = w.element.querySelector('[data-qr-marker]')!;
+    expect(g.getAttribute('data-corner')).toBe('top-right');
+    expect(g.querySelector('[data-qr-marker-frame]')).toBeTruthy();
+    w.unmount();
+  });
+});
+
+describe('QrCodeLogo', () => {
+  it('renders an <image> for src and knocks out the modules behind it', async () => {
+    const withLogo = mountQr({ value: 'logo knockout test value', errorCorrection: 'H' }, () => [
+      h(QrCodeCells, { includeMarkers: true }),
+      h(QrCodeLogo, { src: 'data:image/png;base64,iVBORw0KGgo=', size: 0.3 }),
+    ]);
+    const without = mountQr({ value: 'logo knockout test value', errorCorrection: 'H' }, () =>
+      h(QrCodeCells, { includeMarkers: true }),
+    );
+    // The logo reserves its region on mount, which invalidates the cells path
+    // reactively — flush the resulting re-render before reading the DOM.
+    await nextTick();
+
+    const img = withLogo.element.querySelector('[data-qr-logo] image') as SVGImageElement;
+    expect(img).toBeTruthy();
+    expect(img.namespaceURI).toBe(SVG_NS);
+    expect(img.getAttribute('href')).toContain('data:image/png');
+
+    const knockedD = withLogo.element.querySelector('[data-qr-cells]')!.getAttribute('d')!;
+    const fullD = without.element.querySelector('[data-qr-cells]')!.getAttribute('d')!;
+    expect(knockedD.length).toBeLessThan(fullD.length);
+
+    withLogo.unmount();
+    without.unmount();
+  });
+
+  it('does not knock out modules when knockout is disabled', async () => {
+    const off = mountQr({ value: 'logo knockout test value', errorCorrection: 'H' }, () => [
+      h(QrCodeCells, { includeMarkers: true }),
+      h(QrCodeLogo, { size: 0.3, knockout: false }),
+    ]);
+    const without = mountQr({ value: 'logo knockout test value', errorCorrection: 'H' }, () =>
+      h(QrCodeCells, { includeMarkers: true }),
+    );
+    await nextTick();
+    expect(off.element.querySelector('[data-qr-cells]')!.getAttribute('d'))
+      .toBe(without.element.querySelector('[data-qr-cells]')!.getAttribute('d'));
+    off.unmount();
+    without.unmount();
+  });
+});
+
+describe('custom #cell slot', () => {
+  it('renders one slotted node per dark data module with its type', () => {
+    const qr = encodeText('slot', MEDIUM);
+    let dataModules = 0;
+    for (let y = 0; y < qr.size; y++) {
+      for (let x = 0; x < qr.size; x++) {
+        if (qr.getModule(x, y) && qr.getType(x, y) !== QrCodeDataType.Position)
+          dataModules++;
+      }
+    }
+
+    const w = mountQr({ value: 'slot' }, () => h(QrCodeCells, null, {
+      cell: (slotProps: { cx: number; cy: number }) =>
+        h('circle', { cx: slotProps.cx, cy: slotProps.cy, r: 0.4, class: 'slotted' }),
+    }));
+
+    expect(w.element.querySelectorAll('circle.slotted').length).toBe(dataModules);
+    w.unmount();
+  });
+});
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/qr-code/__test__/__screenshots__/QrCode.test.ts/QrCodeLogo-renders-an--image--for-src-and-knocks-out-the-modules-behind-it-1.png
new file mode 100644
index 0000000..358d9fc
Binary files /dev/null and b/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 differ
diff --git a/vue/primitives/src/qr-code/context.ts b/vue/primitives/src/qr-code/context.ts
new file mode 100644
index 0000000..d01b6c9
--- /dev/null
+++ b/vue/primitives/src/qr-code/context.ts
@@ -0,0 +1,43 @@
+import type { ComputedRef } from 'vue';
+import type { QrCode, QrCodeDataType } from '@robonen/encoding';
+import type { MarkerPlacement, QrCodeRegion } from './utils';
+import { useContextFactory } from '@robonen/vue';
+
+/** Friendly error-correction level: Low (~7%), Medium (~15%), Quartile (~25%), High (~30%). */
+export type QrCodeErrorCorrection = 'L' | 'M' | 'Q' | 'H';
+
+/** Quiet-zone widths around the code, in module units. */
+export interface QrCodeMargin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface QrCodeContext {
+  /** The encoded matrix. Recomputed whenever the input or encoding options change. */
+  qr: ComputedRef<QrCode>;
+  /** Side length of the matrix in modules (21–177). */
+  size: ComputedRef<number>;
+  /** Resolved quiet-zone margins. */
+  margin: ComputedRef<QrCodeMargin>;
+  /** Top-left module index of each of the three finder patterns. */
+  markers: ComputedRef<MarkerPlacement[]>;
+  /** Whether the module at `(x, y)` is dark. Out-of-bounds reads return `false`. */
+  isDark: (x: number, y: number) => boolean;
+  /** Structural role of the module at `(x, y)`. */
+  getModuleType: (x: number, y: number) => QrCodeDataType;
+  /** Whether the module at `(x, y)` is covered by a reserved overlay region. */
+  isReserved: (x: number, y: number) => boolean;
+  /** Registers (or, with `null`, clears) a reserved region keyed by an owner symbol. */
+  reserve: (owner: symbol, region: QrCodeRegion | null) => void;
+  /** Removes a previously reserved region. */
+  release: (owner: symbol) => void;
+  /** Stable id, usable as a prefix for `clipPath`/gradient ids within the code. */
+  id: ComputedRef<string>;
+}
+
+const ctx = useContextFactory<QrCodeContext>('QrCodeContext');
+
+export const provideQrCodeContext = ctx.provide;
+export const useQrCodeContext = ctx.inject;
diff --git a/vue/primitives/src/qr-code/demo.vue b/vue/primitives/src/qr-code/demo.vue
new file mode 100644
index 0000000..b5e44f8
--- /dev/null
+++ b/vue/primitives/src/qr-code/demo.vue
@@ -0,0 +1,103 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  QrCodeBackground,
+  QrCodeCells,
+  QrCodeLogo,
+  QrCodeMarker,
+  QrCodeMarkers,
+  QrCodeRoot,
+} from '@robonen/primitives';
+import type { QrCellPattern, QrMarkerBall, QrMarkerFrame } from '@robonen/primitives';
+
+const value = ref('https://github.com/robonen/tools');
+
+const pattern = ref<QrCellPattern>('fluid');
+const frame = ref<QrMarkerFrame>('rounded');
+const ball = ref<QrMarkerBall>('circle');
+
+const patterns: QrCellPattern[] = ['square', 'dot', 'rounded', 'fluid'];
+const frames: QrMarkerFrame[] = ['square', 'rounded', 'circle'];
+const balls: QrMarkerBall[] = ['square', 'rounded', 'circle', 'diamond'];
+</script>
+
+<template>
+  <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">
+      <QrCodeRoot
+        :value="value"
+        error-correction="H"
+        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)" />
+        <QrCodeLogo v-slot="{ cx, cy, width }" :size="0.22" :padding="1.5">
+          <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)"
+            style="font-family: ui-sans-serif, system-ui; font-weight: 700"
+          >
+            R
+          </text>
+        </QrCodeLogo>
+      </QrCodeRoot>
+
+      <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>
+          <input
+            v-model="value"
+            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">
+            <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">
+              <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">
+              <option v-for="b in balls" :key="b" :value="b">{{ b }}</option>
+            </select>
+          </label>
+        </div>
+      </div>
+    </div>
+
+    <!-- A few canned styles showing per-corner control and gradients -->
+    <div class="grid grid-cols-2 gap-4 sm:grid-cols-3">
+      <QrCodeRoot value="dots" class="size-32 text-emerald-500">
+        <QrCodeCells pattern="dot" :gap="0.2" class="fill-current" />
+        <QrCodeMarkers frame="circle" ball="circle" class="fill-current" />
+      </QrCodeRoot>
+
+      <QrCodeRoot value="fluid" class="size-32 text-indigo-500">
+        <QrCodeCells pattern="fluid" :radius="1" class="fill-current" />
+        <QrCodeMarkers frame="rounded" ball="rounded" :radius="0.6" class="fill-current" />
+      </QrCodeRoot>
+
+      <QrCodeRoot value="per-corner" class="size-32">
+        <QrCodeCells pattern="rounded" :radius="0.4" class="fill-neutral-800 dark:fill-neutral-100" />
+        <QrCodeMarker corner="top-left" frame="circle" ball="circle" class="fill-rose-500" />
+        <QrCodeMarker corner="top-right" frame="rounded" ball="diamond" :radius="0.5" class="fill-amber-500" />
+        <QrCodeMarker corner="bottom-left" frame="square" ball="square" class="fill-sky-500" />
+      </QrCodeRoot>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/qr-code/index.ts b/vue/primitives/src/qr-code/index.ts
new file mode 100644
index 0000000..1d6a537
--- /dev/null
+++ b/vue/primitives/src/qr-code/index.ts
@@ -0,0 +1,35 @@
+export { default as QrCodeRoot } from './QrCodeRoot.vue';
+export { default as QrCodeBackground } from './QrCodeBackground.vue';
+export { default as QrCodeCells } from './QrCodeCells.vue';
+export { default as QrCodeMarker } from './QrCodeMarker.vue';
+export { default as QrCodeMarkers } from './QrCodeMarkers.vue';
+export { default as QrCodeLogo } from './QrCodeLogo.vue';
+
+export type { QrCodeRootProps } from './QrCodeRoot.vue';
+export type { QrCodeBackgroundProps } from './QrCodeBackground.vue';
+export type { QrCodeCellsProps } from './QrCodeCells.vue';
+export type { QrCodeMarkerProps } from './QrCodeMarker.vue';
+export type { QrCodeMarkersProps } from './QrCodeMarkers.vue';
+export type { QrCodeLogoProps } from './QrCodeLogo.vue';
+
+export { provideQrCodeContext, useQrCodeContext } from './context';
+export type { QrCodeContext, QrCodeErrorCorrection, QrCodeMargin } from './context';
+
+export {
+  cellList,
+  cellsPath,
+  circlePath,
+  markerBallPath,
+  markerFramePath,
+  markerPlacements,
+  roundedRectPath,
+} from './utils';
+export type {
+  MarkerCorner,
+  MarkerPlacement,
+  QrCellDescriptor,
+  QrCellPattern,
+  QrCodeRegion,
+  QrMarkerBall,
+  QrMarkerFrame,
+} from './utils';
diff --git a/vue/primitives/src/qr-code/utils.ts b/vue/primitives/src/qr-code/utils.ts
new file mode 100644
index 0000000..f6d6547
--- /dev/null
+++ b/vue/primitives/src/qr-code/utils.ts
@@ -0,0 +1,244 @@
+import type { QrCode } from '@robonen/encoding';
+import { QrCodeDataType } from '@robonen/encoding';
+
+/**
+ * Geometry helpers for rendering a {@link QrCode} matrix to SVG paths.
+ *
+ * Every coordinate is expressed in *module units*: a module at grid index
+ * `(x, y)` occupies the square `[x, x + 1] × [y, y + 1]`, so its center sits at
+ * `(x + 0.5, y + 0.5)`. Multiplying by a scale factor (or letting the SVG
+ * viewBox do it) yields pixels — the paths themselves are resolution-independent.
+ */
+
+/** Visual style applied to each data module ("pixel") of the code. */
+export type QrCellPattern = 'square' | 'dot' | 'rounded' | 'fluid';
+
+/** Shape of the outer 7×7 ring of a finder ("eye") pattern. */
+export type QrMarkerFrame = 'square' | 'rounded' | 'circle';
+
+/** Shape of the inner 3×3 ball of a finder ("eye") pattern. */
+export type QrMarkerBall = 'square' | 'rounded' | 'circle' | 'diamond';
+
+/** Which of the three finder patterns a {@link MarkerPlacement} refers to. */
+export type MarkerCorner = 'top-left' | 'top-right' | 'bottom-left';
+
+/** Position of a single finder pattern, given as the top-left module of its 7×7 region. */
+export interface MarkerPlacement {
+  corner: MarkerCorner;
+  /** X index of the finder's top-left module. */
+  x: number;
+  /** Y index of the finder's top-left module. */
+  y: number;
+}
+
+/** A rectangular region of the matrix, in module units, used to knock out modules behind overlays. */
+export interface QrCodeRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Description of one dark module, passed to the `#cell` slot for custom rendering. */
+export interface QrCellDescriptor {
+  /** Column index. */
+  x: number;
+  /** Row index. */
+  y: number;
+  /** Center X (`x + 0.5`). */
+  cx: number;
+  /** Center Y (`y + 0.5`). */
+  cy: number;
+  /** Structural role of the module (data, timing, alignment, …). */
+  type: QrCodeDataType;
+}
+
+/** Returns the top-left module index of each of the three finder patterns. */
+export function markerPlacements(size: number): MarkerPlacement[] {
+  return [
+    { corner: 'top-left', x: 0, y: 0 },
+    { corner: 'top-right', x: size - 7, y: 0 },
+    { corner: 'bottom-left', x: 0, y: size - 7 },
+  ];
+}
+
+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);
+}
+
+/**
+ * Builds a rectangle path with an independent corner radius per corner. A radius
+ * of `0` collapses that corner to a sharp right angle, which is how the `fluid`
+ * pattern merges a module into its dark neighbours.
+ */
+export function roundedRectPath(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  rTL: number,
+  rTR: number,
+  rBR: number,
+  rBL: number,
+): string {
+  const max = Math.min(w, h) / 2;
+  rTL = clamp(rTL, 0, max);
+  rTR = clamp(rTR, 0, max);
+  rBR = clamp(rBR, 0, max);
+  rBL = clamp(rBL, 0, max);
+
+  let d = `M${fmt(x + rTL)} ${fmt(y)}`;
+  d += `L${fmt(x + w - rTR)} ${fmt(y)}`;
+  if (rTR > 0)
+    d += `A${fmt(rTR)} ${fmt(rTR)} 0 0 1 ${fmt(x + w)} ${fmt(y + rTR)}`;
+  d += `L${fmt(x + w)} ${fmt(y + h - rBR)}`;
+  if (rBR > 0)
+    d += `A${fmt(rBR)} ${fmt(rBR)} 0 0 1 ${fmt(x + w - rBR)} ${fmt(y + h)}`;
+  d += `L${fmt(x + rBL)} ${fmt(y + h)}`;
+  if (rBL > 0)
+    d += `A${fmt(rBL)} ${fmt(rBL)} 0 0 1 ${fmt(x)} ${fmt(y + h - rBL)}`;
+  d += `L${fmt(x)} ${fmt(y + rTL)}`;
+  if (rTL > 0)
+    d += `A${fmt(rTL)} ${fmt(rTL)} 0 0 1 ${fmt(x + rTL)} ${fmt(y)}`;
+  return `${d}Z`;
+}
+
+/** Full circle (disc) path, drawn as two arcs. */
+export function circlePath(cx: number, cy: number, r: number): string {
+  return `M${fmt(cx - r)} ${fmt(cy)}`
+    + `A${fmt(r)} ${fmt(r)} 0 1 0 ${fmt(cx + r)} ${fmt(cy)}`
+    + `A${fmt(r)} ${fmt(r)} 0 1 0 ${fmt(cx - r)} ${fmt(cy)}Z`;
+}
+
+function diamondPath(cx: number, cy: number, r: number): string {
+  return `M${fmt(cx)} ${fmt(cy - r)}L${fmt(cx + r)} ${fmt(cy)}`
+    + `L${fmt(cx)} ${fmt(cy + r)}L${fmt(cx - r)} ${fmt(cy)}Z`;
+}
+
+/** Predicate deciding whether a module participates in cell rendering. */
+type ModuleFilter = (x: number, y: number) => boolean;
+
+interface CellOptions {
+  pattern: QrCellPattern;
+  /** Corner roundness in `[0, 1]` for `rounded`/`fluid` patterns. */
+  radius: number;
+  /** Inset applied to every module in `[0, 1)` to create gaps between cells. */
+  gap: number;
+  /** When `false`, modules belonging to a finder pattern are skipped (drawn by `QrCodeMarker`). */
+  includeMarkers: boolean;
+  /** Returns `true` for modules covered by an overlay (e.g. a logo) — they are skipped. */
+  isReserved: ModuleFilter;
+}
+
+/** Whether a module should be drawn by `QrCodeCells` given the active options. */
+function isCell(qr: QrCode, x: number, y: number, opts: CellOptions): boolean {
+  if (x < 0 || y < 0 || x >= qr.size || y >= qr.size)
+    return false;
+  if (!qr.getModule(x, y))
+    return false;
+  if (!opts.includeMarkers && qr.getType(x, y) === QrCodeDataType.Position)
+    return false;
+  return !opts.isReserved(x, y);
+}
+
+function cellSnippet(qr: QrCode, x: number, y: number, opts: CellOptions): string {
+  const { pattern } = opts;
+
+  if (pattern === 'fluid') {
+    // Connect to dark neighbours by squaring off the corners between them.
+    const r = clamp(opts.radius, 0, 1) * 0.5;
+    const top = isCell(qr, x, y - 1, opts);
+    const bottom = isCell(qr, x, y + 1, opts);
+    const left = isCell(qr, x - 1, y, opts);
+    const right = isCell(qr, x + 1, y, opts);
+    return roundedRectPath(
+      x,
+      y,
+      1,
+      1,
+      !top && !left ? r : 0,
+      !top && !right ? r : 0,
+      !bottom && !right ? r : 0,
+      !bottom && !left ? r : 0,
+    );
+  }
+
+  const gap = clamp(opts.gap, 0, 0.95);
+  const inset = gap / 2;
+  const s = 1 - gap;
+
+  if (pattern === 'dot')
+    return circlePath(x + 0.5, y + 0.5, s / 2);
+
+  const r = pattern === 'rounded' ? clamp(opts.radius, 0, 1) * (s / 2) : 0;
+  return roundedRectPath(x + inset, y + inset, s, s, r, r, r, r);
+}
+
+/** Builds a single `<path>` `d` string covering every rendered data module. */
+export function cellsPath(qr: QrCode, opts: CellOptions): string {
+  const size = qr.size;
+  let d = '';
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      if (isCell(qr, x, y, opts))
+        d += cellSnippet(qr, x, y, opts);
+    }
+  }
+  return d;
+}
+
+/** Collects descriptors for every rendered data module, for slot-based custom rendering. */
+export function cellList(
+  qr: QrCode,
+  opts: Pick<CellOptions, 'includeMarkers' | 'isReserved'>,
+): QrCellDescriptor[] {
+  const full: CellOptions = { ...opts, pattern: 'square', radius: 0, gap: 0 };
+  const size = qr.size;
+  const cells: QrCellDescriptor[] = [];
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      if (isCell(qr, x, y, full))
+        cells.push({ x, y, cx: x + 0.5, cy: y + 0.5, type: qr.getType(x, y) });
+    }
+  }
+  return cells;
+}
+
+/**
+ * Path for a finder pattern's outer ring. The frame occupies the 7×7 region
+ * with a 1-module-thick border (`square`/`rounded`) or an annulus (`circle`),
+ * leaving the standard 1-module light gap before the inner ball. Render with
+ * `fill-rule="evenodd"` so the inner cut-out reads as a hole.
+ */
+export function markerFramePath(mx: number, my: number, shape: QrMarkerFrame, radius: number): string {
+  const cx = mx + 3.5;
+  const cy = my + 3.5;
+  const t = clamp(radius, 0, 1);
+
+  if (shape === 'circle')
+    return circlePath(cx, cy, 3.5) + circlePath(cx, cy, 2.5);
+
+  const ro = shape === 'rounded' ? t * 3.5 : 0;
+  const ri = shape === 'rounded' ? Math.max(0, ro - 1) : 0;
+  return roundedRectPath(mx, my, 7, 7, ro, ro, ro, ro)
+    + roundedRectPath(mx + 1, my + 1, 5, 5, ri, ri, ri, ri);
+}
+
+/** Path for a finder pattern's inner 3×3 ball. */
+export function markerBallPath(mx: number, my: number, shape: QrMarkerBall, radius: number): string {
+  const cx = mx + 3.5;
+  const cy = my + 3.5;
+
+  if (shape === 'circle')
+    return circlePath(cx, cy, 1.5);
+  if (shape === 'diamond')
+    return diamondPath(cx, cy, 1.5);
+
+  const r = shape === 'rounded' ? clamp(radius, 0, 1) * 1.5 : 0;
+  return roundedRectPath(mx + 2, my + 2, 3, 3, r, r, r, r);
+}
diff --git a/vue/primitives/src/radio-group/RadioGroupIndicator.vue b/vue/primitives/src/radio-group/RadioGroupIndicator.vue
index 124a880..c912e4b 100644
--- a/vue/primitives/src/radio-group/RadioGroupIndicator.vue
+++ b/vue/primitives/src/radio-group/RadioGroupIndicator.vue
@@ -1,5 +1,10 @@
 <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;
 
diff --git a/vue/primitives/src/radio-group/RadioGroupItem.vue b/vue/primitives/src/radio-group/RadioGroupItem.vue
index 042a5e0..b2c7cf1 100644
--- a/vue/primitives/src/radio-group/RadioGroupItem.vue
+++ b/vue/primitives/src/radio-group/RadioGroupItem.vue
@@ -1,5 +1,11 @@
 <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;
diff --git a/vue/primitives/src/radio-group/RadioGroupRoot.vue b/vue/primitives/src/radio-group/RadioGroupRoot.vue
index df0820e..e1c6e6d 100644
--- a/vue/primitives/src/radio-group/RadioGroupRoot.vue
+++ b/vue/primitives/src/radio-group/RadioGroupRoot.vue
@@ -2,6 +2,15 @@
 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;
diff --git a/vue/primitives/src/radio-group/demo.vue b/vue/primitives/src/radio-group/demo.vue
new file mode 100644
index 0000000..1f36ce7
--- /dev/null
+++ b/vue/primitives/src/radio-group/demo.vue
@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { RadioGroupIndicator, RadioGroupItem, RadioGroupRoot } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const plans = [
+  { value: 'starter', label: 'Starter', hint: 'For side projects', price: '$0' },
+  { value: 'pro', label: 'Pro', hint: 'For growing teams', price: '$19' },
+  { value: 'enterprise', label: 'Enterprise', hint: 'Custom limits & SSO', price: 'Contact us', disabled: true },
+];
+
+const plan = ref('pro');
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 p-6 max-w-sm bg-(--bg) text-(--fg) border border-(--border) rounded-xl">
+    <div>
+      <h3 class="text-sm font-semibold">
+        Choose a plan
+      </h3>
+      <p class="text-xs text-(--fg-subtle)">
+        Use the arrow keys to move between options.
+      </p>
+    </div>
+
+    <RadioGroupRoot v-model="plan" class="flex flex-col gap-2">
+      <label
+        v-for="p in plans"
+        :key="p.value"
+        class="group flex items-center gap-3 p-3 rounded-lg border border-(--border) bg-(--bg-inset) cursor-pointer transition-colors has-[[data-state=checked]]:border-(--accent) has-[[data-state=checked]]:bg-(--bg-subtle) has-[[data-disabled]]:opacity-50 has-[[data-disabled]]:cursor-not-allowed"
+      >
+        <RadioGroupItem
+          :value="p.value"
+          :disabled="p.disabled"
+          class="grid place-items-center shrink-0 w-4 h-4 rounded-full border border-(--border) bg-(--bg) outline-none transition-colors data-[state=checked]:border-(--accent) focus-visible:ring-2 focus-visible:ring-(--ring)"
+        >
+          <RadioGroupIndicator class="w-2 h-2 rounded-full bg-(--accent)" />
+        </RadioGroupItem>
+
+        <div class="flex flex-col">
+          <span class="text-sm font-medium">{{ p.label }}</span>
+          <span class="text-xs text-(--fg-subtle)">{{ p.hint }}</span>
+        </div>
+
+        <span class="ml-auto text-sm font-semibold text-(--fg-muted)">{{ p.price }}</span>
+      </label>
+    </RadioGroupRoot>
+
+    <p class="text-xs text-(--fg-muted)">
+      Selected plan: <span class="font-semibold text-(--fg)">{{ plan }}</span>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/roving-focus/RovingFocusGroup.vue b/vue/primitives/src/roving-focus/RovingFocusGroup.vue
index 3448bbb..b68ab46 100644
--- a/vue/primitives/src/roving-focus/RovingFocusGroup.vue
+++ b/vue/primitives/src/roving-focus/RovingFocusGroup.vue
@@ -5,6 +5,16 @@ import type { PrimitiveProps } from '../primitive';
 import type { Ref } from 'vue';
 import { useContextFactory } from '@robonen/vue';
 
+/**
+ * A low-level building block that gives a set of items a single shared tab stop
+ * and lets arrow keys "rove" focus between them — the keyboard model behind
+ * toolbars, tabs, radio groups, menus and similar widgets. Only one item is in
+ * the page tab order at a time; Arrow/Home/End keys move focus and update the
+ * current tab stop, honouring `orientation`, writing `dir` (RTL-aware) and
+ * optional `loop` wrapping. Wrap focusable children in `RovingFocusItem`; this
+ * group renders a thin container and manages entry/exit focus, emitting
+ * `entryFocus` so consumers can override where focus lands on first entry.
+ */
 export interface RovingFocusGroupProps extends PrimitiveProps {
   /** Navigation orientation — decides which arrow keys move focus. */
   orientation?: Orientation;
diff --git a/vue/primitives/src/roving-focus/RovingFocusItem.vue b/vue/primitives/src/roving-focus/RovingFocusItem.vue
index c014934..72ba621 100644
--- a/vue/primitives/src/roving-focus/RovingFocusItem.vue
+++ b/vue/primitives/src/roving-focus/RovingFocusItem.vue
@@ -1,6 +1,13 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A single focusable item within a `RovingFocusGroup`. It registers itself with
+ * the group's collection, exposes itself as the sole tab stop when current
+ * (`tabindex="0"`, others `-1`), and handles the arrow-key navigation that moves
+ * focus to its siblings. Use `focusable` to opt an item out of the tab order and
+ * `active` to mark the current selection so it gets focus on group entry.
+ */
 export interface RovingFocusItemProps extends PrimitiveProps {
   /** Unique tab-stop id. Auto-generated via config `useId` when omitted. */
   tabStopId?: string;
diff --git a/vue/primitives/src/scroll-area/ScrollAreaCorner.vue b/vue/primitives/src/scroll-area/ScrollAreaCorner.vue
index 019341d..33d5a4e 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaCorner.vue
+++ b/vue/primitives/src/scroll-area/ScrollAreaCorner.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Fills the square where the horizontal and vertical scrollbars meet. It only renders when
+ * both scrollbars are present and have measurable size; otherwise it is omitted.
+ */
 export type ScrollAreaCornerProps = PrimitiveProps;
 </script>
 
diff --git a/vue/primitives/src/scroll-area/ScrollAreaRoot.vue b/vue/primitives/src/scroll-area/ScrollAreaRoot.vue
index 2ff0d62..8ef5caf 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaRoot.vue
+++ b/vue/primitives/src/scroll-area/ScrollAreaRoot.vue
@@ -2,6 +2,14 @@
 import type { PrimitiveProps } from '../primitive';
 import type { ScrollAreaType } from './types';
 
+/**
+ * Provides a styleable, cross-browser scroll container that swaps native scrollbars for
+ * custom ones while preserving native scrolling, keyboard, and accessibility behaviour.
+ * The root holds shared state and renders nothing visible on its own — compose it with a
+ * `ScrollAreaViewport` (the scrollable region), one or two `ScrollAreaScrollbar`s (each
+ * containing a `ScrollAreaThumb`), and an optional `ScrollAreaCorner`. Reach for it when
+ * the default OS scrollbars clash with your design or differ across platforms.
+ */
 export interface ScrollAreaRootProps extends PrimitiveProps {
   /**
    * Visibility behaviour for scrollbars.
diff --git a/vue/primitives/src/scroll-area/ScrollAreaScrollbar.vue b/vue/primitives/src/scroll-area/ScrollAreaScrollbar.vue
index 442b2d8..3435fe5 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaScrollbar.vue
+++ b/vue/primitives/src/scroll-area/ScrollAreaScrollbar.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A custom scrollbar track for one axis. It picks the appropriate visibility strategy from
+ * the root's `type` (`auto`, `always`, `scroll`, or `hover`) and renders the matching
+ * scrolling behaviour. Render one for each axis you want scrollable and place a
+ * `ScrollAreaThumb` inside it.
+ */
 export interface ScrollAreaScrollbarProps extends PrimitiveProps {
   /** @default 'vertical' */
   orientation?: 'horizontal' | 'vertical';
diff --git a/vue/primitives/src/scroll-area/ScrollAreaThumb.vue b/vue/primitives/src/scroll-area/ScrollAreaThumb.vue
index 5f8c046..1ff22aa 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaThumb.vue
+++ b/vue/primitives/src/scroll-area/ScrollAreaThumb.vue
@@ -10,6 +10,11 @@ import { useForwardExpose } from '@robonen/vue';
 import { useScrollAreaRootContext, useScrollAreaScrollbarContext } from './context';
 import { addUnlinkedScrollListener } from './utils';
 
+/**
+ * The draggable handle inside a `ScrollAreaScrollbar`. Its size and position track the
+ * scroll offset, and dragging it scrolls the viewport. Must be rendered inside a
+ * `ScrollAreaScrollbar`.
+ */
 export interface ScrollAreaThumbProps extends PrimitiveProps {
   /** Keep mounted regardless of `hasThumb`. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/scroll-area/ScrollAreaViewport.vue b/vue/primitives/src/scroll-area/ScrollAreaViewport.vue
index 6d39c47..fcf05d4 100644
--- a/vue/primitives/src/scroll-area/ScrollAreaViewport.vue
+++ b/vue/primitives/src/scroll-area/ScrollAreaViewport.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The scrollable region that clips and natively scrolls its content while the OS scrollbars
+ * are visually hidden. Place all scrollable content inside it; it must be a child of
+ * `ScrollAreaRoot`.
+ */
 export interface ScrollAreaViewportProps extends PrimitiveProps {
   /** Inline `nonce` attribute applied to the injected style tag (CSP support). */
   nonce?: string;
diff --git a/vue/primitives/src/scroll-area/demo.vue b/vue/primitives/src/scroll-area/demo.vue
new file mode 100644
index 0000000..ea43c6f
--- /dev/null
+++ b/vue/primitives/src/scroll-area/demo.vue
@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import {
+  ScrollAreaCorner,
+  ScrollAreaRoot,
+  ScrollAreaScrollbar,
+  ScrollAreaThumb,
+  ScrollAreaViewport,
+} from '@robonen/primitives';
+
+const releases = [
+  { tag: 'v2.4.0', date: '2026-05-28', note: 'Headless scroll-area lands with custom scrollbars and RTL support.' },
+  { tag: 'v2.3.1', date: '2026-05-12', note: 'Fix thumb drag jitter when the viewport resizes mid-gesture.' },
+  { tag: 'v2.3.0', date: '2026-04-30', note: 'New combobox primitive and improved focus-scope teleporting.' },
+  { tag: 'v2.2.2', date: '2026-04-18', note: 'Patch aria-controls wiring between scrollbar and viewport.' },
+  { tag: 'v2.2.1', date: '2026-04-02', note: 'Reduce layout thrash in the resize observer fast path.' },
+  { tag: 'v2.2.0', date: '2026-03-21', note: 'Date-picker range mode plus calendar keyboard navigation.' },
+  { tag: 'v2.1.0', date: '2026-03-05', note: 'Toast region stacking and swipe-to-dismiss gestures.' },
+  { tag: 'v2.0.0', date: '2026-02-14', note: 'Major: tree-shakeable barrel exports and stricter prop types.' },
+];
+</script>
+
+<template>
+  <ScrollAreaRoot
+    type="always"
+    class="h-64 w-full max-w-md overflow-hidden rounded-xl border border-(--border) bg-(--bg-elevated) text-(--fg)"
+  >
+    <ScrollAreaViewport class="h-full w-full">
+      <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)">
+          @robonen/primitives
+        </p>
+      </div>
+
+      <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)">
+            {{ release.tag }}
+          </span>
+          <div class="min-w-0">
+            <p class="text-sm text-(--fg)">
+              {{ release.note }}
+            </p>
+            <p class="mt-0.5 text-xs text-(--fg-subtle)">
+              {{ release.date }}
+            </p>
+          </div>
+        </li>
+      </ul>
+    </ScrollAreaViewport>
+
+    <ScrollAreaScrollbar
+      orientation="vertical"
+      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)" />
+    </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)"
+    >
+      <ScrollAreaThumb class="flex-1 rounded-full bg-(--fg-subtle) transition-colors hover:bg-(--fg-muted)" />
+    </ScrollAreaScrollbar>
+
+    <ScrollAreaCorner class="bg-(--bg-inset)" />
+  </ScrollAreaRoot>
+</template>
diff --git a/vue/primitives/src/select/SelectArrow.vue b/vue/primitives/src/select/SelectArrow.vue
index 185d059..59df716 100644
--- a/vue/primitives/src/select/SelectArrow.vue
+++ b/vue/primitives/src/select/SelectArrow.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PopperArrowProps } from '../popper';
 
+/**
+ * An optional arrow that points from the content back to the trigger. Only
+ * meaningful with `position="popper"`, since it relies on the popper placement;
+ * render it inside `SelectContent`.
+ */
 export type SelectArrowProps = PopperArrowProps;
 </script>
 
diff --git a/vue/primitives/src/select/SelectContent.vue b/vue/primitives/src/select/SelectContent.vue
index 4fb47ae..26162d9 100644
--- a/vue/primitives/src/select/SelectContent.vue
+++ b/vue/primitives/src/select/SelectContent.vue
@@ -1,6 +1,12 @@
 <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>
diff --git a/vue/primitives/src/select/SelectContentImpl.vue b/vue/primitives/src/select/SelectContentImpl.vue
index d6549a5..ae686f7 100644
--- a/vue/primitives/src/select/SelectContentImpl.vue
+++ b/vue/primitives/src/select/SelectContentImpl.vue
@@ -3,6 +3,12 @@ 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';
diff --git a/vue/primitives/src/select/SelectGroup.vue b/vue/primitives/src/select/SelectGroup.vue
index 8fb59c7..76946f6 100644
--- a/vue/primitives/src/select/SelectGroup.vue
+++ b/vue/primitives/src/select/SelectGroup.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Groups a set of related items under a shared label. Renders as a
+ * `role="group"` and provides an id so a child `SelectLabel` can label the
+ * group for assistive technology.
+ */
 export interface SelectGroupProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/select/SelectIcon.vue b/vue/primitives/src/select/SelectIcon.vue
index 1f78029..552bd15 100644
--- a/vue/primitives/src/select/SelectIcon.vue
+++ b/vue/primitives/src/select/SelectIcon.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The decorative icon shown in the trigger (a chevron by default). Marked
+ * `aria-hidden`; override the default glyph by passing slot content.
+ */
 export interface SelectIconProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/select/SelectItem.vue b/vue/primitives/src/select/SelectItem.vue
index 92d3d5d..c3f2562 100644
--- a/vue/primitives/src/select/SelectItem.vue
+++ b/vue/primitives/src/select/SelectItem.vue
@@ -1,6 +1,12 @@
 <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;
diff --git a/vue/primitives/src/select/SelectItemAlignedPosition.vue b/vue/primitives/src/select/SelectItemAlignedPosition.vue
index a1b658e..bf85967 100644
--- a/vue/primitives/src/select/SelectItemAlignedPosition.vue
+++ b/vue/primitives/src/select/SelectItemAlignedPosition.vue
@@ -1,7 +1,13 @@
 <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;
 }
 
diff --git a/vue/primitives/src/select/SelectItemIndicator.vue b/vue/primitives/src/select/SelectItemIndicator.vue
index 8bf9804..5306249 100644
--- a/vue/primitives/src/select/SelectItemIndicator.vue
+++ b/vue/primitives/src/select/SelectItemIndicator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A marker (typically a checkmark) rendered only while its `SelectItem` is the
+ * selected option. Decorative and `aria-hidden`; use inside a `SelectItem`.
+ */
 export interface SelectItemIndicatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/select/SelectItemText.vue b/vue/primitives/src/select/SelectItemText.vue
index 1633bec..c5cec95 100644
--- a/vue/primitives/src/select/SelectItemText.vue
+++ b/vue/primitives/src/select/SelectItemText.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The visible label of a `SelectItem`. Its text is what the root captures to
+ * show in `SelectValue` once the item is chosen, so each item should contain
+ * exactly one; use inside a `SelectItem`.
+ */
 export interface SelectItemTextProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/select/SelectLabel.vue b/vue/primitives/src/select/SelectLabel.vue
index 10b8b16..b981b40 100644
--- a/vue/primitives/src/select/SelectLabel.vue
+++ b/vue/primitives/src/select/SelectLabel.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A non-selectable heading for a `SelectGroup`. Renders the text that labels the
+ * group and wires its id to the group's `aria-labelledby`; must be used inside a
+ * `SelectGroup`.
+ */
 export interface SelectLabelProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/select/SelectPopperPosition.vue b/vue/primitives/src/select/SelectPopperPosition.vue
index d7c0186..11a8d05 100644
--- a/vue/primitives/src/select/SelectPopperPosition.vue
+++ b/vue/primitives/src/select/SelectPopperPosition.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PopperContentEmits, PopperContentProps } from '../popper';
 
+/**
+ * The `'popper'` positioning strategy for the content panel: builds on
+ * `PopperContent` for collision-aware floating placement with `side`, `align`,
+ * and offset controls. Chosen internally by `SelectContentImpl` when `position`
+ * is `'popper'`.
+ */
 export type SelectPopperPositionProps = PopperContentProps;
 export type SelectPopperPositionEmits = PopperContentEmits;
 </script>
@@ -23,6 +29,11 @@ const { forwardRef } = useForwardExpose();
     :side="props.side ?? 'bottom'"
     :side-offset="props.sideOffset ?? 4"
     :align="props.align ?? 'start'"
+    :style="{
+      '--primitives-select-content-available-width': 'var(--popper-available-width)',
+      '--primitives-select-content-available-height': 'var(--popper-available-height)',
+      '--primitives-select-content-transform-origin': 'var(--popper-transform-origin)',
+    }"
     @placed="emit('placed')"
   >
     <slot />
diff --git a/vue/primitives/src/select/SelectPortal.vue b/vue/primitives/src/select/SelectPortal.vue
index 5ae3945..35772e2 100644
--- a/vue/primitives/src/select/SelectPortal.vue
+++ b/vue/primitives/src/select/SelectPortal.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PortalProps } from '../teleport';
 
+/**
+ * Teleports the `SelectContent` into a different part of the DOM (the document
+ * body by default) so it escapes overflow and stacking-context clipping.
+ */
 export interface SelectPortalProps extends PortalProps {}
 </script>
 
diff --git a/vue/primitives/src/select/SelectRoot.vue b/vue/primitives/src/select/SelectRoot.vue
index 173000d..0e9b118 100644
--- a/vue/primitives/src/select/SelectRoot.vue
+++ b/vue/primitives/src/select/SelectRoot.vue
@@ -1,6 +1,20 @@
 <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;
@@ -44,8 +58,6 @@ const {
   autocomplete,
 } = defineProps<SelectRootProps>();
 
-const emit = defineEmits<SelectRootEmits>();
-
 const localOpen = ref<boolean>(defaultOpen);
 const open = defineModel<boolean>('open', {
   default: undefined,
@@ -101,7 +113,6 @@ watch([optionsSet, value], () => {
 function handleValueChange(newValue: SelectValue) {
   value.value = newValue;
   displayValue.value = optionsSet.value.get(newValue);
-  emit('update:modelValue', newValue);
   open.value = false;
 }
 
diff --git a/vue/primitives/src/select/SelectScrollButtonImpl.vue b/vue/primitives/src/select/SelectScrollButtonImpl.vue
index d13d6c3..718bba8 100644
--- a/vue/primitives/src/select/SelectScrollButtonImpl.vue
+++ b/vue/primitives/src/select/SelectScrollButtonImpl.vue
@@ -1,7 +1,13 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Shared implementation behind the up/down scroll buttons: auto-scrolls the
+ * viewport in `direction` while the pointer hovers it. Internal — use
+ * `SelectScrollUpButton` / `SelectScrollDownButton` instead.
+ */
 export interface SelectScrollButtonImplProps extends PrimitiveProps {
+  /** Scroll direction: `-1` scrolls up, `1` scrolls down. */
   direction: 1 | -1;
 }
 </script>
diff --git a/vue/primitives/src/select/SelectScrollDownButton.vue b/vue/primitives/src/select/SelectScrollDownButton.vue
index b2183c2..5d2c889 100644
--- a/vue/primitives/src/select/SelectScrollDownButton.vue
+++ b/vue/primitives/src/select/SelectScrollDownButton.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { SelectScrollButtonImplProps } from './SelectScrollButtonImpl.vue';
 
+/**
+ * An auto-scroll affordance shown at the bottom of the viewport when there is
+ * content scrolled out of view below. Scrolls the viewport down while hovered
+ * and hides itself when already at the bottom.
+ */
 export type SelectScrollDownButtonProps = Omit<SelectScrollButtonImplProps, 'direction'>;
 </script>
 
diff --git a/vue/primitives/src/select/SelectScrollUpButton.vue b/vue/primitives/src/select/SelectScrollUpButton.vue
index cc07868..2871285 100644
--- a/vue/primitives/src/select/SelectScrollUpButton.vue
+++ b/vue/primitives/src/select/SelectScrollUpButton.vue
@@ -1,6 +1,11 @@
 <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>
 
diff --git a/vue/primitives/src/select/SelectSeparator.vue b/vue/primitives/src/select/SelectSeparator.vue
index e238760..2f0a915 100644
--- a/vue/primitives/src/select/SelectSeparator.vue
+++ b/vue/primitives/src/select/SelectSeparator.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A visual divider between groups or items in the content. Renders as a
+ * horizontal `role="separator"` and is purely decorative.
+ */
 export interface SelectSeparatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/select/SelectTrigger.vue b/vue/primitives/src/select/SelectTrigger.vue
index 9f85168..aa265af 100644
--- a/vue/primitives/src/select/SelectTrigger.vue
+++ b/vue/primitives/src/select/SelectTrigger.vue
@@ -1,6 +1,12 @@
 <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;
diff --git a/vue/primitives/src/select/SelectValue.vue b/vue/primitives/src/select/SelectValue.vue
index 1b37bde..b397bd7 100644
--- a/vue/primitives/src/select/SelectValue.vue
+++ b/vue/primitives/src/select/SelectValue.vue
@@ -1,6 +1,11 @@
 <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;
diff --git a/vue/primitives/src/select/SelectViewport.vue b/vue/primitives/src/select/SelectViewport.vue
index d9b3e1a..2616f74 100644
--- a/vue/primitives/src/select/SelectViewport.vue
+++ b/vue/primitives/src/select/SelectViewport.vue
@@ -1,6 +1,11 @@
 <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>
 
diff --git a/vue/primitives/src/select/demo.vue b/vue/primitives/src/select/demo.vue
new file mode 100644
index 0000000..42764f7
--- /dev/null
+++ b/vue/primitives/src/select/demo.vue
@@ -0,0 +1,100 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  SelectContent,
+  SelectGroup,
+  SelectIcon,
+  SelectItem,
+  SelectItemIndicator,
+  SelectItemText,
+  SelectLabel,
+  SelectPortal,
+  SelectRoot,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+  SelectViewport,
+} from '@robonen/primitives';
+
+const value = ref<string | undefined>('cat');
+
+const animals = {
+  Pets: [
+    { value: 'cat', label: 'Cat' },
+    { value: 'dog', label: 'Dog' },
+    { value: 'rabbit', label: 'Rabbit' },
+    { value: 'hamster', label: 'Hamster', disabled: true },
+  ],
+  Wild: [
+    { value: 'lion', label: 'Lion' },
+    { value: 'tiger', label: 'Tiger' },
+    { value: 'bear', label: 'Bear' },
+    { value: 'wolf', label: 'Wolf' },
+    { value: 'fox', label: 'Fox' },
+  ],
+};
+
+const itemClass
+  = 'relative flex cursor-default select-none items-center rounded-md py-1.5 pl-7 pr-2 text-sm text-(--fg) outline-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 focus:bg-(--accent) focus:text-(--accent-fg)';
+</script>
+
+<template>
+  <div class="flex flex-col items-start gap-3 text-(--fg)">
+    <SelectRoot v-model="value" name="animal">
+      <SelectTrigger
+        class="inline-flex w-56 items-center justify-between gap-2 rounded-lg border border-(--border) bg-(--bg) px-3 py-2 text-sm text-(--fg) transition-colors hover:bg-(--bg-subtle) focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--ring) data-[placeholder]:text-(--fg-subtle)"
+      >
+        <SelectValue placeholder="Pick an animal…" />
+        <SelectIcon class="text-(--fg-muted)">
+          <span class="i-carbon-chevron-down block" aria-hidden="true" />
+        </SelectIcon>
+      </SelectTrigger>
+
+      <SelectPortal>
+        <SelectContent
+          position="popper"
+          :side-offset="6"
+          class="z-50 w-[var(--popper-anchor-width)] min-w-56 overflow-hidden rounded-lg border border-(--border) bg-(--bg-elevated) shadow-lg"
+        >
+          <SelectScrollUpButton class="flex h-6 items-center justify-center bg-(--bg-elevated) text-(--fg-muted)">
+            <span class="i-carbon-chevron-up block" aria-hidden="true" />
+          </SelectScrollUpButton>
+
+          <SelectViewport class="max-h-60 p-1">
+            <template v-for="(items, group, gi) in animals" :key="group">
+              <SelectSeparator v-if="gi > 0" class="my-1 h-px bg-(--border)" />
+              <SelectGroup>
+                <SelectLabel class="px-2 py-1.5 text-xs font-medium text-(--fg-subtle)">
+                  {{ group }}
+                </SelectLabel>
+                <SelectItem
+                  v-for="item in items"
+                  :key="item.value"
+                  :value="item.value"
+                  :disabled="item.disabled"
+                  :class="itemClass"
+                >
+                  <SelectItemIndicator class="absolute left-2 inline-flex items-center">
+                    <span class="i-carbon-checkmark block text-(--accent)" aria-hidden="true" />
+                  </SelectItemIndicator>
+                  <SelectItemText>{{ item.label }}</SelectItemText>
+                </SelectItem>
+              </SelectGroup>
+            </template>
+          </SelectViewport>
+
+          <SelectScrollDownButton class="flex h-6 items-center justify-center bg-(--bg-elevated) text-(--fg-muted)">
+            <span class="i-carbon-chevron-down block" aria-hidden="true" />
+          </SelectScrollDownButton>
+        </SelectContent>
+      </SelectPortal>
+    </SelectRoot>
+
+    <p class="text-xs text-(--fg-muted)">
+      Selected:
+      <span class="font-medium text-(--fg)">{{ value ?? 'none' }}</span>
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/separator/Separator.vue b/vue/primitives/src/separator/Separator.vue
index 26dcd6d..1be53c2 100644
--- a/vue/primitives/src/separator/Separator.vue
+++ b/vue/primitives/src/separator/Separator.vue
@@ -1,6 +1,13 @@
 <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';
diff --git a/vue/primitives/src/separator/demo.vue b/vue/primitives/src/separator/demo.vue
new file mode 100644
index 0000000..7375526
--- /dev/null
+++ b/vue/primitives/src/separator/demo.vue
@@ -0,0 +1,52 @@
+<script setup lang="ts">
+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>
+      <h3 class="text-sm font-semibold">
+        Vue Primitives
+      </h3>
+      <p class="text-sm text-(--fg-muted)">
+        Headless, accessible building blocks.
+      </p>
+    </div>
+
+    <Separator class="h-px bg-(--border)" />
+
+    <div class="flex flex-col gap-3">
+      <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)"
+          @click.prevent
+        >Docs</a>
+        <Separator
+          orientation="vertical"
+          decorative
+          class="w-px bg-(--border)"
+        />
+        <a
+          href="#"
+          class="text-(--accent) hover:text-(--accent-hover)"
+          @click.prevent
+        >Source</a>
+        <Separator
+          orientation="vertical"
+          decorative
+          class="w-px bg-(--border)"
+        />
+        <a
+          href="#"
+          class="text-(--accent) hover:text-(--accent-hover)"
+          @click.prevent
+        >Community</a>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/slider/SliderRange.vue b/vue/primitives/src/slider/SliderRange.vue
index 3b144eb..882af08 100644
--- a/vue/primitives/src/slider/SliderRange.vue
+++ b/vue/primitives/src/slider/SliderRange.vue
@@ -1,5 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
+
+/**
+ * The filled portion of the track representing the selected span, rendered
+ * inside `SliderTrack`. It reads the values and bounds from context and absolutely
+ * positions itself from the slider's start to the active thumb (or between the
+ * lowest and highest thumbs in range mode), respecting orientation and direction.
+ */
 export interface SliderRangeProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/slider/SliderRoot.vue b/vue/primitives/src/slider/SliderRoot.vue
index be7f0ed..b041c30 100644
--- a/vue/primitives/src/slider/SliderRoot.vue
+++ b/vue/primitives/src/slider/SliderRoot.vue
@@ -2,9 +2,20 @@
 import type { SliderDirection, SliderOrientation } from './context';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * An accessible slider for picking one or more numeric values from a range by
+ * dragging a thumb along a track or using the keyboard. The root owns the value
+ * state (controlled via `v-model` or uncontrolled via `defaultValue`), snaps to
+ * `step`, clamps to `min`/`max`, and handles pointer drags, focus, and arrow /
+ * Page / Home / End keys. Pass multiple values for a range (multi-thumb) slider
+ * and keep thumbs apart with `minStepsBetweenThumbs`; supports horizontal and
+ * vertical `orientation`, `dir`/`inverted` direction, and emits `valueCommit`
+ * when a drag or keypress settles. It provides context to `SliderTrack`,
+ * `SliderRange`, and `SliderThumb`, and renders hidden form inputs when `name`
+ * is set. Reach for it whenever a user should choose a value within known bounds
+ * (volume, price range, brightness).
+ */
 export interface SliderRootProps extends PrimitiveProps {
-  /** Current value(s) for controlled mode. */
-  modelValue?: number[];
   /** Min value. @default 0 */
   min?: number;
   /** Max value. @default 100 */
@@ -57,7 +68,6 @@ const {
   dir = 'ltr',
   inverted = false,
   disabled = false,
-  modelValue,
   defaultValue,
   name,
   required,
@@ -66,7 +76,12 @@ const {
 
 const { forwardRef } = useForwardExpose();
 
-const emit = defineEmits<SliderRootEmits & { 'update:modelValue': [value: number[]] }>();
+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[]>();
 
 function toArray(v: number | number[] | undefined): number[] {
   if (Array.isArray(v)) return v.slice();
@@ -74,9 +89,9 @@ function toArray(v: number | number[] | undefined): number[] {
   return [];
 }
 
-const d = toArray(defaultValue);
+const seed = model.value !== undefined ? model.value.slice() : toArray(defaultValue);
 // `shallowRef` — the array is always replaced wholesale; no need to proxy items.
-const localValues = shallowRef<number[]>(d.length > 0 ? d : [min]);
+const localValues = shallowRef<number[]>(seed.length > 0 ? seed : [min]);
 
 // Cache decimals per `step` — `String(step).split('.')` out of the pointermove path.
 let stepDecimals = getStepDecimals(step);
@@ -84,18 +99,19 @@ watch(() => step, (s) => {
   stepDecimals = getStepDecimals(s);
 });
 
-watch(() => modelValue, (v) => {
+watch(model, (v) => {
   if (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();
-}, { immediate: true });
+});
 
 const values = computed<number[]>({
   get: () => localValues.value,
   set: (v) => {
     localValues.value = v;
-    emit('update:modelValue', v);
+    // `defineModel` emits `update:modelValue` on write — no manual emit needed.
+    model.value = v;
   },
 });
 
diff --git a/vue/primitives/src/slider/SliderThumb.vue b/vue/primitives/src/slider/SliderThumb.vue
index 2ba59c5..f1cc8e3 100644
--- a/vue/primitives/src/slider/SliderThumb.vue
+++ b/vue/primitives/src/slider/SliderThumb.vue
@@ -1,9 +1,19 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A draggable handle rendered as `role="slider"`, one per value, placed inside
+ * `SliderTrack`. It registers with the root to claim its index, positions itself
+ * along the track by its value's percentage, and handles keyboard interaction
+ * (arrow keys step by `step`, Page Up/Down by a larger step, Home/End jump to
+ * the bounds) with full ARIA value attributes. Render one thumb for a single
+ * value or several for a range; give each an `aria-label`. Exposes `value` and
+ * `percent` as slot props.
+ */
 export interface SliderThumbProps extends PrimitiveProps {
-  /** Accessible label for this thumb. */
-  'aria-label'?: string;
+  // `aria-label` (and other ARIA attributes) are intentionally NOT declared as
+  // props so they fall through to the rendered `role="slider"` element — give
+  // each thumb an `aria-label` for its accessible name.
 }
 </script>
 
diff --git a/vue/primitives/src/slider/SliderTrack.vue b/vue/primitives/src/slider/SliderTrack.vue
index 894c1fe..87dd5ff 100644
--- a/vue/primitives/src/slider/SliderTrack.vue
+++ b/vue/primitives/src/slider/SliderTrack.vue
@@ -1,5 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
+
+/**
+ * The full-length rail the thumbs travel along, rendered inside `SliderRoot`.
+ * It registers itself as the geometry reference for pointer math and starts a
+ * drag (moving the nearest thumb to the click position) when pressed. Use it as
+ * the container for `SliderRange` and one or more `SliderThumb`.
+ */
 export interface SliderTrackProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/slider/demo.vue b/vue/primitives/src/slider/demo.vue
new file mode 100644
index 0000000..464b265
--- /dev/null
+++ b/vue/primitives/src/slider/demo.vue
@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import { SliderRange, SliderRoot, SliderThumb, SliderTrack } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const volume = ref([60]);
+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)">
+    <!-- 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>
+      </div>
+
+      <SliderRoot
+        v-model="volume"
+        :min="0"
+        :max="100"
+        :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>
+        <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"
+        />
+      </SliderRoot>
+    </div>
+
+    <!-- Range (two thumbs) -->
+    <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>
+      </div>
+
+      <SliderRoot
+        v-model="price"
+        :min="0"
+        :max="100"
+        :step="5"
+        :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>
+        <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"
+        />
+        <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"
+        />
+      </SliderRoot>
+    </div>
+
+    <!-- Disabled -->
+    <div class="space-y-3">
+      <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>
+        <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)"
+        />
+      </SliderRoot>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/stepper/StepperDescription.vue b/vue/primitives/src/stepper/StepperDescription.vue
index ff68887..f74d113 100644
--- a/vue/primitives/src/stepper/StepperDescription.vue
+++ b/vue/primitives/src/stepper/StepperDescription.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Optional supporting text for a step. Its `id` is wired to the trigger's
+ * `aria-describedby` so it is announced as a description of the step.
+ */
 export interface StepperDescriptionProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/stepper/StepperIndicator.vue b/vue/primitives/src/stepper/StepperIndicator.vue
index f47b722..d848c00 100644
--- a/vue/primitives/src/stepper/StepperIndicator.vue
+++ b/vue/primitives/src/stepper/StepperIndicator.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The visual marker for a step — typically a numbered circle or check. Defaults
+ * to rendering the step number, and exposes the current `step` and `state` via
+ * slot props so you can swap in icons (e.g. a check when completed).
+ */
 export interface StepperIndicatorProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/stepper/StepperItem.vue b/vue/primitives/src/stepper/StepperItem.vue
index 4351a74..6304371 100644
--- a/vue/primitives/src/stepper/StepperItem.vue
+++ b/vue/primitives/src/stepper/StepperItem.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A single step within the stepper. Associates its child trigger, indicator,
+ * title, and description with a step number and derives that step's state
+ * (`active`, `completed`, or `inactive`) from the root's current value.
+ */
 export interface StepperItemProps extends PrimitiveProps {
   /** 1-based index associating this item with a step. */
   step: number;
diff --git a/vue/primitives/src/stepper/StepperRoot.vue b/vue/primitives/src/stepper/StepperRoot.vue
index 497839a..7ff541f 100644
--- a/vue/primitives/src/stepper/StepperRoot.vue
+++ b/vue/primitives/src/stepper/StepperRoot.vue
@@ -2,9 +2,17 @@
 import type { StepperDirection, StepperOrientation } from './context';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A multi-step progress control that guides users through a sequence of steps —
+ * checkout flows, onboarding wizards, or any task split into ordered stages.
+ * Use it when you need to show where the user is, which steps are done, and
+ * (optionally) let them jump between steps.
+ *
+ * The root owns the active step (1-based), tracks the total via the Collection,
+ * arbitrates linear vs. free navigation, handles roving keyboard focus across
+ * triggers, and provides context to every `StepperItem`.
+ */
 export interface StepperRootProps extends PrimitiveProps {
-  /** Controlled active step (1-based). Use `v-model`. */
-  modelValue?: number;
   /** Uncontrolled initial step. @default 1 */
   defaultValue?: number;
   /** Orientation. @default 'horizontal' */
@@ -23,7 +31,7 @@ export interface StepperRootEmits {
 </script>
 
 <script setup lang="ts">
-import { computed, ref, toRef, watch } from 'vue';
+import { computed, toRef } from 'vue';
 import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
 import { Primitive } from '../primitive';
 import { provideStepperRootContext } from './context';
@@ -33,7 +41,6 @@ import { useForwardExpose } from '@robonen/vue';
 
 const {
   as = 'div',
-  modelValue,
   defaultValue = 1,
   orientation = 'horizontal',
   linear = true,
@@ -41,27 +48,26 @@ const {
   dir,
 } = defineProps<StepperRootProps>();
 
-const emit = defineEmits<StepperRootEmits>();
+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);
 
-const localValue = ref<number>(modelValue ?? defaultValue);
-
-watch(() => modelValue, (v) => {
-  if (v === undefined || v === localValue.value) return;
-  localValue.value = v;
-});
+// Always a defined step for consumers — `model` is seeded above and the setter clamps to numbers.
+const value = computed(() => model.value ?? defaultValue);
 
 const { getItems, CollectionSlot } = useCollectionProvider();
 const total = computed(() => getItems(true).length);
 
 function commit(next: number): void {
-  if (next === localValue.value) return;
-  localValue.value = next;
-  emit('update:modelValue', next);
+  if (next === model.value) return;
+  model.value = next;
 }
 
 function goToStep(step: number): void {
@@ -70,7 +76,7 @@ function goToStep(step: number): void {
   const count = items.length;
   if (count > 0 && step > count) return;
   // respect linear gate — at most one step ahead of current.
-  if (linear && step > localValue.value + 1) return;
+  if (linear && step > value.value + 1) return;
   // skip if target item is marked disabled in DOM.
   const target = items[step - 1]?.ref;
   if (target?.hasAttribute('data-disabled')) return;
@@ -107,7 +113,7 @@ function onTriggerKeyDown(event: KeyboardEvent, el: HTMLElement): void {
 }
 
 provideStepperRootContext({
-  value: localValue,
+  value,
   total,
   orientation: toRef(() => orientation),
   direction,
@@ -131,7 +137,7 @@ provideStepperRootContext({
       :dir="direction"
     >
       <slot
-        :value="localValue"
+        :value="value"
         :total="total"
         :go-to-step="goToStep"
       />
diff --git a/vue/primitives/src/stepper/StepperSeparator.vue b/vue/primitives/src/stepper/StepperSeparator.vue
index 089848e..c8f9d81 100644
--- a/vue/primitives/src/stepper/StepperSeparator.vue
+++ b/vue/primitives/src/stepper/StepperSeparator.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * 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 {}
 </script>
 
diff --git a/vue/primitives/src/stepper/StepperTitle.vue b/vue/primitives/src/stepper/StepperTitle.vue
index 850a5e8..69a52fd 100644
--- a/vue/primitives/src/stepper/StepperTitle.vue
+++ b/vue/primitives/src/stepper/StepperTitle.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The accessible label for a step. Its `id` is wired to the trigger's
+ * `aria-labelledby`, so screen readers announce it when the trigger is focused.
+ */
 export interface StepperTitleProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/stepper/StepperTrigger.vue b/vue/primitives/src/stepper/StepperTrigger.vue
index b672fdf..41cfa43 100644
--- a/vue/primitives/src/stepper/StepperTrigger.vue
+++ b/vue/primitives/src/stepper/StepperTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The interactive control for a step. Clicking or pressing it navigates to the
+ * step (subject to the root's `linear` and `disabled` rules) and it participates
+ * in roving arrow-key focus across all enabled triggers.
+ */
 export interface StepperTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/stepper/demo.vue b/vue/primitives/src/stepper/demo.vue
new file mode 100644
index 0000000..83daccd
--- /dev/null
+++ b/vue/primitives/src/stepper/demo.vue
@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import {
+  StepperDescription,
+  StepperIndicator,
+  StepperItem,
+  StepperRoot,
+  StepperSeparator,
+  StepperTitle,
+  StepperTrigger,
+} from '@robonen/primitives';
+
+const steps = [
+  { step: 1, title: 'Account', description: 'Your details' },
+  { step: 2, title: 'Shipping', description: 'Delivery address' },
+  { step: 3, title: 'Payment', description: 'Card or PayPal' },
+  { step: 4, title: 'Review', description: 'Confirm order' },
+];
+
+const current = ref(1);
+const isLast = computed(() => current.value === steps.length);
+
+function next() {
+  if (current.value < steps.length) current.value++;
+}
+
+function prev() {
+  if (current.value > 1) current.value--;
+}
+</script>
+
+<template>
+  <div class="w-full max-w-xl text-(--fg)">
+    <StepperRoot
+      v-model="current"
+      class="flex items-start"
+    >
+      <StepperItem
+        v-for="(s, i) in steps"
+        :key="s.step"
+        :step="s.step"
+        class="group flex flex-1 flex-col items-center gap-2 last:flex-none"
+      >
+        <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"
+          >
+            <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"
+            >
+              <svg
+                v-if="state === 'completed'"
+                class="size-4"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="3"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <polyline points="20 6 9 17 4 12" />
+              </svg>
+              <template v-else>
+                {{ step }}
+              </template>
+            </StepperIndicator>
+          </StepperTrigger>
+
+          <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"
+          />
+        </div>
+
+        <div class="flex flex-col items-center text-center">
+          <StepperTitle class="text-sm font-medium text-(--fg)">
+            {{ s.title }}
+          </StepperTitle>
+          <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)">
+        Step {{ current }} of {{ steps.length }} —
+        <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"
+        :disabled="current === 1"
+        @click="prev"
+      >
+        Back
+      </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"
+        :disabled="isLast"
+        @click="next"
+      >
+        {{ isLast ? 'Done' : 'Continue' }}
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/switch/Switch.vue b/vue/primitives/src/switch/Switch.vue
index dc1f24a..88d2b53 100644
--- a/vue/primitives/src/switch/Switch.vue
+++ b/vue/primitives/src/switch/Switch.vue
@@ -1,6 +1,16 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A control that toggles between an on and off state, mirroring a physical
+ * switch. Renders with `role="switch"`, exposes `data-state` and `data-disabled`
+ * for styling, and optionally mirrors its value into a hidden form input via
+ * `name`. The value is generic: it defaults to a boolean but can be any pair of
+ * `truthy`/`falsy` values (strings, numbers, objects compared by identity), and
+ * 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.
+ */
 export interface SwitchProps<T = boolean> extends PrimitiveProps {
 
   /** Value representing the "on" state. Defaults to `true`. */
@@ -9,7 +19,9 @@ export interface SwitchProps<T = boolean> extends PrimitiveProps {
   falsy?: T;
   /** Initial uncontrolled value. Defaults to `falsy`. */
   defaultValue?: T;
+  /** Prevents toggling and reflects a disabled state to assistive technology. */
   disabled?: boolean;
+  /** Marks the control as required for form submission (sets `aria-required`). */
   required?: boolean;
   /** Name for the hidden form input. If provided, a hidden input mirrors state. */
   name?: string;
diff --git a/vue/primitives/src/switch/demo.vue b/vue/primitives/src/switch/demo.vue
new file mode 100644
index 0000000..17b32dd
--- /dev/null
+++ b/vue/primitives/src/switch/demo.vue
@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import { Switch } from '@robonen/primitives';
+import { ref } from 'vue';
+
+const wifi = ref(true);
+const notifications = ref(false);
+
+// Generic value pair: this switch toggles between two strings, not booleans.
+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)">
+      Settings
+    </h3>
+
+    <label
+      for="demo-wifi"
+      class="flex cursor-pointer items-center justify-between gap-4 rounded-lg px-1 py-2.5 select-none"
+    >
+      <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>
+      <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)"
+      >
+        <span
+          class="pointer-events-none block size-5 rounded-full bg-white shadow-sm transition-transform duration-200 ease-out"
+          :class="wifi ? 'translate-x-5' : 'translate-x-0'"
+        />
+      </Switch>
+    </label>
+
+    <label
+      for="demo-notify"
+      class="flex cursor-pointer items-center justify-between gap-4 rounded-lg px-1 py-2.5 select-none"
+    >
+      <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>
+      <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)"
+      >
+        <span
+          class="pointer-events-none block size-5 rounded-full bg-white shadow-sm transition-transform duration-200 ease-out"
+          :class="notifications ? 'translate-x-5' : 'translate-x-0'"
+        />
+      </Switch>
+    </label>
+
+    <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>
+      <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)"
+      >
+        <template #default="{ value }">
+          <span
+            class="pointer-events-none flex size-5 items-center justify-center rounded-full bg-white text-[10px] shadow-sm transition-transform duration-200 ease-out"
+            :class="value === 'dark' ? 'translate-x-5' : 'translate-x-0'"
+          >
+            {{ value === 'dark' ? '🌙' : '☀️' }}
+          </span>
+        </template>
+      </Switch>
+    </div>
+
+    <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>.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/tabs/TabsContent.vue b/vue/primitives/src/tabs/TabsContent.vue
index 3b156f4..19ca154 100644
--- a/vue/primitives/src/tabs/TabsContent.vue
+++ b/vue/primitives/src/tabs/TabsContent.vue
@@ -1,6 +1,11 @@
 <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;
diff --git a/vue/primitives/src/tabs/TabsList.vue b/vue/primitives/src/tabs/TabsList.vue
index 20c0d2a..9a89d32 100644
--- a/vue/primitives/src/tabs/TabsList.vue
+++ b/vue/primitives/src/tabs/TabsList.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Container that groups the tab triggers and exposes them as an ARIA `tablist`.
+ * Place one inside `TabsRoot`, wrapping the set of `TabsTrigger` elements.
+ */
 export interface TabsListProps extends PrimitiveProps {
 }
 </script>
diff --git a/vue/primitives/src/tabs/TabsRoot.vue b/vue/primitives/src/tabs/TabsRoot.vue
index 11fd445..b1c07f2 100644
--- a/vue/primitives/src/tabs/TabsRoot.vue
+++ b/vue/primitives/src/tabs/TabsRoot.vue
@@ -2,6 +2,16 @@
 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;
diff --git a/vue/primitives/src/tabs/TabsTrigger.vue b/vue/primitives/src/tabs/TabsTrigger.vue
index 9b35e23..4bd1aa0 100644
--- a/vue/primitives/src/tabs/TabsTrigger.vue
+++ b/vue/primitives/src/tabs/TabsTrigger.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The clickable control that activates its associated `TabsContent` panel.
+ * Selecting it (by click or keyboard) sets the root value to its `value`.
+ * Render one per tab inside a `TabsList`.
+ */
 export interface TabsTriggerProps extends PrimitiveProps {
   /** Value that links this trigger to a content panel. */
   value: string;
diff --git a/vue/primitives/src/tabs/demo.vue b/vue/primitives/src/tabs/demo.vue
new file mode 100644
index 0000000..da4f365
--- /dev/null
+++ b/vue/primitives/src/tabs/demo.vue
@@ -0,0 +1,73 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  TabsContent,
+  TabsList,
+  TabsRoot,
+  TabsTrigger,
+} from '@robonen/primitives';
+
+const tab = ref('account');
+
+const tabs = [
+  { value: 'account', label: 'Account' },
+  { value: 'password', label: 'Password' },
+  { value: 'notifications', label: 'Notifications' },
+];
+</script>
+
+<template>
+  <TabsRoot
+    v-model="tab"
+    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"
+    >
+      <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)"
+      >
+        {{ t.label }}
+      </TabsTrigger>
+    </TabsList>
+
+    <TabsContent
+      value="account"
+      class="p-4 text-sm text-(--fg-muted) outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+    >
+      <p class="font-medium text-(--fg)">
+        Account
+      </p>
+      <p class="mt-1">
+        Update your display name and email. Changes are saved instantly.
+      </p>
+    </TabsContent>
+
+    <TabsContent
+      value="password"
+      class="p-4 text-sm text-(--fg-muted) outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+    >
+      <p class="font-medium text-(--fg)">
+        Password
+      </p>
+      <p class="mt-1">
+        Choose a strong password. We recommend at least 12 characters.
+      </p>
+    </TabsContent>
+
+    <TabsContent
+      value="notifications"
+      class="p-4 text-sm text-(--fg-muted) outline-none focus-visible:ring-2 focus-visible:ring-(--ring)"
+    >
+      <p class="font-medium text-(--fg)">
+        Notifications
+      </p>
+      <p class="mt-1">
+        Pick which updates land in your inbox. You can change this anytime.
+      </p>
+    </TabsContent>
+  </TabsRoot>
+</template>
diff --git a/vue/primitives/src/tags-input/TagsInputClear.vue b/vue/primitives/src/tags-input/TagsInputClear.vue
index 196def2..843471e 100644
--- a/vue/primitives/src/tags-input/TagsInputClear.vue
+++ b/vue/primitives/src/tags-input/TagsInputClear.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that removes every tag at once. No-op when the list is already
+ * empty or the component is disabled.
+ */
 export interface TagsInputClearProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/tags-input/TagsInputInput.vue b/vue/primitives/src/tags-input/TagsInputInput.vue
index 6cbe560..a968d18 100644
--- a/vue/primitives/src/tags-input/TagsInputInput.vue
+++ b/vue/primitives/src/tags-input/TagsInputInput.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The text field where new tags are typed. Commits the current value on Enter,
+ * on the configured delimiter, and (when enabled) on paste, Tab, or blur, and
+ * forwards Backspace/arrow keys to the root for navigating the tag strip.
+ */
 export interface TagsInputInputProps extends PrimitiveProps {
   /** Placeholder text. */
   placeholder?: string;
diff --git a/vue/primitives/src/tags-input/TagsInputItem.vue b/vue/primitives/src/tags-input/TagsInputItem.vue
index 52133a6..9e1c08c 100644
--- a/vue/primitives/src/tags-input/TagsInputItem.vue
+++ b/vue/primitives/src/tags-input/TagsInputItem.vue
@@ -2,6 +2,10 @@
 import type { PrimitiveProps } from '../primitive';
 import type { TagValue } from './context';
 
+/**
+ * A single tag in the strip. Provides item context for its `ItemText` and
+ * `ItemDelete` children and reflects selected/disabled state via data attributes.
+ */
 export interface TagsInputItemProps<U extends TagValue = string> extends PrimitiveProps {
   /** The value associated with this tag. */
   value: U;
diff --git a/vue/primitives/src/tags-input/TagsInputItemDelete.vue b/vue/primitives/src/tags-input/TagsInputItemDelete.vue
index ee5b05d..0bec701 100644
--- a/vue/primitives/src/tags-input/TagsInputItemDelete.vue
+++ b/vue/primitives/src/tags-input/TagsInputItemDelete.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * A button that removes its parent tag from the list when clicked. Render it
+ * inside `TagsInputItem`; it is labelled by the sibling `ItemText`.
+ */
 export interface TagsInputItemDeleteProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/tags-input/TagsInputItemText.vue b/vue/primitives/src/tags-input/TagsInputItemText.vue
index 3a8b733..17c6a41 100644
--- a/vue/primitives/src/tags-input/TagsInputItemText.vue
+++ b/vue/primitives/src/tags-input/TagsInputItemText.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The visible label for a tag. Renders the item's display value and exposes an
+ * id that the surrounding `Item` and `ItemDelete` use for `aria-labelledby`.
+ */
 export interface TagsInputItemTextProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/tags-input/TagsInputRoot.vue b/vue/primitives/src/tags-input/TagsInputRoot.vue
index 0c206f7..ff98c9d 100644
--- a/vue/primitives/src/tags-input/TagsInputRoot.vue
+++ b/vue/primitives/src/tags-input/TagsInputRoot.vue
@@ -2,9 +2,15 @@
 import type { PrimitiveProps } from '../primitive';
 import type { TagValue } from './context';
 
+/**
+ * A headless tags / token input: type a value, commit it on Enter (or paste,
+ * Tab, blur, or a custom delimiter), and manage the resulting list of tags with
+ * full keyboard navigation, duplicate/max guards, and accessible labelling.
+ * Use it for free-form multi-value entry such as email recipients, keywords,
+ * skills, or filter chips. Wraps the `Item`, `ItemText`, `ItemDelete`, `Input`,
+ * and `Clear` parts and provides their shared context.
+ */
 export interface TagsInputRootProps<U extends TagValue = string> extends PrimitiveProps {
-  /** Controlled value. Use `v-model`. */
-  modelValue?: U[];
   /** Uncontrolled initial value. @default [] */
   defaultValue?: U[];
   /** Add on paste (respects `delimiter`). */
@@ -30,7 +36,6 @@ export interface TagsInputRootProps<U extends TagValue = string> extends Primiti
 }
 
 export interface TagsInputRootEmits<U extends TagValue = string> {
-  'update:modelValue': [value: U[]];
   addTag: [value: U];
   removeTag: [value: U];
   invalid: [value: U];
@@ -48,7 +53,6 @@ import { useForwardExpose } from '@robonen/vue';
 
 const {
   as = 'div',
-  modelValue,
   defaultValue,
   addOnPaste = false,
   addOnTab = false,
@@ -64,14 +68,16 @@ const {
 
 const emit = defineEmits<TagsInputRootEmits<T>>();
 
+const model = defineModel<T[]>();
+
 const { forwardRef } = useForwardExpose();
 const config = useConfig();
 const direction = computed(() => dir ?? config.dir.value);
 
 // shallowRef: array is always replaced via commit(), never mutated in place.
-const localValue = shallowRef<T[]>((modelValue ?? defaultValue ?? []).slice()) as Ref<T[]>;
+const localValue = shallowRef<T[]>((model.value ?? defaultValue ?? []).slice()) as Ref<T[]>;
 
-watch(() => modelValue, (v) => {
+watch(model, (v) => {
   if (v === undefined) return;
   const cur = localValue.value;
   if (v.length === cur.length) {
@@ -94,7 +100,7 @@ const { getItems, CollectionSlot } = useCollectionProvider();
 
 function commit(next: T[]): void {
   localValue.value = next;
-  emit('update:modelValue', next);
+  model.value = next;
 }
 
 const convert: (raw: string) => T = convertValue ?? ((raw: string) => raw as unknown as T);
diff --git a/vue/primitives/src/tags-input/demo.vue b/vue/primitives/src/tags-input/demo.vue
new file mode 100644
index 0000000..5f62ced
--- /dev/null
+++ b/vue/primitives/src/tags-input/demo.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import {
+  TagsInputClear,
+  TagsInputInput,
+  TagsInputItem,
+  TagsInputItemDelete,
+  TagsInputItemText,
+  TagsInputRoot,
+} from '@robonen/primitives';
+import { ref } from 'vue';
+
+const recipients = ref<string[]>(['ada@example.com', 'grace@example.com']);
+const wasInvalid = ref(false);
+
+function onInvalid() {
+  wasInvalid.value = true;
+  window.setTimeout(() => {
+    wasInvalid.value = false;
+  }, 1200);
+}
+</script>
+
+<template>
+  <div class="w-full max-w-md rounded-xl border border-(--border) bg-(--bg-elevated) p-6 text-(--fg)">
+    <h3 class="text-base font-semibold">
+      Invite teammates
+    </h3>
+    <p class="mt-1 text-sm text-(--fg-muted)">
+      Type an address and press Enter, comma, or paste a list.
+    </p>
+
+    <TagsInputRoot
+      v-model="recipients"
+      add-on-paste
+      add-on-blur
+      :max="5"
+      delimiter=","
+      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) data-[invalid]:border-red-500 dark:data-[invalid]:border-red-400"
+      @invalid="onInvalid"
+    >
+      <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)"
+      >
+        <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)"
+          aria-label="Remove"
+        >
+          <svg width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden="true">
+            <path d="M1 1l8 8M9 1l-8 8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+          </svg>
+        </TagsInputItemDelete>
+      </TagsInputItem>
+
+      <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)"
+      />
+    </TagsInputRoot>
+
+    <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)'"
+      >
+        <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"
+      >
+        Clear all
+      </TagsInputClear>
+    </div>
+  </div>
+</template>
diff --git a/vue/primitives/src/teleport/Teleport.vue b/vue/primitives/src/teleport/Teleport.vue
index 650f6b7..be7a9d3 100644
--- a/vue/primitives/src/teleport/Teleport.vue
+++ b/vue/primitives/src/teleport/Teleport.vue
@@ -1,4 +1,11 @@
 <script lang="ts">
+/**
+ * Renders its slot content into a different part of the DOM (a portal), wrapping
+ * Vue's built-in `<Teleport>` with SSR-safe defaults and a configurable target.
+ * Use it as the building block for overlay primitives (dialogs, popovers, toasts)
+ * that must escape parent overflow/stacking contexts; the target defaults to the
+ * `teleportTarget` from `ConfigProvider` (`body` unless overridden).
+ */
 export interface TeleportPrimitiveProps {
   /**
    * Target DOM node or CSS selector. When `null`/`undefined`, Vue's built-in
diff --git a/vue/primitives/src/toast/ToastAction.vue b/vue/primitives/src/toast/ToastAction.vue
index b8423d4..0cae5d4 100644
--- a/vue/primitives/src/toast/ToastAction.vue
+++ b/vue/primitives/src/toast/ToastAction.vue
@@ -1,6 +1,11 @@
 <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).
diff --git a/vue/primitives/src/toast/ToastClose.vue b/vue/primitives/src/toast/ToastClose.vue
index 23caa47..10992d7 100644
--- a/vue/primitives/src/toast/ToastClose.vue
+++ b/vue/primitives/src/toast/ToastClose.vue
@@ -1,6 +1,10 @@
 <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>
 
diff --git a/vue/primitives/src/toast/ToastDescription.vue b/vue/primitives/src/toast/ToastDescription.vue
index 52f23e4..e98c45a 100644
--- a/vue/primitives/src/toast/ToastDescription.vue
+++ b/vue/primitives/src/toast/ToastDescription.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The toast's supporting text. Renders the longer description beneath the
+ * `ToastTitle`, placed inside a `ToastRoot`.
+ */
 export interface ToastDescriptionProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/toast/ToastProvider.vue b/vue/primitives/src/toast/ToastProvider.vue
index 6ee0489..fd659ef 100644
--- a/vue/primitives/src/toast/ToastProvider.vue
+++ b/vue/primitives/src/toast/ToastProvider.vue
@@ -1,14 +1,36 @@
 <script lang="ts">
 import type { SwipeDirection } from './context';
 
+/**
+ * Toast — a succinct, non-disruptive notification that appears in a corner of the
+ * screen and auto-dismisses after a timeout. Use it to confirm actions or surface
+ * 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.
+ */
 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. @default 'right' */
+  /**
+   * 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'
+   */
   swipeDirection?: SwipeDirection;
-  /** Minimum swipe distance before a dismiss gesture is recognised. @default 50 */
+  /**
+   * 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
+   */
   swipeThreshold?: number;
 }
 </script>
diff --git a/vue/primitives/src/toast/ToastRoot.vue b/vue/primitives/src/toast/ToastRoot.vue
index 4f7fe00..6c27ff8 100644
--- a/vue/primitives/src/toast/ToastRoot.vue
+++ b/vue/primitives/src/toast/ToastRoot.vue
@@ -1,6 +1,12 @@
 <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;
@@ -9,7 +15,6 @@ export interface ToastRootProps extends PrimitiveProps {
 }
 
 export interface ToastRootEmits {
-  'update:open': [open: boolean];
   escapeKeyDown: [event: KeyboardEvent];
   pause: [];
   resume: [];
@@ -57,13 +62,19 @@ function startTimer(ms: number) {
   if (ms === Infinity || ms <= 0 || !Number.isFinite(ms)) return;
   closeTimer = setTimeout(() => {
     open.value = false;
-    emit('update:open', false);
   }, ms);
 }
 
 function handleClose() {
   open.value = false;
-  emit('update:open', 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() {
@@ -132,7 +143,7 @@ provideToastContext({
       :data-state="open ? 'open' : 'closed'"
       :data-type="type"
       tabindex="-1"
-      @keydown.escape="emit('escapeKeyDown', $event)"
+      @keydown.escape="handleEscapeKeyDown"
     >
       <slot />
     </Primitive>
diff --git a/vue/primitives/src/toast/ToastTitle.vue b/vue/primitives/src/toast/ToastTitle.vue
index e78021e..b6470a6 100644
--- a/vue/primitives/src/toast/ToastTitle.vue
+++ b/vue/primitives/src/toast/ToastTitle.vue
@@ -1,6 +1,10 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * The toast's heading. Renders the short, prominent line that names the
+ * notification, placed inside a `ToastRoot`.
+ */
 export interface ToastTitleProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/toast/ToastViewport.vue b/vue/primitives/src/toast/ToastViewport.vue
index 810110c..b754aff 100644
--- a/vue/primitives/src/toast/ToastViewport.vue
+++ b/vue/primitives/src/toast/ToastViewport.vue
@@ -1,6 +1,11 @@
 <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;
diff --git a/vue/primitives/src/toast/demo.vue b/vue/primitives/src/toast/demo.vue
new file mode 100644
index 0000000..9190dfa
--- /dev/null
+++ b/vue/primitives/src/toast/demo.vue
@@ -0,0 +1,110 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  ToastAction,
+  ToastClose,
+  ToastDescription,
+  ToastProvider,
+  ToastRoot,
+  ToastTitle,
+  ToastViewport,
+} from '@robonen/primitives';
+
+interface ToastItem {
+  id: number;
+  title: string;
+  description: string;
+  open: boolean;
+}
+
+const toasts = ref<ToastItem[]>([]);
+let nextId = 0;
+
+function notify() {
+  const id = nextId++;
+  toasts.value.push({
+    id,
+    title: 'Message archived',
+    description: 'Moved "Weekly digest" to your archive.',
+    open: true,
+  });
+}
+
+function undo(id: number) {
+  const toast = toasts.value.find((t) => t.id === id);
+  if (toast) toast.open = false;
+}
+
+// Drop a toast from the list once it has fully closed.
+function remove(id: number) {
+  toasts.value = toasts.value.filter((t) => t.id !== id);
+}
+</script>
+
+<template>
+  <ToastProvider :duration="4000" swipe-direction="right">
+    <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)"
+        @click="notify"
+      >
+        Archive message
+      </button>
+      <p class="text-xs text-(--fg-muted)">
+        Toasts auto-dismiss after 4s. Hover the stack to pause the timer.
+      </p>
+    </div>
+
+    <ToastRoot
+      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"
+      @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">
+        <svg
+          class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+          stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+        >
+          <path d="M20 6 9 17l-5-5" />
+        </svg>
+      </div>
+
+      <div class="min-w-0 flex-1">
+        <ToastTitle class="text-sm font-semibold text-(--fg)">
+          {{ toast.title }}
+        </ToastTitle>
+        <ToastDescription class="mt-0.5 text-sm text-(--fg-muted)">
+          {{ toast.description }}
+        </ToastDescription>
+      </div>
+
+      <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)"
+          @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)"
+        >
+          <svg
+            class="size-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+            stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"
+          >
+            <path d="M18 6 6 18M6 6l12 12" />
+          </svg>
+        </ToastClose>
+      </div>
+    </ToastRoot>
+
+    <ToastViewport
+      class="fixed bottom-4 right-4 z-50 flex w-[min(92vw,22rem)] flex-col gap-2 outline-none"
+    />
+  </ToastProvider>
+</template>
diff --git a/vue/primitives/src/toggle-group/ToggleGroupItem.vue b/vue/primitives/src/toggle-group/ToggleGroupItem.vue
index adaa293..608f37f 100644
--- a/vue/primitives/src/toggle-group/ToggleGroupItem.vue
+++ b/vue/primitives/src/toggle-group/ToggleGroupItem.vue
@@ -1,5 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
+/**
+ * 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.
+ */
 export interface ToggleGroupItemProps extends PrimitiveProps {
   value: string;
   disabled?: boolean;
diff --git a/vue/primitives/src/toggle-group/ToggleGroupRoot.vue b/vue/primitives/src/toggle-group/ToggleGroupRoot.vue
index d08587a..526711e 100644
--- a/vue/primitives/src/toggle-group/ToggleGroupRoot.vue
+++ b/vue/primitives/src/toggle-group/ToggleGroupRoot.vue
@@ -3,9 +3,18 @@ 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;
-  modelValue?: string | string[];
   defaultValue?: string | string[];
   disabled?: boolean;
   orientation?: 'horizontal' | 'vertical';
@@ -15,13 +24,12 @@ export interface ToggleGroupRootProps extends PrimitiveProps {
 }
 
 export interface ToggleGroupRootEmits {
-  'update:modelValue': [value: string | string[] | undefined];
   valueChange: [value: string | string[]];
 }
 </script>
 
 <script setup lang="ts">
-import { computed, ref, toRef, watch } from 'vue';
+import { computed, toRef } from 'vue';
 import { resolveNextIndex, rovingKeyToAction } from '../utils/roving-focus';
 import { useCollectionProvider } from '../collection';
 import { useForwardExpose } from '@robonen/vue';
@@ -35,7 +43,6 @@ const {
   dir = 'ltr',
   loop = true,
   rovingFocus = true,
-  modelValue,
   defaultValue,
   as = 'div',
 } = defineProps<ToggleGroupRootProps>();
@@ -44,32 +51,29 @@ 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];
 }
 
-const localValue = ref<string[]>(
-  normalize(modelValue).length > 0 ? normalize(modelValue) : normalize(defaultValue),
-);
+// Seed the uncontrolled default once; defineModel owns state thereafter.
+if (model.value === undefined && defaultValue !== undefined)
+  model.value = defaultValue;
 
-watch(() => modelValue, (v) => {
-  if (v === undefined) return;
-  const n = normalize(v);
-  if (n.length === localValue.value.length && n.every((x, i) => x === localValue.value[i])) return;
-  localValue.value = n;
-});
+// Normalized string[] view of the public model (string | string[] | undefined).
+const localValue = computed<string[]>(() => normalize(model.value));
 
 function emitValue(next: string[]): void {
-  localValue.value = next;
   if (type === 'single') {
     const v = next[0];
-    emit('update:modelValue', v);
+    model.value = v;
     emit('valueChange', v ?? '');
   }
   else {
-    emit('update:modelValue', next);
+    model.value = next;
     emit('valueChange', next);
   }
 }
diff --git a/vue/primitives/src/toggle-group/demo.vue b/vue/primitives/src/toggle-group/demo.vue
new file mode 100644
index 0000000..18cb933
--- /dev/null
+++ b/vue/primitives/src/toggle-group/demo.vue
@@ -0,0 +1,77 @@
+<script setup lang="ts">
+import { ToggleGroupItem, ToggleGroupRoot } from '@robonen/primitives';
+import { ref } from 'vue';
+
+// `type="multiple"` → v-model is a string[] of every pressed value.
+const formatting = ref<string[]>(['bold']);
+
+const marks = [
+  { value: 'bold', label: 'B', title: 'Bold', class: 'font-bold' },
+  { value: 'italic', label: 'I', title: 'Italic', class: 'italic' },
+  { value: 'underline', label: 'U', title: 'Underline', class: 'underline' },
+];
+
+// `type="single"` → v-model is a single string (empty when nothing is pressed).
+const align = ref('left');
+
+const alignments = [
+  { value: 'left', title: 'Align left', label: 'L' },
+  { value: 'center', title: 'Align center', label: 'C' },
+  { value: 'right', title: 'Align right', label: 'R' },
+];
+</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-2">
+      <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)"
+      >
+        <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="m.class"
+        >
+          {{ m.label }}
+        </ToggleGroupItem>
+      </ToggleGroupRoot>
+    </div>
+
+    <div class="flex flex-col gap-2">
+      <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)"
+      >
+        <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)"
+        >
+          {{ a.label }}
+        </ToggleGroupItem>
+      </ToggleGroupRoot>
+    </div>
+
+    <p
+      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') },
+        { 'underline': formatting.includes('underline') },
+        align === 'center' ? 'text-center' : align === 'right' ? 'text-right' : 'text-left',
+      ]"
+    >
+      The quick brown fox.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/toggle/Toggle.vue b/vue/primitives/src/toggle/Toggle.vue
index a148a61..974403d 100644
--- a/vue/primitives/src/toggle/Toggle.vue
+++ b/vue/primitives/src/toggle/Toggle.vue
@@ -1,6 +1,16 @@
 <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. */
diff --git a/vue/primitives/src/toggle/demo.vue b/vue/primitives/src/toggle/demo.vue
new file mode 100644
index 0000000..edc6bf6
--- /dev/null
+++ b/vue/primitives/src/toggle/demo.vue
@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import { Toggle } from '@robonen/primitives';
+import { computed, ref } from 'vue';
+
+const bold = ref(true);
+const italic = ref(false);
+const underline = ref(false);
+
+const sampleClass = computed(() => [
+  bold.value && 'font-bold',
+  italic.value && 'italic',
+  underline.value && 'underline',
+]);
+</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">
+      <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)"
+      >
+        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)"
+      >
+        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)"
+      >
+        U
+      </Toggle>
+
+      <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"
+      >
+        S
+      </Toggle>
+    </div>
+
+    <p
+      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.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/toolbar/ToolbarButton.vue b/vue/primitives/src/toolbar/ToolbarButton.vue
index 9f6f5eb..eed7072 100644
--- a/vue/primitives/src/toolbar/ToolbarButton.vue
+++ b/vue/primitives/src/toolbar/ToolbarButton.vue
@@ -1,5 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../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.
+ */
 export interface ToolbarButtonProps extends PrimitiveProps {
 
   disabled?: boolean;
diff --git a/vue/primitives/src/toolbar/ToolbarRoot.vue b/vue/primitives/src/toolbar/ToolbarRoot.vue
index 984debf..44a07d4 100644
--- a/vue/primitives/src/toolbar/ToolbarRoot.vue
+++ b/vue/primitives/src/toolbar/ToolbarRoot.vue
@@ -2,6 +2,16 @@
 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;
diff --git a/vue/primitives/src/toolbar/ToolbarSeparator.vue b/vue/primitives/src/toolbar/ToolbarSeparator.vue
index 15c3b28..16cbb11 100644
--- a/vue/primitives/src/toolbar/ToolbarSeparator.vue
+++ b/vue/primitives/src/toolbar/ToolbarSeparator.vue
@@ -1,5 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../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.
+ */
 export interface ToolbarSeparatorProps extends PrimitiveProps {
   orientation?: 'horizontal' | 'vertical';
 
diff --git a/vue/primitives/src/toolbar/demo.vue b/vue/primitives/src/toolbar/demo.vue
new file mode 100644
index 0000000..4bf9173
--- /dev/null
+++ b/vue/primitives/src/toolbar/demo.vue
@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import { ToolbarButton, ToolbarRoot, ToolbarSeparator } from '@robonen/primitives';
+import { ref } from 'vue';
+
+// Track which formatting marks are "on" so the toolbar reflects active state.
+const marks = ref<Record<string, boolean>>({ bold: true, italic: false });
+
+function toggle(mark: string): void {
+  marks.value[mark] = !marks.value[mark];
+}
+
+const align = ref('left');
+const alignments = [
+  { value: 'left', title: 'Align left', icon: 'i-ph-text-align-left' },
+  { value: 'center', title: 'Align center', icon: 'i-ph-text-align-center' },
+  { value: 'right', title: 'Align right', icon: 'i-ph-text-align-right' },
+];
+</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)">
+    <ToolbarRoot
+      class="flex w-fit items-center gap-1 rounded-lg border border-(--border) bg-(--bg-inset) p-1"
+      aria-label="Text formatting"
+    >
+      <ToolbarButton
+        v-for="m in ['bold', 'italic', 'underline']"
+        :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)',
+        ]"
+        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
+          :class="{
+            'i-ph-text-b-bold': m === 'bold',
+            'i-ph-text-italic': m === 'italic',
+            'i-ph-text-underline': m === 'underline',
+          }"
+          class="h-4 w-4"
+        />
+      </ToolbarButton>
+
+      <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)',
+        ]"
+        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)" />
+
+      <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"
+      >
+        <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="[
+        { 'font-bold': marks.bold },
+        { 'italic': marks.italic },
+        { 'underline': marks.underline },
+        align === 'center' ? 'text-center' : align === 'right' ? 'text-right' : 'text-left',
+      ]"
+    >
+      Tab into the toolbar, then use the arrow keys to move between controls.
+    </p>
+  </div>
+</template>
diff --git a/vue/primitives/src/tooltip/TooltipArrow.vue b/vue/primitives/src/tooltip/TooltipArrow.vue
index 9c2bb22..1a0d365 100644
--- a/vue/primitives/src/tooltip/TooltipArrow.vue
+++ b/vue/primitives/src/tooltip/TooltipArrow.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { PopperArrowProps } from '../popper';
 
+/**
+ * An optional pointer rendered inside Content that visually connects the
+ * tooltip to its Trigger. Place it as a child of `TooltipContent`; it tracks
+ * the resolved side and alignment automatically.
+ */
 export interface TooltipArrowProps extends PopperArrowProps {}
 </script>
 
diff --git a/vue/primitives/src/tooltip/TooltipContent.vue b/vue/primitives/src/tooltip/TooltipContent.vue
index 5d52e97..9ec537d 100644
--- a/vue/primitives/src/tooltip/TooltipContent.vue
+++ b/vue/primitives/src/tooltip/TooltipContent.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { TooltipContentImplEmits, TooltipContentImplProps } from './TooltipContentImpl.vue';
 
+/**
+ * The floating panel that holds the tooltip's label, positioned relative to the
+ * Trigger. It mounts only while the tooltip is open (driven by `Presence`); set
+ * `forceMount` to keep it mounted for CSS exit animations. Side, alignment, and
+ * collision behavior are forwarded to the underlying Popper content.
+ */
 export interface TooltipContentProps extends TooltipContentImplProps {
   /** Keep mounted for CSS exit animations. */
   forceMount?: boolean;
diff --git a/vue/primitives/src/tooltip/TooltipContentImpl.vue b/vue/primitives/src/tooltip/TooltipContentImpl.vue
index 44d769e..d2c59b1 100644
--- a/vue/primitives/src/tooltip/TooltipContentImpl.vue
+++ b/vue/primitives/src/tooltip/TooltipContentImpl.vue
@@ -2,6 +2,12 @@
 import type { PopperContentProps } from '../popper';
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Internal implementation behind `TooltipContent`: renders the Popper content
+ * inside a dismissable layer, exposes the positioning props, mirrors the popper
+ * CSS variables, and adds the hidden `role="tooltip"` accessible label. Use
+ * `TooltipContent` instead — this is not part of the public anatomy.
+ */
 export interface TooltipContentImplProps extends PrimitiveProps, Pick<
   PopperContentProps,
   | 'side'
diff --git a/vue/primitives/src/tooltip/TooltipPortal.vue b/vue/primitives/src/tooltip/TooltipPortal.vue
index 45bfc25..f126d14 100644
--- a/vue/primitives/src/tooltip/TooltipPortal.vue
+++ b/vue/primitives/src/tooltip/TooltipPortal.vue
@@ -1,6 +1,11 @@
 <script lang="ts">
 import type { TeleportPrimitiveProps } from '../teleport';
 
+/**
+ * Teleports the tooltip Content into another part of the DOM (the body by
+ * default) so it escapes parent `overflow`/`transform`/`z-index` stacking
+ * contexts. Wrap Content in a Portal when those clipping issues occur.
+ */
 export interface TooltipPortalProps extends TeleportPrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/tooltip/TooltipProvider.vue b/vue/primitives/src/tooltip/TooltipProvider.vue
index a4ebade..b7be496 100644
--- a/vue/primitives/src/tooltip/TooltipProvider.vue
+++ b/vue/primitives/src/tooltip/TooltipProvider.vue
@@ -1,4 +1,11 @@
 <script lang="ts">
+/**
+ * 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
+ * have a Provider ancestor. It governs the hover `delayDuration` and the
+ * `skipDelayDuration` window that lets neighboring tooltips open instantly once
+ * one has shown, plus group-wide defaults each `TooltipRoot` may override.
+ */
 export interface TooltipProviderProps {
   /**
    * Hover delay before opening, in ms.
diff --git a/vue/primitives/src/tooltip/TooltipRoot.vue b/vue/primitives/src/tooltip/TooltipRoot.vue
index fa784cb..b7ca3d2 100644
--- a/vue/primitives/src/tooltip/TooltipRoot.vue
+++ b/vue/primitives/src/tooltip/TooltipRoot.vue
@@ -1,4 +1,17 @@
 <script lang="ts">
+/**
+ * A small floating label that appears on hover or keyboard focus to describe an
+ * otherwise non-obvious control (such as an icon-only button). Composed from a
+ * Trigger, a Portal, and Content (with an optional Arrow); positioning is handled
+ * by the underlying Popper. Tooltips are pointer/focus driven and non-interactive
+ * by design — reach for Popover when the overlay needs focusable content.
+ *
+ * Root owns the per-tooltip open state and provides context to every part. Each
+ * Root must live inside a `TooltipProvider`, which supplies shared delay/skip
+ * timing for a group of tooltips. Bind `v-model:open` to control it, or rely on
+ * the Trigger for uncontrolled use. Props here override the matching Provider
+ * defaults for this one tooltip.
+ */
 export interface TooltipRootProps {
   /** Initial open state in uncontrolled mode. */
   defaultOpen?: boolean;
diff --git a/vue/primitives/src/tooltip/TooltipTrigger.vue b/vue/primitives/src/tooltip/TooltipTrigger.vue
index 6326d66..011fbf5 100644
--- a/vue/primitives/src/tooltip/TooltipTrigger.vue
+++ b/vue/primitives/src/tooltip/TooltipTrigger.vue
@@ -1,6 +1,12 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../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.
+ */
 export interface TooltipTriggerProps extends PrimitiveProps {}
 </script>
 
diff --git a/vue/primitives/src/tooltip/demo.vue b/vue/primitives/src/tooltip/demo.vue
new file mode 100644
index 0000000..5c9cc20
--- /dev/null
+++ b/vue/primitives/src/tooltip/demo.vue
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import {
+  TooltipArrow,
+  TooltipContent,
+  TooltipPortal,
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+} from '@robonen/primitives';
+
+const actions = [
+  {
+    label: 'Bold',
+    side: 'top' as const,
+    path: 'M6 4h7a4 4 0 0 1 0 8H6zm0 8h8a4 4 0 0 1 0 8H6z',
+  },
+  {
+    label: 'Italic',
+    side: 'top' as const,
+    path: 'M19 4h-9M14 20H5M15 4 9 20',
+  },
+  {
+    label: 'Add link',
+    side: 'top' as const,
+    path: 'M10 13a5 5 0 0 0 7.07 0l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71M14 11a5 5 0 0 0-7.07 0l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71',
+  },
+];
+</script>
+
+<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)">
+      <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)"
+        >
+          <svg
+            class="size-4.5" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+            stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"
+          >
+            <path :d="action.path" />
+          </svg>
+        </TooltipTrigger>
+
+        <TooltipPortal>
+          <TooltipContent
+            :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"
+          >
+            {{ 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)" />
+              </svg>
+            </TooltipArrow>
+          </TooltipContent>
+        </TooltipPortal>
+      </TooltipRoot>
+    </div>
+  </TooltipProvider>
+</template>
diff --git a/vue/primitives/src/tree/TreeItem.vue b/vue/primitives/src/tree/TreeItem.vue
index 82891b6..928cb8a 100644
--- a/vue/primitives/src/tree/TreeItem.vue
+++ b/vue/primitives/src/tree/TreeItem.vue
@@ -2,6 +2,13 @@
 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>;
diff --git a/vue/primitives/src/tree/TreeRoot.vue b/vue/primitives/src/tree/TreeRoot.vue
index 4726f8f..73cb566 100644
--- a/vue/primitives/src/tree/TreeRoot.vue
+++ b/vue/primitives/src/tree/TreeRoot.vue
@@ -2,6 +2,19 @@
 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[];
@@ -9,12 +22,8 @@ export interface TreeRootProps<U = unknown> extends PrimitiveProps {
   getKey: (item: U) => string;
   /** Return the children of an item, or `undefined` if it is a leaf. */
   getChildren?: (item: U) => readonly U[] | undefined | null;
-  /** Controlled selected key(s). Use `v-model`. */
-  modelValue?: string | string[];
   /** Uncontrolled initial selected key(s). */
   defaultValue?: string | string[];
-  /** Controlled expanded keys. Use `v-model:expanded`. */
-  expanded?: string[];
   /** Uncontrolled initial expanded keys. */
   defaultExpanded?: string[];
   /** Allow selecting multiple items. @default false */
@@ -26,11 +35,6 @@ export interface TreeRootProps<U = unknown> extends PrimitiveProps {
   /** When `true`, selecting a parent also selects all of its descendants (requires `multiple`). */
   propagateSelect?: boolean;
 }
-
-export interface TreeRootEmits {
-  'update:modelValue': [value: string | string[] | undefined];
-  'update:expanded': [value: string[]];
-}
 </script>
 
 <script setup lang="ts" generic="T">
@@ -53,9 +57,7 @@ const {
   items,
   getKey,
   getChildren = ((item: any) => item?.children) as (item: T) => readonly T[] | undefined | null,
-  modelValue,
   defaultValue,
-  expanded,
   defaultExpanded,
   multiple = false,
   disabled = false,
@@ -63,7 +65,8 @@ const {
   propagateSelect = false,
 } = defineProps<TreeRootProps<T>>();
 
-const emit = defineEmits<TreeRootEmits>();
+const selectedModel = defineModel<string | string[] | undefined>();
+const expandedModel = defineModel<string[]>('expanded');
 
 const { forwardRef } = useForwardExpose();
 const config = useConfig();
@@ -79,10 +82,10 @@ function normalize(v: string | string[] | undefined): string[] {
 // --- Selection state ------------------------------------------------------
 
 const localSelected = ref<string[]>(
-  modelValue !== undefined ? normalize(modelValue) : normalize(defaultValue),
+  selectedModel.value !== undefined ? normalize(selectedModel.value) : normalize(defaultValue),
 );
 
-watch(() => modelValue, (v) => {
+watch(selectedModel, (v) => {
   if (v === undefined) return;
   const arr = normalize(v);
   const cur = localSelected.value;
@@ -92,7 +95,7 @@ watch(() => modelValue, (v) => {
 
 function commitSelected(next: string[]): void {
   localSelected.value = next;
-  emit('update:modelValue', multiple ? next : next[0]);
+  selectedModel.value = multiple ? next : next[0];
 }
 
 // O(1) membership lookup — replaces linear `.includes()` that was called once
@@ -168,10 +171,10 @@ function select(value: T): void {
 // --- Expanded state -------------------------------------------------------
 
 const localExpanded = ref<string[]>(
-  expanded !== undefined ? [...expanded] : [...(defaultExpanded ?? [])],
+  expandedModel.value !== undefined ? [...expandedModel.value] : [...(defaultExpanded ?? [])],
 );
 
-watch(() => expanded, (v) => {
+watch(expandedModel, (v) => {
   if (v === undefined) return;
   const cur = localExpanded.value;
   if (v.length === cur.length && v.every((x, i) => x === cur[i])) return;
@@ -186,7 +189,7 @@ function isExpanded(key: string): boolean {
 
 function commitExpanded(next: string[]): void {
   localExpanded.value = next;
-  emit('update:expanded', next);
+  expandedModel.value = next;
 }
 
 function toggleExpanded(value: T): void {
diff --git a/vue/primitives/src/tree/demo.vue b/vue/primitives/src/tree/demo.vue
new file mode 100644
index 0000000..05c4ea1
--- /dev/null
+++ b/vue/primitives/src/tree/demo.vue
@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TreeItem, TreeRoot } from '@robonen/primitives';
+
+interface Node {
+  key: string;
+  label: string;
+  children?: Node[];
+}
+
+const items: Node[] = [
+  {
+    key: 'src',
+    label: 'src',
+    children: [
+      {
+        key: 'components',
+        label: 'components',
+        children: [
+          { key: 'button.vue', label: 'Button.vue' },
+          { key: 'input.vue', label: 'Input.vue' },
+        ],
+      },
+      {
+        key: 'composables',
+        label: 'composables',
+        children: [
+          { key: 'use-tree.ts', label: 'useTree.ts' },
+          { key: 'use-theme.ts', label: 'useTheme.ts' },
+        ],
+      },
+      { key: 'main.ts', label: 'main.ts' },
+    ],
+  },
+  {
+    key: 'public',
+    label: 'public',
+    children: [{ key: 'favicon.ico', label: 'favicon.ico' }],
+  },
+  { key: 'readme.md', label: 'README.md' },
+];
+
+const selected = ref<string>('button.vue');
+const expanded = ref<string[]>(['src', 'components']);
+</script>
+
+<template>
+  <TreeRoot
+    v-model="selected"
+    v-model:expanded="expanded"
+    :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)"
+  >
+    <template #default="{ flatItems }">
+      <TreeItem
+        v-for="item in flatItems"
+        :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)"
+      >
+        <template #default="{ isExpanded }">
+          <svg
+            v-if="item.hasChildren"
+            class="size-3.5 shrink-0 text-(--fg-subtle) transition-transform duration-150"
+            :class="{ 'rotate-90': isExpanded }"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2.5"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <polyline points="9 6 15 12 9 18" />
+          </svg>
+          <svg
+            v-else
+            class="size-3.5 shrink-0 text-(--fg-subtle)"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+            <polyline points="14 2 14 8 20 8" />
+          </svg>
+          <span class="truncate">{{ item.value.label }}</span>
+        </template>
+      </TreeItem>
+    </template>
+  </TreeRoot>
+</template>
diff --git a/vue/primitives/src/tree/index.ts b/vue/primitives/src/tree/index.ts
index 5578b13..50009fa 100644
--- a/vue/primitives/src/tree/index.ts
+++ b/vue/primitives/src/tree/index.ts
@@ -3,7 +3,7 @@ export { default as TreeItem } from './TreeItem.vue';
 
 export { useTreeContext, provideTreeContext } from './context';
 
-export type { TreeRootProps, TreeRootEmits } from './TreeRoot.vue';
+export type { TreeRootProps } from './TreeRoot.vue';
 export type { TreeItemProps } from './TreeItem.vue';
 export type { TreeContext } from './context';
 export type { FlatItem } from './utils';
diff --git a/vue/primitives/src/visually-hidden/VisuallyHidden.vue b/vue/primitives/src/visually-hidden/VisuallyHidden.vue
index 80357bd..b83f03f 100644
--- a/vue/primitives/src/visually-hidden/VisuallyHidden.vue
+++ b/vue/primitives/src/visually-hidden/VisuallyHidden.vue
@@ -1,11 +1,20 @@
 <script lang="ts">
 import type { PrimitiveProps } from '../primitive';
 
+/**
+ * Visually hides its content while keeping it available to assistive
+ * technology. The element is removed from the visual layout but stays in the
+ * accessibility tree (and remains focusable) so screen readers can still
+ * announce it. Use it for accessible labels, status text, or skip links that
+ * should be heard but not seen — for example a hidden heading, an icon-only
+ * button's name, or extra context for a control.
+ */
 export interface VisuallyHiddenProps extends PrimitiveProps {
   /**
-   * Exclude the element from the accessibility tree entirely.
-   * Useful when the content is purely decorative and must not be announced.
-   * @default false
+   * How the content participates: `'focusable'` keeps it in the accessibility
+   * tree and focusable (visually hidden only — e.g. skip links); `'hidden'`
+   * additionally hides it from layout and focus.
+   * @default 'focusable'
    */
   feature?: 'focusable' | 'hidden';
 }
diff --git a/vue/primitives/src/visually-hidden/demo.vue b/vue/primitives/src/visually-hidden/demo.vue
new file mode 100644
index 0000000..1c90d69
--- /dev/null
+++ b/vue/primitives/src/visually-hidden/demo.vue
@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import { VisuallyHidden } from '@robonen/primitives';
+import { ref } from 'vue';
+
+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="flex flex-col gap-1">
+      <h3 class="text-sm font-semibold">
+        Icon-only buttons
+      </h3>
+      <p class="text-sm text-(--fg-muted)">
+        Each button shows only an icon, but exposes a real accessible name to screen readers.
+      </p>
+    </div>
+
+    <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)"
+        @click="count -= 1"
+      >
+        <span
+          aria-hidden="true"
+          class="text-base leading-none"
+        >&minus;</span>
+        <VisuallyHidden>Decrease quantity</VisuallyHidden>
+      </button>
+
+      <span class="min-w-8 text-center text-sm font-medium tabular-nums">
+        {{ count }}
+      </span>
+
+      <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)"
+        @click="count += 1"
+      >
+        <span
+          aria-hidden="true"
+          class="text-base leading-none"
+        >+</span>
+        <VisuallyHidden>Increase quantity</VisuallyHidden>
+      </button>
+    </div>
+
+    <p class="text-sm text-(--fg-subtle)">
+      Quantity is now
+      <span class="font-medium text-(--fg)">{{ count }}</span>.
+      <VisuallyHidden
+        as="span"
+        aria-live="polite"
+      >
+        Quantity changed to {{ count }}.
+      </VisuallyHidden>
+    </p>
+  </div>
+</template>
diff --git a/vue/toolkit/src/composables/forms/index.ts b/vue/toolkit/src/composables/forms/index.ts
index 3c9d55a..dcd1001 100644
--- a/vue/toolkit/src/composables/forms/index.ts
+++ b/vue/toolkit/src/composables/forms/index.ts
@@ -1,4 +1,7 @@
+export * from './mask';
 export * from './useField';
 export * from './useFieldArray';
 export * from './useForm';
 export * from './useFormContext';
+export * from './useMaskedField';
+export * from './useMaskedInput';
diff --git a/vue/toolkit/src/composables/forms/mask/conform.ts b/vue/toolkit/src/composables/forms/mask/conform.ts
new file mode 100644
index 0000000..c0a8ef5
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/conform.ts
@@ -0,0 +1,265 @@
+import { clamp, isFunction } from '@robonen/stdlib';
+import type { ElementState, Mask, MaskExpression, OverwriteMode } from './types';
+
+/**
+ * Resolve a (possibly dynamic) mask to a concrete {@link MaskExpression}.
+ */
+export function resolveMask(mask: Mask, state: ElementState): MaskExpression {
+  return isFunction(mask) ? mask(state) : mask;
+}
+
+/**
+ * Whether a mask slot is a fixed (literal) character rather than a matcher.
+ */
+export function isFixedCharacter(slot: RegExp | string): slot is string {
+  return typeof slot === 'string';
+}
+
+/**
+ * Whether `value` is a valid (possibly partial) prefix of the mask. Used as the
+ * conform fast-path and to derive a `complete` signal at full length.
+ */
+export function validateValueWithMask(value: string, mask: MaskExpression): boolean {
+  if (mask instanceof RegExp)
+    return mask.test(value);
+
+  if (value.length > mask.length)
+    return false;
+
+  for (let i = 0; i < value.length; i++) {
+    const slot = mask[i];
+    const char = value[i];
+
+    if (slot === undefined || char === undefined)
+      return false;
+
+    if (isFixedCharacter(slot)) {
+      if (char !== slot)
+        return false;
+    }
+    else if (!slot.test(char)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Whether `value` fully satisfies the mask (array: every slot filled).
+ */
+export function isMaskComplete(value: string, mask: MaskExpression): boolean {
+  if (mask instanceof RegExp)
+    return mask.test(value);
+
+  return value.length === mask.length && validateValueWithMask(value, mask);
+}
+
+/**
+ * Collect the contiguous run of fixed (literal) characters starting at
+ * `startIndex`, stopping at the first matcher slot or the end of the mask. These
+ * are auto-inserted before the next typed character (and a literal the user
+ * happens to type is harmlessly dropped at the following matcher slot).
+ */
+export function collectFixedCharacters(mask: ReadonlyArray<RegExp | string>, startIndex: number): string {
+  let fixed = '';
+
+  for (let i = startIndex; i < mask.length; i++) {
+    const slot = mask[i];
+
+    if (slot === undefined || !isFixedCharacter(slot))
+      break;
+
+    fixed += slot;
+  }
+
+  return fixed;
+}
+
+/**
+ * Conform a value to an array mask slot-by-slot: auto-insert fixed characters,
+ * accept matcher slots one character at a time, drop characters that don't fit,
+ * and track the caret in masked-output coordinates.
+ */
+export function guessValidValueByPattern(
+  state: ElementState,
+  mask: ReadonlyArray<RegExp | string>,
+): ElementState {
+  const { value, selection } = state;
+  const [from, to] = selection;
+
+  let built = '';
+  let maskedFrom: number | null = null;
+  let maskedTo: number | null = null;
+
+  for (let i = 0; i <= value.length; i++) {
+    if (maskedFrom === null && i >= from)
+      maskedFrom = built.length;
+    if (maskedTo === null && i >= to)
+      maskedTo = built.length;
+
+    if (i === value.length)
+      break;
+
+    const char = value[i];
+    if (char === undefined)
+      continue;
+
+    built += collectFixedCharacters(mask, built.length);
+
+    const slot = mask[built.length];
+    if (slot === undefined)
+      break;
+
+    if (isFixedCharacter(slot))
+      built += slot;
+    else if (slot.test(char))
+      built += char;
+    // else: the character is rejected (built does not advance).
+  }
+
+  // Eagerly append the run of fixed characters that follows the filled slots
+  // (e.g. the trailing ')' once digits before it are present).
+  const finalValue = built.length > 0
+    ? built + collectFixedCharacters(mask, built.length)
+    : built;
+
+  const end = finalValue.length;
+
+  return {
+    value: finalValue,
+    selection: [clamp(maskedFrom ?? end, 0, end), clamp(maskedTo ?? end, 0, end)],
+  };
+}
+
+/**
+ * Conform a value to a single-RegExp mask: keep the greedy prefix for which the
+ * value still matches, dropping the first character that breaks the pattern.
+ */
+export function guessValidValueByRegExp(state: ElementState, mask: RegExp): ElementState {
+  const { value, selection } = state;
+  const [from, to] = selection;
+
+  let accepted = '';
+  let newFrom = from;
+  let newTo = to;
+
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (char === undefined)
+      continue;
+
+    if (mask.test(accepted + char)) {
+      accepted += char;
+    }
+    else {
+      if (i < from)
+        newFrom -= 1;
+      if (i < to)
+        newTo -= 1;
+    }
+  }
+
+  const end = accepted.length;
+
+  return {
+    value: accepted,
+    selection: [clamp(newFrom, 0, end), clamp(newTo, 0, end)],
+  };
+}
+
+/**
+ * Entry point: conform `state.value` to `mask`. Fast-returns when the value is
+ * already a valid prefix, otherwise dispatches to the array or RegExp guesser.
+ */
+export function calibrateValueByMask(state: ElementState, mask: Mask): ElementState {
+  const expression = resolveMask(mask, state);
+
+  if (validateValueWithMask(state.value, expression))
+    return state;
+
+  if (expression instanceof RegExp)
+    return guessValidValueByRegExp(state, expression);
+
+  return guessValidValueByPattern(state, expression);
+}
+
+/**
+ * Strip fixed mask characters from a (masked) state, returning the raw value and
+ * the selection remapped into that unmasked space. RegExp masks have no fixed
+ * characters, so the state is returned unchanged.
+ */
+export function removeFixedMaskCharacters(state: ElementState, mask: MaskExpression): ElementState {
+  if (mask instanceof RegExp)
+    return state;
+
+  const { value, selection } = state;
+  const [from, to] = selection;
+
+  let unmasked = '';
+  let newFrom = from;
+  let newTo = to;
+
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (char === undefined)
+      continue;
+
+    const slot = mask[i];
+    const fixed = slot !== undefined && isFixedCharacter(slot);
+
+    if (fixed) {
+      if (i < from)
+        newFrom -= 1;
+      if (i < to)
+        newTo -= 1;
+    }
+    else {
+      unmasked += char;
+    }
+  }
+
+  const end = unmasked.length;
+
+  return {
+    value: unmasked,
+    selection: [clamp(newFrom, 0, end), clamp(newTo, 0, end)],
+  };
+}
+
+/**
+ * Resolve a (possibly function) {@link OverwriteMode} to a concrete value.
+ */
+export function resolveOverwriteMode(mode: OverwriteMode, state: ElementState): 'replace' | 'shift' {
+  return isFunction(mode) ? mode(state) : mode;
+}
+
+/**
+ * Under a collapsed caret, `replace` extends the selection to cover the next
+ * `newCharacters.length` characters (so they are overwritten); `shift` leaves it
+ * collapsed (pure insert). An existing range is returned untouched.
+ */
+export function applyOverwriteMode(state: ElementState, newCharacters: string, mode: OverwriteMode): ElementState {
+  const [from, to] = state.selection;
+
+  if (from !== to)
+    return state;
+
+  if (resolveOverwriteMode(mode, state) === 'replace') {
+    return {
+      value: state.value,
+      selection: [from, clamp(from + newCharacters.length, 0, state.value.length)],
+    };
+  }
+
+  return state;
+}
+
+/**
+ * Deep value + selection equality, used as the no-op-change guard.
+ */
+export function areElementStatesEqual(a: ElementState, b: ElementState): boolean {
+  // selection is always a [from, to] tuple — a direct compare avoids isEqual's
+  // per-call WeakMap allocation and deep-equality dispatch on this hot path.
+  return a.value === b.value && a.selection[0] === b.selection[0] && a.selection[1] === b.selection[1];
+}
diff --git a/vue/toolkit/src/composables/forms/mask/index.test.ts b/vue/toolkit/src/composables/forms/mask/index.test.ts
new file mode 100644
index 0000000..839a25e
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/index.test.ts
@@ -0,0 +1,247 @@
+import { describe, expect, it } from 'vitest';
+import {
+  calibrateValueByMask,
+  isMaskComplete,
+  removeFixedMaskCharacters,
+} from './conform';
+import { MASK_NOOP, MaskModel, maskTransform, normalizeMaskOptions, resolveMaskOptions, unmask } from './model';
+import {
+  PHONE_COUNTRIES,
+  maskCardOptions,
+  maskDateOptions,
+  maskFromTemplate,
+  maskNumberOptions,
+  maskPhoneCountryOptions,
+  maskPhoneOptions,
+} from './presets';
+import type { ElementState } from './types';
+
+const PHONE = maskPhoneOptions({ template: '+1 (###) ###-####' });
+
+describe(maskFromTemplate, () => {
+  it('compiles tokens to matchers and keeps literals fixed', () => {
+    const mask = maskFromTemplate('##/##');
+    expect(mask).toHaveLength(5);
+    expect(mask[2]).toBe('/');
+    expect(mask[0]).toBeInstanceOf(RegExp);
+  });
+});
+
+describe('maskTransform — array (phone) mask', () => {
+  it('conforms a full number, inserting all fixed characters', () => {
+    expect(maskTransform('1234567890', PHONE)).toBe('+1 (123) 456-7890');
+  });
+
+  it('does not let a digit be eaten by a literal in the prefix', () => {
+    // The leading literal "+1 (" must be auto-inserted; the typed digits fill slots.
+    expect(maskTransform('12', PHONE)).toBe('+1 (12');
+  });
+
+  it('eagerly appends the trailing separator once a segment is filled', () => {
+    expect(maskTransform('123', PHONE)).toBe('+1 (123) ');
+  });
+
+  it('drops characters that do not fit a matcher slot', () => {
+    expect(maskTransform('1a2', PHONE)).toBe('+1 (12');
+  });
+
+  it('returns empty for empty input (no eager prefix)', () => {
+    expect(maskTransform('', PHONE)).toBe('');
+  });
+});
+
+describe('maskTransform — single RegExp mask', () => {
+  const HEX = { mask: /^#?[0-9a-f]*$/i };
+
+  it('keeps the greedy valid prefix', () => {
+    expect(maskTransform('#1a2zz', HEX)).toBe('#1a2');
+  });
+});
+
+describe('MaskModel — insertion in unmasked space', () => {
+  function model(initial: ElementState) {
+    return new MaskModel(initial, resolveMaskOptions(PHONE));
+  }
+
+  it('inserts a digit and places the caret after it (masked coords)', () => {
+    const m = model({ value: '+1 (12', selection: [6, 6] });
+    m.addCharacters('3');
+    expect(m.value).toBe('+1 (123) ');
+    // caret sits right after the 3rd digit, before the auto-inserted ") "
+    expect(m.selection[0]).toBe(7);
+  });
+
+  it('throws MASK_NOOP when an insertion changes nothing', () => {
+    const m = model({ value: '+1 (123) ', selection: [9, 9] });
+    // typing the auto-present space/paren area produces no change
+    let thrown: unknown;
+    try {
+      m.addCharacters(' ');
+    }
+    catch (error) {
+      thrown = error;
+    }
+    expect(thrown).toBe(MASK_NOOP);
+  });
+});
+
+describe('MaskModel — deletion across fixed characters', () => {
+  function model(initial: ElementState) {
+    return new MaskModel(initial, resolveMaskOptions(PHONE));
+  }
+
+  it('backspacing right after a fixed char deletes the preceding digit', () => {
+    // caret after ")" in "+1 (123) " (index 9). Backspace should remove the "3".
+    const m = model({ value: '+1 (123) ', selection: [9, 9] });
+    m.deleteCharacters(false);
+    expect(m.value).toBe('+1 (12');
+  });
+
+  it('forward-delete removes the next unmasked digit', () => {
+    const m = model({ value: '+1 (123', selection: [5, 5] }); // between 1 and 2
+    m.deleteCharacters(true);
+    expect(m.value).toBe('+1 (13');
+  });
+});
+
+describe(unmask, () => {
+  it('strips fixed characters from an array mask', () => {
+    expect(unmask('+1 (123) 456-7890', PHONE)).toBe('1234567890');
+  });
+
+  it('strips separators from the number preset via its preprocessor', () => {
+    const opts = maskNumberOptions({ thousandSeparator: ',', precision: 2 });
+    expect(unmask('1,234.50', opts)).toBe('1234.50');
+  });
+
+  it('strips date separators', () => {
+    expect(unmask('31/12/2024', maskDateOptions())).toBe('31122024');
+  });
+});
+
+describe(maskDateOptions, () => {
+  it('inserts separators while typing', () => {
+    expect(maskTransform('31122024', maskDateOptions())).toBe('31/12/2024');
+  });
+
+  it('clamps an out-of-range day segment', () => {
+    expect(maskTransform('99122024', maskDateOptions())).toBe('31/12/2024');
+  });
+
+  it('clamps an out-of-range month for mm/dd/yyyy', () => {
+    expect(maskTransform('99012024', maskDateOptions({ mode: 'mm/dd/yyyy' }))).toBe('12/01/2024');
+  });
+
+  it('supports ISO order with a dash separator', () => {
+    expect(maskTransform('20240131', maskDateOptions({ mode: 'yyyy-mm-dd' }))).toBe('2024-01-31');
+  });
+});
+
+describe(maskNumberOptions, () => {
+  it('groups thousands', () => {
+    expect(maskTransform('1234567', maskNumberOptions({ thousandSeparator: ',' }))).toBe('1,234,567');
+  });
+
+  it('keeps a decimal part within precision', () => {
+    expect(maskTransform('1234.567', maskNumberOptions({ thousandSeparator: ',', precision: 2 }))).toBe('1,234.56');
+  });
+
+  it('applies prefix and live max clamp', () => {
+    const opts = maskNumberOptions({ thousandSeparator: ',', prefix: '$', max: 100 });
+    expect(maskTransform('250', opts)).toBe('$100');
+    expect(maskTransform('50', opts)).toBe('$50');
+  });
+
+  it('drops non-numeric characters', () => {
+    expect(maskTransform('12a34', maskNumberOptions())).toBe('1234');
+  });
+});
+
+describe(maskPhoneCountryOptions, () => {
+  // Deterministic format assertions against an explicit country list.
+  const CUSTOM = maskPhoneCountryOptions({
+    countries: [
+      { code: '1', template: '+# (###) ###-####' },
+      { code: '34', template: '+## ### ### ###' },
+      { code: '380', template: '+### (##) ###-##-##' },
+    ],
+  });
+
+  it('formats by the matched dialing code', () => {
+    expect(maskTransform('12345678901', CUSTOM)).toBe('+1 (234) 567-8901');
+    expect(maskTransform('34612345678', CUSTOM)).toBe('+34 612 345 678');
+  });
+
+  it('matches the longest dialing-code prefix (+380, not +3…)', () => {
+    expect(maskTransform('380441234567', CUSTOM)).toBe('+380 (44) 123-45-67');
+  });
+
+  it('uses the fallback template before a code is recognized', () => {
+    expect(maskTransform('999', maskPhoneCountryOptions())).toBe('+999');
+  });
+
+  it('ships a mask for every country and switches by code with the default set', () => {
+    expect(PHONE_COUNTRIES.length).toBeGreaterThan(200);
+    expect(PHONE_COUNTRIES.some(country => country.code === '380')).toBeTruthy();
+    // No dialing code is a prefix of another (NANP territories are normalized to '1').
+    const codes = PHONE_COUNTRIES.map(country => country.code);
+    expect(codes.some(a => codes.some(b => a !== b && b.startsWith(a)))).toBeFalsy();
+
+    const masked = maskTransform('12025550123', maskPhoneCountryOptions());
+    expect(masked.startsWith('+1 ')).toBeTruthy();
+    expect(unmask(masked, maskPhoneCountryOptions())).toBe('12025550123');
+  });
+});
+
+describe(maskCardOptions, () => {
+  it('groups digits by the detected brand', () => {
+    expect(maskTransform('4111111111111111', maskCardOptions())).toBe('4111 1111 1111 1111');
+    expect(maskTransform('371449635398431', maskCardOptions())).toBe('3714 496353 98431'); // amex 4-6-5
+  });
+
+  it('falls back to 16-digit grouping for an unknown prefix', () => {
+    expect(maskTransform('0000000000000000', maskCardOptions())).toBe('0000 0000 0000 0000');
+  });
+
+  it('unmasks to the raw digits', () => {
+    expect(unmask('4111 1111 1111 1111', maskCardOptions())).toBe('4111111111111111');
+  });
+});
+
+describe(normalizeMaskOptions, () => {
+  it('compiles a template string', () => {
+    const opts = normalizeMaskOptions('##/##');
+    expect(maskTransform('1234', opts)).toBe('12/34');
+  });
+
+  it('wraps a bare array mask', () => {
+    const opts = normalizeMaskOptions([/\d/, /\d/]);
+    expect(maskTransform('99', opts)).toBe('99');
+  });
+
+  it('passes full options through', () => {
+    expect(normalizeMaskOptions(PHONE)).toBe(PHONE);
+  });
+});
+
+describe('isMaskComplete / calibrate / removeFixed', () => {
+  it('reports completeness for an array mask', () => {
+    const mask = maskFromTemplate('##/##');
+    expect(isMaskComplete('12/34', mask)).toBeTruthy();
+    expect(isMaskComplete('12/3', mask)).toBeFalsy();
+  });
+
+  it('calibrate fast-returns a valid prefix unchanged', () => {
+    const mask = maskFromTemplate('###');
+    const state: ElementState = { value: '12', selection: [2, 2] };
+    expect(calibrateValueByMask(state, mask)).toBe(state);
+  });
+
+  it('removeFixedMaskCharacters remaps the selection', () => {
+    const mask = maskFromTemplate('(##)');
+    // "(12)" caret after ")" → unmasked "12" caret at 2
+    const result = removeFixedMaskCharacters({ value: '(12)', selection: [4, 4] }, mask);
+    expect(result.value).toBe('12');
+    expect(result.selection).toEqual([2, 2]);
+  });
+});
diff --git a/vue/toolkit/src/composables/forms/mask/index.ts b/vue/toolkit/src/composables/forms/mask/index.ts
new file mode 100644
index 0000000..acf85ce
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/index.ts
@@ -0,0 +1,40 @@
+export type {
+  ElementState,
+  Mask,
+  MaskAction,
+  MaskExpression,
+  MaskOptionInput,
+  MaskOptions,
+  MaskPostprocessor,
+  MaskPreprocessor,
+  MaskPreprocessorParams,
+  MaskPreprocessorResult,
+  OverwriteMode,
+  SelectionRange,
+} from './types';
+
+export { isMaskComplete } from './conform';
+export { maskTransform, normalizeMaskOptions, unmask } from './model';
+export {
+  CARD_BRANDS,
+  DEFAULT_MASK_TOKENS,
+  findCardBrand,
+  findPhoneCountry,
+  isValidCardNumber,
+  maskCardOptions,
+  maskDateOptions,
+  maskFromTemplate,
+  maskNumberOptions,
+  maskPhoneCountryOptions,
+  maskPhoneOptions,
+  PHONE_COUNTRIES,
+} from './presets';
+export type {
+  CardBrand,
+  MaskCardParams,
+  MaskDateParams,
+  MaskNumberParams,
+  MaskPhoneCountryParams,
+  MaskPhoneParams,
+  PhoneCountry,
+} from './presets';
diff --git a/vue/toolkit/src/composables/forms/mask/model.ts b/vue/toolkit/src/composables/forms/mask/model.ts
new file mode 100644
index 0000000..bad4815
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/model.ts
@@ -0,0 +1,225 @@
+import { isArray, isFunction, isString } from '@robonen/stdlib';
+import {
+  applyOverwriteMode,
+  areElementStatesEqual,
+  calibrateValueByMask,
+  removeFixedMaskCharacters,
+  resolveMask,
+} from './conform';
+import { maskFromTemplate } from './presets';
+import type {
+  ElementState,
+  Mask,
+  MaskAction,
+  MaskOptionInput,
+  MaskOptions,
+  MaskPostprocessor,
+  MaskPreprocessor,
+  ResolvedMaskOptions,
+  SelectionRange,
+} from './types';
+
+/**
+ * Thrown by {@link MaskModel} mutations that produce no change, so callers can
+ * swallow the gesture (e.g. typing a fixed character that is already present)
+ * without polluting input/undo history.
+ */
+export const MASK_NOOP = Symbol('mask-noop');
+
+/**
+ * Apply {@link MaskOptions} defaults.
+ */
+export function resolveMaskOptions(options: MaskOptions): ResolvedMaskOptions {
+  return {
+    mask: options.mask,
+    preprocessors: options.preprocessors ?? [],
+    postprocessors: options.postprocessors ?? [],
+    overwriteMode: options.overwriteMode ?? 'shift',
+  };
+}
+
+/**
+ * Normalize the friendly authoring union to full {@link MaskOptions}: a template
+ * string is compiled via {@link maskFromTemplate}, a bare mask is wrapped, and
+ * full options pass through.
+ */
+export function normalizeMaskOptions(input: MaskOptionInput): MaskOptions {
+  if (isString(input))
+    return { mask: maskFromTemplate(input) };
+
+  if (input instanceof RegExp || isArray(input) || isFunction(input))
+    return { mask: input as Mask };
+
+  return input as MaskOptions;
+}
+
+/**
+ * Run the preprocessor chain, threading `{ elementState, data }`.
+ */
+export function runPreprocessors(
+  processors: readonly MaskPreprocessor[],
+  elementState: ElementState,
+  data: string,
+  action: MaskAction,
+): { elementState: ElementState; data: string } {
+  let state = elementState;
+  let currentData = data;
+
+  for (const process of processors) {
+    const result = process({ elementState: state, data: currentData }, action);
+    state = result.elementState;
+    if (result.data !== undefined)
+      currentData = result.data;
+  }
+
+  return { elementState: state, data: currentData };
+}
+
+/**
+ * Run the postprocessor chain against `initialState`.
+ */
+export function runPostprocessors(
+  processors: readonly MaskPostprocessor[],
+  state: ElementState,
+  initialState: ElementState,
+): ElementState {
+  let current = state;
+
+  for (const process of processors)
+    current = process(current, initialState);
+
+  return current;
+}
+
+/**
+ * The stateful masking model. Holds the masked `value`/`selection` and performs
+ * insertions/deletions in **unmasked space** (fixed characters stripped) before
+ * re-calibrating to the masked form — the device that makes backspacing across
+ * fixed characters and `overwriteMode` correct.
+ */
+export class MaskModel implements ElementState {
+  public value: string;
+  public selection: SelectionRange;
+
+  private readonly options: ResolvedMaskOptions;
+
+  constructor(initial: ElementState, options: ResolvedMaskOptions) {
+    this.options = options;
+
+    const calibrated = calibrateValueByMask(initial, options.mask);
+    this.value = calibrated.value;
+    this.selection = calibrated.selection;
+  }
+
+  /**
+   * Insert `characters` at the current selection. Throws {@link MASK_NOOP} when
+   * the result is identical to the current state.
+   */
+  public addCharacters(characters: string): void {
+    const initial: ElementState = { value: this.value, selection: this.selection };
+    const mask = resolveMask(this.options.mask, initial);
+
+    const overwritten = applyOverwriteMode(initial, characters, this.options.overwriteMode);
+    const unmasked = removeFixedMaskCharacters(overwritten, mask);
+    const [from, to] = unmasked.selection;
+
+    const leading = unmasked.value.slice(0, from) + characters;
+    const nextValue = leading + unmasked.value.slice(to);
+    const caret = leading.length;
+
+    this.applyCalibrated({ value: nextValue, selection: [caret, caret] }, initial, true);
+  }
+
+  /**
+   * Delete from the current selection. A collapsed caret removes one *unmasked*
+   * character in the given direction (auto-skipping fixed characters); a range
+   * removes its unmasked span.
+   */
+  public deleteCharacters(isForward: boolean): void {
+    const initial: ElementState = { value: this.value, selection: this.selection };
+    const mask = resolveMask(this.options.mask, initial);
+
+    const unmasked = removeFixedMaskCharacters(initial, mask);
+    let [from, to] = unmasked.selection;
+
+    if (from === to) {
+      if (isForward)
+        to = Math.min(to + 1, unmasked.value.length);
+      else
+        from = Math.max(from - 1, 0);
+    }
+
+    const nextValue = unmasked.value.slice(0, from) + unmasked.value.slice(to);
+
+    this.applyCalibrated({ value: nextValue, selection: [from, from] }, initial, false);
+  }
+
+  private applyCalibrated(candidate: ElementState, initial: ElementState, guardNoop: boolean): void {
+    const calibrated = calibrateValueByMask(candidate, this.options.mask);
+
+    if (guardNoop && areElementStatesEqual(initial, calibrated))
+      throw MASK_NOOP;
+
+    this.value = calibrated.value;
+    this.selection = calibrated.selection;
+  }
+}
+
+/**
+ * @name maskTransform
+ * @category Forms
+ * @description Pure, DOM-free masking: conform a string (or {@link ElementState})
+ * through the full preprocessor → mask → postprocessor pipeline. Ideal for SSR,
+ * server-side validation, and tests. Returns a `string` for string input and an
+ * {@link ElementState} for state input.
+ *
+ * @example
+ * maskTransform('1234567890', maskPhoneOptions({ template: '+1 (###) ###-####' }));
+ * // '+1 (123) 456-7890'
+ *
+ * @since 0.0.17
+ */
+export function maskTransform(value: string, options: MaskOptions): string;
+export function maskTransform(state: ElementState, options: MaskOptions): ElementState;
+export function maskTransform(valueOrState: string | ElementState, options: MaskOptions): string | ElementState {
+  const resolved = resolveMaskOptions(options);
+  const inputIsString = isString(valueOrState);
+  const initial: ElementState = inputIsString
+    ? { value: valueOrState, selection: [valueOrState.length, valueOrState.length] }
+    : valueOrState;
+
+  const pre = runPreprocessors(resolved.preprocessors, initial, '', 'validation');
+  const model = new MaskModel(pre.elementState, resolved);
+  const post = runPostprocessors(
+    resolved.postprocessors,
+    { value: model.value, selection: model.selection },
+    initial,
+  );
+
+  return inputIsString ? post.value : post;
+}
+
+/**
+ * @name unmask
+ * @category Forms
+ * @description The masked → raw bridge: strip a mask's fixed characters from a
+ * masked string, without needing a DOM element. RegExp masks have no fixed
+ * characters, so the value is returned unchanged.
+ *
+ * @example
+ * unmask('+1 (123) 456-7890', maskPhoneOptions({ template: '+1 (###) ###-####' }));
+ * // '1234567890'
+ *
+ * @since 0.0.17
+ */
+export function unmask(maskedValue: string, options: MaskOptions): string {
+  const resolved = resolveMaskOptions(options);
+  const state: ElementState = { value: maskedValue, selection: [maskedValue.length, maskedValue.length] };
+
+  // Run preprocessors so preset normalizers (e.g. the number mask stripping
+  // thousand separators/affixes) define the raw value too.
+  const pre = runPreprocessors(resolved.preprocessors, state, '', 'validation');
+  const mask = resolveMask(resolved.mask, pre.elementState);
+
+  return removeFixedMaskCharacters(pre.elementState, mask).value;
+}
diff --git a/vue/toolkit/src/composables/forms/mask/presets/card.ts b/vue/toolkit/src/composables/forms/mask/presets/card.ts
new file mode 100644
index 0000000..3be09d6
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/presets/card.ts
@@ -0,0 +1,76 @@
+import { CARD_BRANDS, findCardBrand } from '@robonen/platform/multi';
+import type { CardBrand } from '@robonen/platform/multi';
+import type { ElementState, MaskExpression, MaskOptions } from '../types';
+import { maskFromTemplate } from './template';
+
+// Re-export the platform reference data + resolver + validator (source of truth
+// lives in `@robonen/platform`; the Luhn primitive lives in `@robonen/encoding`).
+export { CARD_BRANDS, findCardBrand, isValidCardNumber } from '@robonen/platform/multi';
+export type { CardBrand } from '@robonen/platform/multi';
+
+const NON_DIGIT = /\D/g;
+const DEFAULT_CARD_FALLBACK = '#### #### #### ####';
+
+/**
+ * Parameters for {@link maskCardOptions}.
+ */
+export interface MaskCardParams {
+  /**
+   * Known card brands, matched by {@link findCardBrand}.
+   *
+   * @default CARD_BRANDS
+   */
+  readonly brands?: readonly CardBrand[];
+  /**
+   * Template used before a brand is recognized (and for unknown brands).
+   *
+   * @default '#### #### #### ####'
+   */
+  readonly fallback?: string;
+  /**
+   * Token map applied to every template.
+   */
+  readonly tokens?: Readonly<Record<string, RegExp>>;
+}
+
+/**
+ * @name maskCardOptions
+ * @category Forms
+ * @description A dynamic payment-card mask that groups digits by the detected
+ * brand. The mask is a function of state: it reads the digits, resolves the brand
+ * via {@link findCardBrand} (by IIN/BIN prefix), and applies that brand's grouping
+ * template (e.g. `#### ###### #####` for Amex) — falling back to a generic 16-digit
+ * grouping until a brand is recognized. The unmasked value is the digit string.
+ *
+ * @param {MaskCardParams} [params={}] Brands and fallback template
+ * @returns {MaskOptions} Ready-to-use mask options (a function mask)
+ *
+ * @example
+ * const card = useMaskedInput({ mask: maskCardOptions() });
+ * // <input v-bind="card.bind">  — 4111… → '4111 1111 1111 1111', 3714… → Amex 4-6-5
+ *
+ * @since 0.0.17
+ */
+export function maskCardOptions(params: MaskCardParams = {}): MaskOptions {
+  const brands = params.brands ?? CARD_BRANDS;
+  const fallback = params.fallback ?? DEFAULT_CARD_FALLBACK;
+
+  // 1-entry memo: resolveMask fires several times per keystroke with the same
+  // digits, and the expression is a pure function of those digits.
+  let lastDigits = '';
+  let lastExpression: MaskExpression = maskFromTemplate(fallback, params.tokens);
+
+  return {
+    mask: (state: ElementState): MaskExpression => {
+      const digits = state.value.replaceAll(NON_DIGIT, '');
+      if (digits === lastDigits)
+        return lastExpression;
+
+      const brand = findCardBrand(digits, brands);
+      lastDigits = digits;
+      lastExpression = maskFromTemplate(brand?.template ?? fallback, params.tokens);
+
+      return lastExpression;
+    },
+  };
+}
diff --git a/vue/toolkit/src/composables/forms/mask/presets/date.ts b/vue/toolkit/src/composables/forms/mask/presets/date.ts
new file mode 100644
index 0000000..f7a417a
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/presets/date.ts
@@ -0,0 +1,82 @@
+import type { MaskOptions, MaskPostprocessor } from '../types';
+
+/**
+ * Parameters for {@link maskDateOptions}.
+ */
+export interface MaskDateParams {
+  /**
+   * Segment order and separator style.
+   *
+   * @default 'dd/mm/yyyy'
+   */
+  readonly mode?: 'dd/mm/yyyy' | 'mm/dd/yyyy' | 'yyyy-mm-dd';
+  /**
+   * Override the separator character.
+   */
+  readonly separator?: string;
+}
+
+interface DateSegment {
+  readonly kind: 'day' | 'month' | 'year';
+  readonly length: number;
+}
+
+const DATE_SEGMENTS: Record<NonNullable<MaskDateParams['mode']>, readonly DateSegment[]> = {
+  'dd/mm/yyyy': [{ kind: 'day', length: 2 }, { kind: 'month', length: 2 }, { kind: 'year', length: 4 }],
+  'mm/dd/yyyy': [{ kind: 'month', length: 2 }, { kind: 'day', length: 2 }, { kind: 'year', length: 4 }],
+  'yyyy-mm-dd': [{ kind: 'year', length: 4 }, { kind: 'month', length: 2 }, { kind: 'day', length: 2 }],
+};
+
+const SEGMENT_MAX: Record<DateSegment['kind'], number> = { day: 31, month: 12, year: 9999 };
+const ALL_DIGITS = /^\d+$/;
+
+function clampDateSegments(segments: readonly DateSegment[], separator: string): MaskPostprocessor {
+  return (state) => {
+    const parts = state.value.split(separator);
+
+    const clamped = parts.map((part, index) => {
+      const segment = segments[index];
+      // Clamp only fully-typed segments so partial input (e.g. "3" → 31) isn't fought.
+      if (!segment || part.length < segment.length || !ALL_DIGITS.test(part))
+        return part;
+
+      const max = SEGMENT_MAX[segment.kind];
+      const value = Number(part);
+
+      return value > max ? String(max).padStart(segment.length, '0') : part;
+    });
+
+    return { value: clamped.join(separator), selection: state.selection };
+  };
+}
+
+/**
+ * @name maskDateOptions
+ * @category Forms
+ * @description Mask options for a date. Auto-inserts separators and clamps
+ * fully-typed day/month segments (day ≤ 31, month ≤ 12). No calendar/timezone
+ * validation — pair with a schema for that.
+ *
+ * @param {MaskDateParams} [params={}] Segment order and separator
+ * @returns {MaskOptions} Ready-to-use mask options
+ *
+ * @example
+ * maskDateOptions({ mode: 'dd/mm/yyyy' });
+ *
+ * @since 0.0.17
+ */
+export function maskDateOptions(params: MaskDateParams = {}): MaskOptions {
+  const mode = params.mode ?? 'dd/mm/yyyy';
+  const separator = params.separator ?? (mode === 'yyyy-mm-dd' ? '-' : '/');
+  const segments = DATE_SEGMENTS[mode];
+
+  const mask: Array<RegExp | string> = [];
+  segments.forEach((segment, index) => {
+    if (index > 0)
+      mask.push(separator);
+    for (let i = 0; i < segment.length; i++)
+      mask.push(/\d/);
+  });
+
+  return { mask, postprocessors: [clampDateSegments(segments, separator)] };
+}
diff --git a/vue/toolkit/src/composables/forms/mask/presets/index.ts b/vue/toolkit/src/composables/forms/mask/presets/index.ts
new file mode 100644
index 0000000..727a9c4
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/presets/index.ts
@@ -0,0 +1,11 @@
+export { DEFAULT_MASK_TOKENS, maskFromTemplate } from './template';
+export { maskPhoneOptions } from './phone';
+export type { MaskPhoneParams } from './phone';
+export { findPhoneCountry, maskPhoneCountryOptions, PHONE_COUNTRIES } from './phone-country';
+export type { MaskPhoneCountryParams, PhoneCountry } from './phone-country';
+export { CARD_BRANDS, findCardBrand, isValidCardNumber, maskCardOptions } from './card';
+export type { CardBrand, MaskCardParams } from './card';
+export { maskDateOptions } from './date';
+export type { MaskDateParams } from './date';
+export { maskNumberOptions } from './number';
+export type { MaskNumberParams } from './number';
diff --git a/vue/toolkit/src/composables/forms/mask/presets/number.ts b/vue/toolkit/src/composables/forms/mask/presets/number.ts
new file mode 100644
index 0000000..249fa04
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/presets/number.ts
@@ -0,0 +1,237 @@
+import { clamp } from '@robonen/stdlib';
+import type { ElementState, MaskOptions, MaskPostprocessor, MaskPreprocessor } from '../types';
+
+const ESCAPE_REGEXP = /[$()*+.?[\\\]^{|}]/g;
+
+function escapeRegExp(source: string): string {
+  return source.replaceAll(ESCAPE_REGEXP, '\\$&');
+}
+
+/**
+ * Parameters for {@link maskNumberOptions}.
+ */
+export interface MaskNumberParams {
+  /**
+   * Decimal separator.
+   *
+   * @default '.'
+   */
+  readonly decimalSeparator?: string;
+  /**
+   * Grouping separator for thousands. Empty disables grouping.
+   *
+   * @default ''
+   */
+  readonly thousandSeparator?: string;
+  /**
+   * Max fractional digits. `0` means integer only.
+   *
+   * @default 0
+   */
+  readonly precision?: number;
+  /**
+   * Upper bound — typed values above it snap down to it (applied live).
+   */
+  readonly max?: number;
+  /**
+   * Allow a leading minus sign.
+   *
+   * @default false
+   */
+  readonly allowNegative?: boolean;
+  /**
+   * Static prefix (e.g. `'$'`).
+   *
+   * @default ''
+   */
+  readonly prefix?: string;
+  /**
+   * Static postfix (e.g. `' USD'`).
+   *
+   * @default ''
+   */
+  readonly postfix?: string;
+}
+
+interface ResolvedNumberParams {
+  readonly decimalSeparator: string;
+  readonly thousandSeparator: string;
+  readonly precision: number;
+  readonly max: number | undefined;
+  readonly allowNegative: boolean;
+  readonly prefix: string;
+  readonly postfix: string;
+}
+
+/**
+ * Remove every `char` from `value`, remapping the selection to the stripped text.
+ */
+function stripCharacter(state: ElementState, char: string): ElementState {
+  if (!char)
+    return state;
+
+  const { value, selection } = state;
+  const [from, to] = selection;
+
+  let stripped = '';
+  let newFrom = from;
+  let newTo = to;
+
+  for (let i = 0; i < value.length; i++) {
+    const current = value[i];
+    if (current === undefined)
+      continue;
+
+    if (current === char) {
+      if (i < from)
+        newFrom -= 1;
+      if (i < to)
+        newTo -= 1;
+    }
+    else {
+      stripped += current;
+    }
+  }
+
+  const end = stripped.length;
+
+  return { value: stripped, selection: [clamp(newFrom, 0, end), clamp(newTo, 0, end)] };
+}
+
+/**
+ * Strip a fixed prefix/postfix, shifting the selection into the body.
+ */
+function stripAffixes(state: ElementState, prefix: string, postfix: string): ElementState {
+  let { value } = state;
+  let [from, to] = state.selection;
+
+  if (prefix && value.startsWith(prefix)) {
+    value = value.slice(prefix.length);
+    from -= prefix.length;
+    to -= prefix.length;
+  }
+
+  if (postfix && value.endsWith(postfix))
+    value = value.slice(0, -postfix.length);
+
+  const end = value.length;
+
+  return { value, selection: [clamp(from, 0, end), clamp(to, 0, end)] };
+}
+
+function numberPreprocessor(params: ResolvedNumberParams): MaskPreprocessor {
+  return ({ elementState, data }) => {
+    const withoutAffixes = stripAffixes(elementState, params.prefix, params.postfix);
+    const canonical = stripCharacter(withoutAffixes, params.thousandSeparator);
+
+    // Treat a typed '.'/',' as the configured decimal separator.
+    const normalizedData = params.precision > 0 && (data === '.' || data === ',')
+      ? params.decimalSeparator
+      : data;
+
+    return { elementState: canonical, data: normalizedData };
+  };
+}
+
+function groupThousands(intDigits: string, separator: string): string {
+  if (!separator)
+    return intDigits;
+
+  let grouped = '';
+  for (let i = 0; i < intDigits.length; i++) {
+    if (i > 0 && (intDigits.length - i) % 3 === 0)
+      grouped += separator;
+    grouped += intDigits[i];
+  }
+
+  return grouped;
+}
+
+/**
+ * Map a caret in canonical (separator-free) coordinates onto the grouped body by
+ * walking the body and skipping thousand separators.
+ */
+function mapCaretToBody(body: string, separator: string, canonicalCaret: number): number {
+  if (!separator)
+    return canonicalCaret;
+
+  let significant = 0;
+  for (let i = 0; i < body.length; i++) {
+    if (significant === canonicalCaret)
+      return i;
+    if (body[i] !== separator)
+      significant += 1;
+  }
+
+  return body.length;
+}
+
+function numberPostprocessor(params: ResolvedNumberParams): MaskPostprocessor {
+  const { decimalSeparator, thousandSeparator, prefix, postfix, max } = params;
+
+  return (state) => {
+    const [caret] = state.selection;
+    let canonical = state.value;
+
+    // Live max clamp on the settled numeric value.
+    if (max !== undefined && canonical && !canonical.endsWith(decimalSeparator)) {
+      const numeric = Number(canonical.replace(decimalSeparator, '.'));
+      if (Number.isFinite(numeric) && numeric > max)
+        canonical = String(max).replace('.', decimalSeparator);
+    }
+
+    const negative = canonical.startsWith('-');
+    const unsigned = negative ? canonical.slice(1) : canonical;
+    const [intPart = '', fracPart] = unsigned.split(decimalSeparator);
+
+    const sign = negative ? '-' : '';
+    const grouped = groupThousands(intPart, thousandSeparator);
+    const body = sign + grouped + (fracPart !== undefined ? decimalSeparator + fracPart : '');
+
+    const value = prefix + body + postfix;
+    const bodyCaret = mapCaretToBody(body, thousandSeparator, clamp(caret, 0, canonical.length));
+    const mapped = prefix.length + clamp(bodyCaret, 0, body.length);
+
+    return { value, selection: [mapped, mapped] };
+  };
+}
+
+/**
+ * @name maskNumberOptions
+ * @category Forms
+ * @description Mask options for a formatted number: optional thousands grouping,
+ * decimal precision, sign, prefix/postfix, and a live upper-bound clamp. The
+ * unmasked value is the canonical, separator-free number string.
+ *
+ * @param {MaskNumberParams} [params={}] Formatting options
+ * @returns {MaskOptions} Ready-to-use mask options
+ *
+ * @example
+ * maskNumberOptions({ thousandSeparator: ',', precision: 2, prefix: '$' });
+ * // typing 1234.5 → '$1,234.5'
+ *
+ * @since 0.0.17
+ */
+export function maskNumberOptions(params: MaskNumberParams = {}): MaskOptions {
+  const resolved: ResolvedNumberParams = {
+    decimalSeparator: params.decimalSeparator ?? '.',
+    thousandSeparator: params.thousandSeparator ?? '',
+    precision: params.precision ?? 0,
+    max: params.max,
+    allowNegative: params.allowNegative ?? false,
+    prefix: params.prefix ?? '',
+    postfix: params.postfix ?? '',
+  };
+
+  const sign = resolved.allowNegative ? '-?' : '';
+  const decimal = resolved.precision > 0
+    ? `(${escapeRegExp(resolved.decimalSeparator)}\\d{0,${resolved.precision}})?`
+    : '';
+  const mask = new RegExp(`^${sign}\\d*${decimal}$`);
+
+  return {
+    mask,
+    preprocessors: [numberPreprocessor(resolved)],
+    postprocessors: [numberPostprocessor(resolved)],
+  };
+}
diff --git a/vue/toolkit/src/composables/forms/mask/presets/phone-country.ts b/vue/toolkit/src/composables/forms/mask/presets/phone-country.ts
new file mode 100644
index 0000000..3674040
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/presets/phone-country.ts
@@ -0,0 +1,84 @@
+import { PHONE_COUNTRIES, findPhoneCountry } from '@robonen/platform/multi';
+import type { PhoneCountry } from '@robonen/platform/multi';
+import type { ElementState, MaskExpression, MaskOptions } from '../types';
+import { maskFromTemplate } from './template';
+
+// Re-export the platform reference data + resolver so mask consumers get them
+// from one place (the source of truth lives in `@robonen/platform`).
+export { PHONE_COUNTRIES, findPhoneCountry } from '@robonen/platform/multi';
+export type { PhoneCountry } from '@robonen/platform/multi';
+
+const NON_DIGIT = /\D/g;
+const DEFAULT_PHONE_FALLBACK = '+###############';
+
+/**
+ * Parameters for {@link maskPhoneCountryOptions}.
+ */
+export interface MaskPhoneCountryParams {
+  /**
+   * Known countries, matched by {@link findPhoneCountry}.
+   *
+   * @default PHONE_COUNTRIES
+   */
+  readonly countries?: readonly PhoneCountry[];
+  /**
+   * Template used before any country code is recognized.
+   *
+   * @default '+###############'
+   */
+  readonly fallback?: string;
+  /**
+   * Token map applied to every template.
+   */
+  readonly tokens?: Readonly<Record<string, RegExp>>;
+}
+
+/**
+ * @name maskPhoneCountryOptions
+ * @category Forms
+ * @description A dynamic phone mask that switches format based on the typed
+ * country dialing code. The mask is a function of state: it reads the leading
+ * digits, resolves the country via {@link findPhoneCountry} (dialing code → area
+ * code → priority), and applies that country's template — falling back to a
+ * generic international template until a code is recognized. Defaults to the full
+ * {@link PHONE_COUNTRIES} set. The unmasked value is the digit string.
+ *
+ * @param {MaskPhoneCountryParams} [params={}] Countries and fallback template
+ * @returns {MaskOptions} Ready-to-use mask options (a function mask)
+ *
+ * @example
+ * // Typing "+1…" formats as US, "+380…" as Ukraine, etc.
+ * const phone = useMaskedInput({ mask: maskPhoneCountryOptions() });
+ * // <input v-bind="phone.bind">
+ *
+ * @example
+ * maskPhoneCountryOptions({
+ *   countries: [{ code: '34', template: '+## ### ### ###' }], // Spain only
+ *   fallback: '+#############',
+ * });
+ *
+ * @since 0.0.17
+ */
+export function maskPhoneCountryOptions(params: MaskPhoneCountryParams = {}): MaskOptions {
+  const countries = params.countries ?? PHONE_COUNTRIES;
+  const fallback = params.fallback ?? DEFAULT_PHONE_FALLBACK;
+
+  // 1-entry memo: resolveMask fires several times per keystroke with the same
+  // digits, and the expression is a pure function of those digits.
+  let lastDigits = '';
+  let lastExpression: MaskExpression = maskFromTemplate(fallback, params.tokens);
+
+  return {
+    mask: (state: ElementState): MaskExpression => {
+      const digits = state.value.replaceAll(NON_DIGIT, '');
+      if (digits === lastDigits)
+        return lastExpression;
+
+      const country = findPhoneCountry(digits, countries);
+      lastDigits = digits;
+      lastExpression = maskFromTemplate(country?.template ?? fallback, params.tokens);
+
+      return lastExpression;
+    },
+  };
+}
diff --git a/vue/toolkit/src/composables/forms/mask/presets/phone.ts b/vue/toolkit/src/composables/forms/mask/presets/phone.ts
new file mode 100644
index 0000000..52fe0ab
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/presets/phone.ts
@@ -0,0 +1,35 @@
+import type { MaskOptions } from '../types';
+import { maskFromTemplate } from './template';
+
+/**
+ * Parameters for {@link maskPhoneOptions}.
+ */
+export interface MaskPhoneParams {
+  /**
+   * The phone template, e.g. `'+1 (###) ###-####'`.
+   */
+  readonly template: string;
+  /**
+   * Override the token → matcher map.
+   */
+  readonly tokens?: Readonly<Record<string, RegExp>>;
+}
+
+/**
+ * @name maskPhoneOptions
+ * @category Forms
+ * @description Mask options for a phone number, built from a single template
+ * string. For a mask that adapts to the typed country code, see
+ * {@link maskPhoneCountryOptions}.
+ *
+ * @param {MaskPhoneParams} params The template (and optional tokens)
+ * @returns {MaskOptions} Ready-to-use mask options
+ *
+ * @example
+ * maskPhoneOptions({ template: '+1 (###) ###-####' });
+ *
+ * @since 0.0.17
+ */
+export function maskPhoneOptions(params: MaskPhoneParams): MaskOptions {
+  return { mask: maskFromTemplate(params.template, params.tokens) };
+}
diff --git a/vue/toolkit/src/composables/forms/mask/presets/template.ts b/vue/toolkit/src/composables/forms/mask/presets/template.ts
new file mode 100644
index 0000000..64be533
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/presets/template.ts
@@ -0,0 +1,57 @@
+/**
+ * Default {@link maskFromTemplate} tokens: `#` → digit, `A` → letter,
+ * `*` → letter or digit. Every other template character is a fixed literal.
+ */
+export const DEFAULT_MASK_TOKENS: Readonly<Record<string, RegExp>> = {
+  '#': /\d/,
+  A: /[a-z]/i,
+  '*': /[a-z0-9]/i,
+};
+
+// Compiled-mask cache for the default-token path. Function masks (phone/card)
+// re-resolve the same template several times per keystroke; caching collapses
+// each repeat to a Map hit instead of rebuilding a 12-17 element array.
+const TEMPLATE_CACHE = new Map<string, ReadonlyArray<RegExp | string>>();
+
+function compileTemplate(template: string, tokens: Readonly<Record<string, RegExp>>): Array<RegExp | string> {
+  const mask: Array<RegExp | string> = [];
+
+  for (const char of template)
+    mask.push(tokens[char] ?? char);
+
+  return mask;
+}
+
+/**
+ * @name maskFromTemplate
+ * @category Forms
+ * @description Compile a human-readable template into a mask array. Token
+ * characters become matcher slots; everything else becomes a fixed literal. With
+ * the default tokens the compiled array is cached and shared (frozen) per
+ * template string; pass a custom `tokens` map to opt out.
+ *
+ * @param {string} template e.g. `'+1 (###) ###-####'`
+ * @param {Record<string, RegExp>} [tokens=DEFAULT_MASK_TOKENS] Token → matcher map
+ * @returns {ReadonlyArray<RegExp | string>} The compiled mask expression
+ *
+ * @example
+ * maskFromTemplate('##/##/####'); // [/\d/, /\d/, '/', /\d/, /\d/, '/', /\d/, /\d/, /\d/, /\d/]
+ *
+ * @since 0.0.17
+ */
+export function maskFromTemplate(
+  template: string,
+  tokens: Readonly<Record<string, RegExp>> = DEFAULT_MASK_TOKENS,
+): ReadonlyArray<RegExp | string> {
+  if (tokens !== DEFAULT_MASK_TOKENS)
+    return compileTemplate(template, tokens);
+
+  const cached = TEMPLATE_CACHE.get(template);
+  if (cached)
+    return cached;
+
+  const compiled = Object.freeze(compileTemplate(template, tokens));
+  TEMPLATE_CACHE.set(template, compiled);
+
+  return compiled;
+}
diff --git a/vue/toolkit/src/composables/forms/mask/types.ts b/vue/toolkit/src/composables/forms/mask/types.ts
new file mode 100644
index 0000000..3dbf5ae
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/mask/types.ts
@@ -0,0 +1,107 @@
+/**
+ * A selection range as `[from, to]`. A collapsed caret has `from === to`.
+ */
+export type SelectionRange = readonly [from: number, to: number];
+
+/**
+ * The DOM-free editable state the masking engine operates on: a value plus its
+ * selection. Structurally compatible with `@robonen/platform`'s `InputState`.
+ */
+export interface ElementState {
+  readonly value: string;
+  readonly selection: SelectionRange;
+}
+
+/**
+ * A concrete mask pattern: either a single {@link RegExp} validating the whole
+ * value, or an array of slots where a `string` is a fixed (auto-inserted)
+ * character and a {@link RegExp} validates exactly one character.
+ */
+export type MaskExpression = ReadonlyArray<RegExp | string> | RegExp;
+
+/**
+ * A mask: a concrete {@link MaskExpression} or a function deriving one from the
+ * current {@link ElementState} (a dynamic mask).
+ */
+export type Mask = MaskExpression | ((state: ElementState) => MaskExpression);
+
+/**
+ * The user gesture a preprocessor is reacting to.
+ */
+export type MaskAction = 'deleteBackward' | 'deleteForward' | 'insert' | 'validation';
+
+/**
+ * How newly typed characters interact with the text under a collapsed caret:
+ * - `shift` — insert, pushing existing characters right (default);
+ * - `replace` — overwrite the following characters;
+ * - a function resolving the mode per {@link ElementState}.
+ */
+export type OverwriteMode = 'replace' | 'shift' | ((state: ElementState) => 'replace' | 'shift');
+
+/**
+ * Input to a {@link MaskPreprocessor}.
+ */
+export interface MaskPreprocessorParams {
+  readonly elementState: ElementState;
+  readonly data: string;
+}
+
+/**
+ * Output of a {@link MaskPreprocessor}.
+ */
+export interface MaskPreprocessorResult {
+  readonly elementState: ElementState;
+  readonly data?: string;
+}
+
+/**
+ * Runs before the mask conforms a value — normalizes the upcoming state/data.
+ */
+export type MaskPreprocessor = (params: MaskPreprocessorParams, action: MaskAction) => MaskPreprocessorResult;
+
+/**
+ * Runs after the mask conforms a value — applies finishing touches (separators,
+ * padding, clamping). Receives the conformed state and the pre-change state.
+ */
+export type MaskPostprocessor = (state: ElementState, initialState: ElementState) => ElementState;
+
+/**
+ * A full mask configuration.
+ */
+export interface MaskOptions {
+  /**
+   * The mask pattern (or a function of state).
+   */
+  readonly mask: Mask;
+  /**
+   * Normalizers run before conforming.
+   */
+  readonly preprocessors?: readonly MaskPreprocessor[];
+  /**
+   * Finishers run after conforming.
+   */
+  readonly postprocessors?: readonly MaskPostprocessor[];
+  /**
+   * Insert vs overwrite behavior.
+   *
+   * @default 'shift'
+   */
+  readonly overwriteMode?: OverwriteMode;
+}
+
+/**
+ * The friendly authoring union accepted at every public boundary: a full
+ * {@link MaskOptions}, a bare {@link Mask}, or a template `string`
+ * (compiled via `maskFromTemplate`, e.g. `'+1 (###) ###-####'`).
+ */
+export type MaskOptionInput = Mask | string | MaskOptions;
+
+/**
+ * {@link MaskOptions} after defaults are applied (internal).
+ */
+export interface ResolvedMaskOptions {
+  readonly mask: Mask;
+  readonly preprocessors: readonly MaskPreprocessor[];
+  readonly postprocessors: readonly MaskPostprocessor[];
+  readonly overwriteMode: OverwriteMode;
+}
diff --git a/vue/toolkit/src/composables/forms/useMaskedField/demo.vue b/vue/toolkit/src/composables/forms/useMaskedField/demo.vue
new file mode 100644
index 0000000..f2babd5
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedField/demo.vue
@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import { useForm } from '../useForm';
+import { useMaskedField } from './index';
+
+interface Values {
+  phone: string;
+}
+
+const form = useForm<Values>({ initialValues: { phone: '' }, validateOn: 'value' });
+
+const { bind, display, complete, errorMessage } = useMaskedField('phone', {
+  mask: '+1 (###) ###-####',
+  validate: value => (typeof value === 'string' && value.length === 10) || 'Enter a complete phone number',
+});
+
+const onSubmit = form.handleSubmit((values) => {
+  // eslint-disable-next-line no-alert
+  globalThis.alert(`Submitted raw value: ${values.phone}`);
+});
+
+const inputClass = 'w-full rounded-lg border bg-(--bg) px-3 py-2 text-sm text-(--fg) placeholder:text-(--fg-subtle) transition focus:outline-none focus:ring-2 focus:ring-(--ring)';
+</script>
+
+<template>
+  <form class="flex w-full max-w-sm flex-col gap-4" @submit.prevent="onSubmit">
+    <div class="flex flex-col gap-1.5">
+      <label class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">
+        Phone number
+      </label>
+      <!-- One spread wires the ref, mask handlers, name, blur, and aria-invalid. -->
+      <input
+        v-bind="bind"
+        type="text"
+        inputmode="numeric"
+        placeholder="+1 (###) ###-####"
+        :class="[
+          inputClass,
+          errorMessage
+            ? 'border-red-500/60 focus:border-red-500'
+            : 'border-(--border) focus:border-(--accent)',
+        ]"
+      >
+      <p v-if="errorMessage" class="text-xs text-red-600 dark:text-red-400">
+        {{ errorMessage }}
+      </p>
+      <p v-else class="text-xs text-(--fg-subtle)">
+        Display is masked; the form stores the raw digits.
+      </p>
+    </div>
+
+    <div class="flex flex-wrap gap-2">
+      <span
+        class="inline-flex items-center rounded-md border px-2 py-0.5 text-xs font-medium"
+        :class="complete
+          ? 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400'
+          : 'border-(--border) bg-(--bg-inset) text-(--fg-subtle)'"
+      >
+        {{ complete ? 'complete' : 'incomplete' }}
+      </span>
+    </div>
+
+    <button
+      type="submit"
+      class="inline-flex items-center justify-center rounded-lg border border-transparent bg-(--accent) px-3 py-1.5 text-sm font-medium text-(--accent-fg) transition hover:bg-(--accent-hover) active:scale-[0.98] cursor-pointer"
+    >
+      Submit
+    </button>
+
+    <div class="rounded-lg border border-(--border) bg-(--bg-inset) p-3 font-mono text-sm text-(--fg) tabular-nums">
+      <div>display: "{{ display }}"</div>
+      <div>form value (raw): "{{ form.values.phone }}"</div>
+    </div>
+  </form>
+</template>
diff --git a/vue/toolkit/src/composables/forms/useMaskedField/index.test.ts b/vue/toolkit/src/composables/forms/useMaskedField/index.test.ts
new file mode 100644
index 0000000..88f98b3
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedField/index.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { defineComponent, h, nextTick } from 'vue';
+import { maskNumberOptions } from '../mask';
+import { useMaskedField } from './index';
+import type { UseMaskedFieldOptions, UseMaskedFieldReturn } from './index';
+
+function mountField(options: UseMaskedFieldOptions): {
+  field: UseMaskedFieldReturn;
+  input: HTMLInputElement;
+  unmount: () => void;
+} {
+  let field!: UseMaskedFieldReturn;
+  const wrapper = mount(
+    defineComponent({
+      setup() {
+        field = useMaskedField('phone', options);
+        return () => h('input', field.bind.value as Record<string, unknown>);
+      },
+    }),
+    { attachTo: document.body },
+  );
+
+  return { field, input: wrapper.element as HTMLInputElement, unmount: () => wrapper.unmount() };
+}
+
+describe(useMaskedField, () => {
+  it('shows the masked value but stores the raw value in the field', async () => {
+    const { field, input, unmount } = mountField({ mask: '+1 (###) ###-####', initialValue: '' });
+
+    input.value = '1234567890';
+    input.dispatchEvent(new Event('input'));
+    await nextTick();
+
+    expect(field.display.value).toBe('+1 (123) 456-7890');
+    expect(field.unmasked.value).toBe('1234567890');
+    expect(field.value.value).toBe('1234567890');
+    expect(field.complete.value).toBeTruthy();
+
+    unmount();
+  });
+
+  it('stores the masked value when modelValue is "masked"', async () => {
+    const { field, input, unmount } = mountField({
+      mask: maskNumberOptions({ thousandSeparator: ',' }),
+      modelValue: 'masked',
+      initialValue: '',
+    });
+
+    input.value = '1234567';
+    input.dispatchEvent(new Event('input'));
+    await nextTick();
+
+    expect(field.display.value).toBe('1,234,567');
+    expect(field.value.value).toBe('1,234,567');
+
+    unmount();
+  });
+
+  it('re-seeds the input when the field value is set programmatically', async () => {
+    const { field, input, unmount } = mountField({ mask: '+1 (###) ###-####', initialValue: '' });
+
+    field.setValue('5551234567');
+    await nextTick();
+
+    expect(field.display.value).toBe('+1 (555) 123-4567');
+    expect(input.value).toBe('+1 (555) 123-4567');
+
+    unmount();
+  });
+});
diff --git a/vue/toolkit/src/composables/forms/useMaskedField/index.ts b/vue/toolkit/src/composables/forms/useMaskedField/index.ts
new file mode 100644
index 0000000..ee4e46b
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedField/index.ts
@@ -0,0 +1,69 @@
+import { computed, watch } from 'vue';
+import type { MaybeRefOrGetter } from 'vue';
+import { useField } from '../useField';
+import { useMaskedInput } from '../useMaskedInput';
+import type { UseMaskedFieldOptions, UseMaskedFieldReturn } from './types';
+
+export type { UseMaskedFieldOptions, UseMaskedFieldReturn } from './types';
+
+/**
+ * @name useMaskedField
+ * @category Forms
+ * @description A masked form field: fuses {@link useField} with
+ * {@link useMaskedInput} so a formatted value is shown while the form stores the
+ * raw value (validation, dirty/touched, schema, and submit all read raw). Returns
+ * a single `bind` object to spread onto the input — it merges the field's
+ * `name`/`onBlur`/`aria-invalid` with the mask bindings (ref + handlers). Purely
+ * additive — it composes the existing form composables without modifying them.
+ *
+ * @param {MaybeRefOrGetter<string>} path The dotted field path
+ * @param {UseMaskedFieldOptions} options The mask plus any {@link useField} options
+ * @returns {UseMaskedFieldReturn} The field API plus `display`, `unmasked`, `complete`, `bind`
+ *
+ * @example
+ * const { bind, errorMessage } = useMaskedField('phone', { mask: '+1 (###) ###-####' });
+ * // <input v-bind="bind">  — the form stores the raw digits
+ *
+ * @since 0.0.17
+ */
+export function useMaskedField<T = string>(
+  path: MaybeRefOrGetter<string>,
+  options: UseMaskedFieldOptions<T>,
+): UseMaskedFieldReturn<T> {
+  const field = useField<T>(path, options);
+  const writesMasked = options.modelValue === 'masked';
+
+  const mask = useMaskedInput({
+    mask: options.mask,
+    overwriteMode: options.overwriteMode,
+    onAccept: ({ masked, unmasked }) => {
+      field.handleChange((writesMasked ? masked : unmasked) as T);
+    },
+  });
+
+  // Form → element: when the stored value changes from elsewhere (reset,
+  // programmatic set), re-seed and re-conform the input. Skip echoes of our own
+  // writes via the value we last pushed to the form.
+  watch(
+    () => field.value.value,
+    (raw) => {
+      const desired = raw === null || raw === undefined ? '' : String(raw);
+      const written = writesMasked ? mask.masked.value : mask.unmasked.value;
+      if (written === desired)
+        return;
+
+      mask.setValue(desired);
+    },
+    { immediate: true, flush: 'post' },
+  );
+
+  const bind = computed<Record<string, unknown>>(() => ({ ...field.attrs.value, ...mask.bind }));
+
+  return {
+    ...field,
+    display: mask.masked,
+    unmasked: mask.unmasked,
+    complete: mask.complete,
+    bind,
+  };
+}
diff --git a/vue/toolkit/src/composables/forms/useMaskedField/types.ts b/vue/toolkit/src/composables/forms/useMaskedField/types.ts
new file mode 100644
index 0000000..f93a520
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedField/types.ts
@@ -0,0 +1,55 @@
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue';
+import type { MaskOptionInput, OverwriteMode } from '../mask';
+import type { UseFieldOptions, UseFieldReturn } from '../useForm';
+
+/**
+ * Options for {@link useMaskedField}. Extends {@link UseFieldOptions} with the
+ * mask configuration.
+ */
+export interface UseMaskedFieldOptions<T = string> extends UseFieldOptions<T> {
+  /**
+   * The mask source: a full options object, a bare mask, or a template string.
+   * May be reactive.
+   */
+  mask: MaybeRefOrGetter<MaskOptionInput>;
+
+  /**
+   * Which view of the value is written into the form (and submitted):
+   * - `unmasked` — the raw value (recommended: schemas validate clean data);
+   * - `masked` — the formatted display string.
+   *
+   * @default 'unmasked'
+   */
+  modelValue?: 'masked' | 'unmasked';
+
+  /**
+   * Insert vs overwrite behavior under a collapsed caret.
+   *
+   * @default 'shift'
+   */
+  overwriteMode?: OverwriteMode;
+}
+
+/**
+ * The reactive API returned by {@link useMaskedField}: everything from
+ * {@link useField} plus the masking views and a single `bind` object.
+ */
+export interface UseMaskedFieldReturn<T = string> extends UseFieldReturn<T> {
+  /**
+   * The masked display text (read-only; the input shows it via `bind`).
+   */
+  display: ShallowRef<string>;
+  /**
+   * The raw unmasked value (mirrors what is written to the form by default).
+   */
+  unmasked: Readonly<ShallowRef<string>>;
+  /**
+   * Whether the mask is fully satisfied.
+   */
+  complete: ComputedRef<boolean>;
+  /**
+   * Spread onto the input (`<input v-bind="bind">`): merges the field's
+   * `name`/`onBlur`/`aria-invalid` with the mask bindings (ref + input handlers).
+   */
+  bind: ComputedRef<Record<string, unknown>>;
+}
diff --git a/vue/toolkit/src/composables/forms/useMaskedInput/demo.vue b/vue/toolkit/src/composables/forms/useMaskedInput/demo.vue
new file mode 100644
index 0000000..94a1958
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedInput/demo.vue
@@ -0,0 +1,97 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { getCountryFlagByCode } from '@robonen/platform/multi';
+import { findCardBrand, findPhoneCountry, isValidCardNumber, maskCardOptions, maskDateOptions, maskNumberOptions, maskPhoneCountryOptions } from '../mask';
+import { useMaskedInput } from './index';
+
+const phone = useMaskedInput({ mask: '+1 (###) ###-####' });
+
+const intl = useMaskedInput({ mask: maskPhoneCountryOptions() });
+// Resolve the country from the typed digits (dialing code → area code → priority)
+// and show its flag via the platform helper.
+const intlCountry = computed(() => findPhoneCountry(intl.unmasked.value));
+const intlFlag = computed(() => {
+  const iso2 = intlCountry.value?.iso2;
+  return iso2 ? getCountryFlagByCode(iso2) : '🌐';
+});
+
+const money = useMaskedInput({
+  mask: maskNumberOptions({ thousandSeparator: ',', precision: 2, prefix: '$' }),
+});
+
+const date = useMaskedInput({ mask: maskDateOptions({ mode: 'dd/mm/yyyy' }) });
+
+const card = useMaskedInput({ mask: maskCardOptions() });
+// The grouping (and this label) follow the detected brand: Amex is 4-6-5, etc.
+const cardBrand = computed(() => findCardBrand(card.unmasked.value)?.name ?? 'unknown');
+// Luhn + length validation (separate from the mask, which only formats).
+const cardValid = computed(() => isValidCardNumber(card.unmasked.value));
+
+const inputClass = 'w-full rounded-lg border border-(--border) bg-(--bg) px-3 py-2 text-sm text-(--fg) placeholder:text-(--fg-subtle) transition focus:outline-none focus:border-(--accent) focus:ring-2 focus:ring-(--ring)';
+const labelClass = 'text-xs font-medium uppercase tracking-wide text-(--fg-subtle)';
+const readoutClass = 'flex flex-wrap items-center gap-2 font-mono text-xs text-(--fg-muted)';
+
+function badgeClass(on: boolean): string {
+  return on
+    ? 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400'
+    : 'border-(--border) bg-(--bg-inset) text-(--fg-subtle)';
+}
+</script>
+
+<template>
+  <div class="flex w-full max-w-sm flex-col gap-5">
+    <div class="flex flex-col gap-1.5">
+      <label :class="labelClass">Phone</label>
+      <input v-bind="phone.bind" type="text" placeholder="+1 (###) ###-####" :class="inputClass">
+      <div :class="readoutClass">
+        <span>raw: "{{ phone.unmasked.value }}"</span>
+        <span class="inline-flex items-center rounded-md border px-1.5 py-0.5 font-medium" :class="badgeClass(phone.complete.value)">
+          {{ phone.complete.value ? 'complete' : 'incomplete' }}
+        </span>
+      </div>
+    </div>
+
+    <div class="flex flex-col gap-1.5">
+      <label :class="labelClass">International phone (mask follows the country code)</label>
+      <div class="flex items-center gap-2">
+        <span class="text-xl leading-none" aria-hidden="true">{{ intlFlag }}</span>
+        <input v-bind="intl.bind" type="text" inputmode="tel" placeholder="+1 / +7 / +44 / +380 …" :class="[inputClass, 'min-w-0 flex-1']">
+      </div>
+      <div :class="readoutClass">
+        <span>{{ intlCountry?.name ?? 'unknown country' }}</span>
+        <span>raw: "{{ intl.unmasked.value }}"</span>
+      </div>
+    </div>
+
+    <div class="flex flex-col gap-1.5">
+      <label :class="labelClass">Amount</label>
+      <input v-bind="money.bind" type="text" inputmode="decimal" placeholder="$0.00" :class="inputClass">
+      <div :class="readoutClass">
+        <span>raw: "{{ money.unmasked.value }}"</span>
+      </div>
+    </div>
+
+    <div class="flex flex-col gap-1.5">
+      <label :class="labelClass">Date</label>
+      <input v-bind="date.bind" type="text" inputmode="numeric" placeholder="dd/mm/yyyy" :class="inputClass">
+      <div :class="readoutClass">
+        <span>raw: "{{ date.unmasked.value }}"</span>
+        <span class="inline-flex items-center rounded-md border px-1.5 py-0.5 font-medium" :class="badgeClass(date.complete.value)">
+          {{ date.complete.value ? 'complete' : 'incomplete' }}
+        </span>
+      </div>
+    </div>
+
+    <div class="flex flex-col gap-1.5">
+      <label :class="labelClass">Card number (mask follows the brand)</label>
+      <input v-bind="card.bind" type="text" inputmode="numeric" placeholder="#### #### #### ####" :class="inputClass">
+      <div :class="readoutClass">
+        <span>{{ cardBrand }}</span>
+        <span>raw: "{{ card.unmasked.value }}"</span>
+        <span class="inline-flex items-center rounded-md border px-1.5 py-0.5 font-medium" :class="badgeClass(cardValid)">
+          {{ cardValid ? 'valid' : 'invalid' }}
+        </span>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/vue/toolkit/src/composables/forms/useMaskedInput/index.test.ts b/vue/toolkit/src/composables/forms/useMaskedInput/index.test.ts
new file mode 100644
index 0000000..0316624
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedInput/index.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { defineComponent, h, nextTick } from 'vue';
+import { maskNumberOptions } from '../mask';
+import type { MaskOptionInput } from '../mask';
+import { useMaskedInput } from './index';
+import type { UseMaskedInputReturn } from './index';
+
+function mountInput(mask: MaskOptionInput): {
+  api: UseMaskedInputReturn;
+  input: HTMLInputElement;
+  unmount: () => void;
+} {
+  let api!: UseMaskedInputReturn;
+  const wrapper = mount(
+    defineComponent({
+      setup() {
+        api = useMaskedInput({ mask });
+        return () => h('input', api.bind as unknown as Record<string, unknown>);
+      },
+    }),
+    { attachTo: document.body },
+  );
+
+  return { api, input: wrapper.element as HTMLInputElement, unmount: () => wrapper.unmount() };
+}
+
+describe(useMaskedInput, () => {
+  it('binds the element via `bind` and conforms through ensureFitsMask', () => {
+    const { api, input, unmount } = mountInput('+1 (###) ###-####');
+
+    input.value = '1234567890';
+    api.ensureFitsMask();
+
+    expect(input.value).toBe('+1 (123) 456-7890');
+    expect(api.unmasked.value).toBe('1234567890');
+    expect(api.complete.value).toBeTruthy();
+
+    unmount();
+  });
+
+  it('masks a real beforeinput dispatched on the bound element', () => {
+    const { input, unmount } = mountInput('+1 (###) ###-####');
+
+    input.focus();
+    input.value = '+1 (12';
+    input.setSelectionRange(6, 6);
+
+    const event = new InputEvent('beforeinput', { inputType: 'insertText', data: '3', cancelable: true });
+    input.dispatchEvent(event);
+
+    expect(input.value).toBe('+1 (123) ');
+    expect(event.defaultPrevented).toBeTruthy();
+
+    unmount();
+  });
+
+  it('re-conforms on the input event (fallback path)', () => {
+    const { api, input, unmount } = mountInput('+1 (###) ###-####');
+
+    input.value = '99';
+    input.dispatchEvent(new Event('input'));
+
+    expect(input.value).toBe('+1 (99');
+    expect(api.unmasked.value).toBe('99');
+
+    unmount();
+  });
+
+  it('sets the value programmatically via setValue', () => {
+    const { api, input, unmount } = mountInput('+1 (###) ###-####');
+
+    api.setValue('5551234567');
+
+    expect(input.value).toBe('+1 (555) 123-4567');
+    expect(api.unmasked.value).toBe('5551234567');
+
+    unmount();
+  });
+
+  it('reports the raw value of a number mask through onAccept-fed refs', async () => {
+    const { api, input, unmount } = mountInput(maskNumberOptions({ thousandSeparator: ',' }));
+    await nextTick();
+
+    input.value = '1234567';
+    input.dispatchEvent(new Event('input'));
+
+    expect(input.value).toBe('1,234,567');
+    expect(api.unmasked.value).toBe('1234567');
+
+    unmount();
+  });
+});
diff --git a/vue/toolkit/src/composables/forms/useMaskedInput/index.ts b/vue/toolkit/src/composables/forms/useMaskedInput/index.ts
new file mode 100644
index 0000000..036b3a4
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedInput/index.ts
@@ -0,0 +1,185 @@
+import { computed, shallowRef, toValue, watch } from 'vue';
+import { readInputState, writeInputState } from '@robonen/platform/browsers';
+import type { TextFieldElement } from '@robonen/platform/browsers';
+import { isMaskComplete, resolveMask } from '../mask/conform';
+import {
+  MASK_NOOP,
+  MaskModel,
+  maskTransform,
+  normalizeMaskOptions,
+  resolveMaskOptions,
+  runPostprocessors,
+  runPreprocessors,
+  unmask,
+} from '../mask/model';
+import type { ElementState, MaskOptionInput, ResolvedMaskOptions } from '../mask/types';
+import type { MaskInputBindings, UseMaskedInputOptions, UseMaskedInputReturn } from './types';
+
+export type { MaskInputBindings, UseMaskedInputOptions, UseMaskedInputReturn } from './types';
+
+/**
+ * @name useMaskedInput
+ * @category Forms
+ * @description Headless input masking. Returns a `bind` object to spread onto an
+ * `<input>`/`<textarea>` (`<input v-bind="bind">`) — it carries the template ref
+ * and the event handlers, so there is no separate ref wiring. Conforms the value
+ * on every keystroke (insert/delete/paste/IME) with a correct caret, and exposes
+ * the `masked`/`unmasked` views plus a `complete` signal.
+ *
+ * @param {UseMaskedInputOptions} options The mask and behavior
+ * @returns {UseMaskedInputReturn} `bind`, `masked`, `unmasked`, `complete`, `ensureFitsMask`, `setValue`
+ *
+ * @example
+ * const phone = useMaskedInput({ mask: '+1 (###) ###-####' });
+ * // <input v-bind="phone.bind">
+ * // phone.unmasked.value → '1234567890'
+ *
+ * @example
+ * const amount = useMaskedInput({
+ *   mask: maskNumberOptions({ thousandSeparator: ',', precision: 2, prefix: '$' }),
+ *   onAccept: ({ unmasked }) => save(unmasked),
+ * });
+ *
+ * @since 0.0.17
+ */
+export function useMaskedInput(options: UseMaskedInputOptions): UseMaskedInputReturn {
+  const masked = shallowRef('');
+  const unmasked = shallowRef('');
+  const element = shallowRef<TextFieldElement | null>(null);
+
+  // Memoize the resolved options on the mask source: currentOptions() runs on
+  // every event/handler and every `complete` read, but the result is a pure
+  // function of the (referentially stable) mask source + overwriteMode.
+  let cachedSource: MaskOptionInput | undefined;
+  let cachedResolved: ResolvedMaskOptions | undefined;
+
+  function currentOptions(): ResolvedMaskOptions {
+    const source = toValue(options.mask);
+    if (source !== cachedSource || cachedResolved === undefined) {
+      cachedSource = source;
+      const base = normalizeMaskOptions(source);
+      cachedResolved = resolveMaskOptions({
+        ...base,
+        overwriteMode: options.overwriteMode ?? base.overwriteMode,
+      });
+    }
+    return cachedResolved;
+  }
+
+  const complete = computed<boolean>(() => {
+    const value = masked.value;
+    const mask = resolveMask(currentOptions().mask, { value, selection: [value.length, value.length] });
+    return isMaskComplete(value, mask);
+  });
+
+  function commit(el: TextFieldElement, state: ElementState, options_: ResolvedMaskOptions): void {
+    writeInputState(el, state);
+
+    if (masked.value === el.value)
+      return;
+
+    masked.value = el.value;
+    unmasked.value = unmask(el.value, options_);
+    options.onAccept?.({ masked: masked.value, unmasked: unmasked.value });
+  }
+
+  function ensureFitsMask(): void {
+    const el = element.value;
+    if (!el)
+      return;
+
+    const options_ = currentOptions();
+    commit(el, maskTransform(readInputState(el), options_), options_);
+  }
+
+  function setValue(value: string): void {
+    const options_ = currentOptions();
+    const next = maskTransform({ value, selection: [value.length, value.length] }, options_);
+    const el = element.value;
+
+    if (el) {
+      commit(el, next, options_);
+      return;
+    }
+
+    // No element bound yet — keep the exposed refs in sync anyway.
+    if (masked.value !== next.value) {
+      masked.value = next.value;
+      unmasked.value = unmask(next.value, options_);
+      options.onAccept?.({ masked: masked.value, unmasked: unmasked.value });
+    }
+  }
+
+  function onBeforeinput(event: InputEvent): void {
+    const el = element.value;
+    if (!el)
+      return;
+
+    const { inputType, data } = event;
+    const options_ = currentOptions();
+    const before = readInputState(el);
+
+    try {
+      let next: ElementState;
+
+      if (inputType.startsWith('insert') && data !== null) {
+        const pre = runPreprocessors(options_.preprocessors, before, data, 'insert');
+        const model = new MaskModel(pre.elementState, options_);
+        model.addCharacters(pre.data);
+        next = runPostprocessors(options_.postprocessors, { value: model.value, selection: model.selection }, before);
+      }
+      else if (inputType.startsWith('delete')) {
+        const isForward = inputType.toLowerCase().includes('forward');
+        const pre = runPreprocessors(options_.preprocessors, before, '', isForward ? 'deleteForward' : 'deleteBackward');
+        const model = new MaskModel(pre.elementState, options_);
+        model.deleteCharacters(isForward);
+        next = runPostprocessors(options_.postprocessors, { value: model.value, selection: model.selection }, before);
+      }
+      else {
+        // Exotic input types (word delete, replacement, history) and composition
+        // fall through to the `input` handler's full re-conform.
+        return;
+      }
+
+      event.preventDefault();
+      commit(el, next, options_);
+    }
+    catch (error) {
+      if (error === MASK_NOOP) {
+        event.preventDefault();
+        return;
+      }
+      throw error;
+    }
+  }
+
+  function onInput(): void {
+    const el = element.value;
+    // Re-entrancy guard: skip when the value already matches what we produced.
+    if (!el || el.value === masked.value)
+      return;
+
+    ensureFitsMask();
+  }
+
+  const bind: MaskInputBindings = {
+    ref: (el) => {
+      element.value = (el as TextFieldElement | null) ?? null;
+    },
+    onInput,
+    onBeforeinput,
+    onCompositionend: ensureFitsMask,
+  };
+
+  // Initial calibration + re-conform when the element binds or the mask changes.
+  watch(
+    () => [element.value, toValue(options.mask)] as const,
+    ([el]) => {
+      if (el && options.initialCalibration !== false)
+        ensureFitsMask();
+    },
+    { immediate: true, flush: 'post' },
+  );
+
+  return { masked, unmasked, complete, bind, ensureFitsMask, setValue };
+}
diff --git a/vue/toolkit/src/composables/forms/useMaskedInput/types.ts b/vue/toolkit/src/composables/forms/useMaskedInput/types.ts
new file mode 100644
index 0000000..95840db
--- /dev/null
+++ b/vue/toolkit/src/composables/forms/useMaskedInput/types.ts
@@ -0,0 +1,88 @@
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue';
+import type { MaskOptionInput, OverwriteMode } from '../mask';
+
+/**
+ * Options for {@link useMaskedInput}.
+ */
+export interface UseMaskedInputOptions {
+  /**
+   * The mask source: a full options object, a bare mask expression, or a
+   * template string (e.g. `'+1 (###) ###-####'`). May be reactive.
+   */
+  mask: MaybeRefOrGetter<MaskOptionInput>;
+
+  /**
+   * Insert vs overwrite behavior under a collapsed caret. Overrides any
+   * `overwriteMode` carried by the resolved mask options.
+   *
+   * @default 'shift'
+   */
+  overwriteMode?: OverwriteMode;
+
+  /**
+   * Conform the element's current value once, as soon as it is bound.
+   *
+   * @default true
+   */
+  initialCalibration?: boolean;
+
+  /**
+   * Called after each accepted change with both views of the value. The
+   * one-liner bridge for feeding the raw value into a form.
+   */
+  onAccept?: (state: { masked: string; unmasked: string }) => void;
+}
+
+/**
+ * Bindings to spread onto the `<input>`/`<textarea>` via `v-bind`. Contains the
+ * template-ref callback that attaches the element plus the event handlers that
+ * drive masking — no separate `ref` wiring needed.
+ */
+export interface MaskInputBindings {
+  /**
+   * Template-ref callback — attaches the element (`v-bind` sets it for you).
+   */
+  ref: (element: Element | null) => void;
+  /**
+   * `input` handler — re-conforms after exotic/composition input types.
+   */
+  onInput: () => void;
+  /**
+   * `beforeinput` handler — the insert/delete masking pipeline.
+   */
+  onBeforeinput: (event: InputEvent) => void;
+  /**
+   * `compositionend` handler — re-conforms after IME composition.
+   */
+  onCompositionend: () => void;
+}
+
+/**
+ * The reactive API returned by {@link useMaskedInput}.
+ */
+export interface UseMaskedInputReturn {
+  /**
+   * The conformed, displayed value (kept in sync with the element).
+   */
+  masked: ShallowRef<string>;
+  /**
+   * The raw value with fixed mask characters (and preset separators) stripped.
+   */
+  unmasked: Readonly<ShallowRef<string>>;
+  /**
+   * Whether `masked` fully satisfies the mask.
+   */
+  complete: ComputedRef<boolean>;
+  /**
+   * Spread onto the input element: `<input v-bind="bind">`.
+   */
+  bind: MaskInputBindings;
+  /**
+   * Re-conform the element's current value (e.g. after a programmatic set).
+   */
+  ensureFitsMask: () => void;
+  /**
+   * Set the value programmatically — treated as raw input and conformed.
+   */
+  setValue: (value: string) => void;
+}