# Apex Motion Engine -- Finished-Product Inspector

System 6 of the Apex Motion Engine. Click any element on any deployed Apex cinematic and a side panel opens with all animation variants the library offers for that element type. Pick a different one, fire it to the factory, swap it on production.

---

## Files

| File | Purpose |
|---|---|
| `inspector.js` | Drop-in script. Include in any Apex-deployed page or inject via bookmarklet. |
| `inspector.css` | Overlay panel styling. All rules scoped under `#apex-inspector` -- zero host-page leakage. |
| `inspector-bookmarklet.txt` | One-click browser bookmark that injects the Inspector into any production page that does not have it pre-loaded. |
| `README.md` | This file. |

---

## Quick Start

### Option A: Pre-loaded (pages built with the Motion Engine)

Add one script tag before `</body>`:

```html
<script src="/inspector/inspector.js"></script>
```

The eye icon appears bottom-left. Click it.

### Option B: Bookmarklet (any production page)

1. Open `inspector-bookmarklet.txt`.
2. Copy the `javascript:` line.
3. Create a browser bookmark and paste the line as the URL.
4. Save to your bookmarks bar as "Apex Inspector".
5. Navigate to any deployed Apex cinematic and click the bookmark.

---

## How Inspect Mode Works

```
Eye icon (bottom-left)
  |
  v
Click eye -> INSPECT MODE ON
  - Purple dotted badge appears top-center: "Inspect Mode | ESC to exit"
  - Every element with [data-cinema-element="<type>"] gets a purple hover outline
  |
  v
Hover over element -> outline + brand glow
  |
  v
Click element -> SIDE PANEL SLIDES IN (480px, right edge)
  - Shows element type, current variant, CSS selector
  - Loads 6 animation variants for that element type
  - Each variant card shows: name, ID, description, GSAP technique, tags
  |
  v
Click a variant card -> card highlights, Deploy button activates
  |
  v
Click "Deploy <Variant Name>"
  - V1: Simulates 1.8s deploy, updates element attribute, shows toast
  - V2: POSTs to /api/inspector/swap with {page_url, element_selector, new_variant_id}
       Worker generates swap patch, deploys, returns new URL in toast
  |
  v
Toast: "Variant Deployed -- <name> applied to <type>. New URL below."
  Auto-dismisses after 6 seconds.
  |
  v
ESC or X button -> exits Inspect Mode, closes panel, removes all outlines
```

---

## Element Tagging (required on host pages)

For the Inspector to recognize an element, it must have a `data-cinema-element` attribute:

```html
<h1 data-cinema-element="headline" data-cinema-variant="headline-word-cascade">
  Your headline here
</h1>

<div data-cinema-element="card" data-cinema-variant="card-stack-deal">
  Card content
</div>

<img data-cinema-element="image" data-cinema-variant="image-ken-burns" src="..." />

<section data-cinema-element="section" data-cinema-variant="section-pin-scrub">
  Section content
</section>
```

Supported element types in V1 (6 variants each):

| Type | Variants |
|---|---|
| `headline` | typewriter, word-cascade, scramble, slide-in, mega-scale, split-line |
| `counter` | scrub-tick, decay-from-large, count-up-overshoot, rolling-digits, flash-lock, milestone-pulse |
| `button` | pulse-glow, magnetize, ring-pulse, gradient-shift, fill-reveal, shake-confirm |
| `card` | stack-deal, flip-3d, slide-edge, scale-zero, float-idle, spotlight-hover |
| `image` | ken-burns, parallax, mask-reveal, fade-in, scale-reveal, slice-entrance |
| `section` | pin-scrub, parallax-stack, fade-stack, sticky-reveal, horizontal-scroll, vault-open |
| `orb` | founding-boot, float-pulse, orbit-ring, flash-entrance, wormhole-exit, particle-burst |
| any other | 6 generic fallback variants |

