the-nexus/LEGACY_MATRIX_AUDIT.md

Legacy Matrix Audit — Migration Table

Purpose: Preserve quality work from /Users/apayne/the-matrix before the Nexus browser shell is rebuilt.

Canonical rule:

• Timmy_Foundation/the-nexus is the only canonical 3D repo.
• /Users/apayne/the-matrix is legacy source material, not a parallel product.
• This document is the authoritative migration table for issue #685.

Verified Legacy State

Local legacy repo: /Users/apayne/the-matrix

Observed facts:

• Vite browser app, vanilla JS + Three.js 0.171.0
• 24 JS modules under js/
• Smoke suite: 87 passed, 0 failed
• Package scripts: dev, build, preview, test
• PWA manifest + service worker
• Vite config with code-splitting (Three.js in separate chunk)
• Quality-tier system for hardware detection
• WebSocket client with reconnection, heartbeat, mock mode
• Full avatar FPS movement + PiP camera
• Sub-world portal system with zone triggers

Migration Table

Decision key:

• CARRY = transplant concepts and patterns into Nexus vNext
• ARCHIVE = keep as reference, do not directly transplant
• DROP = do not preserve unless re-justified

Core Modules

File	Lines	Capability	Decision	Why for Nexus
js/main.js	180	App bootstrap, render loop, WebGL context recovery	CARRY	Architectural pattern. Shows clean init/teardown lifecycle, context-loss recovery, visibility pause. Nexus needs this loop but should not copy the monolithic wiring.
js/world.js	95	Scene, camera, renderer, grid, lights	CARRY	Foundational. Quality-tier-aware renderer setup, grid floor, lighting. Nexus already has a world but should adopt the tier-aware antialiasing and pixel-ratio capping.
js/config.js	68	Connection config via URL params + env vars	ARCHIVE	Pattern reference only. Nexus config should route through Hermes harness, not Vite env vars. The URL-override pattern (ws, token, mock) is worth remembering.
js/quality.js	90	Hardware detection, quality tier (low/medium/high)	CARRY	Directly useful. DPR capping, core/memory/screen heuristics, WebGL renderer sniffing. Nexus needs this for graceful degradation on Mac/iPad.
js/storage.js	39	Safe localStorage with in-memory fallback	CARRY	Small, robust, sandbox-proof. Nexus should use this or equivalent. Prevents crashes in sandboxed iframes.

Agent System

File	Lines	Capability	Decision	Why for Nexus
js/agent-defs.js	30	Agent identity data (id, label, color, role, position)	CARRY	Seed data model. Nexus agents should be defined similarly — data-driven, not hardcoded in render logic. Color hex helper is trivial but useful.
js/agents.js	523	Agent 3D objects, movement, state, connection lines, hot-add/remove	CARRY	Core visual system. Shared geometries (perf), movement interpolation, wallet-health stress glow, auto-placement algorithm, connection-line pulse. All valuable. Needs integration with real agent state from Hermes.
js/behaviors.js	413	Autonomous agent behavior state machine	ARCHIVE	Pattern reference. The personality-weighted behavior selection, conversation pairing, and artifact-placement system are well-designed. But Nexus behaviors should be driven by Hermes, not a client-side simulation. Keep the architecture, drop the fake-autonomy.
js/presence.js	139	Agent presence HUD (online/offline, uptime, state)	CARRY	Valuable UX. Live "who's here" panel with uptime tickers and state indicators. Needs real backend state, not mock assumptions.

Visitor & Interaction

