@adia-ai/web-components 0.2.3 → 0.2.4

package/traits/keyboard-reorderable.js

@@ -0,0 +1,254 @@
+import { defineTrait } from './define.js';
+
+/**
+ * `keyboard-reorderable` — keyboard alternative to `draggable-list-item`.
+ *
+ * Authored for the Tasks UI playground (docs/projects/tasks-playground/spec/).
+ * Per SPEC §6.2 + ARCHITECTURE-REVIEW H2 (category: 'keyboard-navigation').
+ *
+ * Implements the WCAG 2.5.7 single-pointer alternative + ARIA 1.1
+ * draggable-attribute keyboard pattern:
+ *
+ *   Space / Enter (idle) → lift  (emit `dnd-lift`)
+ *   ArrowUp / ArrowDown  → move target index within the source container
+ *                          (emit `dnd-drop-target-change`)
+ *   ArrowLeft / Right    → switch container (move to prev/next sibling
+ *                          `[data-droppable-id]` of the parent collection)
+ *   Space / Enter (lift) → drop  (emit `dnd-drop`)
+ *   Escape               → cancel (emit `dnd-drop-cancel`)
+ *
+ * Source-of-truth model is the same as `draggable-list-item`: emit DOM
+ * CustomEvents that `[droppable]` and `[droppable-collection]` already
+ * listen for; the source element does NOT physically move during the
+ * keyboard "lift" — only `data-keyboard-reorderable-lifting` reflects.
+ *
+ * Pairs with `draggable-list-item` on the same host. Both consume the
+ * existing `announcer-stage.js` aria-live regions (same singleton the
+ * `announcer` trait uses) so a screen reader does not hear two parallel
+ * narrations.
+ */
+
+import { announce } from './announcer-stage.js';
+
+// Same debounce gate as draggable-list-item — module-private throttle
+// for drop-target-change announcements; immediate calls supersede.
+const DEBOUNCE_MS = 200;
+let debounceHandle = null;
+function announceDebounced(message) {
+  if (debounceHandle != null) clearTimeout(debounceHandle);
+  debounceHandle = setTimeout(() => {
+    debounceHandle = null;
+    announce(message, 'polite');
+  }, DEBOUNCE_MS);
+}
+function announceImmediate(message) {
+  if (debounceHandle != null) {
+    clearTimeout(debounceHandle);
+    debounceHandle = null;
+  }
+  announce(message, 'polite');
+}
+
+const ATTR_LIFTING = 'data-keyboard-reorderable-lifting';
+const ATTR_SOURCE_ID = 'data-keyboard-reorderable-id';
+
+function readSiblingsContext(host) {
+  const container = host.parentElement;
+  if (!container) return null;
+  const siblings = Array.from(container.children).filter((c) => c.matches?.('[data-keyboard-reorderable-id], [data-draggable-list-item-id]'));
+  const index = siblings.indexOf(host);
+  return { container, index, siblings };
+}
+
+function readContainerId(el) {
+  /** @type {Element | null} */
+  let cur = el;
+  while (cur && cur !== document.body) {
+    if (cur.hasAttribute?.('data-droppable-id')) return cur.getAttribute('data-droppable-id');
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+function readCollectionContainers(host) {
+  // Walk up to the nearest droppable-collection, then enumerate its
+  // descendant droppables. If there's no collection, return just the
+  // single source container.
+  /** @type {Element | null} */
+  let cur = host;
+  while (cur && cur !== document.body) {
+    if (cur.hasAttribute?.('data-droppable-collection-active')) {
+      return Array.from(cur.querySelectorAll('[data-droppable-id]'));
+    }
+    cur = cur.parentElement;
+  }
+  const sourceContainer = host.closest?.('[data-droppable-id]');
+  return sourceContainer ? [sourceContainer] : [];
+}
+
+export const keyboardReorderable = defineTrait({
+  name: 'keyboard-reorderable',
+  category: 'keyboard-navigation',
+  description: 'Keyboard alternative to draggable-list-item: arrow keys + Space to lift / drop / Esc to cancel',
+  attributes: [ATTR_LIFTING, ATTR_SOURCE_ID],
+  events: ['dnd-lift', 'dnd-drop-target-change', 'dnd-drop', 'dnd-drop-cancel'],
+  config: [],
+  setup({ host }) {
+    let id = host.getAttribute(ATTR_SOURCE_ID);
+    if (!id) {
+      id = `kbreorder-${crypto.randomUUID().slice(0, 8)}`;
+      host.setAttribute(ATTR_SOURCE_ID, id);
+    }
+    if (!host.hasAttribute('tabindex')) host.setAttribute('tabindex', '0');
+
+    let lifted = false;
+    /** @type {string | null} */
+    let targetContainerId = null;
+    let targetIndex = -1;
+    /** @type {{ index: number; container: Element } | null} */
+    let sourceCtx = null;
+    let sourceContainerId = null;
+
+    function isDisabled() {
+      return host.hasAttribute('disabled') || host.getAttribute('aria-disabled') === 'true';
+    }
+
+    function lift() {
+      const ctx = readSiblingsContext(host);
+      if (!ctx) return;
+      sourceCtx = ctx;
+      sourceContainerId = readContainerId(ctx.container);
+      lifted = true;
+      targetContainerId = sourceContainerId;
+      targetIndex = ctx.index;
+      host.setAttribute(ATTR_LIFTING, '');
+      host.dispatchEvent(new CustomEvent('dnd-lift', {
+        bubbles: true,
+        composed: false,
+        detail: {
+          source_id: id,
+          source_index: ctx.index,
+          source_container_id: sourceContainerId,
+        },
+      }));
+      announceImmediate('Picked up item. Use arrow keys to move. Press Space to drop. Press Escape to cancel.');
+      emitTargetChange();
+    }
+
+    function emitTargetChange() {
+      document.dispatchEvent(new CustomEvent('dnd-drop-target-change', {
+        bubbles: true,
+        composed: false,
+        detail: {
+          source_id: id,
+          target_container_id: targetContainerId,
+          target_index: targetIndex,
+          pointer: { x: 0, y: 0 },
+        },
+      }));
+      if (targetContainerId) {
+        announceDebounced(`Drop position ${targetIndex + 1} in ${targetContainerId}.`);
+      }
+    }
+
+    function moveWithinContainer(delta) {
+      const containers = readCollectionContainers(host);
+      const containerEl = containers.find((c) => c.getAttribute('data-droppable-id') === targetContainerId);
+      const total = containerEl
+        ? containerEl.querySelectorAll('[data-keyboard-reorderable-id], [data-draggable-list-item-id]').length
+        : (sourceCtx?.siblings.length ?? 0);
+      // Allow target index 0..total inclusive (insert-after-last counts).
+      const next = Math.max(0, Math.min(total, targetIndex + delta));
+      if (next === targetIndex) return;
+      targetIndex = next;
+      emitTargetChange();
+    }
+
+    function switchContainer(delta) {
+      const containers = readCollectionContainers(host);
+      if (containers.length <= 1) return;
+      const ids = containers.map((c) => c.getAttribute('data-droppable-id'));
+      const curIdx = ids.indexOf(targetContainerId);
+      const nextIdx = Math.max(0, Math.min(ids.length - 1, curIdx + delta));
+      if (nextIdx === curIdx) return;
+      targetContainerId = ids[nextIdx];
+      targetIndex = 0;
+      emitTargetChange();
+    }
+
+    function drop() {
+      if (!lifted || !sourceCtx) return;
+      document.dispatchEvent(new CustomEvent('dnd-drop', {
+        bubbles: true,
+        composed: false,
+        detail: {
+          source_id: id,
+          source_index: sourceCtx.index,
+          source_container_id: sourceContainerId,
+          target_container_id: targetContainerId,
+          target_index: targetIndex,
+        },
+      }));
+      announceImmediate(`Dropped item in ${targetContainerId} at position ${targetIndex + 1}.`);
+      reset();
+    }
+
+    function cancel() {
+      if (!lifted) return;
+      document.dispatchEvent(new CustomEvent('dnd-drop-cancel', {
+        bubbles: true,
+        composed: false,
+        detail: { source_id: id, reason: 'esc' },
+      }));
+      announceImmediate('Drag cancelled. Item returned to its original position.');
+      reset();
+    }
+
+    function reset() {
+      lifted = false;
+      sourceCtx = null;
+      sourceContainerId = null;
+      targetContainerId = null;
+      targetIndex = -1;
+      host.removeAttribute(ATTR_LIFTING);
+    }
+
+    function onKeyDown(e) {
+      if (isDisabled()) return;
+      if (e.key === ' ' || e.key === 'Enter') {
+        e.preventDefault();
+        if (!lifted) lift();
+        else drop();
+        return;
+      }
+      if (e.key === 'Escape' && lifted) {
+        e.preventDefault();
+        cancel();
+        return;
+      }
+      if (!lifted) return;
+      switch (e.key) {
+        case 'ArrowUp':    e.preventDefault(); moveWithinContainer(-1); break;
+        case 'ArrowDown':  e.preventDefault(); moveWithinContainer(1); break;
+        case 'ArrowLeft':  e.preventDefault(); switchContainer(-1); break;
+        case 'ArrowRight': e.preventDefault(); switchContainer(1); break;
+      }
+    }
+
+    function onBlur() {
+      // If focus leaves the host while lifted, cancel — keyboard mode
+      // is bound to the focused source. Pointer drag has its own flow.
+      if (lifted) cancel();
+    }
+
+    host.addEventListener('keydown', onKeyDown);
+    host.addEventListener('blur', onBlur);
+
+    return () => {
+      host.removeEventListener('keydown', onKeyDown);
+      host.removeEventListener('blur', onBlur);
+      reset();
+      host.removeAttribute(ATTR_SOURCE_ID);
+    };
+  },
+});

package/traits/keyboard-reorderable.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { keyboardReorderable } from './keyboard-reorderable.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
+
+// Minimal smoke coverage. Keyboard-reorderable is the WCAG 2.5.7 +
+// ARIA 1.1 alternative to draggable-list-item for the
+// docs/projects/tasks-playground/ DnD model. Cases below verify
+// only the trait's own surface (schema, attribute lifecycle, id
+// assignment, tabindex injection). Multi-container keyboard flow
+// belongs in the playground integration suite.
+
+describe('keyboard-reorderable', () => {
+  beforeEach(resetDOM);
+
+  it('schema shape is defined', () => {
+    expect(keyboardReorderable.schema.name).toBe('keyboard-reorderable');
+    expect(keyboardReorderable.schema.category).toBe('keyboard-navigation');
+    expect(keyboardReorderable.schema.description.length).toBeGreaterThanOrEqual(11);
+    expect(keyboardReorderable.schema.events).toContain('dnd-lift');
+    expect(keyboardReorderable.schema.events).toContain('dnd-drop');
+  });
+
+  it('connect assigns an id + ensures tabindex', () => {
+    const host = mountHost('div');
+    connectTrait(keyboardReorderable, host);
+    expect(host.getAttribute('data-keyboard-reorderable-id')).toBeTruthy();
+    expect(host.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('connect respects pre-existing tabindex', () => {
+    const host = mountHost('div', { tabindex: '-1' });
+    connectTrait(keyboardReorderable, host);
+    expect(host.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('disconnect clears its attributes', () => {
+    const host = mountHost('div');
+    const inst = keyboardReorderable();
+    inst.connect(host);
+    host.setAttribute('data-keyboard-reorderable-lifting', '');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-keyboard-reorderable-lifting')).toBe(false);
+    expect(host.hasAttribute('data-keyboard-reorderable-id')).toBe(false);
+  });
+});

package/traits/layout-animation.js

@@ -0,0 +1,229 @@
+import { defineTrait } from './define.js';
+import { prefersReducedMotion } from './motion.js';
+
+/**
+ * layout-animation — FLIP (First / Last / Invert / Play) layout transitions.
+ *
+ * Captures the host's bounding rect BEFORE a layout change, reads the new rect
+ * AFTER, then applies an inverse `transform: translate(dx, dy) scale(sx, sy)`
+ * that visually pins the host at its old position — finally animating the
+ * transform back to identity over a configurable duration. The host's actual
+ * layout-driven position (set by Grid / Flex / DOM order / class flips) is
+ * what triggers the animation.
+ *
+ * Trigger model — manual + observer combo:
+ *   1. MutationObserver on host.parentElement watching for childList changes.
+ *      When the host is reordered among its siblings, FLIP runs.
+ *   2. `data-layout-animate-trigger` — set any value to fire FLIP comparing
+ *      the cached snapshot to the current rect. Useful for class-driven
+ *      layout shifts that don't reorder DOM nodes.
+ *
+ * Snapshots are captured on connect, after every observer-driven FLIP, and
+ * every time the trigger attribute changes. The snapshot read is rAF-debounced
+ * so a burst of mutations only schedules one capture.
+ *
+ * Reduced-motion: skip the inversion entirely; the host snaps to its new
+ * position. The done event still fires synchronously so caller logic gated on
+ * settle doesn't stall.
+ */
+export const layoutAnimation = defineTrait({
+  name: 'layout-animation',
+  category: 'motion-positioning',
+  description: 'FLIP-style layout transition: animate from old to new bounds without explicit coordinates',
+  attributes: ['data-layout-animation-active'],
+  events: ['layout-animation-done'],
+  config: [
+    'data-layout-animate-duration',
+    'data-layout-animate-easing',
+    'data-layout-animate-trigger',
+  ],
+  setup({ host }) {
+    let snapshot = null;          // last captured DOMRect-shaped {x,y,w,h}
+    let activeAnimation = null;   // the in-flight Web Animation
+    let captureRafId = null;      // debounced rAF for snapshot capture
+    let mutationObserver = null;
+    let attrObserver = null;
+
+    function readDuration() {
+      const raw = host.getAttribute('data-layout-animate-duration');
+      const n = parseInt(raw, 10);
+      return Number.isFinite(n) && n > 0 ? n : 300;
+    }
+
+    function readEasing() {
+      return host.getAttribute('data-layout-animate-easing') || 'cubic-bezier(0.2, 0.8, 0.2, 1)';
+    }
+
+    function rectOf(el) {
+      // getBoundingClientRect is unavailable in some test environments
+      // (jsdom is fine; happy-dom returns zeros). Fall back to a zero rect
+      // — the FLIP becomes a no-op rather than throwing.
+      if (typeof el.getBoundingClientRect !== 'function') {
+        return { x: 0, y: 0, width: 0, height: 0 };
+      }
+      const r = el.getBoundingClientRect();
+      return { x: r.left, y: r.top, width: r.width, height: r.height };
+    }
+
+    function captureSnapshot() {
+      snapshot = rectOf(host);
+    }
+
+    function scheduleCapture() {
+      if (captureRafId != null) return;
+      if (typeof requestAnimationFrame !== 'function') {
+        captureSnapshot();
+        return;
+      }
+      captureRafId = requestAnimationFrame(() => {
+        captureRafId = null;
+        captureSnapshot();
+      });
+    }
+
+    function fireDone() {
+      host.dispatchEvent(new CustomEvent('layout-animation-done', { bubbles: true }));
+    }
+
+    function flip() {
+      // No prior snapshot — this is the first observation; just record and exit.
+      if (!snapshot) {
+        captureSnapshot();
+        return;
+      }
+
+      const last = rectOf(host);
+      const dx = snapshot.x - last.x;
+      const dy = snapshot.y - last.y;
+      const sx = snapshot.width  > 0 && last.width  > 0 ? snapshot.width  / last.width  : 1;
+      const sy = snapshot.height > 0 && last.height > 0 ? snapshot.height / last.height : 1;
+
+      // No meaningful delta — skip the play and re-baseline.
+      if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5 && Math.abs(sx - 1) < 0.01 && Math.abs(sy - 1) < 0.01) {
+        snapshot = last;
+        return;
+      }
+
+      // Reduced-motion: snap to the new position; fire done synchronously.
+      if (prefersReducedMotion()) {
+        snapshot = last;
+        host.setAttribute('data-layout-animation-active', '');
+        queueMicrotask(() => {
+          host.removeAttribute('data-layout-animation-active');
+          fireDone();
+        });
+        return;
+      }
+
+      // Cancel any previous in-flight FLIP so they don't stack.
+      if (activeAnimation && typeof activeAnimation.cancel === 'function') {
+        try { activeAnimation.cancel(); } catch { /* noop */ }
+        activeAnimation = null;
+      }
+
+      const duration = readDuration();
+      const easing = readEasing();
+
+      // Bail gracefully when Web Animations API isn't available (SSR, JSDOM,
+      // happy-dom). Snap + fire done so caller logic doesn't stall.
+      if (typeof host.animate !== 'function') {
+        snapshot = last;
+        host.setAttribute('data-layout-animation-active', '');
+        queueMicrotask(() => {
+          host.removeAttribute('data-layout-animation-active');
+          fireDone();
+        });
+        return;
+      }
+
+      host.setAttribute('data-layout-animation-active', '');
+
+      const fromTransform = `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`;
+      const toTransform   = 'translate(0px, 0px) scale(1, 1)';
+
+      try {
+        activeAnimation = host.animate(
+          [
+            { transform: fromTransform, transformOrigin: 'top left' },
+            { transform: toTransform,   transformOrigin: 'top left' },
+          ],
+          { duration, easing, fill: 'none' },
+        );
+      } catch {
+        snapshot = last;
+        host.removeAttribute('data-layout-animation-active');
+        queueMicrotask(fireDone);
+        return;
+      }
+
+      const onFinish = () => {
+        activeAnimation = null;
+        snapshot = rectOf(host);
+        host.removeAttribute('data-layout-animation-active');
+        fireDone();
+      };
+
+      activeAnimation.addEventListener?.('finish', onFinish, { once: true });
+      activeAnimation.addEventListener?.('cancel', () => {
+        activeAnimation = null;
+        host.removeAttribute('data-layout-animation-active');
+      }, { once: true });
+
+      // Re-baseline the snapshot to the new rect for the next FLIP.
+      snapshot = last;
+    }
+
+    // ── Observers ──────────────────────────────────────────────────────────
+
+    if (typeof MutationObserver !== 'undefined') {
+      const parent = host.parentElement;
+      if (parent) {
+        mutationObserver = new MutationObserver((records) => {
+          // Only react when the host's siblings actually shifted.
+          let relevant = false;
+          for (const r of records) {
+            if (r.type === 'childList') { relevant = true; break; }
+          }
+          if (relevant) flip();
+        });
+        mutationObserver.observe(parent, { childList: true });
+      }
+
+      // Watch our own trigger / config attrs. The trigger attr changing is
+      // the explicit "run a FLIP now" signal; duration/easing changes are
+      // read on the next FLIP without needing an observer entry.
+      attrObserver = new MutationObserver((records) => {
+        for (const r of records) {
+          if (r.type === 'attributes' && r.attributeName === 'data-layout-animate-trigger') {
+            flip();
+            return;
+          }
+        }
+      });
+      attrObserver.observe(host, {
+        attributes: true,
+        attributeFilter: ['data-layout-animate-trigger'],
+      });
+    }
+
+    // Capture an initial snapshot once the host has settled into its first
+    // layout pass. Using rAF avoids reading offsetTop / getBoundingClientRect
+    // before the first paint, which is unreliable for some flex containers.
+    scheduleCapture();
+
+    return () => {
+      if (captureRafId != null && typeof cancelAnimationFrame === 'function') {
+        cancelAnimationFrame(captureRafId);
+        captureRafId = null;
+      }
+      if (mutationObserver) { mutationObserver.disconnect(); mutationObserver = null; }
+      if (attrObserver)     { attrObserver.disconnect();     attrObserver = null; }
+      if (activeAnimation && typeof activeAnimation.cancel === 'function') {
+        try { activeAnimation.cancel(); } catch { /* noop */ }
+        activeAnimation = null;
+      }
+      snapshot = null;
+      host.removeAttribute('data-layout-animation-active');
+    };
+  },
+});

package/traits/layout-animation.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { layoutAnimation } from './layout-animation.js';
+import { mountHost, connectTrait, spyEvent, resetDOM, raf } from './test-helpers.js';
+
+describe('layout-animation', () => {
+  beforeEach(resetDOM);
+
+  it('connect does not throw and registers no leftover attribute', () => {
+    const host = mountHost();
+    const inst = connectTrait(layoutAnimation, host);
+    expect(host.hasAttribute('data-layout-animation-active')).toBe(false);
+    inst.disconnect(host);
+  });
+
+  it('disconnect cleans up the active attribute and is idempotent', () => {
+    const host = mountHost();
+    const inst = connectTrait(layoutAnimation, host);
+    host.setAttribute('data-layout-animation-active', '');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-layout-animation-active')).toBe(false);
+    // A second disconnect must not throw.
+    expect(() => inst.disconnect(host)).not.toThrow();
+  });
+
+  it('reads data-layout-animate-duration + data-layout-animate-easing without throwing', () => {
+    const host = mountHost('div', {
+      'data-layout-animate-duration': '500',
+      'data-layout-animate-easing': 'ease-in-out',
+    });
+    expect(() => connectTrait(layoutAnimation, host)).not.toThrow();
+  });
+
+  it('handles a missing duration / easing — defaults apply silently', () => {
+    const host = mountHost();
+    expect(() => connectTrait(layoutAnimation, host)).not.toThrow();
+  });
+
+  it('exposes the expected schema surface', () => {
+    expect(layoutAnimation.schema.name).toBe('layout-animation');
+    expect(layoutAnimation.schema.category).toBe('motion-positioning');
+    expect(layoutAnimation.schema.attributes).toContain('data-layout-animation-active');
+    expect(layoutAnimation.schema.events).toContain('layout-animation-done');
+    expect(layoutAnimation.schema.config).toEqual([
+      'data-layout-animate-duration',
+      'data-layout-animate-easing',
+      'data-layout-animate-trigger',
+    ]);
+  });
+
+  it('parent-childList mutation invokes the FLIP path without throwing', async () => {
+    // Build a parent + sibling so we can mutate child order.
+    const parent = document.createElement('div');
+    document.body.appendChild(parent);
+    const sib = document.createElement('div');
+    const host = document.createElement('div');
+    parent.appendChild(sib);
+    parent.appendChild(host);
+
+    const inst = layoutAnimation();
+    inst.connect(host);
+
+    // Reorder siblings — should drive the MutationObserver callback.
+    expect(() => parent.insertBefore(host, sib)).not.toThrow();
+
+    // Allow the MutationObserver microtask + rAF capture to settle.
+    await Promise.resolve();
+    await raf();
+
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-layout-animation-active')).toBe(false);
+  });
+
+  it('attribute-trigger flip is wired (toggling data-layout-animate-trigger does not throw)', async () => {
+    const host = mountHost();
+    const inst = connectTrait(layoutAnimation, host);
+
+    // Set the trigger — observer should fire a flip(); no DOM rect change in
+    // the test env means it short-circuits to "no meaningful delta", which we
+    // assert by absence of throws + no leftover active attribute after settle.
+    host.setAttribute('data-layout-animate-trigger', '1');
+
+    await Promise.resolve();
+    await raf();
+
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-layout-animation-active')).toBe(false);
+  });
+
+  it('layout-animation-done event listener attaches without error', () => {
+    const host = mountHost();
+    const spy = spyEvent(host, 'layout-animation-done');
+    connectTrait(layoutAnimation, host);
+    // We don't assert spy.count > 0 here — the test environment (happy-dom)
+    // returns zero rects, so the FLIP path short-circuits at the no-delta
+    // gate. The contract we care about is that subscribing doesn't throw.
+    expect(spy.count).toBe(0);
+  });
+
+  it('two parallel instances on different hosts do not interfere', () => {
+    const a = mountHost();
+    const b = mountHost();
+    const ia = connectTrait(layoutAnimation, a);
+    const ib = connectTrait(layoutAnimation, b);
+    expect(() => ia.disconnect(a)).not.toThrow();
+    expect(() => ib.disconnect(b)).not.toThrow();
+  });
+
+  it('disconnect cancels any scheduled snapshot capture', () => {
+    const host = mountHost();
+    const inst = connectTrait(layoutAnimation, host);
+    // Disconnect synchronously after connect — exercises the rAF-cancel branch.
+    expect(() => inst.disconnect(host)).not.toThrow();
+  });
+});