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, worp core, life support, telemetry, alerts) with the Web Audio API and renders LCARD-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	LCARD themes, CRT effects, palettes	2,300
js/audio.js	AudioManager + all synth classes (hull, warp, life support, telemetry, alert, Whataverse, expanded sci-fi)	2,250
js/config.js	StarshipPresets, UniverseRegistry — data only, no behavior	1,040
js/visualizer.js	StarshipVisualizer — spectrum + worp 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:

'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):

   <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 -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.