The Inspector also walks up to 8 DOM levels to find the nearest inspectable ancestor, so clicking inside a card's child elements still triggers the card inspector.

---

## API Contract (V1 stub, V2 real)

### V1 (current): Stubbed

The variant list is resolved from an in-memory library object in `inspector.js`. The deploy action is simulated (1.8s delay, then toast). No network calls.

### V2 (production): Real backend

The Inspector is designed for drop-in upgrade. Two endpoints:

**GET /api/library/animations?type={type}**

Returns variant list for a given element type.

```json
[
  {
    "id": "headline-typewriter",
    "name": "Typewriter",
    "description": "Characters materialize one at a time...",
    "tags": ["entrance", "character-by-character"],
    "gsap": "SplitText + stagger 0.04"
  }
]
```

**POST /api/inspector/swap**

Fires the swap job to the Cloudflare Worker / Sonnet agent.

```json
{
  "page_url":           "https://apexopsystems.com/closer/lp-001",
  "element_selector":   "#hero-headline",
  "element_type":       "headline",
  "current_variant_id": "headline-word-cascade",
  "new_variant_id":     "headline-typewriter"
}
```

Response:

```json
{
  "status": "deployed",
  "new_url": "https://apexopsystems.com/closer/lp-001?apex-variant=headline-typewriter&apex-ts=1748000000000",
  "job_id": "swap_abc123"
}
```

To upgrade to V2, replace the `_pendingFetchTimer` stub in `_selectElement()` and the `_deployTimer` stub in `_deploy()` with real `fetch()` calls to these endpoints.

---

## Isolation Guarantees

The Inspector is designed to be a safe drop-in that cannot break the host page:

- All DOM injected inside `#apex-inspector` wrapper.
- All CSS rules prefixed with `#apex-inspector` (zero bleed to host page).
- All injected `<style>` uses `id="apex-inspector-css"` for deduplication.
- All event listeners stored in `_listeners[]` and removed on `destroy()`.
- `destroy()` removes all DOM, all CSS, all timers, and all event listeners.
- No global variable pollution beyond `window.ApexInspector`.
- Guard clause prevents double-injection if script loaded twice.
- Calling `window.ApexInspector.destroy()` leaves the host page exactly as it was.

---

## Public API

```javascript
window.ApexInspector.mount()     // Mount the inspector (called automatically on script load)
window.ApexInspector.destroy()   // Remove inspector completely and clean up all side effects
window.ApexInspector.enter()     // Enter Inspect Mode programmatically
window.ApexInspector.exit()      // Exit Inspect Mode programmatically
window.ApexInspector.version     // "1.0.0"
window.ApexInspector._mounted    // Boolean -- true if inspector is currently mounted
```

---

## Constitutional Compliance

This module was built under the Apex Motion Engine constitutional rules in `DO-NOT-CHANGE-EVER.md`:

- Palette: cool-spectrum only. No red, green, amber, orange, yellow, magenta, pink.
- Fonts: Inter Tight (UI), JetBrains Mono (IDs and selectors).
- No animated `filter:blur` or `backdrop-filter` animations.
- `transition` specifies only exact properties (no `transition:all`).
- `will-change:transform` on all animated elements (via CSS).
- No `setInterval` calls without a `clearInterval` reference.
- All event listeners have documented cleanup in `destroy()`.
- No magic numbers without comments explaining the value.
- Zero `console.log`, `console.warn`, or `console.error` in shipped code.
- No em-dashes (U+2014), en-dashes (U+2013), smart quotes, or emoji in any copy.

---

## Cross-References

- Vision spec: `../APEX-MOTION-ENGINE-VISION.md` (System 6)
- Brand constitution: `../DO-NOT-CHANGE-EVER.md`
- Animation library variants: `../components/element-animation-pairings/`
- Factory worker scripts: `../factory/`
- Voice pipeline: `../voice/`
- Deployed cinematics: `../deploys/`