feat: add ofxpimapper-full-stack OpenSpec artifacts

Comprehensive blueprint for a headless Raspberry Pi 3B projection mapping appliance:
- Unified installer with 2GB swap safety for C++ source builds.
- WebSocket-driven real-time vertex/surface manipulation.
- 5-tab responsive dashboard (Dashboard, Mapping, Media, Network, System).
- Media validation with ffprobe (H.264 check) and resource warnings.
- Throttled log streaming and explicit mapping persistence.

openspec/changes/ofxpimapper-full-stack/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-10

openspec/changes/ofxpimapper-full-stack/design.md

@@ -0,0 +1,46 @@
+## Context
+
+Unifying the Raspberry Pi 3B (1GB RAM) into a dedicated projection mapping appliance. The system must be entirely headless, controllable via any browser-enabled device on the same network.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide a "one-liner" setup script that installs the entire stack.
+- Enable real-time remote manipulation of mapping surfaces via WebSockets.
+- Implement a robust system for media management and system monitoring.
+- Maintain a permanent WiFi AP while allowing connection to external networks (Hybrid Mode).
+
+**Non-Goals:**
+- **Audio Support**: Explicitly out of scope for the Pi 3B in this version.
+- **Pi 4/5 Support**: Target hardware is strictly Pi 3B for this design.
+- **Multi-Projector Sync**: Synchronizing multiple Pi units is not part of this version.
+
+## Decisions
+
+### 1. Real-Time Communication (WebSockets)
+We will use **Socket.io** for all vertex and surface updates. This bypasses the overhead of HTTP and allows the browser to feel like a direct remote for the `ofxPiMapper` engine.
+
+### 2. Networking Architecture (Permanent AP)
+- **Primary**: The Pi acts as an Access Point (`MPVJ-AP`) on `wlan0`.
+- **Secondary**: A virtual interface or shared `wlan0` configuration will allow connecting to venue WiFi.
+- **Safety**: The AP never turns off, ensuring you can always reach the UI even if the venue WiFi fails.
+
+### 3. Media Assignment & Validation
+The Node.js backend will maintain a JSON manifest of mapping surfaces and their assigned sources.
+- **Validation**: On upload, the backend will use `ffprobe` to verify the codec (H.264 required) and resolution (Warn if > 1080p).
+- **Resource Warning**: The UI will display a "High Load" warning if multiple 1080p videos are assigned, recommending 720p for stable multi-surface playback.
+
+### 4. Graphics & Build Strategy (The "Source-First" Build)
+To handle the "Highlight Surface" functionality, we will modify the `ofxPiMapper` C++ source code to include a `/ofxPiMapper/surface/highlight` OSC listener.
+- **Build Safety**: The setup script will increase the swap file to 2GB during the ~1 hour compilation to prevent OOM panics on the Pi 3B.
+- **Binary Fallback**: The script will accept an optional argument to point to a pre-compiled binary if available.
+
+### 5. Log & Data Streaming
+- **Log Throttling**: The backend will buffer and throttle the `stdout` stream (max 10 lines per 500ms) to prevent WebSocket congestion.
+- **State Persistence**: A explicit "Save Mapping" button in the UI will trigger the `/ofxPiMapper/save` OSC command to persist changes to the `settings.xml` file.
+
+## Risks / Trade-offs
+
+- **[Risk] RAM Exhaustion** → **Mitigation**: Use Preact/Vite for a lightweight frontend, set `NODE_OPTIONS="--max-old-space-size=512"`, and force `npm jobs=1`.
+- **[Risk] WiFi Interference** → **Mitigation**: Prioritize the WebSocket channel for vertex movements.
+- **[Risk] ofxPiMapper Build Time** → **Mitigation**: Attempt to pull pre-compiled binaries first; if building from source, notify the user of the 1-hour duration.

openspec/changes/ofxpimapper-full-stack/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+Currently, setting up a Raspberry Pi for projection mapping requires manually piecing together the OS, the mapping engine (`ofxPiMapper`), and various control scripts. This is fragmented, difficult to manage headlessly, and lacks a modern "appliance" feel. `ofxpimapper-full-stack` aims to unify these into a single, polished, and professional product: the Modern PocketVJ (MPVJ). It provides an "it just works" experience for artists, from the initial setup script to the real-time web-based mapping remote.
+
+## What Changes
+
+- **Unified Headless Installer**: A single setup script that installs the entire stack, including the `ofxPiMapper` engine, Node.js backend, and React frontend.
+- **Integrated Mapping Engine**: Automated installation of `ofxPiMapper` (pre-compiled binary or source build) with a systemd service to launch fullscreen on boot.
+- **Virtual Canvas 2.0**: A responsive React/Tailwind web UI for real-time vertex/surface manipulation via WebSockets, with live feedback on the beamer.
+- **Enhanced Media Vault**: Complete media management (upload/delete/preview) with the ability to assign different sources (video/image/color) to individual surfaces.
+- **Appliance Dashboard**: Integrated monitoring of system health (CPU, RAM, Temp) and process status, with remote power and restart controls.
+- **Hybrid Networking**: A robust networking stack that maintains a permanent Access Point while allowing connection to external venue WiFi via a web interface.
+
+## Capabilities
+
+### New Capabilities
+- `ofxpimapper-engine`: The core C++ mapping engine, integrated into the system-wide process management.
+- `web-remote-dashboard`: A modern, responsive TUI-inspired web interface for full system control.
+- `media-source-assignment`: The ability to dynamically map specific files or colors to specific geometric surfaces.
+- `live-logs-streaming`: Real-time streaming of system and mapper logs to the web interface.
+
+### Modified Capabilities
+- `headless-installer`: Upgraded to handle the C++ engine installation and graphics driver configuration.
+- `osc-bridge-api`: Expanded to handle naming, surface selection highlighting, and source assignment.
+- `hybrid-network-control`: Updated with a scan-and-connect web UI while preserving the AP.
+
+## Impact
+
+- **Hardware**: Strictly optimized for the Raspberry Pi 3B (1GB RAM).
+- **User Experience**: Transition from a "CLI-first" or "Desktop-first" workflow to a "Web-Remote-first" workflow.
+- **Performance**: Heavy reliance on WebSockets and optimized C++ binaries to ensure low-latency interaction.
+- **Stability**: Automated swap management and process monitoring to prevent OOM crashes during high-resolution playback.

