Metadata-Version: 2.4
Name: luvatrix
Version: 0.1.0
Summary: Luvatrix runtime and plotting toolkit
Requires-Python: <3.15,>=3.14
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.4.2
Requires-Dist: torch>=2.4.0
Provides-Extra: plot
Provides-Extra: macos
Requires-Dist: pyobjc-core>=12.1; extra == "macos"
Requires-Dist: pyobjc-framework-cocoa>=12.1; extra == "macos"
Requires-Dist: pyobjc-framework-quartz>=12.1; extra == "macos"
Provides-Extra: vulkan
Requires-Dist: vulkan>=1.3.275.1; extra == "vulkan"
Provides-Extra: dev
Requires-Dist: matplotlib>=3.10.8; extra == "dev"

# Luvatrix

Custom app protocol + custom rendering protocol runtime in Python.

## Current Focus

Phase 1 is a macOS-first OS-level renderer:
- Window Matrix protocol (`H x W x 4` RGBA255, PyTorch)
- Vulkan presentation loop (`init -> loop -> stop`)
- HDI thread + Sensor manager thread
- In-process app protocol (`app.toml` + Python entrypoint)

## Planning Document

See `planning.md` for the integrated Phase 1 spec and visual TLDR protocol models.

## Repository Layout

- Core engine/runtime source lives in `luvatrix_core/`.
- In-repo UI contracts/components live in `luvatrix_ui/` (`text/`, `controls/`, `style/`).

## `luvatrix_ui` (In-Repo, v0)

`luvatrix_ui` is a first-party in-repo UI layer with explicit, future-extractable boundaries.

Current v0 surface:

- `TextRenderer` + text command/style contracts in `luvatrix_ui/text/renderer.py`.
- `SVGRenderer` + `SVGComponent` contracts in `luvatrix_ui/controls/svg_renderer.py` and
  `luvatrix_ui/controls/svg_component.py`.
- `ButtonModel` state machine in `luvatrix_ui/controls/button.py`:
  `idle`, `hover`, `press_down`, `press_hold`, `disabled`.
- `ThemeTokens` + validation/default merging in `luvatrix_ui/style/theme.py`.

Runtime-side compiler:

- `MatrixUIFrameRenderer` in `luvatrix_core/core/ui_frame_renderer.py` compiles first-party
  component batches (including SVG) into matrix frame tensors for `WriteBatch` submission.

Interaction model:

- Consumes standardized HDI `press` phases (`down`, `hold_start`, `hold_tick`, `up`, `cancel`, etc.).
- Keeps runtime/platform internals out of `luvatrix_ui`; integrations should adapt events/renderers at the boundary.

See:

- `docs/ui_component_protocol.md` for component contracts
- `docs/app_protocol.md` for runtime contract
- `docs/json_ui_compiler.md` for JSON page/lottie-oriented compiler design

## macOS Visualizer Examples

Run stretch mode:
```bash
uv run --python 3.14 python examples/macos_visualizer/stretch_mode.py
```

Run preserve-aspect mode (black bars when needed):
```bash
uv run --python 3.14 python examples/macos_visualizer/preserve_aspect_mode.py
```

Run the full interactive suite app-protocol example (runs until window closes):
```bash
uv run --python 3.14 python examples/app_protocol/run_full_suite_interactive.py --aspect stretch
uv run --python 3.14 python examples/app_protocol/run_full_suite_interactive.py --aspect preserve
```

Force experimental Vulkan path:
```bash
LUVATRIX_ENABLE_EXPERIMENTAL_VULKAN=1 uv run --python 3.14 python examples/macos_visualizer/stretch_mode.py
```

Force fallback layer-blit path:
```bash
unset LUVATRIX_ENABLE_EXPERIMENTAL_VULKAN
uv run --python 3.14 python examples/macos_visualizer/stretch_mode.py
```

Quick Vulkan environment probe (no window):
```bash
uv run --python 3.14 python examples/macos_visualizer/vulkan_probe.py
```

## App Protocol Example

Minimal input + sensor logger app:
```bash
uv run --python 3.14 python examples/app_protocol/run_input_sensor_logger.py --simulate-hdi --simulate-sensors
```

Choose which sensors to log:
```bash
uv run --python 3.14 python examples/app_protocol/run_input_sensor_logger.py \
  --simulate-hdi \
  --sensor thermal.temperature \
  --sensor power.voltage_current
```

Additional available sensor metadata types:
`sensor.motion`, `camera.device`, `microphone.device`, `speaker.device`.

Open a macOS logger window and report real mouse hover coordinates (window-relative only, gated by active/focused window):
```bash
uv run --python 3.14 python examples/app_protocol/run_input_sensor_logger.py \
  --open-window \
  --sensor thermal.temperature \
  --sensor power.voltage_current
```

Notes:
- `--simulate-hdi` intentionally emits synthetic keyboard events (`key='a'`) for test visibility.
- With `--open-window` and without `--simulate-hdi`, logger emits real window-gated mouse and keyboard input.

## Unified Runtime CLI

App manifests can now include optional `platform_support` and `[[variants]]` blocks so runtime picks only the host-compatible variant entrypoint/module root.

Run any app protocol folder (`app.toml` + entrypoint) headless:
```bash
uv run --python 3.14 python main.py run-app examples/app_protocol/input_sensor_logger --render headless --ticks 300
```

Run it with macOS window rendering:
```bash
uv run --python 3.14 python main.py run-app examples/app_protocol/input_sensor_logger --render macos --width 640 --height 360
```

Use real macOS sensor providers:
```bash
uv run --python 3.14 python main.py run-app examples/app_protocol/input_sensor_logger --render headless --sensor-backend macos
```

Enable runtime energy safety monitoring (throttles on warn, can enforce shutdown on sustained critical telemetry):
```bash
uv run --python 3.14 python main.py run-app examples/app_protocol/input_sensor_logger \
  --sensor-backend macos \
  --energy-safety monitor
```

Enforce shutdown instead of monitor-only mode:
```bash
uv run --python 3.14 python main.py run-app examples/app_protocol/input_sensor_logger \
  --sensor-backend macos \
  --energy-safety enforce \
  --energy-critical-streak 3
```

Persist audit events to SQLite or JSONL:
```bash
uv run --python 3.14 python main.py run-app examples/app_protocol/input_sensor_logger --audit-sqlite ./.luvatrix/audit.db
uv run --python 3.14 python main.py run-app examples/app_protocol/input_sensor_logger --audit-jsonl ./.luvatrix/audit.jsonl
```

With the logger example, you can explicitly include motion:
```bash
uv run --python 3.14 python examples/app_protocol/run_input_sensor_logger.py \
  --open-window \
  --sensor sensor.motion \
  --sensor thermal.temperature \
  --simulate-sensors
```
