maestro-flow 0.5.31 → 0.5.33

package/.agy/skills/team-interactive-craft/specs/interaction-patterns.md

@@ -0,0 +1,362 @@
+# Interaction Pattern Catalog
+
+Reference patterns for common interactive components. Each pattern defines the core interaction model, browser APIs, state machine, animation approach, and accessibility requirements.
+
+---
+
+## Glass Terminal Pattern
+
+Split-view layout with frosted glass effect, tab navigation, and command input simulation.
+
+**Core Interaction**:
+- Tab-based view switching (2-4 panels)
+- Command input field with syntax-highlighted output
+- Frosted glass background via `backdrop-filter: blur()`
+- Resize-aware layout via ResizeObserver
+
+**State Machine**:
+```
+[idle] --(tab-click)--> [switching]
+[switching] --(transition-end)--> [idle]
+[idle] --(input-focus)--> [input-active]
+[input-active] --(Enter)--> [processing]
+[processing] --(output-ready)--> [idle]
+[input-active] --(Escape)--> [idle]
+```
+
+**Browser APIs**: ResizeObserver, CSS backdrop-filter, CSS custom properties
+
+**Animation**:
+- Tab switch: opacity crossfade (200ms, ease-out), GPU-only
+- Output appear: translateY(10px)->0 + opacity (300ms, ease-out)
+- Cursor blink: CSS animation (1s steps(2))
+
+**CSS Key Properties**:
+```css
+.glass-terminal {
+  backdrop-filter: blur(12px) saturate(180%);
+  -webkit-backdrop-filter: blur(12px) saturate(180%);
+  background: rgba(255, 255, 255, 0.1);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+}
+```
+
+**Accessibility**:
+- role="tablist" + role="tab" + role="tabpanel"
+- aria-selected on active tab
+- Arrow keys navigate tabs, Enter/Space activates
+- Input field: role="textbox", aria-label
+- Output: aria-live="polite" for new content
+
+---
+
+## Split Compare Pattern
+
+Before/after overlay with draggable divider for visual comparison.
+
+**Core Interaction**:
+- Draggable vertical divider splits two overlapping images/views
+- Pointer events for drag with Lerp interpolation (speed: 0.15)
+- clip-path animation reveals before/after content
+- Touch-friendly with full pointer event support
+
+**State Machine**:
+```
+[idle] --(pointerenter)--> [hover]
+[hover] --(pointerdown on divider)--> [dragging]
+[hover] --(pointerleave)--> [idle]
+[dragging] --(pointermove)--> [dragging] (update position)
+[dragging] --(pointerup)--> [settling]
+[settling] --(lerp-complete)--> [idle]
+[any] --(focus + ArrowLeft/Right)--> [keyboard-adjusting]
+[keyboard-adjusting] --(keyup)--> [idle]
+```
+
+**Browser APIs**: Pointer Events, CSS clip-path, ResizeObserver, requestAnimationFrame
+
+**Animation**:
+- Divider follow: Lerp `current += (target - current) * 0.15` per frame
+- Clip-path update: `clip-path: inset(0 0 0 ${position}%)` on after layer
+- Settle: natural Lerp deceleration to final position
+- Hover hint: divider scale(1.1) + glow (200ms, ease-out)
+
+**CSS Key Properties**:
+```css
+.split-compare__after {
+  clip-path: inset(0 0 0 var(--split-position, 50%));
+  transition: none; /* JS-driven via lerp */
+}
+.split-compare__divider {
+  cursor: col-resize;
+  touch-action: none; /* prevent scroll during drag */
+}
+```
+
+**Keyboard**:
+- Tab to divider element (tabindex="0")
+- ArrowLeft/ArrowRight: move divider 2% per keypress
+- Home/End: move to 0%/100%
+
+**Accessibility**:
+- role="slider", aria-valuenow, aria-valuemin="0", aria-valuemax="100"
+- aria-label="Image comparison slider"
+- Keyboard step: 2%, large step (PageUp/PageDown): 10%
+
+---
+
+## Scroll-Snap Gallery Pattern
+
+Horizontal scroll with CSS scroll-snap, navigation controls, and active item detection.
+
+**Core Interaction**:
+- CSS scroll-snap-type: x mandatory on container
+- scroll-snap-align: start on children
+- Touch-friendly: native momentum scrolling
+- Navigation dots/arrows update with IntersectionObserver
+- Keyboard: ArrowLeft/ArrowRight navigate between items
+
+**State Machine**:
+```
+[idle] --(scroll-start)--> [scrolling]
+[scrolling] --(scroll-end)--> [snapped]
+[snapped] --(intersection-change)--> [idle] (update active)
+[idle] --(arrow-click)--> [navigating]
+[navigating] --(scrollTo-complete)--> [idle]
+[idle] --(keyboard-arrow)--> [navigating]
+```
+
+**Browser APIs**: CSS scroll-snap, IntersectionObserver, Element.scrollTo(), Pointer Events
+
+**Animation**:
+- Scroll: native CSS scroll-snap (browser-handled, smooth)
+- Active dot: scale(1) -> scale(1.3) + opacity change (200ms, ease-out)
+- Item entry: opacity 0->1 as intersection threshold crossed (CSS transition)
+- Arrow hover: translateX(+-2px) (150ms, ease-out)
+
+**CSS Key Properties**:
+```css
+.gallery__track {
+  display: flex;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  scroll-behavior: smooth;
+  -webkit-overflow-scrolling: touch;
+  scrollbar-width: none; /* Firefox */
+}
+.gallery__track::-webkit-scrollbar { display: none; }
+.gallery__item {
+  scroll-snap-align: start;
+  flex: 0 0 100%; /* or 80% for peek */
+}
+```
+
+**IntersectionObserver Config**:
+```javascript
+new IntersectionObserver(entries => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) updateActiveItem(entry.target);
+  });
+}, { root: trackElement, threshold: 0.5 });
+```
+
+**Accessibility**:
+- role="region", aria-label="Image gallery"
+- role="group" on each item, aria-roledescription="slide"
+- aria-label="Slide N of M" on each item
+- Navigation: role="tablist" on dots, role="tab" on each dot
+- ArrowLeft/ArrowRight between items, Home/End to first/last
+
+---
+
+## Scroll Reveal Pattern
+
+Elements animate into view as user scrolls, using IntersectionObserver with staggered delays.
+
+**Core Interaction**:
+- IntersectionObserver with threshold: 0.1 triggers entry animation
+- data-reveal attribute marks revealable elements
+- Staggered delay: index * 80ms for grouped items
+- GPU-only: translateY(20px)->0 + opacity 0->1
+- One-shot: element stays visible after reveal
+
+**State Machine**:
+```
+[hidden] --(intersection: entering)--> [revealing]
+[revealing] --(animation-end)--> [visible]
+[visible] -- (terminal state, no transition out)
+```
+
+**Browser APIs**: IntersectionObserver, CSS transitions, requestAnimationFrame
+
+**Animation**:
+- Entry: translateY(20px) -> translateY(0) + opacity 0->1
+- Duration: 400ms
+- Easing: cubic-bezier(0.16, 1, 0.3, 1)
+- Stagger: CSS custom property `--reveal-delay: calc(var(--reveal-index) * 80ms)`
+- Reduced motion: opacity-only crossfade (200ms)
+
+**CSS Key Properties**:
+```css
+[data-reveal] {
+  opacity: 0;
+  transform: translateY(20px);
+  transition: opacity 400ms cubic-bezier(0.16, 1, 0.3, 1),
+              transform 400ms cubic-bezier(0.16, 1, 0.3, 1);
+  transition-delay: var(--reveal-delay, 0ms);
+}
+[data-reveal="visible"] {
+  opacity: 1;
+  transform: translateY(0);
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-reveal] {
+    transform: none;
+    transition: opacity 200ms ease;
+  }
+}
+```
+
+**IntersectionObserver Config**:
+```javascript
+new IntersectionObserver(entries => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      entry.target.dataset.reveal = 'visible';
+      observer.unobserve(entry.target); // one-shot
+    }
+  });
+}, { threshold: 0.1 });
+```
+
+**Accessibility**:
+- Content must be accessible in DOM before reveal (no display:none)
+- Use opacity + transform only (content readable by screen readers at all times)
+- aria-hidden NOT used (content is always in accessibility tree)
+- Stagger delay < 500ms total to avoid perception of broken page
+
+---
+
+## Lens/Overlay Pattern
+
+Magnification overlay that follows pointer position over an image or content area.
+
+**Core Interaction**:
+- Circular/rectangular lens follows pointer over source content
+- Magnified view rendered via CSS transform: scale() on background
+- Lens positioned via transform: translate() (GPU-only)
+- Toggle on click/tap, follow on pointermove
+
+**State Machine**:
+```
+[inactive] --(click/tap on source)--> [active]
+[active] --(pointermove)--> [active] (update lens position)
+[active] --(click/tap)--> [inactive]
+[active] --(pointerleave)--> [inactive]
+[active] --(Escape)--> [inactive]
+[inactive] --(Enter/Space on source)--> [active-keyboard]
+[active-keyboard] --(Arrow keys)--> [active-keyboard] (move lens)
+[active-keyboard] --(Escape)--> [inactive]
+```
+
+**Browser APIs**: Pointer Events, CSS transform, CSS clip-path/border-radius, requestAnimationFrame
+
+**Animation**:
+- Lens appear: opacity 0->1 + scale(0.8)->scale(1) (200ms, ease-out)
+- Lens follow: Lerp position tracking (speed: 0.2)
+- Lens dismiss: opacity 1->0 + scale(1)->scale(0.9) (150ms, ease-in)
+
+**CSS Key Properties**:
+```css
+.lens__overlay {
+  position: absolute;
+  width: 150px;
+  height: 150px;
+  border-radius: 50%;
+  overflow: hidden;
+  pointer-events: none;
+  transform: translate(var(--lens-x), var(--lens-y));
+  will-change: transform;
+}
+.lens__magnified {
+  transform: scale(var(--lens-zoom, 2));
+  transform-origin: var(--lens-origin-x) var(--lens-origin-y);
+}
+```
+
+**Accessibility**:
+- Source: role="img" with descriptive aria-label
+- Lens toggle: aria-expanded on source element
+- Keyboard: Enter/Space to activate, Arrow keys to pan, Escape to dismiss
+- Screen reader: aria-live="polite" announces zoom state changes
+- Not essential content: decorative enhancement, base content always visible
+
+---
+
+## Lightbox Pattern
+
+Full-viewport overlay for content viewing with background dim and entry animation.
+
+**Core Interaction**:
+- Click/tap thumbnail opens full-viewport overlay
+- Background dim via backdrop-filter + background overlay
+- Scale-up entry animation from thumbnail position
+- Dismiss: click outside, Escape key, close button
+- Focus trap: Tab cycles within lightbox
+- Scroll lock on body while open
+
+**State Machine**:
+```
+[closed] --(click thumbnail)--> [opening]
+[opening] --(animation-end)--> [open]
+[open] --(click-outside / Escape / close-btn)--> [closing]
+[closing] --(animation-end)--> [closed]
+[open] --(ArrowLeft)--> [navigating-prev]
+[open] --(ArrowRight)--> [navigating-next]
+[navigating-*] --(content-loaded)--> [open]
+```
+
+**Browser APIs**: CSS backdrop-filter, Focus trap (manual), CSS transitions, Pointer Events
+
+**Animation**:
+- Open: scale(0.85)->scale(1) + opacity 0->1 (300ms, cubic-bezier(0.16,1,0.3,1))
+- Close: scale(1)->scale(0.95) + opacity 1->0 (200ms, ease-in)
+- Backdrop: opacity 0->1 (250ms, ease-out)
+- Navigation: translateX crossfade between items (250ms)
+
+**CSS Key Properties**:
+```css
+.lightbox__backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.8);
+  backdrop-filter: blur(4px);
+  z-index: 1000;
+}
+.lightbox__content {
+  transform: scale(var(--lb-scale, 0.85));
+  opacity: var(--lb-opacity, 0);
+  transition: transform 300ms cubic-bezier(0.16, 1, 0.3, 1),
+              opacity 300ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+.lightbox--open .lightbox__content {
+  --lb-scale: 1;
+  --lb-opacity: 1;
+}
+```
+
+**Focus Trap Implementation**:
+```javascript
+// On open: store trigger, move focus to first focusable in lightbox
+// On Tab: cycle within lightbox (first <-> last focusable)
+// On close: restore focus to original trigger element
+// Prevent body scroll: document.body.style.overflow = 'hidden'
+```
+
+**Accessibility**:
+- role="dialog", aria-modal="true", aria-label="Image viewer"
+- Close button: aria-label="Close lightbox"
+- Focus trap: Tab cycles within dialog
+- Escape dismisses
+- ArrowLeft/ArrowRight for gallery navigation
+- aria-live="polite" announces current item "Image N of M"
+- Scroll lock: prevent background scroll while open