File	Lines	Capability	Decision	Why for Nexus
js/visitor.js	141	Visitor enter/leave protocol, chat input	CARRY	Session lifecycle. Device detection, visibility-based leave/return, chat input wiring. Directly applicable to Nexus visitor tracking.
js/avatar.js	360	FPS movement, PiP dual-camera, touch input	CARRY	Visitor embodiment. WASD + arrow movement, first/third person swap, PiP canvas, touch joystick, right-click mouse-look. Strong work. Needs tuning for Nexus world bounds.
js/interaction.js	296	Raycasting, click-to-select agents, info popup	CARRY	Essential for any browser world. OrbitControls, pointer/tap detection, agent popup with state/role, TALK button. The popup-anchoring-to-3D-position logic is particularly well done.
js/zones.js	161	Proximity trigger zones (portal enter/exit, events)	CARRY	Spatial event system. Portal traversal, event triggers, once-only zones. Nexus portals (#672) need this exact pattern.

Chat & Communication

File	Lines	Capability	Decision	Why for Nexus
js/bark.js	141	Speech bubble system with typing animation	CARRY	Timmy's voice in-world. Typing animation, queue, auto-dismiss, emotion tags, demo bark lines. Strong expressive presence. The demo lines ("The Tower watches. The Tower remembers.") are good seed content.
js/ui.js	285	Chat panel, agent list, HUD, streaming tokens	CARRY	Chat infrastructure. Rolling chat buffer, per-agent localStorage history, streaming token display with cursor animation, HTML escaping. Needs reconnection to Hermes chat instead of WS mock.
js/transcript.js	183	Conversation transcript logger, export	ARCHIVE	Pattern reference. The rolling buffer, structured JSON entries, TXT/JSON download, HUD badge are all solid. But transcript authority should live in Hermes, not browser localStorage. Keep the UX pattern, rebuild storage layer.

Visual Effects

File	Lines	Capability	Decision	Why for Nexus
js/effects.js	195	Matrix rain particles + starfield	CARRY	Atmospheric foundation. Quality-tier particle counts, frame-skip optimization, adaptive draw-range (FPS-budget recovery), bounding-sphere pre-compute. This is production-grade particle work.
js/ambient.js	212	Mood-driven atmosphere (lighting, fog, rain, stars)	CARRY	Scene mood engine. Smooth eased transitions between mood states (calm, focused, excited, contemplative, stressed), per-mood lighting/fog/rain/star parameters. Directly supports Nexus atmosphere.
js/satflow.js	261	Lightning payment particle flow	CARRY	Economy visualization. Bezier-arc particles, staggered travel, burst-on-arrival, pooling. If Nexus shows any payment/economy flow, this is the pattern.

Economy & Scene

File	Lines	Capability	Decision	Why for Nexus
js/economy.js	100	Wallet/treasury HUD panel	ARCHIVE	UI pattern reference. Clean sats formatting, per-agent balance rows, health-colored dots, recent transactions. Worth rebuilding when backed by real sovereign metrics.
js/scene-objects.js	718	Dynamic 3D object registry, portals, sub-worlds	CARRY	Critical. Geometry/material factories, animation system (rotate/bob/pulse/orbit), portal visual (torus ring + glow disc + zone), sub-world load/unload, text sprites, compound groups. This is the most complex and valuable module. Nexus portals (#672) should build on this.

Backend Bridge

File	Lines	Capability	Decision	Why for Nexus
js/websocket.js	598	WebSocket client, message dispatcher, mock mode	ARCHIVE	Pattern reference only. Reconnection with exponential backoff, heartbeat/zombie detection, rich message dispatch (40+ message types), streaming chat support. The architecture is sound but must be reconnected to Hermes transport, not copied wholesale. The message-type catalog is the most valuable reference artifact.
js/demo.js	~300	Demo autopilot (mock mode simulation)	DROP	Fake activity simulation. Deliberately creates the illusion of live data. Do not preserve. If Nexus needs a demo mode, build a clearly-labeled one that doesn't pretend to be real.

Testing & Build

File	Lines	Capability	Decision	Why for Nexus
test/smoke.mjs	235	Automated browser smoke test suite	CARRY	Testing discipline. Module inventory check, export verification, HTML structure validation, Vite build test, bundle-size budget, PWA manifest check. Nexus should adopt this pattern (adapted for its own module structure).
vite.config.js	53	Build config with code splitting, SW generation	ARCHIVE	Build tooling reference. manualChunks for Three.js, SW precache generation plugin. Relevant if Nexus re-commits to Vite.
sw.js	~40	Service worker with precache	ARCHIVE	PWA reference. Relevant only if Nexus pursues offline-first PWA.
manifest.json	~20	PWA manifest	ARCHIVE	PWA reference.

Server-Side (Python)

File	Lines	Capability	Decision	Why for Nexus
server/bridge.py	~900	WebSocket bridge server	ARCHIVE	Reference. Hermes replaces this role. Keep for protocol schema reference.
server/gateway.py	~400	HTTP gateway	ARCHIVE	Reference.
server/ollama_client.py	~280	Ollama integration	ARCHIVE	Reference. Relevant if Nexus needs local model calls.
server/research.py	~450	Research pipeline	ARCHIVE	Reference.
server/webhooks.py	~350	Webhook handler	ARCHIVE	Reference.
server/test_*.py	~5 files	Server test suites	ARCHIVE	Testing patterns worth studying.

Summary by Decision

CARRY FORWARD (17 modules)

These modules contain patterns, algorithms, or entire implementations that should move into the Nexus browser shell:

• quality.js — hardware detection
• storage.js — safe persistence
• world.js — scene foundation
• agent-defs.js — agent data model
• agents.js — agent visualization + movement
• presence.js — online presence HUD
• visitor.js — session lifecycle
• avatar.js — FPS embodiment
• interaction.js — click/select/raycast
• zones.js — spatial triggers
• bark.js — speech bubbles
• ui.js — chat/HUD
• effects.js — particle effects
• ambient.js — mood atmosphere
• satflow.js — payment flow particles
• scene-objects.js — dynamic objects + portals
• test/smoke.mjs — smoke test discipline

ARCHIVE AS REFERENCE (9 modules/files)

Keep for patterns, protocol schemas, and architectural reference. Do not directly transplant:

• config.js — config pattern (use Hermes instead)
• behaviors.js — behavior architecture (use Hermes-driven state)
• transcript.js — transcript UX (use Hermes storage)
• economy.js — economy UI pattern (use real metrics)
• websocket.js — message protocol catalog + reconnection patterns
• vite.config.js — build tooling
• sw.js, manifest.json — PWA reference
• server/*.py — server protocol schemas

DELIBERATELY DROP (2)

Do not preserve unless re-justified:

• demo.js — fake activity simulation; creates false impression of live system
• main.js monolithic wiring — the init pattern carries, the specific module wiring does not

Concern Separation for Nexus vNext

When rebuilding inside the-nexus, keep these concerns in separate modules:

1. World shell — scene, camera, renderer, grid, lights, fog
2. Effects layer — rain, stars, ambient mood transitions
3. Agent visualization — 3D objects, labels, connection lines, movement
4. Visitor embodiment — avatar, FPS controls, PiP camera
5. Interaction layer — raycasting, selection, zones, portal traversal
6. Communication surface — bark, chat panel, streaming tokens
7. Presence & HUD — who's-online, economy panel, transcript controls
8. Harness bridge — WebSocket/API transport to Hermes (NOT a copy of websocket.js)
9. Quality & config — hardware detection, runtime configuration
10. Smoke tests — automated validation

Do not collapse all of this into one giant app file again. Do not let visual shell code become telemetry authority.

Migration Rule

Rescue knowledge first. Then rescue modules. Then rebuild the browser shell inside the-nexus.

No more ghost worlds. No more parallel 3D repos.