@adia-ai/web-components 0.2.2 → 0.2.4

package/traits/arrow-grid-nav.test.js

@@ -0,0 +1,375 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { arrowGridNav } from './arrow-grid-nav.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './test-helpers.js';
+
+/**
+ * Build a row-flat grid with `total` cells laid out in `cols` columns.
+ * Returns the host element pre-populated with <button> children.
+ */
+function flatGrid(cols, total) {
+  const host = mountHost('div', { 'data-grid-columns': String(cols) });
+  for (let i = 0; i < total; i++) {
+    const btn = document.createElement('button');
+    btn.textContent = `cell-${i}`;
+    btn.setAttribute('data-cell-index', String(i));
+    host.appendChild(btn);
+  }
+  return host;
+}
+
+/**
+ * Build a row-nested grid: each direct child is a row, each row's children
+ * are cells. `rowSpec` is an array of column counts per row.
+ */
+function nestedGrid(rowSpec) {
+  const host = mountHost('div', { 'data-grid-mode': 'row-nested' });
+  rowSpec.forEach((cols, rowIdx) => {
+    const row = document.createElement('div');
+    for (let c = 0; c < cols; c++) {
+      const btn = document.createElement('button');
+      btn.textContent = `r${rowIdx}c${c}`;
+      row.appendChild(btn);
+    }
+    host.appendChild(row);
+  });
+  return host;
+}
+
+function key(host, k, modifiers = {}) {
+  host.dispatchEvent(new KeyboardEvent('keydown', {
+    key: k,
+    bubbles: true,
+    ...modifiers,
+  }));
+}
+
+describe('arrow-grid-nav', () => {
+  beforeEach(resetDOM);
+
+  it('paints active row + col on connect at (0, 0)', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    expect(host.getAttribute('data-grid-active-row')).toBe('0');
+    expect(host.getAttribute('data-grid-active-col')).toBe('0');
+    const first = host.children[0];
+    expect(first.hasAttribute('data-grid-active')).toBe(true);
+    expect(first.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('sets host tabindex to 0 when not pre-set', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    expect(host.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('preserves a pre-set host tabindex', () => {
+    const host = flatGrid(7, 42);
+    host.setAttribute('tabindex', '5');
+    connectTrait(arrowGridNav, host);
+    expect(host.getAttribute('tabindex')).toBe('5');
+  });
+
+  it('non-active cells receive tabindex="-1"', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    expect(host.children[1].getAttribute('tabindex')).toBe('-1');
+    expect(host.children[10].getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('ArrowRight increments col within the row', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowRight');
+    expect(host.getAttribute('data-grid-active-col')).toBe('1');
+    expect(host.getAttribute('data-grid-active-row')).toBe('0');
+    expect(host.children[1].hasAttribute('data-grid-active')).toBe(true);
+    expect(host.children[0].hasAttribute('data-grid-active')).toBe(false);
+  });
+
+  it('ArrowLeft decrements col', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowRight');
+    key(host, 'ArrowRight');
+    key(host, 'ArrowLeft');
+    expect(host.getAttribute('data-grid-active-col')).toBe('1');
+  });
+
+  it('ArrowDown increments row, keeps col', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowRight');
+    key(host, 'ArrowRight');
+    key(host, 'ArrowRight');
+    key(host, 'ArrowDown');
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+    expect(host.getAttribute('data-grid-active-col')).toBe('3');
+    // index 3 + 7 = 10
+    expect(host.children[10].hasAttribute('data-grid-active')).toBe(true);
+  });
+
+  it('ArrowUp decrements row', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowDown');
+    key(host, 'ArrowDown');
+    key(host, 'ArrowUp');
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+  });
+
+  it('Home moves to col 0 within current row', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowDown');
+    key(host, 'ArrowRight');
+    key(host, 'ArrowRight');
+    expect(host.getAttribute('data-grid-active-col')).toBe('2');
+    key(host, 'Home');
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+    expect(host.getAttribute('data-grid-active-col')).toBe('0');
+  });
+
+  it('Ctrl+Home moves to (0, 0)', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowDown');
+    key(host, 'ArrowDown');
+    key(host, 'ArrowRight');
+    key(host, 'Home', { ctrlKey: true });
+    expect(host.getAttribute('data-grid-active-row')).toBe('0');
+    expect(host.getAttribute('data-grid-active-col')).toBe('0');
+  });
+
+  it('End moves to last col in current row', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'End');
+    expect(host.getAttribute('data-grid-active-col')).toBe('6');
+    expect(host.getAttribute('data-grid-active-row')).toBe('0');
+  });
+
+  it('Ctrl+End moves to (lastRow, lastCol)', () => {
+    const host = flatGrid(7, 42); // 6 rows × 7 cols
+    connectTrait(arrowGridNav, host);
+    key(host, 'End', { ctrlKey: true });
+    expect(host.getAttribute('data-grid-active-row')).toBe('5');
+    expect(host.getAttribute('data-grid-active-col')).toBe('6');
+  });
+
+  it('Meta+End is treated as Ctrl+End on Mac', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'End', { metaKey: true });
+    expect(host.getAttribute('data-grid-active-row')).toBe('5');
+    expect(host.getAttribute('data-grid-active-col')).toBe('6');
+  });
+
+  it('Enter dispatches grid-activate with row, col, element', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    const spy = spyEvent(host, 'grid-activate');
+    key(host, 'ArrowRight');
+    key(host, 'ArrowDown');
+    key(host, 'Enter');
+    expect(spy.count).toBe(1);
+    expect(spy.last).toMatchObject({ row: 1, col: 1 });
+    expect(spy.last.element).toBe(host.children[8]); // row 1 col 1 = index 8
+  });
+
+  it('Space dispatches grid-activate', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    const spy = spyEvent(host, 'grid-activate');
+    key(host, ' ');
+    expect(spy.count).toBe(1);
+    expect(spy.last).toMatchObject({ row: 0, col: 0 });
+  });
+
+  it('emits grid-edge "left" at column 0', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    const spy = spyEvent(host, 'grid-edge');
+    key(host, 'ArrowLeft');
+    expect(spy.count).toBe(1);
+    expect(spy.last.edge).toBe('left');
+  });
+
+  it('emits grid-edge "right" at last column', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'End');
+    const spy = spyEvent(host, 'grid-edge');
+    key(host, 'ArrowRight');
+    expect(spy.count).toBe(1);
+    expect(spy.last.edge).toBe('right');
+  });
+
+  it('emits grid-edge "top" at row 0', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    const spy = spyEvent(host, 'grid-edge');
+    key(host, 'ArrowUp');
+    expect(spy.count).toBe(1);
+    expect(spy.last.edge).toBe('top');
+  });
+
+  it('emits grid-edge "bottom" at last row', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    key(host, 'End', { ctrlKey: true });
+    const spy = spyEvent(host, 'grid-edge');
+    key(host, 'ArrowDown');
+    expect(spy.count).toBe(1);
+    expect(spy.last.edge).toBe('bottom');
+  });
+
+  it('grid-cell-change fires when active changes', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    const spy = spyEvent(host, 'grid-cell-change');
+    key(host, 'ArrowRight');
+    key(host, 'ArrowRight');
+    expect(spy.count).toBe(2);
+    expect(spy.last).toMatchObject({ row: 0, col: 2 });
+  });
+
+  it('grid-cell-change does NOT fire when no movement happens at edge', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    const spy = spyEvent(host, 'grid-cell-change');
+    key(host, 'ArrowLeft'); // already at col 0
+    expect(spy.count).toBe(0);
+  });
+
+  it('row-nested mode infers rows from container children', () => {
+    const host = nestedGrid([3, 3, 3]); // 3x3 grid
+    connectTrait(arrowGridNav, host);
+    expect(host.getAttribute('data-grid-active-row')).toBe('0');
+    expect(host.getAttribute('data-grid-active-col')).toBe('0');
+    key(host, 'ArrowDown');
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+    const row1 = host.children[1];
+    expect(row1.children[0].hasAttribute('data-grid-active')).toBe(true);
+  });
+
+  it('row-nested mode handles ragged rows by clamping col on row change', () => {
+    const host = nestedGrid([5, 2, 4]); // row 0 has 5 cols, row 1 has 2, row 2 has 4
+    connectTrait(arrowGridNav, host);
+    key(host, 'End'); // col 4 in row 0
+    expect(host.getAttribute('data-grid-active-col')).toBe('4');
+    key(host, 'ArrowDown'); // row 1 only has 2 cols → clamp to 1
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+    expect(host.getAttribute('data-grid-active-col')).toBe('1');
+  });
+
+  it('disabled cells are skipped in row-flat mode', () => {
+    const host = flatGrid(7, 42);
+    host.children[1].setAttribute('disabled', '');
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowRight');
+    // Disabled child #1 is filtered out → row-flat splits the remaining
+    // 41 cells; index 1 in the post-filter list is original cell #2.
+    expect(host.children[2].hasAttribute('data-grid-active')).toBe(true);
+  });
+
+  it('does not steal arrow keys from <input> within a cell', () => {
+    const host = mountHost('div', { 'data-grid-columns': '3' });
+    for (let i = 0; i < 3; i++) {
+      const cell = document.createElement('div');
+      const inp = document.createElement('input');
+      cell.appendChild(inp);
+      host.appendChild(cell);
+    }
+    connectTrait(arrowGridNav, host);
+    const inp = host.querySelector('input');
+    inp.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    // No movement — col remains 0.
+    expect(host.getAttribute('data-grid-active-col')).toBe('0');
+  });
+
+  it('does not respond to non-handled keys', () => {
+    const host = flatGrid(7, 42);
+    connectTrait(arrowGridNav, host);
+    const spy = spyEvent(host, 'grid-cell-change');
+    key(host, 'a');
+    key(host, 'Tab');
+    key(host, 'Escape');
+    expect(spy.count).toBe(0);
+  });
+
+  it('MutationObserver re-paints when children are added', async () => {
+    const host = flatGrid(7, 7); // 1 row of 7
+    connectTrait(arrowGridNav, host);
+    key(host, 'End'); // col 6
+    expect(host.getAttribute('data-grid-active-col')).toBe('6');
+    // Add 7 more children → row 1 exists.
+    for (let i = 0; i < 7; i++) {
+      const btn = document.createElement('button');
+      btn.textContent = `new-${i}`;
+      host.appendChild(btn);
+    }
+    await new Promise((r) => setTimeout(r, 10));
+    // Active should still be at (0, 6).
+    expect(host.getAttribute('data-grid-active-row')).toBe('0');
+    // Now arrow-down should reach the new row.
+    key(host, 'ArrowDown');
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+  });
+
+  it('disconnect removes all managed attrs from host and active cell', () => {
+    const host = flatGrid(7, 42);
+    const inst = connectTrait(arrowGridNav, host);
+    key(host, 'ArrowRight');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-arrow-grid-nav-active')).toBe(false);
+    expect(host.hasAttribute('data-grid-active-row')).toBe(false);
+    expect(host.hasAttribute('data-grid-active-col')).toBe(false);
+    for (const child of host.children) {
+      expect(child.hasAttribute('data-grid-active')).toBe(false);
+    }
+  });
+
+  it('disconnect removes the keydown listener', () => {
+    const host = flatGrid(7, 42);
+    const inst = connectTrait(arrowGridNav, host);
+    inst.disconnect(host);
+    const spy = spyEvent(host, 'grid-cell-change');
+    key(host, 'ArrowRight');
+    expect(spy.count).toBe(0);
+  });
+
+  it('reconnect after disconnect works', () => {
+    const host = flatGrid(7, 42);
+    const inst1 = connectTrait(arrowGridNav, host);
+    inst1.disconnect(host);
+    const inst2 = connectTrait(arrowGridNav, host);
+    expect(host.getAttribute('data-grid-active-row')).toBe('0');
+    expect(host.children[0].hasAttribute('data-grid-active')).toBe(true);
+    inst2.disconnect(host);
+  });
+
+  it('default mode is row-flat when data-grid-mode missing', () => {
+    const host = flatGrid(4, 12);
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowDown');
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+    expect(host.children[4].hasAttribute('data-grid-active')).toBe(true);
+  });
+
+  it('missing data-grid-columns falls back to 1 (single column)', () => {
+    const host = mountHost('div');
+    for (let i = 0; i < 4; i++) {
+      const btn = document.createElement('button');
+      host.appendChild(btn);
+    }
+    connectTrait(arrowGridNav, host);
+    key(host, 'ArrowDown');
+    expect(host.getAttribute('data-grid-active-row')).toBe('1');
+    expect(host.getAttribute('data-grid-active-col')).toBe('0');
+  });
+
+  it('empty grid does not throw', () => {
+    const host = mountHost('div', { 'data-grid-columns': '7' });
+    expect(() => connectTrait(arrowGridNav, host)).not.toThrow();
+  });
+});