package/.agy/skills/team-interactive-craft/specs/pipelines.md

@@ -0,0 +1,85 @@
+# Pipeline Definitions
+
+Interactive craft pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Count |
+|------|-------------|------------|
+| single | Single component: research -> interaction design -> build -> a11y test | 4 tasks |
+| gallery | Gallery: base component + scroll container, two build phases | 6 tasks |
+| page | Full page: parallel component builds after single interaction design | 3 + N tasks |
+
+## Single Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| RESEARCH-001 | researcher | [] | Interaction inventory, browser API audit, pattern reference |
+| INTERACT-001 | interaction-designer | [RESEARCH-001] | State machine, event flow, gesture spec, animation choreography |
+| BUILD-001 | builder | [INTERACT-001] | Vanilla JS + CSS component: ES module, GPU animations, touch-aware |
+| A11Y-001 | a11y-tester | [BUILD-001] | Keyboard, screen reader, reduced motion, focus, contrast audit |
+
+## Gallery Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| RESEARCH-001 | researcher | [] | Interaction patterns for base component + gallery container |
+| INTERACT-001 | interaction-designer | [RESEARCH-001] | Base component interaction blueprint |
+| BUILD-001 | builder | [INTERACT-001] | Base component implementation |
+| INTERACT-002 | interaction-designer | [BUILD-001] | Gallery/scroll-snap container blueprint |
+| BUILD-002 | builder | [INTERACT-002] | Gallery container + navigation implementation |
+| A11Y-001 | a11y-tester | [BUILD-002] | Full gallery accessibility audit |
+
+## Page Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| RESEARCH-001 | researcher | [] | Interaction patterns for all page sections |
+| INTERACT-001 | interaction-designer | [RESEARCH-001] | Blueprints for all interactive sections |
+| BUILD-001 | builder | [INTERACT-001] | Section 1 component |
+| BUILD-002 | builder | [INTERACT-001] | Section 2 component |
+| ... | builder | [INTERACT-001] | Additional sections (parallel) |
+| BUILD-00N | builder | [INTERACT-001] | Section N component |
+| A11Y-001 | a11y-tester | [BUILD-001..N] | Full page accessibility audit |
+
+## Quality Gate (A11y Checkpoint)
+
+| Checkpoint | Task | Condition | Action |
+|------------|------|-----------|--------|
+| A11Y Gate | A11Y-001 completes | 0 critical, 0 high | Pipeline complete |
+| A11Y GC Loop | A11Y-* completes | Critical or high issues | Create BUILD-fix task, new A11Y task (max 2 rounds) |
+
+## GC Loop Behavior
+
+| Signal | Condition | Action |
+|--------|-----------|--------|
+| a11y_passed | 0 critical, 0 high | GC converged -> pipeline complete |
+| a11y_result | 0 critical, high > 0 | gc_rounds < max -> create BUILD-fix task |
+| fix_required | critical > 0 | gc_rounds < max -> create BUILD-fix task (CRITICAL) |
+| Any | gc_rounds >= max | Escalate to user: accept / try one more / terminate |
+
+## Parallel Spawn Rules
+
+| Mode | After | Spawn Behavior |
+|------|-------|----------------|
+| single | Sequential | One task at a time |
+| gallery | Sequential | One task at a time |
+| page | INTERACT-001 | Spawn BUILD-001..N in parallel (CP-3 fan-out) |
+| page | All BUILD complete | Spawn A11Y-001 |
+
+## Collaboration Patterns
+
+| Pattern | Roles | Description |
+|---------|-------|-------------|
+| CP-1 Linear Pipeline | All | Base sequential flow for single/gallery modes |
+| CP-2 Review-Fix | builder <-> a11y-tester | GC loop with max 2 rounds |
+| CP-3 Parallel Fan-out | builder (multiple) | Page mode: multiple BUILD tasks in parallel |
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| RESEARCH-001 | <session>/research/*.json |
+| INTERACT-* | <session>/interaction/blueprints/*.md |
+| BUILD-* | <session>/build/components/*.js + *.css |
+| A11Y-* | <session>/a11y/a11y-audit-*.md |

package/.agy/skills/team-interactive-craft/specs/team-config.json

@@ -0,0 +1,105 @@
+{
+  "team_name": "interactive-craft",
+  "team_display_name": "Interactive Craft",
+  "description": "Interactive component team with vanilla JS + CSS. Research -> interaction design -> build -> a11y test.",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Scope assessment, pipeline orchestration, GC loop control between builder and a11y-tester",
+      "message_types": ["task_unblocked", "a11y_checkpoint", "fix_required", "error", "shutdown"]
+    },
+    "researcher": {
+      "task_prefix": "RESEARCH",
+      "responsibility": "Interaction pattern analysis, browser API audit, reference pattern collection",
+      "message_types": ["research_ready", "research_progress", "error"]
+    },
+    "interaction-designer": {
+      "task_prefix": "INTERACT",
+      "responsibility": "State machine design, event flow mapping, gesture specification, animation choreography",
+      "message_types": ["blueprint_ready", "blueprint_revision", "blueprint_progress", "error"]
+    },
+    "builder": {
+      "task_prefix": "BUILD",
+      "inner_loop": true,
+      "responsibility": "Vanilla JS + CSS component implementation, progressive enhancement, GPU-only animations",
+      "message_types": ["build_ready", "build_revision", "build_progress", "error"]
+    },
+    "a11y-tester": {
+      "task_prefix": "A11Y",
+      "responsibility": "Keyboard navigation, screen reader, reduced motion, focus management, contrast testing",
+      "message_types": ["a11y_passed", "a11y_result", "fix_required", "error"]
+    }
+  },
+
+  "pipelines": {
+    "single": {
+      "description": "Single component: research -> interaction design -> build -> a11y test",
+      "task_chain": ["RESEARCH-001", "INTERACT-001", "BUILD-001", "A11Y-001"],
+      "complexity": "low"
+    },
+    "gallery": {
+      "description": "Gallery with base component + scroll container: two build phases",
+      "task_chain": [
+        "RESEARCH-001",
+        "INTERACT-001", "BUILD-001",
+        "INTERACT-002", "BUILD-002",
+        "A11Y-001"
+      ],
+      "complexity": "medium"
+    },
+    "page": {
+      "description": "Full interactive page with parallel component builds",
+      "task_chain": [
+        "RESEARCH-001",
+        "INTERACT-001",
+        "BUILD-001..N (parallel)",
+        "A11Y-001"
+      ],
+      "parallel_stage": "BUILD-001..N",
+      "complexity": "high"
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "builder",
+      "critic": "a11y-tester",
+      "max_rounds": 2,
+      "convergence": "a11y.critical_count === 0 && a11y.high_count === 0",
+      "escalation": "Coordinator intervenes after max rounds"
+    },
+    "shared_memory": {
+      "file": "shared-memory.json",
+      "fields": {
+        "researcher": ["interaction_inventory", "browser_apis"],
+        "interaction-designer": ["state_machines", "event_flows"],
+        "builder": ["component_registry", "implementation_decisions"],
+        "a11y-tester": ["audit_history"]
+      }
+    },
+    "dynamic_pipeline": {
+      "criteria": {
+        "single": "scope.component_count <= 1",
+        "gallery": "scope.has_gallery || scope.has_scroll_collection",
+        "page": "scope.is_full_page || scope.section_count > 2"
+      }
+    },
+    "parallel_fanout": {
+      "pattern": "CP-3",
+      "description": "Multiple BUILD tasks spawned in parallel after single INTERACT blueprint",
+      "trigger": "page mode after INTERACT-001 completes",
+      "fallback": "If parallel fails, coordinator falls back to sequential execution"
+    }
+  },
+
+  "session_dirs": {
+    "base": ".workflow/.team/IC-{slug}-{YYYY-MM-DD}/",
+    "research": "research/",
+    "interaction": "interaction/blueprints/",
+    "build": "build/components/",
+    "a11y": "a11y/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}

package/.agy/skills/team-interactive-craft/specs/vanilla-constraints.md

@@ -0,0 +1,83 @@
+# Vanilla Constraints
+
+Zero-dependency rules for all interactive components built by this team. These constraints are non-negotiable and apply to every BUILD task output.
+
+## Dependency Rules
+
+| Rule | Requirement |
+|------|-------------|
+| No npm packages | Zero `import` from node_modules or CDN URLs |
+| No build tools required | Components run directly via `<script type="module">` |
+| No framework dependency | No React, Vue, Svelte, Angular, jQuery, etc. |
+| No CSS preprocessor | No Sass, Less, PostCSS, Tailwind -- pure CSS only |
+| No bundler required | No webpack, Vite, Rollup, esbuild in critical path |
+
+## JavaScript Rules
+
+| Rule | Requirement |
+|------|-------------|
+| ES modules only | `export class`, `export function`, `import` syntax |
+| Class-based components | Private fields (#), constructor(element, options) |
+| No inline styles from JS | Set CSS custom properties or toggle CSS classes |
+| No document.write | Use DOM APIs (createElement, append, etc.) |
+| No eval or innerHTML | Use textContent or DOM construction |
+| requestAnimationFrame | All animation loops use rAF, not setInterval |
+| Pointer Events primary | Use pointer events; touch events as fallback only |
+| Cleanup required | destroy() method disconnects all observers/listeners |
+| Auto-init pattern | `document.querySelectorAll('[data-component]')` on load |
+
+## CSS Rules
+
+| Rule | Requirement |
+|------|-------------|
+| Custom properties | All configurable values as CSS custom properties |
+| No inline styles | JS sets `--custom-prop` values, not style.left/top |
+| State via data attributes | `[data-state="active"]`, not inline style changes |
+| GPU-only animations | `transform` and `opacity` ONLY in transitions/animations |
+| No layout animations | Never animate `width`, `height`, `top`, `left`, `margin`, `padding` |
+| will-change on animated | Hint browser for animated elements |
+| Reduced motion | `@media (prefers-reduced-motion: reduce)` with instant fallback |
+| focus-visible | `:focus-visible` for keyboard-only focus indicators |
+| Responsive | Min touch target 44x44px on mobile, use @media breakpoints |
+
+## Progressive Enhancement
+
+| Rule | Requirement |
+|------|-------------|
+| Content without JS | Base content visible and readable without JavaScript |
+| CSS-only fallback | Essential layout works with CSS alone |
+| No-JS class | Optional `[data-js-enabled]` class for JS-enhanced styles |
+| Semantic HTML base | Use appropriate elements (button, a, nav, dialog) |
+
+## Performance Budget
+
+| Metric | Budget |
+|--------|--------|
+| Frame time | < 5ms per frame (leaves room for browser work in 16ms budget) |
+| Interaction response | < 50ms from input to visual feedback |
+| Animation jank | 0 frames dropped at 60fps for GPU-composited animations |
+| Observer callbacks | < 1ms per IntersectionObserver/ResizeObserver callback |
+| Component init | < 100ms from constructor to interactive |
+| Memory | No detached DOM nodes after destroy() |
+| Listeners | All removed in destroy(), no orphaned listeners |
+
+## Forbidden Patterns
+
+| Pattern | Why |
+|---------|-----|
+| `element.style.left = ...` | Forces layout recalc, not GPU composited |
+| `element.offsetWidth` in animation loop | Forces synchronous layout (reflow) |
+| `setInterval` for animation | Not synced to display refresh rate |
+| `setTimeout` for animation | Not synced to display refresh rate |
+| `innerHTML = userContent` | XSS vector |
+| Passive: false on scroll/touch without need | Blocks scrolling performance |
+| `!important` in component CSS | Breaks cascade, unmaintainable |
+| Global CSS selectors (tag-only) | Leaks styles outside component scope |
+
+## File Output Convention
+
+| File | Purpose | Location |
+|------|---------|----------|
+| `{name}.js` | ES module component class | `<session>/build/components/` |
+| `{name}.css` | Component styles with custom properties | `<session>/build/components/` |
+| `demo.html` | Optional: standalone demo page | `<session>/build/components/` |