thornhill-tv/AGENTS.md

# AGENTS.md — Thornhill TV

Guidance for AI agents and contributors working in this repository.

## What this project is

**Thornhill TV** is a desktop Electron app with a Vue 3 frontend. It presents a scrollable “space” of feed tiles and a year/month timeline overlay, controlled primarily by the keyboard. The UI is dark-themed, full-viewport, and framed as a TV-like surface rather than a conventional document app.

At a high level:

- **Electron** owns the window, native theme, optional CORS bypass, and packaging.
- **Vue 3** owns the interactive UI (space grid + timeline).
- **Vite** serves the UI in development and bundles it for production.
- **electron-builder** produces platform installers (AppImage / NSIS / DMG).

Package metadata: `thornhill-tv` `0.1.0`, MIT, entry `start.js`.

## Architecture overview

```
┌─────────────────────────────────────────────────────────────┐
│  Node process (start.js dual role)                          │
│                                                             │
│  yarn start → start.js as Node                              │
│    ├─ Vite dev server (src-vue, random free port)           │
│    └─ spawn(electron, start.js) with PORT env               │
│                                                             │
│  start.js as Electron main                                  │
│    ├─ BrowserWindow + preload (src-electron/preload.js)     │
│    ├─ config.js → window chrome / CORS / title              │
│    └─ loadURL(localhost:PORT) | loadFile(dist/index.html)   │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  Renderer (Vue 3)                                           │
│  App.vue                                                    │
│    ├─ Space.vue  → grid of Feed.vue tiles (scrollable)      │
│    └─ Timeline.vue → year / month navigator (Tab toggle)    │
└─────────────────────────────────────────────────────────────┘
```

### Dual-entry bootstrap (`start.js`)

`start.js` is both the npm `main` and the Electron entry. Behavior depends on what `require('electron')` returns:

| Context | `require('electron')` | Behavior |
| --- | --- | --- |
| Plain Node (`yarn start`) | Path string to the Electron binary | Start Vite on an ephemeral port, spawn Electron with `PORT` set, exit when the child exits |
| Electron main process | Electron API object | Create the window, apply config, load the UI |

This avoids a separate “main” vs “launcher” file.

### Dev vs packaged load path

- **Development:** renderer loads `http://localhost:${PORT}/` from Vite. Vue DevTools (`nhdogjmejiglipccpnnnanhbledajbpd`) is installed when unpackaged. Detached DevTools open and stay active.
- **Packaged:** renderer loads `./dist/index.html`. DevTools are closed after open.

Native theme is forced to dark (`electron.nativeTheme.themeSource = 'dark'`).

### Build pipeline (`build.mjs`)

