First-party React and Node web MUD client for LuminariMUD-compatible games, with a browser UI, WebSocket-to-Telnet proxy, and MSDP-driven HUD state.

What we call the "Lumiverse":

• LuminariMUD game server
• Sage GraphRAG lore and world building
• InterMUD-3 client
• Discord bridge
• Wilderness editor
• Mudlet interface

Install dependencies once:

npm install

Run the frontend and proxy together:

npm run dev

Default local services:

• Frontend: http://localhost:5190
• Proxy/API server: http://localhost:5191
• Health check: http://localhost:5191/health

.
|-- src/                 # React browser client
|-- server/              # Express and WebSocket-to-Telnet proxy
|-- shared/              # Shared app settings and MUD protocol types
|-- public/              # Static browser assets
|-- docs/                # Project documentation
|-- package.json         # npm scripts and dependencies
\-- vite.config.ts       # Vite frontend and dev proxy configuration

• Onboarding
• Structured Account and Character Onboarding
• Development Guide
• Architecture
• Environments
• Deployment
• Bridge Deployment Options
• Bridge Fallback Runbook
• Protocol Feature Checklist
• API and WebSocket Contracts
• Tests
• Contributing
• Historical Product Requirements

• Browser terminal output rendered from Telnet text and ANSI sequences.
• React HUD and side panels for character, combat, group, affects, inventory, room, map, and quest data when matching MSDP values arrive.
• Progressive structured account and character onboarding for paired protocol-v1 Luminari-Source servers, with an optional media-capable browser presentation and classic-terminal fallback.
• Command input with history, tab completion, numpad movement, aliases, triggers, and import/export for client configuration.
• Dynamic terminal resize updates the proxy NAWS state when the server has negotiated support.
• Runtime app settings endpoint at /api/settings.
• WebSocket endpoint at /ws that bridges browser messages to a Telnet MUD connection.
• Telnet negotiation for MSDP, TTYPE, NAWS, ECHO, and SGA, with MCCP, MXP, and CHARSET currently rejected.
• Protocol status checklist and inspector coverage for supported, partial, rejected, deferred, and validation-gap protocol claims.
• Public proxy guardrails for origin checks, destination allowlists, banned ports, DNS/IP safety, quotas, and timeouts.
• Fixture-backed MSDP mapping tests and normalized shared state helpers for parser and state coverage.
• Curated MUD presets plus manual host and port input for private or operator-approved routing.

Phase 00 aligned the client with confirmed Luminari-Source MSDP data and made unsupported data states explicit. Phase 01 hardened the Telnet parser, reconnect lifecycle, resize handling, renderer decision, and public proxy safety. Phase 02 added the character, combat, group, affects, inventory, room, map, and quest fallback panels. Phase 03 records protocol support boundaries in the Protocol Feature Checklist. The product plan still tracks source-level protocol work in later phases.

Primary defaults live in shared/app-settings.ts. The browser loads those settings at runtime from /api/settings.

Environment overrides:

The supported public deployment path is the integrated game-aware proxy. Bridge fallbacks are separate terminal-only transport options, not replacements for the React app's /ws protocol.

Architecture decisions, protocol boundaries, and active operational guidance are tracked in docs/. Historical product planning is retained in docs/prev_prd/PRD.md.