Void-Homelab/docs/superpowers/specs/2026-06-08-fold-in-timelapse-aiusage-design.md

# Design: Fold Timelapse + AI Usage into the Void

**Date:** 2026-06-08
**Status:** Approved (brainstorm), pending implementation plan
**Target version:** void-server `2.0.0-alpha.27`

## Summary

Make the **Timelapse** app and the **AI Usage (phuryn/claude-usage)** dashboard
first-class, navigable items in the Void's left rail, embedded as **cross-origin
HTTPS iframes**. Each app remains reachable at its own `*.hynesy.com` URL, and
when accessed there it shows only the bare app — no Void chrome, so there is no
way to "backtrack" into the Void. The Timelapse app additionally gets a Phase‑1
restyle (palette + typography) to align with the Void aesthetic.

This is the **fold-in feature**. Three things are explicitly **out of scope**
here and tracked separately:

- The phuryn dashboard "not really working" **functional fix** (deferred by user).
- The Timelapse **Phase‑2 full visual match** (preview-first follow-up).
- **Void 1 / CT 301 teardown** (separate infra effort, sequenced after this).
- Moving the existing **Terminal** rail item into the new section.

## Background / current state

- **Void 2** — `/project/src/void-v2`, Express + hash-routed SPA, deployed to
  CT 311 (`192.168.1.216`), served at `void.hynesy.com` behind CF Access.
  - Sidebar (`public/components/sidebar.js`) has sections: Spaces, Agents, Navigate.
  - **Embedding precedent:** the `Terminal` item is an `<iframe src="/terminal/">`
    that `server.js` reverse-proxies (with WebSocket upgrade) to ttyd on CT 300.
- **Timelapse** — `/project/farm-timelapse`, FastAPI + HTMX (Python) on CT 108,
  served at `timelapse.hynesy.com` (CF tunnel → Traefik on CT 100 → CT 108:8000,
  behind CF Access / Google IdP).
- **AI Usage** — `phuryn/claude-usage`, a Python-stdlib web SPA on **CT 300**
  (`192.168.1.212:8080`). Its data source is CT 300's local
  `/root/.claude/projects/**/*.jsonl` (Claude Code transcripts). There is also a
  Sacred Valley card `public/views/cards/ai_usage.js` whose `Full dashboard ↗`
  link currently points at the raw `http://192.168.1.212:8080/`.

### Why phuryn stays on CT 300

Its entire data source is CT 300's local Claude Code transcripts. Relocating it
to the Void CT would require continuously syncing those JSONL files across hosts
for no benefit. Void already proxies to CT 300 for the Terminal, so CT 300 is an
already-trusted backend.

## Decisions

| Decision | Choice | Rationale |
|---|---|---|
| Embed strategy | **A — cross-origin HTTPS iframes** | Both apps use root-relative paths; a same-origin prefix proxy would collide with Void's own routes (timelapse's hardcoded `/browse…`, phuryn's `fetch('/api/…')`). Cross-origin iframes to each app's own HTTPS origin sidestep all path rewriting. |
| phuryn hostname | **`aiusage.hynesy.com`** | New CF tunnel host → CT 300:8080 behind CF Access. Also *adds* auth to phuryn, which is currently unauthenticated on the LAN. |
| Timelapse standalone URL | `timelapse.hynesy.com` (unchanged) | Already HTTPS, no `X-Frame-Options`, directly frameable. |
| SV AI Usage card | **Keep as-is**, retarget its link only | Card stays; `Full dashboard ↗` retargets to in-Void `#/ai-usage`. |
| Rail placement | New **"Apps"** sidebar section | Groups embedded external apps; Terminal stays under Navigate (moving it is out of scope). |
| Timelapse restyle | **Phase 1 = palette + typography only** | Fast, low-risk, no markup restructure. Phase 2 deferred. |

## Architecture

Void renders, per app, a thin Void-styled header bar + a full-height `<iframe>`
pointing at the app's own HTTPS origin. No "back to Void" affordance is injected
into either app, so standalone visits stay chromeless.

| App | Standalone URL | Backend host | Iframe `src` |
|---|---|---|---|
| Timelapse | `timelapse.hynesy.com` (exists) | CT 108 | `https://timelapse.hynesy.com` |
| AI Usage | `aiusage.hynesy.com` (new) | CT 300:8080 | `https://aiusage.hynesy.com` |

## Components

### Void (CT 311, `/project/src/void-v2`)

