SciFi-XZBT/agents.md

# AGENTS.md — SciFi-XZBT

Guidance for AI coding agents working in this repository.

## What this project is

A browser-only, zero-dependency **sci-fi ambient audio + visual display**. It
synthesizes starship room tone (hull drone, warp core, life support, telemetry,
alerts) with the Web Audio API and renders LCARS-styled UI, an audio
visualizer, and a procedural "observation" viewscreen on HTML canvas.

It runs by opening `index.html` in a browser. There is **no build step, no
package manager, no server, and no test suite.**

## Architecture

`index.html` loads one stylesheet and six scripts **in a fixed order**:

```
css/style.css
js/audio.js               -> js/config.js -> js/visualizer.js
js/observation-bezels.js  -> js/observation-engine.js -> js/app.js
```

Order matters: every file defines plain classes/objects and publishes them on
`window`; `js/app.js` runs last and consumes all of them. Do not reorder the
tags without checking the dependencies.

| File | Owns | ~Lines |
| --- | --- | --- |
| `index.html` | DOM skeleton, script/link tags | 370 |
| `css/style.css` | LCARS themes, CRT effects, palettes | 2,300 |
| `js/audio.js` | `AudioManager` + all synth classes (hull, warp, life support, telemetry, alert, Whoniverse, expanded sci-fi) | 2,250 |
| `js/config.js` | `StarshipPresets`, `UniverseRegistry` — data only, no behavior | 1,040 |
| `js/visualizer.js` | `StarshipVisualizer` — spectrum + warp core canvas | 640 |
| `js/observation-bezels.js` | `ObservationBezels` — procedural SVG viewport frames per era | 270 |
| `js/observation-engine.js` | `ObservationEngine` — celestial simulation and canvas rendering | 2,780 |
| `js/app.js` | DOM bindings, hotkeys, UI controllers, main loop | 3,960 |
| `tools/package.ps1` | Builds the standalone single-file HTML | — |
| `dist/SciFiAmbientDisplay_v4.html` | **Generated output — never edit by hand** | — |

## Hard constraints

- **No dependencies.** No npm, no CDN links, no external fonts, images, or
  audio files. The packaged build must work when double-clicked while offline.
- **No ES modules.** No `import` / `export`, no `type="module"`. Scripts are
  classic globals.
- **Publish globals explicitly.** End each file with `window.Thing = Thing;`,
  matching the existing pattern.
- **All audio is synthesized**, not sampled. New sounds are built from
  oscillators / noise / filters in `js/audio.js`.

## Where to make a change

- New room or ship preset, universe, palette → `js/config.js`
- Sound generation, oscillators, envelopes, filters → `js/audio.js`
- Spectrum bars, warp-core animation → `js/visualizer.js`
- Viewscreen frame / bezel shapes per era → `js/observation-bezels.js`
- Planets, stars, drift, observation-mode canvas → `js/observation-engine.js`
- Buttons, sliders, hotkeys, state wiring, animation loop → `js/app.js`
- Colors, layout, theme classes, CRT overlay → `css/style.css`

Presets in `config.js` follow a fixed shape — copy an existing one rather than
inventing fields:

```js
'era-room': {
  id, name, era, theme, alertType, description,
  hull:        { volume, baseFreq, filterCutoff, resonance, noiseMix, harmonicSpread },
  warp:        { volume, bpm, carrierFreq, filterCutoff, pulseShape, resonance, swirlMix },
  lifeSupport: { volume, noiseType, highpassFreq, lowpassFreq, airflowModSpeed, airflowModDepth },
  telemetry:   { volume, density, era }
}
```

## Adding a new JS file

1. Create `js/your-file.js` and end it with `window.YourThing = YourThing;`.
2. Add the tag to `index.html` **in this exact form**, positioned before any
   file that depends on it (and always before `js/app.js`):

   ```html
   <script src="js/your-file.js"></script>
   ```

   `tools/package.ps1` inlines assets by matching
   `<script\s+src="([^"]+)"></script>` and
   `<link\s+rel="stylesheet"\s+href="([^"]+)"\s*/?>`. Extra attributes, a
   different quote style, or a self-closing script tag will be silently left as
   an external reference and the standalone build will break.

## Build

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\package.ps1
```

Writes `dist/SciFiAmbientDisplay_v4.html` (CSS and JS inlined). Re-run it after
any change to CSS, JS, or `index.html`. `tools/extract.ps1` is the original
extraction script, kept for reference only.

## Verifying work

There are no automated tests. Verification is manual:

1. Open `index.html` in a browser; check the console is clean.
2. Exercise the affected area — play a preset, switch era/universe, open
   observation mode.
3. Re-run `package.ps1` and open `dist/SciFiAmbientDisplay_v4.html` **with the
   network disabled** to confirm it is genuinely self-contained.

Browser autoplay policy blocks audio until a user gesture; audio starting only
after a click is expected behavior, not a bug.

## Conventions and cautions

- 2-space indentation; single quotes in JS; existing brace and spacing style.
- `js/app.js` and `js/observation-engine.js` are large. Make **surgical, scoped
  edits** — do not rewrite, reorder, or reformat whole files.
- Do not reformat or lint files wholesale; diffs should stay minimal and
  reviewable.
- Never edit anything in `dist/` — regenerate it instead.
- Preserve the offline, single-file-deliverable property in every change.