package/traits/attention-pulse.js

@@ -1,5 +1,5 @@
 import { defineTrait } from './define.js';
-import { prefersReducedMotion } from './_motion.js';
+import { prefersReducedMotion } from './motion.js';
 
 export const attentionPulse = defineTrait({
   name: 'attention-pulse',

package/traits/attention-pulse.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { attentionPulse } from './attention-pulse.js';
-import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
 
 describe('attention-pulse', () => {
   beforeEach(resetDOM);

package/traits/confetti-burst.js

@@ -1,91 +1,121 @@
 import { defineTrait } from './define.js';
-import { prefersReducedMotion } from './_motion.js';
+import { prefersReducedMotion } from './motion.js';
+import { getStage, viewportCenterOf, spawnParticle, SHARED_COLORS } from './confetti-stage.js';
+
+/**
+ * `confetti-burst` — upward fountain on connect + on every `press`.
+ *
+ * Each burst pushes ~80 particles into the singleton body-level
+ * `<div popover="manual" id="adia-confetti-stage">`. Particles are
+ * anchored to the host's viewport position at fire-time via
+ * `getBoundingClientRect()` — they escape `overflow: hidden`
+ * ancestors and render above modals, drawers, and any z-stacking
+ * context (the Popover API's top-layer promotion).
+ *
+ * The trait listens for `press` (button-ui's normalized click event)
+ * so declarative usage — `<button-ui traits="confetti-burst">` —
+ * fires a fresh burst on each click. Programmatic usage that calls
+ * `confettiBurst().connect(el)` per-click gets its single burst at
+ * connect-time, matching the existing animation-page contract.
+ */
+const BURST_DURATION_MS = 1500;
 
 export const confettiBurst = defineTrait({
   name: 'confetti-burst',
   category: 'interaction-delight',
-  description: 'Upward fountain particle burst',
+  description: 'Upward fountain particle burst — fires on each `press` event',
   attributes: ['data-confetti-burst-active'],
   events: ['confetti-burst-done'],
   config: [],
   setup({ host }) {
-    // Reduced-motion: skip the burst, fire done event immediately.
-    if (prefersReducedMotion()) {
-      host.setAttribute('data-confetti-burst-active', '');
-      queueMicrotask(() => {
-        host.removeAttribute('data-confetti-burst-active');
-        host.dispatchEvent(new CustomEvent('confetti-burst-done', { bubbles: true }));
-      });
-      return () => host.removeAttribute('data-confetti-burst-active');
-    }
-
-    const canvas = document.createElement('canvas');
-    canvas.style.cssText = 'position:absolute;inset:0;pointer-events:none;z-index:9999;';
-    host.style.position = host.style.position || 'relative';
-    host.appendChild(canvas);
+    const inflight = new Set();
+    const burstTimers = new Set();
 
-    const ctx = canvas.getContext('2d');
-    let rafId = null;
-
-    // Bail gracefully when canvas 2D isn't available (SSR, JSDOM, happy-dom).
-    if (!ctx) {
+    function reducedMotionBurst() {
       host.setAttribute('data-confetti-burst-active', '');
-      // Fire the done event on next tick so listeners still hear it.
       queueMicrotask(() => {
         host.removeAttribute('data-confetti-burst-active');
         host.dispatchEvent(new CustomEvent('confetti-burst-done', { bubbles: true }));
       });
-      return () => {
-        canvas.remove();
-        host.removeAttribute('data-confetti-burst-active');
-      };
     }
 
-    const colors = ['#f44', '#4a4', '#44f', '#ff4', '#f4f', '#4ff'];
-    const particles = Array.from({ length: 80 }, () => ({
-      x: 0.5,
-      y: 0.5,
-      vx: (Math.random() - 0.5) * 8,
-      vy: (Math.random() - 0.5) * 8 - 2,
-      size: Math.random() * 4 + 2,
-      color: colors[Math.floor(Math.random() * colors.length)],
-      life: 1,
-    }));
+    function fireBurst() {
+      if (prefersReducedMotion()) {
+        reducedMotionBurst();
+        return;
+      }
 
-    host.setAttribute('data-confetti-burst-active', '');
-    const startTime = performance.now();
+      const stage = getStage();
+      const center = viewportCenterOf(host);
+      host.setAttribute('data-confetti-burst-active', '');
 
-    function tick(now) {
-      const elapsed = now - startTime;
-      if (elapsed > 2000) {
-        canvas.remove();
-        host.removeAttribute('data-confetti-burst-active');
-        host.dispatchEvent(new CustomEvent('confetti-burst-done', { bubbles: true }));
+      // Detached host (rect = 0,0,0,0): mark active, fire done on
+      // next tick. The original implementation's no-canvas path did
+      // the same shape — graceful degrade, never throw.
+      if (!center) {
+        queueMicrotask(() => {
+          host.removeAttribute('data-confetti-burst-active');
+          host.dispatchEvent(new CustomEvent('confetti-burst-done', { bubbles: true }));
+        });
         return;
       }
 
-      canvas.width = host.offsetWidth;
-      canvas.height = host.offsetHeight;
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      const burstId = Symbol('burst');
+      inflight.add(burstId);
 
-      for (const p of particles) {
-        p.x += p.vx * 0.004;
-        p.y += p.vy * 0.004;
-        p.vy += 0.15;
-        p.life = Math.max(0, 1 - elapsed / 2000);
-        ctx.globalAlpha = p.life;
-        ctx.fillStyle = p.color;
-        ctx.fillRect(p.x * canvas.width, p.y * canvas.height, p.size, p.size);
+      // Spawn ~80 fountain particles. Each gets a random vector
+      // weighted upward (vy < 0), plus gravity baked into a steeper
+      // dy so the trajectory looks parabolic. The keyframes do the
+      // motion; we set dx/dy/rot via custom properties.
+      for (let i = 0; i < 80; i++) {
+        const angle = -Math.PI / 2 + (Math.random() - 0.5) * Math.PI * 0.9;
+        const speed = 80 + Math.random() * 200;
+        const dx = Math.cos(angle) * speed;
+        // Gravity: launch up, fall back. dy is the final offset after
+        // the keyframe — start up by `speed`, end below by gravity.
+        const dy = Math.sin(angle) * speed + 280;
+        const rot = (Math.random() - 0.5) * 720;
+        const size = Math.random() * 4 + 2;
+        const color = SHARED_COLORS[Math.floor(Math.random() * SHARED_COLORS.length)];
+        const dur = 1200 + Math.random() * 300;
+
+        const p = spawnParticle(stage, center.x, center.y, { size, color });
+        p.style.setProperty('--dx', `${dx}px`);
+        p.style.setProperty('--dy', `${dy}px`);
+        p.style.setProperty('--rot', `${rot}deg`);
+        p.style.animation = `adia-confetti-fountain ${dur}ms ease-out forwards`;
       }
-      ctx.globalAlpha = 1;
-      rafId = requestAnimationFrame(tick);
+
+      // Fire `confetti-burst-done` once the burst's lifetime elapses.
+      // We use a single timeout per burst (vs listening for the last
+      // particle's animationend) — robust to detached/early-removed
+      // particles, and matches the original 2s tear-down semantic.
+      const timer = setTimeout(() => {
+        inflight.delete(burstId);
+        if (inflight.size === 0) host.removeAttribute('data-confetti-burst-active');
+        host.dispatchEvent(new CustomEvent('confetti-burst-done', { bubbles: true }));
+      }, BURST_DURATION_MS);
+
+      // Track the timer so disconnect can cancel.
+      burstTimers.add(timer);
     }
 
-    rafId = requestAnimationFrame(tick);
+    // Fire one burst at connect-time. Preserves the existing
+    // animation-page semantic (`confettiBurst().connect(el)` on every
+    // click of a separate trigger button).
+    fireBurst();
+
+    // Listen for `press` so the declarative case
+    // (`<button-ui traits="confetti-burst">`) fires a fresh burst on
+    // each click. button-ui dispatches `press` from its #onClick.
+    const onPress = () => fireBurst();
+    host.addEventListener('press', onPress);
 
     return () => {
-      if (rafId) cancelAnimationFrame(rafId);
-      canvas.remove();
+      host.removeEventListener('press', onPress);
+      for (const t of burstTimers) clearTimeout(t);
+      burstTimers.clear();
+      inflight.clear();
       host.removeAttribute('data-confetti-burst-active');
     };
   },

package/traits/confetti-burst.test.js

@@ -1,9 +1,13 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { confettiBurst } from './confetti-burst.js';
-import { mountHost, connectTrait, spyEvent, resetDOM, wait } from './_test-helpers.js';
+import { _resetStage } from './confetti-stage.js';
+import { mountHost, connectTrait, spyEvent, resetDOM, wait } from './test-helpers.js';
 
 describe('confetti-burst', () => {
-  beforeEach(resetDOM);
+  beforeEach(() => {
+    resetDOM();
+    _resetStage();
+  });
 
   it('sets data-confetti-burst-active on connect', () => {
     const host = mountHost();
@@ -11,12 +15,12 @@ describe('confetti-burst', () => {
     expect(host.hasAttribute('data-confetti-burst-active')).toBe(true);
   });
 
-  it('without canvas (happy-dom), still fires confetti-burst-done', async () => {
+  it('fires confetti-burst-done even without real layout (happy-dom)', async () => {
     const host = mountHost();
     const spy = spyEvent(host, 'confetti-burst-done');
     connectTrait(confettiBurst, host);
-    // In happy-dom, canvas.getContext('2d') returns null. The trait's
-    // graceful-degradation path bails immediately and queues the done event.
+    // happy-dom returns rect = 0,0,0,0 for unattached layout. The
+    // trait's graceful-degradation path queues `done` on next tick.
     await wait(50);
     expect(spy.count).toBeGreaterThanOrEqual(1);
   });
@@ -29,10 +33,14 @@ describe('confetti-burst', () => {
     expect(host.hasAttribute('data-confetti-burst-active')).toBe(false);
   });
 
-  it('host position is set to relative for canvas to anchor', () => {
+  it('host stays unmodified by particle injection', () => {
     const host = mountHost();
-    connectTrait(confettiBurst, host);
-    // Either the canvas-based path or the no-op path leaves the host stable.
+    const inst = connectTrait(confettiBurst, host);
+    // New contract: particles live in the body-level popover stage,
+    // not on the host. The host must not gain children or inline
+    // position/cssText hacks (the old canvas-injection path did).
     expect(host.tagName).toBe('DIV');
+    expect(host.children.length).toBe(0);
+    inst.disconnect(host);
   });
 });