tribunal-kit 8.0.0 → 9.0.1

package/.agents/skills/micro-interaction/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: micro-interaction
+description: Use when designing and engineering interactive component micro-motion, tactile button feedback, spring toggles, draw-on checkboxes, toasts, drawer gestures, and shared-element transitions.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - delight
+  - better-ui
+  - 60fps-animation
+  - review-animations
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Micro-Interaction — Tactile Component Physics & Interactive State Synthesis
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `micro-interaction` domain, inspect these 5 critical parameters:
+
+1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
+2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
+3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
+4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
+5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
+
+## Activation Boundaries
+
+- **Activate when:** Use when designing and engineering interactive component micro-motion, tactile button feedback, spring toggles, draw-on checkboxes, toasts, drawer gestures, and shared-element transitions.
+- **DO NOT activate when:** The task falls outside the `micro-interaction` domain or is managed by a different dedicated specialist.
+
+## 🔁 Multi-Pass Execution Protocol
+
+Execute all non-trivial tasks through this 7-pass cognitive loop:
+
+| Pass | Phase | Core Action |
+|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
+| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
+| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
+| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
+| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+Micro-interactions bridge intention and confirmation. When a button compresses beneath a pointer or a toggle thumb squashes as it slides across the track, digital interfaces cross the chasm from static abstractions to physical, responsive objects. Poor micro-interactions feel floaty, sluggish (>250ms), or introduce layout displacement. Master-grade micro-interactions operate under a strict sub-180ms execution budget, maintain volume mass conservation, anchor transform origins directly to interaction loci, and fire subtle tactile feedback.
+
+---
+
+
+---
+
+
+---
+
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+### 1. The Micro-Interaction Timing & Easing Matrix
+
+| Component | Target Duration | Recommended Curve / Physics | Perceived Feel |
+|:---|:---|:---|:---|
+| **Button Press (`:active`)** | 80ms–120ms | `cubic-bezier(0.2, 0, 0, 1)` | Crisp, immediate tactile resistance |
+| **Toggle Switch** | 160ms–200ms | `spring(stiffness: 420, damping: 26)` | Snappy with slight organic overshoot |
+| **Checkbox Tick** | 140ms–180ms | `stroke-dashoffset` linear deceleration | Decisive, pencil-drawn precision |
+| **Toast Pop-In** | 180ms–240ms | `cubic-bezier(0.16, 1, 0.3, 1)` | Smooth magnetic arrival |
+| **Popover / Dropdown** | 140ms–180ms | `scale(0.96) -> 1` + origin anchoring | Anchored physical unfold |
+
+---
+
+### 2. Five Production-Grade Implementation Recipes
+
+#### Recipe 1: Tactile Elastic Button Press (React + Framer Motion)
+
+```tsx
+import React from 'react';
+import { motion } from 'framer-motion';
+
+export function TactileButton({
+  children,
+  onClick,
+  className = '',
+}: {
+  children: React.ReactNode;
+  onClick?: () => void;
+  className?: string;
+}) {
+  const handleClick = () => {
+    if (typeof window !== 'undefined' && 'vibrate' in navigator) {
+      navigator.vibrate(8); // Subtle 8ms tactile micro-pulse
+    }
+    onClick?.();
+  };
+
+  return (
+    <motion.button
+      type="button"
+      onClick={handleClick}
+      whileHover={{ scale: 1.02, y: -1 }}
+      whileTap={{ scale: 0.96, y: 1 }}
+      transition={{ type: 'spring', stiffness: 500, damping: 30 }}
+      className={`inline-flex items-center justify-center px-4 py-2 font-medium text-sm rounded-xl bg-neutral-900 dark:bg-white text-white dark:text-neutral-900 shadow-sm hover:shadow active:shadow-inner touch-manipulation focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500 ${className}`}
+    >
+      {children}
+    </motion.button>
+  );
+}
+```
+
+---
+
+#### Recipe 2: Organic Squash-and-Stretch Toggle Switch
+
+```tsx
+import React from 'react';
+import { motion } from 'framer-motion';
+
+export function ElasticToggle({
+  checked,
+  onChange,
+  label,
+}: {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  label: string;
+}) {
+  return (
+    <label className="inline-flex items-center gap-3 cursor-pointer select-none">
+      <span className="text-sm font-medium text-neutral-700 dark:text-neutral-300">{label}</span>
+      <button
+        type="button"
+        role="switch"
+        aria-checked={checked}
+        onClick={() => onChange(!checked)}
+        className={`relative w-12 h-7 rounded-full p-0.5 transition-colors duration-200 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500 ${
+          checked ? 'bg-indigo-600' : 'bg-neutral-300 dark:bg-neutral-700'
+        }`}
+      >
+        <motion.div
+          animate={{
+            x: checked ? 20 : 0,
+            scaleX: [1, 1.25, 0.95, 1], // Squash as it pushes off, stretches in transit, snaps into place
+            scaleY: [1, 0.85, 1.05, 1],
+          }}
+          transition={{
+            x: { type: 'spring', stiffness: 480, damping: 28 },
+            scaleX: { duration: 0.22 },
+            scaleY: { duration: 0.22 },
+          }}
+          className="w-6 h-6 rounded-full bg-white shadow-md"
+        />
+      </button>
+    </label>
+  );
+}
+```
+
+---
+
+#### Recipe 3: Animated SVG Draw-On Checkbox
+
+```tsx
+import React from 'react';
+import { motion } from 'framer-motion';
+
+export function DrawOnCheckbox({
+  checked,
+  onChange,
+  label,
+}: {
+  checked: boolean;
+  onChange: (c: boolean) => void;
+  label: string;
+}) {
+  return (
+    <label className="inline-flex items-center gap-3 cursor-pointer select-none">
+      <button
+        type="button"
+        role="checkbox"
+        aria-checked={checked}
+        onClick={() => onChange(!checked)}
+        className={`w-5 h-5 rounded-md border flex items-center justify-center transition-colors duration-150 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500 ${
+          checked
+            ? 'bg-indigo-600 border-indigo-600 text-white'
+            : 'border-neutral-400 dark:border-neutral-600 bg-white dark:bg-neutral-900'
+        }`}
+      >
+        <svg viewBox="0 0 16 16" className="w-3.5 h-3.5 stroke-current fill-none stroke-[2.4] stroke-linecap-round stroke-linejoin-round">
+          <motion.path
+            d="M 3.5 8.5 L 6.5 11.5 L 12.5 4.5"
+            initial={false}
+            animate={{ pathLength: checked ? 1 : 0, opacity: checked ? 1 : 0 }}
+            transition={{ duration: 0.16, ease: [0.16, 1, 0.3, 1] }}
+          />
+        </svg>
+      </button>
+      <span className="text-sm text-neutral-800 dark:text-neutral-200">{label}</span>
+    </label>
+  );
+}
+```
+
+---
+
+#### Recipe 4: Dynamic Directional Toast with Spring Layout
+
+```tsx
+import React from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+
+interface ToastProps {
+  id: string;
+  message: string;
+  onDismiss: (id: string) => void;
+}
+
+export function ToastContainer({ toasts, onDismiss }: { toasts: ToastProps[]; onDismiss: (id: string) => void }) {
+  return (
+    <div className="fixed bottom-6 right-6 z-50 flex flex-col gap-2 pointer-events-none">
+      <AnimatePresence mode="popLayout">
+        {toasts.map(toast => (
+          <motion.div
+            key={toast.id}
+            layout
+            initial={{ opacity: 0, y: 24, scale: 0.94 }}
+            animate={{ opacity: 1, y: 0, scale: 1 }}
+            exit={{ opacity: 0, scale: 0.92, transition: { duration: 0.14 } }}
+            transition={{ type: 'spring', stiffness: 420, damping: 28 }}
+            className="pointer-events-auto flex items-center justify-between min-w-[280px] p-4 rounded-xl bg-neutral-900 text-white shadow-xl border border-neutral-800"
+          >
+            <span className="text-sm font-medium">{toast.message}</span>
+            <button
+              type="button"
+              onClick={() => onDismiss(toast.id)}
+              className="ml-3 text-xs text-neutral-400 hover:text-white transition-colors"
+            >
+              Dismiss
+            </button>
+          </motion.div>
+        ))}
+      </AnimatePresence>
+    </div>
+  );
+}
+```
+
+---
+
+#### Recipe 5: Context-Aware Popover with Dynamic `transform-origin`
+
+```css
+/* Popover Unfold from Anchor Coordinate */
+.popover-bubble {
+  transform-origin: var(--radix-popover-content-transform-origin, top center);
+  animation: popover-unfold 160ms cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+
+@keyframes popover-unfold {
+  from {
+    opacity: 0;
+    transform: scale(0.94) translateY(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+```
+
+---
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Mitigation Strategy |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
+
+---
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **The Instant Pop Trap** | Conditionally unmounting elements without animated interpolation | Use AnimatePresence or coordinate morphs with continuous geometry |
+| **Layout Thrashing** | Animating width, height, top, or left inside animation loops | Animate composite-only transform (translate3d, scale) and opacity |
+| **Sluggish Duration** | Setting micro-interaction transitions to 600ms+ causing interface lag | Cap interactive feedback at 160ms–240ms with snappy ease-out curves |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `frontend-reviewer` · `motion-reviewer` · `ui-ux-auditor`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ Pre-Flight Self-Audit Checklist
+
+```
+✅ Does animation maintain 60fps/120fps using transform and opacity?
+✅ Is optical mass conserved across state interpolations without volume collapse?
+✅ Is duration capped within micro-interaction budgets (160ms–280ms)?
+✅ Is prefers-reduced-motion respected with graceful instant fallbacks?
+✅ Did I prevent layout thrashing and continuous geometry mutations?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/.agents/skills/mobile-design/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: mobile-design
+description: Use when Mobile-first design for iOS, Android, Foldables, React Native, Flutter. Touch interaction, haptics, 120Hz performance, on-device AI, spatial UI, Reanimated 3. Use when building mobile UI, animations, or cross-platform apps.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - building-native-ui
+  - adapt
+  - 60fps-animation
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Mobile Design — Dense Reference
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `mobile-design` domain, inspect these 5 critical parameters:
+
+1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
+2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
+3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
+4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
+5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
+
+## Activation Boundaries
+
+- **Activate when:** Use when Mobile-first design for iOS, Android, Foldables, React Native, Flutter. Touch interaction, haptics, 120Hz performance, on-device AI, spatial UI, Reanimated 3. Use when building mobile UI, animations, or cross-platform apps.
+- **DO NOT activate when:** The task falls outside the `mobile-design` domain or is managed by a different dedicated specialist.
+
+## 🔁 Multi-Pass Execution Protocol
+
+Execute all non-trivial tasks through this 7-pass cognitive loop:
+
+| Pass | Phase | Core Action |
+|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
+| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
+| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
+| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
+| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+
+## Hallucination Traps (Read First)
+
+- ❌ `Animated.View` for any animation → ✅ `Reanimated 3` worklets (Animated API is legacy, runs on JS thread)
+- ❌ `ScrollView` for lists → ✅ `FlashList` (Shopify) — ScrollView renders ALL items at once
+- ❌ `estimatedItemSize` optional in FlashList → ✅ **REQUIRED** or you get 0-height items
+- ❌ White backgrounds (`#FFFFFF`) → ✅ OLED: `#000000` true black; off-white: `#FAFAFA`
+- ❌ Linear animations (`easing: linear`) → ✅ Spring physics (`stiffness`, `damping`)
+- ❌ Touch targets < 48px → ✅ Min 48px hitbox (visual size can be smaller via padding)
+- ❌ `useAnimatedStyle` in worklet without `'worklet'` directive → crashes on native thread
+- ❌ iOS: `useSafeAreaInsets()` optional → ✅ Required — screen content goes under dynamic island/home indicator
+- ❌ Android: hardcoded status bar height (24dp) → ✅ `StatusBar.currentHeight` (varies per device)
+- ❌ Platform-specific code with `if (platform === 'ios')` scattered everywhere → ✅ centralize in platform/ files
+- ❌ `console.log` in production → ✅ blocks JS thread — remove before release
+
+---
+
+## React Native Performance
+
+### FlashList (Required for Lists)
+
+```tsx
+import { FlashList } from '@shopify/flash-list';
+<FlashList
+  data={items}
+  renderItem={({ item }) => <ItemCard item={item} />}
+  estimatedItemSize={100} // REQUIRED — measure actual item height first
+  keyExtractor={item => item.id}
+  getItemType={item => item.type} // multi-type optimization
+/>;
+// ❌ NEVER: <ScrollView>{items.map(...)}</ScrollView> for lists
+// ❌ NEVER: <FlatList> for perf-critical lists — FlashList is 5-10x faster
+```
+
+### Reanimated 3 — Worklet Animations (Required for 120Hz)
+
+```tsx
+import {
+  useSharedValue,
+  useAnimatedStyle,
+  withSpring,
+  withTiming,
+  runOnJS,
+} from 'react-native-reanimated';
+
+// Shared values run on the UI thread — never on JS thread
+const scale = useSharedValue(1);
+const opacity = useSharedValue(0);
+
+// Animated style — computed on UI thread (no bridge crossing)
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.value }],
+  opacity: opacity.value,
+}));
+
+// Triggers
+const onPress = () => {
+  scale.value = withSpring(0.95, { stiffness: 400, damping: 15 });
+  opacity.value = withTiming(1, { duration: 200 });
+};
+
+// Call JS function from worklet
+const onComplete = () => runOnJS(setVisible)(true);
+scale.value = withSpring(1, {}, onComplete);
+
+// ❌ TRAP: Accessing shared value with .value inside useAnimatedStyle is fine — but inside a gesture handler callback, you need runOnJS to call React setState
+```
+
+### 120Hz Animation Rules
+
+- ✅ Animate ONLY: `transform` (translateX/Y, scale, rotate), `opacity` — all GPU composited
+- ❌ Never animate: `width`, `height`, `margin`, `padding`, `top/left/bottom/right` — causes layout recalc at 60 times per second → janky, battery draining
+- ✅ Use `withSpring` for all UI interactions (feel alive) — `withTiming` only for intentional timed animations
+- ✅ `Gesture.Pan()` / `Gesture.Tap()` from `react-native-gesture-handler` v2 (not `PanResponder`)
+
+---
+
+## Haptics
+
+```tsx
+import * as Haptics from 'expo-haptics';
+// light → switch toggle, tap feedback
+// medium → selection change, confirm
+// heavy → destructive action, strong confirm
+// notificationAsync('success' | 'warning' | 'error') → operation outcomes
+Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light); // tap, toggle
+Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success); // save complete
+// ❌ Never overuse — haptics must mean something
+// ❌ Haptics not supported on Android emulators — test on device
+```
+
+---
+
+## Safe Areas & Platform Layout
+
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { Platform, StatusBar } from 'react-native';
+
+function Screen() {
+  const insets = useSafeAreaInsets();
+  return (
+    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
+      {/* Content safe from Dynamic Island, home indicator, status bar */}
+    </View>
+  );
+}
+// Android status bar
+const STATUS_BAR_HEIGHT = Platform.OS === 'android' ? (StatusBar.currentHeight ?? 24) : 0;
+
+// Foldable/tablet — dual pane
+import { useWindowDimensions } from 'react-native';
+function AdaptiveLayout() {
+  const { width } = useWindowDimensions();
+  const isTablet = width >= 600;
+  return isTablet ? <TwoPaneView /> : <SinglePaneView />;
+}
+```
+
+---
+
+## Touch Psychology & Thumb Zones
+
+- **Thumb zone**: Bottom 40% of screen = primary actions, FABs, CTAs
+- **Dead zone**: Top 25% = destructive/rare actions only
+- **48px minimum hitbox**: Visual icon can be 24px, padding expands hitbox to 48px
+  ```tsx
+  // Magnetic padding — visually small, touch-friendly
+  <TouchableOpacity style={{ padding: 12, margin: -4 }}>
+    <Icon size={24} />
+  </TouchableOpacity>
+  ```
+- **Coyote time**: Allow 100–150ms buffer after button intent registers before processing — prevents mis-taps
+
+---
+
+## Navigation (Expo Router / React Navigation)
+
+```tsx
+// Expo Router v3+ (file-based, recommended)
+// app/(tabs)/_layout.tsx — tab navigator
+// app/[id].tsx — dynamic segment
+// app/(modal)/settings.tsx — modal group
+
+// Stack navigation with gesture
+import { Stack } from 'expo-router';
+<Stack screenOptions={{ headerShown: false, animation: 'slide_from_right' }}>
+  <Stack.Screen name="(tabs)" />
+  <Stack.Screen name="[id]" options={{ presentation: 'modal' }} />
+</Stack>;
+
+// Deep linking (Expo Router handles automatically via app.json scheme)
+// ❌ TRAP: Don't use react-navigation Link for deep links in Expo Router — use expo-router Link
+import { Link, useRouter } from 'expo-router';
+const router = useRouter();
+router.push('/user/42');
+```
+
+---
+
+## On-Device AI UX Patterns
+
+- **Zero-wait illusion**: When model runs → immediately show contextual skeleton/partial tokens
+- **Progressive disclosure**: Low confidence → softer UI, soft colors, require confirmation
+- **Streaming UI**: `useEffect` + SSE or `StreamingText` component appending tokens
+- **Local models** (MediaPipe, Core ML, ONNX): always wrap in try/catch — device capability varies
+
+---
+
+## Color & Typography
+
+```tsx
+// OLED-safe dark mode
+const colors = {
+  background: '#000000',    // true black — OLED pixel off
+  surface: '#0A0A0A',       // cards
+  surfaceAlt: '#121212',    // elevated surfaces
+  border: '#1F1F1F',
+  text: '#FFFFFF',
+  textMuted: '#8E8E93',     // iOS system gray
+};
+// Dynamic type (iOS) — always use system font with scalesWithContentSizeCategory
+import { Text } from 'react-native';
+<Text style={{ fontSize: 16, fontFamily: Platform.OS === 'ios' ? 'System' : 'Roboto' }}>
+```
+
+---
+
+## Performance Checklist
+
+| Issue             | Fix                                                 |
+| ----------------- | --------------------------------------------------- |
+| JS thread jank    | Move ALL animations to Reanimated worklets          |
+| Slow list         | Replace ScrollView/FlatList with FlashList          |
+| Image flicker     | `Image` from `expo-image` (faster cache, blurhash)  |
+| Re-render cascade | `React.memo` + stable callbacks + Zustand selectors |
+| Large bundle      | Dynamic imports + Metro tree shaking                |
+| Memory leak       | `useEffect` cleanup + cancel animation on unmount   |
+
+```tsx
+// Cancel animation on unmount
+useEffect(() => {
+  opacity.value = withTiming(1);
+  return () => cancelAnimation(opacity); // ← critical
+}, []);
+```
+
+---
+
+## iOS-Specific
+
+- **BlurView**: Use `@react-native-community/blur` for frosted glass nav bars/modals
+- **SF Symbols**: Use `@expo/vector-icons/Ionicons` for system-native icons
+- **Haptics**: `expo-haptics` — rich feedback on iOS, limited on Android
+- **Dynamic Island**: Check `insets.top > 50` for Dynamic Island devices
+- **Sheet presentations**: `presentation: 'formSheet'` in Expo Router for iOS bottom sheet native feel
+
+## Android-Specific
+
+- **Material You**: Use `react-native-paper` for M3 dynamic color theming
+- **Edge-to-edge**: Set `android:windowLayoutInDisplayCutoutMode="shortEdges"` in AndroidManifest
+- **Back gesture prediction**: Wrap routes in `GestureHandlerRootView` at root
+- **Splash**: Use `expo-splash-screen` — never hardcode a delay
+
+---
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Mitigation Strategy |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
+
+---
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **JS Thread Animation Lag** | Driving gestures and scrolling physics on the React Native JS thread | Use React Native Reanimated worklets running directly on the UI thread |
+| **Missing Keyboard Offset** | Forms hidden behind native software keyboard on iOS/Android | Wrap form views in KeyboardAvoidingView with platform-calibrated behavior |
+| **Uncached Image Flooding** | Rendering raw image URLs in list items without memory caching | Use FastImage or Expo Image with disk cache policies and thumbnail previews |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `mobile-reviewer` · `frontend-reviewer` · `type-safety`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ Pre-Flight Self-Audit Checklist
+
+```
+✅ Do touch targets satisfy the 44x44px minimum touch boundary standard?
+✅ Are gesture handlers and native thread animations offloaded via Reanimated?
+✅ Are keyboard avoiding views, safe areas, and notch offsets handled?
+✅ Is offline storage and state hydration handled with optimistic sync?
+✅ Did I verify compatibility across iOS, Android, and varying densities?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.