the-nexus/BROWSER_CONTRACT.md

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