# XZBT

Immersive visuals and creative soundscapes.

XZBT is a self-contained browser runtime for declarative procedural audiovisual exhibits. `XZBT.html` provides capabilities; `.xzbt` documents define experiences.

## Reading order and authority

| Resource | Purpose | Status |
| --- | --- | --- |
| [MVP Product Requirements Document](XZBT_0-1_MVP_Product_Requirements_Document.md) | Product scope, user behavior, delivery requirements, and release acceptance | Document revision 0.3; format version remains 0.1 |
| [Format Specification 0.1](docs/XZBT_0-1_Format_Specification.md) | Runtime semantics, contract inventory, and required authoring examples | Document revision 0.10; audio, visual, cadence/event, and scenario contracts complete |
| [Gap Closure Decisions](docs/XZBT_0-1_Gap_Closure_Decisions.md) | Decisions and rationale for the seven pre-implementation gaps | Record revision 0.3; GC1–GC5 Phase 0 evidence complete |
| [Verification Gates](docs/XZBT_0-1_Verification_Gates.md) | Evidence required before architecture commitment, subsystem work, and release | Phase 0 complete; later subsystem, GC6, and GC7 checks scheduled |
| [Implementation status](docs/IMPLEMENTATION_STATUS.md) | Current phase, stop reason, saved work, and resume prerequisites | Implemented through Phase 6; real-duration soak, direct-file and hardware/listening gates pending |
| [Implementation plan](docs/XZBT_0-1_Implementation_Plan.md) | Sequenced phases, completion/challenge mapping, and GC6/GC7 verification schedule | Phase 1–9 plan recorded |

The PRD is authoritative for product requirements. The format specification is authoritative for runtime semantics where a contract is explicitly defined. The decision record explains those choices; the verification gates define how to check them. These documents must be updated together when a decision changes. An unresolved conflict is a specification defect, not permission for an implementation to choose silently.

The earlier ChatGPT discussion, **Discuss Application Vision** (conversation `6a9b5c32-1ffc-83e8-a219-fa8113167f03`), is historical design input. Its proposals must be reconciled into these local resources before they become implementation contracts. It is not a second source of executable instructions.

## Planning entry point

The production runtime is implemented through Phase 6, with 252 automated checks passing.
Scenarios support seven trigger types, relative/random timing, finite repeats, branching,
priority/concurrency, nested-event ownership, bounded cleanup, and development acceleration.
Exhibit E runs for forty logical minutes; A/B expose temporary scenario overrides. Open
`XZBT.html`, import the exhibits, then use the scenario Start/Cancel controls.

Run `npm run test:phase6` for scenario tests and `npm run build:scenario-acceptance` for the
[standalone scenario/soak page](prototypes/phase6/XZBT-scenario-acceptance.html).
[Instructions](prototypes/phase6/README.md) explain the real two-hour development soak,
which remains pending. Earlier direct-file restart, audio listening/protection, and
Phase 4h hardware gates also remain open; accelerated tests do not close them.

The full PRD completion criteria remain the 0.1 release target. Early integrated demonstrations are milestones, not completed MVPs. Reference exhibits develop alongside the engine; Phase 9 completes and audits the suite.

All 10 Phase 0 direct-file feasibility checks in GC1 are verified, and the GC2–GC5 contract oracles pass. Phase 1 turns those contracts into a standalone runtime shell with import, caching, activation control, diagnostics, and production seeded RNG. Phase 2 adds parameters, state, signals, values, conditions, actions, bindings, transitions, overrides, and per-exhibit parameter persistence. Phases 3a and 3b add the audio graph contract and engine; Phase 3c adds the remaining audio contract, lifecycle/voice management, automation and master protection. Measured protection acceptance, visual, cadence, scenario, UI, library-hardening, benchmark, and soak gates remain explicit in the implementation plan.

## Repository configuration

The [storage-failure evidence](docs/evidence/phase0/2026-09-04-user-storage-failure.md) additionally confirms session settings changes, directory import, and heard native playback during injected write failures. The user also confirmed the visible session-only warning; the injected-storage-failure check passed.

Copy `.env.example` to `.env` for local repository configuration. `.env` and its variants are ignored by Git; never commit real credentials. The example contains placeholders only.

The repository's existing [LICENSE](LICENSE) is preserved.

## Runtime build and verification

Build the standalone, dependency-free runtime with the pinned Node version in `.nvmrc`:

```powershell
npm run build
```

This deterministically combines the modules in `src/runtime`, the application shell, and local styles into `XZBT.html`. Open that file directly in a supported desktop Chromium browser, then import the three minimal exhibits from `exhibits`. Imported definitions and the last active exhibit are cached in IndexedDB and restored on reopen when browser storage is available. The diagnostics panel reports validation, lifecycle, and storage failures; storage failure leaves the current session usable.

Run the Phase 1 production-module, lifecycle, fixture, PRNG-vector, cache, and reproducible-build tests with:

```powershell
npm run test:phase1
```

Run the Phase 2 common-grammar conformance suite with:

```powershell
npm run test:phase2
```

Run the Phase 3 audio subsystem suite with:

```powershell
npm run test:phase3
```

Run every suite with `npm test`.

Run just the Phase 3c slice-3 traces with `npm run test:phase3c3`. The [slice-3 evidence](docs/evidence/phase3/2026-09-05-phase3c-automation.md) records coverage and the remaining manual gates.

The active performance supports typed parameters and state, read-only runtime signals, ValueSpec and ConditionSpec evaluation, ordered `set` and `override` actions, same-tick bindings with deterministic smoothing, numeric transitions, and priority-based temporary overrides. The audio subsystem validates and expands declared graphs without touching an `AudioContext`, instantiates them deterministically from the seeded stream, and realizes them through Web Audio; the application exposes gesture unlock, master volume, per-bus gain, and per-sound triggering. `exhibits/minimal-audio.xzbt` exercises components, modulation, buses, and both recipe modes.

The runtime implements recipe `release`, the seven-state lifecycle, determinable one-shot endings, voice ceilings, and graph-local `automation`. Tracks support `absolute`, `offset`, and `scale`, with `step`, `linear`, `exponential`, and `smooth` interpolation. Values are sampled once from the owning sound's seeded stream; duplicate targets and expanded limits are validated. Exposed component parameters participate without exposing component internals. Bus gains now use the shared binding → automation → override → modulation → clamp resolver. Bus automation/modulation registration is internal: the contract does not add document fields to buses or permit external node bindings/overrides.

Master protection now uses an engine-owned AudioWorklet limiter with finite-sample guards and output measurement support. `npm run build:audio-acceptance` builds the self-contained hardware capture page using the production engine and frozen stress/challenge fixtures. No sound has yet been heard from a production build; real-browser measured protection, the audio acceptance challenge, real GC4 synchronization and listening observations remain open Phase 3 gates. See the [slice-4 evidence](docs/evidence/phase3/2026-09-05-phase3c-protection.md). Visuals, cadence, events, scenarios, and the final schema-driven UI remain assigned to later phases.

## Local development server

For automated browser development checks, start the dependency-free loopback server with:

```powershell
node tools/dev-server.mjs
```

It binds only to `127.0.0.1:5173` and serves the workspace through `http://localhost:5173/`; the root route opens the Phase 0 probe for layout or control-flow inspection only. Set `XZBT_DEV_PORT` to use a different port. This server is a development aid, not part of the delivered runtime.

Do not use localhost results as Phase 0 direct-file evidence. Serving changes the origin, security model, and module-loading path. The final `XZBT.html` must still be opened and tested directly from disk for every GC1 conclusion.