openspec/changes/ofxpimapper-full-stack/specs/ofxpimapper-full-stack/spec.md

@@ -0,0 +1,34 @@
+# ofxpimapper-full-stack Spec
+
+## System Dashboard (Status Tab)
+- **GIVEN** the web UI is loaded
+- **THEN** it SHALL display real-time CPU Load, RAM Usage, and CPU Temperature.
+- **AND** it SHALL show the status of the `ofxPiMapper` process (Running/Stopped).
+- **AND** it SHALL provide "Restart Mapper", "Reboot Pi", and "Shutdown Pi" buttons.
+- **AND** it SHALL display the "Throttled Logs" (max 10 lines per 500ms) from the Mapper process.
+
+## Mapping Engine (Mapping Tab)
+- **GIVEN** the Virtual Canvas
+- **WHEN** a vertex is dragged in the UI
+- **THEN** it SHALL send an OSC message to `localhost:9999` via WebSockets in < 50ms.
+- **AND** it SHALL support adding/deleting surfaces (Quad/Triangle).
+- **AND** it SHALL provide a prominent "Save Mapping" button to persist changes to disk.
+- **AND** clicking a surface in the UI SHALL send a highlight OSC command to the beamer.
+
+## Media Management (Media Tab)
+- **GIVEN** the Media Vault
+- **WHEN** a file is uploaded
+- **THEN** it SHALL be stored in `/home/pi/media`.
+- **AND** the backend SHALL validate that the file is H.264 and show a warning if resolution exceeds 1080p.
+- **AND** the user SHALL be able to assign any file to any named surface, with a "Resource Warning" if total pixel throughput is too high.
+
+## Networking (Network Tab)
+- **GIVEN** the Network settings
+- **THEN** the UI SHALL list available WiFi networks for client mode connection.
+- **AND** it SHALL allow changing the AP SSID and Password.
+- **AND** it SHALL display the current IP Address and Hostname (`.local`).
+
+## Hardware Constraints
+- **Processor**: Raspberry Pi 3B (ARMv8).
+- **Memory**: 1GB LPDDR2.
+- **Resolution**: Support up to 1080p hardware-accelerated H.264 video.

openspec/changes/ofxpimapper-full-stack/tasks.md

@@ -0,0 +1,30 @@
+## 1. Setup Script Upgrades
+
+- [ ] 1.1 Add `ofxPiMapper` installation logic (source build with 2GB swap safety).
+- [ ] 1.2 Modify `ofxPiMapper` C++ source code to add `/ofxPiMapper/surface/highlight` OSC listener.
+- [ ] 1.3 Implement graphics driver configuration (KMS/DRM) for headless operation.
+
+## 2. Backend Expansion (Node.js)
+
+- [ ] 2.1 Implement WebSocket (Socket.io) handlers for low-latency vertex updates.
+- [ ] 2.2 Create the Throttled Log Streamer (max 10 lines / 500ms) for process output.
+- [ ] 2.3 Implement the "Mapping Manifest" with `ffprobe` codec validation (H.264).
+- [ ] 2.4 Add System Control endpoints (Shutdown, Reboot, Restart Mapper, Save Mapping).
+
+## 3. Frontend Overhaul (React/Tailwind)
+
+- [ ] 3.1 Implement the 5-tab navigation system (Dashboard, Mapping, Media, Network, System).
+- [ ] 3.2 Build the "Responsive Dashboard" with real-time stats (CPU/RAM/Temp).
+- [ ] 3.3 Create the "Media Vault" with file upload, preview, and delete.
+- [ ] 3.4 Upgrade the "Virtual Canvas" with Surface Naming, Quad/Triangle adding, and drag/scale/rotate.
+
+## 4. Hybrid Networking UI
+
+- [ ] 4.1 Implement the WiFi scanner and client-mode connection interface.
+- [ ] 4.2 Add AP configuration (SSID/Password change) with graceful reboot handling.
+
+## 5. Integration & Stress-Testing
+
+- [ ] 5.1 Test 1080p playback stability on Pi 3B with active mapping.
+- [ ] 5.2 Validate the "LAN-Rescue" mDNS connectivity.
+- [ ] 5.3 Conduct end-to-end "Clean Install" test using the setup script.