# Browser Contract — The Nexus

The minimal set of guarantees a working Nexus browser surface must satisfy.
This is the target the smoke suite validates against.

## 1. Static Assets

The following files MUST exist at the repo root and be serveable:

| File              | Purpose                          |
|-------------------|----------------------------------|
| `index.html`      | Entry point HTML shell           |
| `app.js`          | Main Three.js application        |
| `style.css`       | Visual styling                   |
| `portals.json`    | Portal registry data             |
| `vision.json`     | Vision points data               |
| `manifest.json`   | PWA manifest                     |
| `gofai_worker.js` | GOFAI web worker                 |
| `server.py`       | WebSocket bridge                 |

## 2. DOM Contract

The following elements MUST exist after the page loads:

| ID                    | Type     | Purpose                            |
|-----------------------|----------|------------------------------------|
| `nexus-canvas`        | canvas   | Three.js render target             |
| `loading-screen`      | div      | Initial loading overlay            |
| `hud`                 | div      | Main HUD container                 |
| `chat-panel`          | div      | Chat interface panel               |
| `chat-input`          | input    | Chat text input                    |
| `chat-messages`       | div      | Chat message history               |
| `chat-send`           | button   | Send message button                |
| `chat-toggle`         | button   | Collapse/expand chat               |
| `debug-overlay`       | div      | Debug info overlay                 |
| `nav-mode-label`      | span     | Current navigation mode display    |
| `ws-status-dot`       | span     | Hermes WS connection indicator     |
| `hud-location-text`   | span     | Current location label             |
| `portal-hint`         | div      | Portal proximity hint              |
| `spatial-search`      | div      | Spatial memory search overlay      |
| `enter-prompt`        | div      | Click-to-enter overlay (transient) |

## 3. Three.js Contract

After initialization completes:

- `window` has a THREE renderer created from `#nexus-canvas`
- The canvas has a WebGL rendering context
- `scene` is a `THREE.Scene` with fog
- `camera` is a `THREE.PerspectiveCamera`
- `portals` array is populated from `portals.json`
- At least one portal mesh exists in the scene
- The render loop is running (`requestAnimationFrame` active)

## 4. Loading Contract

1. Page loads → loading screen visible
2. Progress bar fills to 100%
3. Loading screen fades out
4. Enter prompt appears
5. User clicks → enter prompt fades → HUD appears

## 5. Provenance Contract

A validation run MUST prove:

- The served files match a known hash manifest from `Timmy_Foundation/the-nexus` main
- No file is served from `/Users/apayne/the-matrix` or other stale source
- The hash manifest is generated from a clean git checkout
- Screenshot evidence is captured and timestamped

## 6. Data Contract

- `portals.json` MUST parse as valid JSON array
- Each portal MUST have: `id`, `name`, `status`, `destination`
- `vision.json` MUST parse as valid JSON
- `manifest.json` MUST have `name`, `start_url`, `theme_color`

## 7. WebSocket Contract

- `server.py` starts without error on port 8765
- A browser client can connect to `ws://localhost:8765`
- The connection status indicator reflects connected state