# JavaScript Events

## PostMessage Protocol

AjaxPress uses `window.postMessage()` for communication between parent and child iframes. All messages are JSON objects with a `type` field.

### Child -> Parent Messages

#### `AJAXPRESS_NAVIGATE`

Sent when the user clicks a link in the child iframe.

```json
{
  "type": "AJAXPRESS_NAVIGATE",
  "url": "https://example.com/about/"
}
```

**Triggers:** Link click (after bypass check passes)

#### `AJAXPRESS_PREFETCH_REQUEST`

Sent when the user hovers over or mousedowns on a link.

```json
{
  "type": "AJAXPRESS_PREFETCH_REQUEST",
  "url": "https://example.com/contact/"
}
```

**Triggers:** Mouse hover (if `enable_prefetch`) or mousedown (if `prefetch_on_mousedown`)

#### `AJAXPRESS_FORM_SUBMIT`

Sent when a form is submitted in the child iframe.

```json
{
  "type": "AJAXPRESS_FORM_SUBMIT",
  "action": "https://example.com/search/",
  "method": "GET",
  "data": { "s": "query" }
}
```

#### `AJAXPRESS_NAV`

Sent by a loaded iframe to report its URL and title to the parent.

```json
{
  "type": "AJAXPRESS_NAV",
  "url": "https://example.com/about/",
  "title": "About Us - Example Site"
}
```

**Triggers:** Iframe finishes loading a page

#### `AJAXPRESS_PERSIST_ELEMENT`

Requests that an element be persisted across navigations.

```json
{
  "type": "AJAXPRESS_PERSIST_ELEMENT",
  "html": "<audio src='...'></audio>",
  "rect": { "top": 100, "left": 50, "width": 300, "height": 60 }
}
```

#### `AJAXPRESS_CHECK_PERSISTED`

Checks if an element is already in the persist container.

```json
{
  "type": "AJAXPRESS_CHECK_PERSISTED",
  "selector": "[data-ajaxpress-persist]"
}
```

#### `AJAXPRESS_UPDATE_PERSIST_RECT`

Updates the position of a persisted element.

```json
{
  "type": "AJAXPRESS_UPDATE_PERSIST_RECT",
  "selector": "[data-ajaxpress-persist]",
  "rect": { "top": 120, "left": 50, "width": 300, "height": 60 }
}
```

## AJAX Request Header

When the frontend loads a page via AJAX navigation, it sends a custom HTTP header:

```
Ajaxpress-Ajax: true
```

Server-side detection in PHP:

```php
AjaxPress\Templates::is_ajax_request()
```

This can be used by themes or plugins to modify output for AJAX-loaded pages.

## Window Globals

### `window.ajaxpress_vars` (Frontend)

Available on the public site after script enqueue:

```javascript
{
  rest: { url: '/wp-json/ajaxpress/', nonce: '...' },
  site: { name: 'Site Name', language: 'en-US', email: '...' },
  plugin: { url: '/wp-content/plugins/ajaxpress/', version: '2.3.0' },
  settings: { /* all plugin settings */ },
  navigation: true,
  user_logged_in: false,
  license: { key: '...', status: 'active' },
  debug: false
}
```

### `window.ajaxpress_admin_vars` (Admin)

Available on AjaxPress admin pages:

```javascript
{
  rest: { url: '/wp-json/ajaxpress/', nonce: '...' },
  site: { name: '...', url: '...', admin_url: '...', language: '...' },
  plugin: { url: '...', path: '...', version: '2.3.0' },
  server: { php: '8.2', mysql: '8.0', platform: 'nginx' },
  settings: { /* current settings */ },
  default_settings: { /* default values */ },
  license: { /* license object */ },
  cf_status: { /* cloudflare status */ },
  diagnostic: 'allowed',
  tour: { completed: false, mode: null }
}
```

### `window.licenseStatus` (Frontend)

Set by the license validation feature:

```javascript
{
  isValid: true,
  isChecking: false
}
```

### Event Listener Tracking

```javascript
window.ajaxpress_tracked_listeners    // { document: [], window: [] }
window.ajaxpress_tracked_timers       // { timeouts: Set, intervals: Set, observers: [] }
window.ajaxpress_core_scripts         // Scripts that should never re-execute
window.ajaxpress_executed_scripts     // All executed script URLs
```

## CSS Classes

### Persistent Elements

Add these to elements that should survive SPA navigation:

| Selector | Usage |
|----------|-------|
| `[data-ajaxpress-persist]` | Data attribute (recommended) |
| `.ajaxpress-persist` | CSS class |
| `audio[data-persist]` | Audio elements |
| `video[data-persist]` | Video elements |

### Animation Classes

Applied during page transitions:

| Class | Effect |
|-------|--------|
| `.ajaxpress-animate-fade` | Fade in |
| `.ajaxpress-animate-slide-up` | Slide up with fade |
| `.ajaxpress-animate-slide-down` | Slide down with fade |

### Loader Elements

| Selector | Description |
|----------|-------------|
| `.ajaxpress-progressbar` | Progress bar container |
| `.progressbar-wave` | Wave animation modifier |
| `.ajaxpress-spinner` | Spinner container |