84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# 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
|