- `public/router.js` — add routes `timelapse` (`#/timelapse`) and `ai-usage`
  (`#/ai-usage`).
- `public/components/sidebar.js` — add an **"Apps"** section with `Timelapse`
  and `AI Usage` nav items (active-highlight synced like existing items).
- `public/views/timelapse.js` and `public/views/aiusage.js` — each mirrors
  `public/views/terminal.js`:
  - Void header bar: `◆ <Title>`, an `↗ Open` link to the standalone URL
    (`target=_blank`), and a `⟳ Reload` button (`f.src = f.src`).
  - Full-height `<iframe>` with correct `src`. Timelapse iframe gets
    `allow="fullscreen"` for video playback.
  - No back-to-Void affordance inside the embedded app.
- `public/app.js` — wire the two new view modules into the render switch
  (matching how `terminal` is dispatched).
- `public/views/cards/ai_usage.js` (line ~33) — retarget `Full dashboard ↗`
  from `http://192.168.1.212:8080/` to in-Void `#/ai-usage` (drop `target=_blank`
  so it opens session-shared within the SPA). Card otherwise unchanged.
- `package.json` / version string in `server.js` — bump to `2.0.0-alpha.27`;
  CHANGELOG entry.

### Cloudflare / infra (provisioned via CF API; creds in memory)

- **Traefik (CT 100) dynamic config:** router for `aiusage.hynesy.com` →
  `http://192.168.1.212:8080`. Wildcard `*.hynesy.com` DNS already targets the
  tunnel, so no new DNS record is required.
- **CF Access application** for `aiusage.hynesy.com` — Google IdP + email
  allowlist, cloned from the existing `timelapse` Access app.

### Timelapse restyle — Phase 1 (CT 108, `/project/farm-timelapse`)

- Port Void's design tokens into `tlcapture/static/style.css`:
  - Palette: `--bg #0a0a0e`, `--panel #14141c`, `--panel-2 #1c1c26`,
    `--border #2a2a36`, `--text #e8e6ed`, `--muted #888094`,
    `--accent #ff4f2e` (blackflame), `--ok/--warn/--bad` as in Void.
  - Fonts: display `Cinzel`/`Cormorant Garamond` serif, body
    `Cormorant Garamond`, UI `system-ui`, mono `JetBrains Mono`.
- Colors, typography, and surface backgrounds only. **No markup restructure**
  (that is Phase 2). The app keeps its own internal navigation/controls.

## Data flow

No new data paths. phuryn keeps reading CT 300's local JSONL transcripts; only
its *exposure* changes (LAN `:8080` → additionally `aiusage.hynesy.com` via
Traefik/CF Access). Timelapse is functionally untouched; only its CSS changes.

## Error handling

Cross-origin iframes cannot report load status to the parent, so each Void view
always surfaces an `↗ Open in new tab` fallback in its header (usable even if the
frame is blank) plus a `⟳ Reload`. If CF Access ever shows a login wall inside
the frame, the fallback link routes the user there at top level. Validating that
CF Access SSO renders frame-inline (no login wall, given an existing session) is
the **first** implementation step.

## Testing

- **vitest + jsdom:** router resolves `#/timelapse` and `#/ai-usage`; sidebar
  renders the two Apps items; each view mounts an iframe with the expected `src`;
  the SV card link points at `#/ai-usage`.
- **CF / infra:** `curl -I https://aiusage.hynesy.com` → CF Access challenge when
  unauthenticated; `200` with a valid session/service token.
- **Playwright (webapp-testing):** click each rail item → embed loads; visit
  `timelapse.hynesy.com` and `aiusage.hynesy.com` directly → no Void rail present.

## Sequencing & safety

1. Provision `aiusage.hynesy.com` (Traefik route + CF Access app); **validate
   iframe SSO** renders without a login wall before touching Void.
2. Void changes: Apps section + routes + two views + SV-card retarget + version
   bump → `alpha.27`. Deploy via existing `deploy/`.
3. Timelapse Phase‑1 restyle. Deploy via `scripts/install.sh`.

`pct snapshot` CT 311 before the Void deploy and CT 108 before the restyle
deploy (backup-before-changes rule).

## Out of scope (tracked elsewhere)

- phuryn functional fix ("not really working").
- Timelapse Phase‑2 full component restyle (preview first).
- Void 1 / CT 301 teardown (separate infra effort).
- Migrating the Terminal rail item into the Apps section.