Magid React Client

Web-ready React client for the Magid server.

This project mirrors an earlier JavaFX desktop client and is designed to make Magid easier to deploy, access, and evolve without requiring a desktop app installation.

Status: this client is currently a prototype.

The Magid server is not yet publicly available, so production deployment/running is not a primary focus yet.

What this repository contains

• magid-app/ — the actual React + TypeScript application (Vite-based)

Note: this client was initially generated with Claude under close human supervision, with parts hand-crafted and refined.

What is Magid?

Magid is a declarative storytelling engine centered on XML/Markdown-authored stories.

At runtime, the server exposes an HTTP API and returns JSON responses that describe what the client should render:

• narration/text blocks
• interactive menu choices and standalone commands
• visual transitions
• dynamic theming/CSS configuration
• background music references

This React client is the web counterpart of the JavaFX client and follows the same server contract.

Architecture summary (current prototype)

Component flow (magid-app/src/components)

• App.tsx is the shell: options access, status feedback, and initial connection/bootstrap flow.
• MagidRoot.tsx is the central dispatcher that maps parsed protocol elements to concrete UI components.
• ResponsesContainer.tsx preserves server response order and handles blocking visual transitions before unlocking later elements.
• MenuScene.tsx, NarrationText.tsx, CommandButton.tsx, and VisualFade.tsx are focused renderers for protocol element types.
• OptionsModal.tsx manages runtime client preferences (server URL, XML selection, toggles, volume).

Hooks (magid-app/src/hooks)

• useMagidCommand exposes a stable command callback that routes user actions into store-driven server requests.
• useTypewriter implements timeline-aware progressive text rendering (DCSTP_...) with cleanup-safe timers.
• useAudio attaches/cleans looping background audio per scene.

API layer (magid-app/src/api)

• magidClient.ts contains all HTTP communication (sendCommand, serverStatus, getXmlList, requestXml).
• It also resolves magid:// anchors to the active base URL, including nested response data where needed.

Lib layer (magid-app/src/lib)

• elementFactory.ts converts server JSON into a typed ParsedElement union and handles protocol aliases/responses recursion.
• textTimeline.ts parses timeline markers for typewriter animation.
• cssUtils.ts injects/clears server-provided stylesheets dynamically.
• renderText.tsx handles line-break-preserving text rendering helpers.

State management (magid-app/src/store)

This project uses Zustand (magidStore.ts) as the single shared state container for connection status, parsed elements, config/env vars, CSS state, and command loading/error flow.

Zustand was selected because it fits the app's protocol-driven architecture:

• lightweight API with minimal boilerplate (faster to evolve during prototype work),
• easy React integration via selectors/hooks without Redux-style ceremony,
• simple colocated actions for async command flow (sendCommand) and immediate side-effects (config/CSS/app vars),
• enough structure for global cross-component state, while keeping components and utility modules small.

Magid protocol (quick overview)

• Requests are sent to a base URL using ?cmd=... (for example server-status, list-xmls, reload-xml, set-xml, or story commands).
• Responses are JSON objects containing protocol keys such as menu, narration/text, command, visual, config, or a responses array.
• magid:// anchors in response strings are resolved to the configured base server URL.
• Text can include DCSTP_ timeline markers to trigger typewriter-style progressive rendering.

For deeper protocol and architecture details, see CLAUDE.md and magid-app/src/types/protocol.ts.

Requirements

• Node.js 20.19+ or 22.12+ (Node 22 LTS recommended)
• npm 10+

Installation

1) Install/upgrade Node.js

Windows

winget install OpenJS.NodeJS.LTS

macOS (Homebrew)

brew install node@22

If needed, link it:

brew link --overwrite --force node@22

Linux

Use your distro package manager, or install via NVM (recommended for consistent Node versions).

NVM (Ubuntu/Debian/Fedora/Arch and others):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22
nvm use 22

Then reopen your terminal so PATH updates are applied.

Verify:

node --version   # should be v22.x.x or v20.19+
npm --version

2) PowerShell execution policy (Windows only, if needed)

If you get running scripts is disabled on this system while running npm scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3) Install dependencies

cd magid-app
npm install

Run in development

cd magid-app
npm run dev

Default local URL: http://localhost:5173

Build for production

cd magid-app
npm run build

Build output is generated in magid-app/dist/.

Available scripts (inside magid-app)

Command	Description
npm run dev	Start the development server with HMR
npm run build	Type-check and build for production
npm run preview	Preview the production build locally
npm run lint	Run ESLint
npm run test	Run tests once
npm run test:watch	Run tests in watch mode

Troubleshooting

Cannot find native binding / rolldown error

This usually means node_modules was installed on a different machine or Node version.

From magid-app/, reinstall cleanly:

Remove-Item -Recurse -Force node_modules, package-lock.json
npm install