For builders

How to run, test, and extend every part of the repository — and how this book's own images were generated.

Layout

dreamlayer/
├── halo-lua/            device firmware (Lua)
│   ├── main.lua         the ~20 fps tick loop and card queue
│   ├── app/             state machine, IMU gestures
│   ├── ble/             framing, message types, host comm
│   ├── display/         renderer, horizon, materials, palette, animations,
│   │                    typography, particles, parallax, dream renderer, prism
│   └── compat/          the frame adapter (the hardware seam table)
├── host-python/
│   └── src/dreamlayer/
│       ├── orchestrator/  the hub (see the mind chapters)
│       ├── ai_brain/      router, verify, saga; server/ = the Mac Brain
│       ├── hud/           Python mirror renderer, cards, goldens, motion math
│       ├── bridge/        BLE bridge + the Lua raster harness
│       ├── demo/          the emissive overlay / film pipeline
│       └── tests/         the whole suite lives here
├── phone-app/           Expo / React Native
├── laptop-companion/    the minimal context agent + macOS installer
├── docs/                specs; docs/gitbook/ is this book
└── scripts/             demos, exporters, the Halo lab

Running each runtime

# The Python engine (hub + Brain + HUD mirror)
pip install -e ./host-python

# The Mac Brain server + control panel
python -m dreamlayer.ai_brain.server --token <token>     # port 7777

# The phone app
cd phone-app && npm install && npx expo start             # Expo Go on your phone

# End-to-end walkthrough (install, run, pair): docs/TESTING.md

The test suites

cd host-python && python -m pytest -q     # 1,368 passing at time of writing

• Python: unit + live-HTTP server tests (the suite boots the real Brain on a loopback port), pairing codec parity, verify parsing, saga, profile bridge, and all the orchestrator engines. Requires pytest; two dream engine tests additionally use pytest-asyncio.
• The Lua raster harness (bridge/lua_raster.py, requires lupa + Pillow): boots the actual device Lua against a software frame, counts draw calls and font switches, and asserts the Meridian contracts — draw budget (max 420 calls on measured worst frames), palette write budget (8/tick), particle pool (24), the strobe guard, reduce-motion stillness (settled frames pixel-identical), Solid richness floors (at least 1.25x pre-Solid lit pixels), typography metrics (glyph advances within +-2 px of the reference face), and Lua-to-Python motion-constant parity.
• Phone: npx tsc --noEmit (strict TypeScript). No test runner in the package today.

Golden images — every card as a still

python -m dreamlayer.hud.golden_images --generate --dir out/goldens   # 23 deterministic keys
python - <<'PY'
from dreamlayer.hud.cards import ALL_SAMPLES
from dreamlayer.hud.golden_images import generate_golden
for key in ALL_SAMPLES:                 # all 31 sample cards
    generate_golden(key, "out/goldens")
PY

256x256 circular PNGs from the mirror renderer; regression diffing tolerates 8/255 per channel on at most 2 percent of pixels. Device-accurate goldens — rendered by the device Lua through the harness — come from python -m dreamlayer.hud.export_cinema_v2_golden and live under assets/cinema_v2/golden/.

The demo pipeline — real HUD, compositing-ready

host-python/src/dreamlayer/demo/ renders storyboards of real cards into emissive overlays (the waveguide look) over a dark plate. Pure PIL + numpy; no ffmpeg needed.

python -m dreamlayer.demo --list                 # storyboards
python -m dreamlayer.demo the_tour out/the_tour  # the 8-card, ~32 s montage
python -m dreamlayer.demo all out/demo           # every storyboard
python -m dreamlayer.demo catalog out/catalog    # every feature clip + master film + catalog.md

Each scene directory gets transparent overlays/, an EDL manifest.json, a composited preview.gif, and a poster.png; catalog adds the master film and catalog.md — a generated narration script in lockstep with the film's beat order. demo/README.md, STORYBOARDS.md, and AI_VIDEO.md document the video workflow (the honesty rule: the HUD is always real; AI may only draw the world behind it).

Motion exports

pip install lupa
python scripts/export_meridian_motion.py    # -> out/meridian_motion/*.gif

Steps the device code on a 50 ms clock and writes PNG sequences + GIFs: wake and aurora, focus physics, the save moment, the loading chase, the promise shatter, the prism bloom. Sibling exporters: scripts/run_demo_prism.py, scripts/run_demo_palette_cycle.py, scripts/anim_preview.py (per-card enter/hold/exit GIFs, pure PIL), scripts/run_demo_cinema.py (the 45 s v1 reel).

The Halo lab and device scripts

scripts/halo_lab.py runs scripted scenarios (scripts/scenarios/*.json) through the emulator/raster stack, producing step PNGs, a contact sheet, a timeline GIF, and a report; scripts/halo_bridge.py plays the same scenarios on a real Halo over BLE; scripts/upload.py deploys the Lua. A dozen scripts/run_demo_*.py files exercise individual lenses end to end (AI brain tiers, the Brain app over HTTP, object lens, provenance, commitment drift, confluence, REM, Reality Compiler v2, edge cases).

How this book's assets were made

Everything under docs/gitbook/assets/ is reproducible from the repo:

Extending

• A new HUD card is device-Lua-first: a draw function and DRAW entry in renderer.lua, a constructor in cards.lua and hud/cards.py, a sample in ALL_SAMPLES, mirror parity in hud/renderer.py, and raster-harness tests (budget, richness, reduce-motion) — the O3 conversation cards (FactCheck, AnswerAhead, OracleReply, Hark) are the template.
• A new brain tier or provider implements the two-method VisionBrain / KnowledgeBrain protocols and registers with the router.
• A new device implements the BLE framing and the frame adapter surface; everything above the seam is unchanged.