1. Delete `./dist` and `./build` if present.
2. Vite build of `src-vue` → `../dist` with `base: './'` (file://-safe relative assets).
3. `electron-builder` for the **current host platform only**:
   - Linux → AppImage (x64)
   - Windows → NSIS (x64)
   - macOS → DMG
4. Output under `./build`; build resources from `src-electron/assets`.
5. Packaged file set is derived from the repo root listing, excluding `.git`, tooling files, and most `.gitignore` entries (but keeping `dist`, `node_modules`, and `config.js` in the packaged set when present).

### Configuration (`config.js`)

Runtime config is **required** as `./config.js` (gitignored). Copy from `config.example.js`:

| Key | Type | Role |
| --- | --- | --- |
| `isSpellcheckEnabled` | boolean | BrowserWindow spellcheck |
| `isTitleBarEnabled` | boolean | Native frame / title bar (`frame`) |
| `isMenuBarEnabled` | boolean | Menu bar visibility |
| `isCorsEnabled` | boolean | When `false`, strips real CORS headers and injects `*` allow-origin/methods/headers on all responses (useful for embedding remote media in feeds) |
| `title` | string | Window / HTML title (falls back to package name) |

Agents changing window behavior should update `config.example.js` and document new keys here; never commit secrets in `config.js`.

### Preload (`src-electron/preload.js`)

Currently a stub (`console.log`). The preload path is wired in `BrowserWindow` `webPreferences.preload`. Prefer exposing a narrow `contextBridge` API here if the renderer needs Node/Electron capabilities; do not enable `nodeIntegration` unless explicitly required.

## Directory map

```
thornhill-tv/
├── AGENTS.md                 # This file
├── package.json              # Scripts, deps, Electron main = start.js
├── yarn.lock
├── start.js                  # Dev launcher + Electron main
├── build.mjs                 # Vite production build + electron-builder
├── config.example.js         # Template for config.js
├── config.js                 # Local overrides (gitignored)
├── src-electron/
│   ├── preload.js            # Preload script for the renderer
│   └── assets/
│       └── icon.png          # App / builder icon
├── src-vue/
│   ├── index.html            # Shell: destyle.css, dark color-scheme, Apple font
│   ├── main.js               # createApp(App) → .App
│   ├── static/fonts/
│   │   └── Apple.woff2
│   └── components/
│       ├── App.vue           # Layout + Tab focus switch
│       ├── Space.vue         # Feed grid + arrow-key pan
│       ├── Timeline.vue      # Year/month bar
│       └── Space/
│           └── Feed.vue      # Single feed tile (placeholder color)
├── dist/                     # Vite output (gitignored)
└── build/                    # electron-builder output (gitignored)
```

## UI features and interaction model

### Layout (`App.vue`)

- Full viewport CSS grid: `1fr` main area + `125px` bottom strip for the timeline.
- Two siblings: `Space` and `Timeline`.
- **Tab** (on keyup): toggles `isTimelineActive`, focuses either Timeline or Space. Tab keydown is always prevented (no browser focus cycle).
- Timeline receives `:is-active` to animate open/closed.

### Space — feed mosaic (`Space.vue`)

- Renders `feedCount` (currently **100**) `Feed` children in a CSS grid.
- Grid dimensions: `columnCount = floor(sqrt(feedCount))`, `rowCount = ceil(feedCount / columnCount)` so the mosaic stays roughly square.
- Tile size via CSS variables: `--feed-width: 400px`, `--feed-height: 300px`, `--feed-gap: 50px`. Outer `Space` overflows hidden; the inner `Space__Feeds` is larger and is panned by scrolling the host.
- **Arrow keys** while Space is focused: continuous pan via `requestAnimationFrame` loops (`SCROLL_STEP = 25` px per frame). Separate flags for X/Y so diagonal motion works. Keyup clears the corresponding axis flag.
- Host is `tabindex="1"` so it can receive keyboard focus.

### Feed tile (`Space/Feed.vue`)

- Placeholder: random hex background color per instance.
- Intended extension point for real video / stream / channel content.

### Timeline (`Timeline.vue`)

- Collapsed by default (`max-height: 0`); when `Timeline--active`, expands with a 0.25s transition over a semi-transparent black bar.
- Years: current year − 5 through current year + 1 (seven slots). Default `activeYear` index is `5` (current year).
- Months: single-letter labels `J F M A M J J A S O N D`. Month row appears only when `activeMonth` is a number.
- Keyboard (on keyup, when Timeline focused):
  - **Up:** leave month mode (`activeMonth = undefined`).
  - **Down:** enter month mode (current calendar month if active year is current; otherwise month `0`).
  - **Left / Right:** move month (0–11) or year index within bounds.
- Active year/month use opacity (0.5 inactive, 1 active). Uses the custom `Apple` font face.

### Visual / CSS conventions

- Global reset: `destyle.css`.
- `color-scheme: dark`; `:focus-visible { outline: none }` (keyboard focus is app-managed).
- Prefer local `<style>` in SFCs; layout uses CSS grid and custom properties rather than a CSS framework.
- Do not introduce Inter/Roboto/system defaults for branded chrome; the project already ships `Apple.woff2` for timeline type.

## Scripts and workflow

| Command | Purpose |
| --- | --- |
| `yarn` / `yarn install` | Install dependencies |
| `yarn start` | Vite + Electron (development) |
| `yarn build` | Production Vite build + electron-builder for this OS |

Prerequisites for agents:

1. Ensure `config.js` exists (`cp config.example.js config.js`) before `start` or `build`.
2. Use **Yarn** (lockfile is `yarn.lock`); do not switch package managers without an explicit request.
3. Do not commit `config.js`, `dist/`, `build/`, or `node_modules/`.

## Dependency roles

| Package | Role |
| --- | --- |
| `electron` | Desktop shell |
| `electron-builder` | Installers |
| `electron-devtools-installer` | Vue DevTools in unpackaged runs |
| `vite`, `@vitejs/plugin-vue`, `vite-plugin-html` | Dev server + HTML title injection + production bundle |
| `vue` | UI framework (Options API via `defineComponent`) |
| `destyle.css` | CSS reset |
| `dayjs` | Declared dependency; not yet used in source — prefer it for any new date logic to match the package intent |

## Conventions for code changes

### Prefer existing patterns

- Vue components use **Options API** (`defineComponent`, `data`, `methods`, `mounted` / `beforeUnmount`). Match that style unless migrating the whole tree.
- Keyboard handling is done with DOM listeners on the component root (or `window` in `App`), not Vue `@keydown` templates — keep that consistent for focus-scoped controls.
- Event listener cleanup belongs in `beforeUnmount`.
- Keep Electron concerns in `start.js` / `src-electron`; keep UI in `src-vue`.

### Safe extension points

- **Real feeds:** flesh out `Feed.vue` (and possibly props from `Space.vue`) without changing the grid math unless product requirements demand it.
- **Timeline ↔ Space coupling:** today Timeline selection does not filter feeds; wiring year/month to feed data is a natural next feature.
- **IPC / APIs:** add through `preload.js` + `contextBridge`, then consume from Vue.
- **Config toggles:** extend `config.example.js` and destructure in `start.js`.

### Avoid unless asked

- Enabling `nodeIntegration` or disabling `contextIsolation`.
- Committing generated `dist/` / `build/` artifacts.
- Cross-compiling all platforms in one build (current builder only targets `process.platform`).
- Rewriting the dual-role `start.js` without a clear migration plan — Vite port discovery and Electron spawn are tightly coupled.

### Testing / verification

There is no automated test suite. After UI or Electron changes:

1. `yarn start` and verify Tab focus switching, Space arrow panning, Timeline year/month navigation.
2. For packaging changes, `yarn build` on the relevant OS and smoke-test the artifact under `build/`.

## Mental model for agents

Treat Thornhill TV as a **keyboard-first media wall**: a large pannable grid of feeds plus a temporal navigator. Changes should preserve full-viewport immersion, dark theme, and arrow/Tab navigation. Electron is a thin host; almost all product behavior lives under `src-vue/components`.