# 3D/VR Coding Systems and Interfaces

Status: local Notion-ready research packet.

Notion note: the Notion connector search failed in this session with `UNAUTHORIZED / oauth_token_invalid_grant`, so this document is prepared locally first. Reauthenticate Notion, then publish or rerun the source scan.

## Executive Summary

AetherDesk already has the core pieces for a 3D/VR coding interface:

- Prism Shadow is the intent-to-code visualizer.
- Display Rig is the screen and overlay compositor.
- Immersive Controls is the VR, voice, haptic, gamepad, dwell, and switch input lane.
- `/api/code/cube` is the agent-usable coding contract.
- Notion is the right documentation and research sink, but it must stay connector-authenticated rather than storing secrets in the build.

The practical architecture is: user intent enters as plain language, gets converted into a fast-read packet, projects through the code prism, routes into bounded execution surfaces, and leaves a documentation receipt.

## AetherDesk System Map

### 1. Prism Shadow

Role: intent-to-code visualizer.

Current contract:

- Treat user intent as the light source.
- Show language faces, collisions, and possible code paths as a rotatable prism.
- Keep fast-read output available before slower full-file or full-site reading.
- Emit function outputs, code segments, workflow injections, ChoiceScript branches, and timed intervention steps.

Routes and files:

- `/api/autocoding-systems`
- `/api/code/cube`
- `C:\Users\issda\AetherDesk\aetherdesk\public\real-pc-shell.js`
- `C:\Users\issda\AetherDesk\aetherdesk\public\real-pc-shell.css`

### 2. Display Rig

Role: screen and overlay compositor.

Current contract:

- Default first to the HP Pavilion laptop layout.
- Support ultrawide, micro-screen, headless, VR stereo, and fractal holographic overlays.
- Keep overlays visual-only with `pointer-events: none`.
- Let the same work surface scale from normal laptop use to headset planning.

Route:

- `/api/display-modes`

### 3. Immersive Controls

Role: input lane for voice, VR, gamepad, haptics, dwell, and switch control.

Current contract:

- Detect browser capabilities like WebXR, speech, gamepad, and vibration.
- Keep headset and controller actions routed through bounded AetherDesk APIs.
- Preserve keyboard, mouse, and text input parity for normal PC use.
- Keep mutation actions behind existing gates.

Routes:

- `/api/immersive-controls`
- `/api/immersive-controls/event`

### 4. Cube Coding API

Role: agent-usable coding contract.

Current contract:

- Accept token strands and target languages.
- Return verified polyglot code when the backend is available.
- Return a graceful offline shape when the backend is unavailable.

Route:

- `/api/code/cube`

### 5. Notion Connector

Role: research and documentation lane.

Current contract:

- Import or compare exported Notion snapshots.
- Publish research only through authenticated connector state.
- Do not hardcode secrets in AetherDesk.

Routes:

- `/api/connectors/notion`
- `/api/connectors/notion/compare`

## Interface Model

1. Human intent
   - Plain language request, preserved before rewriting.

2. Fast-read packet
   - Short AI-first packet that names goal, scope, tool lanes, and risk.

3. Coding prism
   - Rotatable language faces show possible code paths, collisions, and receipts.

4. Autocoding systems
   - Function outputs, code segments, workflow injections, ChoiceScript branches, and timed intervention steps.

5. Bounded execution
   - Terminal, cube-code, workflow, and tool routes run through allowlisted or gated APIs.

6. Display and VR overlays
   - Same data remains usable on laptop, ultrawide, micro, headless, and VR stereo views.

7. Documentation receipt
   - Local Markdown and API packet first; Notion publish only through authenticated connector state.

## External Research Notes

- W3C WebXR Device API: WebXR is the standards-aligned browser API for VR/AR devices, sensors, and head-mounted displays. Source: https://www.w3.org/TR/webxr/
- MDN WebXR Device API: WebXR manages device selection, frame timing, rendering to the selected output device, and motion vectors from input controllers. Source: https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API
- MDN WebXR inputs: XR input sources need explicit handling; do not assume a desktop mouse maps cleanly to controllers or hands. Source: https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API/Inputs
- three.js VRButton: Three.js provides a WebXR entry utility for creating an immersive VR session button. Source: https://threejs.org/docs/pages/VRButton.html
- Windows touch/input guidance: app functionality should remain exposed consistently across touch, mouse, pen, keyboard, and text alternatives. Source: https://learn.microsoft.com/en-us/windows/apps/develop/input/touch-developer-guide

## Build Queue

1. Reauthenticate Notion and publish this packet.
2. Add a Playwright visual proof that opens Prism Shadow, rotates/zooms/curves the stage, and saves screenshot evidence.
3. Keep WebXR optional: laptop keyboard/mouse/text routes must remain fully capable without a headset.
4. Force AI-facing code/system reads through the fast-read packet before full UI or full-file inspection.
5. Add a visible "Publish to Notion" action only after connector auth is valid.

## Product Rule

The app is a real PC first. VR, holographic overlays, and prism visuals are optional display and thinking layers, not replacements for a working terminal, editor, files, writing surface, and bounded AI tool routes.
