meatloaf-config/README.md

Meatloaf Manipulator

A Progressive Web App (PWA) for configuring and managing Meatloaf devices — open-source Commodore 64/128 hardware that adds modern networking, storage, and peripheral support.

Features

• Status — live system status, activity log, file info, loading progress, directory and disk map overlays; WebSocket connection status; reset device or host (sends command via WebSocket)
• Devices — browse and manage attached IEC devices; Rescan Bus sends iec scan via WebSocket
• IEC — configure the IEC serial bus (fastloaders, chainloaders, directory options)
• Network — manage WiFi networks (scan, connect, remove); clicking a known network reconnects and moves it to the top; all connect/scan actions send commands via WebSocket
• Media Manager — WebDAV file browser with per-row action menus, folder configuration (.config editor), media set detection with existence checks, and smart base_url mount logic
• Reality Override — full-screen WebSocket command display over a Three.js Digital Tokamak vortex; double-tap to toggle background; twinkling star field when hidden
• Reality Override Admin — command palette for Image/Audio/Video conversion commands plus freeform input; broadcasts to all connected clients via WebSocket
• Apps — built-in tools grouped by category:
  • Management: Media Manager, Print Manager, Serial Console, Short Codes
  • Disk: RAM/ROM Explorer, BAM Editor, Directory Editor, Sector Editor, Disk Visualizer, Dump/Write Disk Image
  • Cartridge: PRG to CRT, Magic Desk Cart Builder, Easy Flash Cart Builder
  • Development: Basic Editor, Assembler, Sprite Editor, Character Set Editor, PETSCII Editor
  • Display: Idle Animation, Loading Animation, Reality Override, Override Admin
• PWA — installable on desktop and mobile; runs offline via service worker; fullscreen-capable with safe-area insets for notched phones

Architecture Highlights

Shared WebSocket

A single WebSocket connection to ws://<device-hostname>/ws is managed by WsProvider (src/app/ws.tsx) and shared app-wide via React Context. Any component can send commands or subscribe to incoming frames via useWs(). The connection auto-reconnects every 3 s on drop.

Split Config Storage

Device settings are stored in two separate files on the device (LittleFS erase-block friendly, ≤ 4 096 bytes each):

File	Contents
/.sys/config.json	General, host, hardware, WiFi, network, Bluetooth, modem, cassette, BOIP, IEC bus settings
/.sys/devices.json	IEC device list (devices.iec)

useSettings() loads both files in parallel and merges them; saves split them back automatically. A bundled fallback (src/imports/config.json) is used as the initial UI state while the device is being contacted.

WebDAV Layer

All file I/O goes through src/app/webdav.ts, which wraps the vendored webdav-component (browser-native fetch + DOMParser, no npm dependencies).

Requirements

• Node.js 18+
• npm or pnpm

Installation

npm install
# or
pnpm install

Development

npm run dev

The app is served at http://localhost:5173/config/ by default.

Start the local WebDAV + WebSocket dev server (requires Python 3):

python webdav3.py

This serves files/ over WebDAV and provides a /ws WebSocket endpoint on port 80.

To use a different base path:

BASE_PATH=/my-path/ npm run dev

Production Build

npm run build

Output is written to dist/. The build uses /config/ as the base path by default. Override with the BASE_PATH environment variable at build time:

BASE_PATH=/config/ npm run build

Deploy the contents of dist/ to the Meatloaf device web server under the configured base path.