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	Product scope, user behavior, delivery requirements, and release acceptance	Document revision 0.3; format version remains 0.1
Format Specification 0.1	Runtime semantics, contract inventory, and required authoring examples	Document revision 0.4; Phase 0 shared contracts and the Phase 3a/3b audio authoring contract complete, remaining subsystem contracts in dependency order
Gap Closure Decisions	Decisions and rationale for the seven pre-implementation gaps	Record revision 0.3; GC1–GC5 Phase 0 evidence complete
Verification Gates	Evidence required before architecture commitment, subsystem work, and release	Phase 0 complete; later subsystem, GC6, and GC7 checks scheduled
Implementation status	Current phase, stop reason, saved work, and resume prerequisites	Phase 3a/3b audio contract and implementation complete; Phase 1 direct-file and Phase 3 audible observations pending
Implementation plan	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

Phase 0 is complete, and the production runtime is implemented through Phase 3b. Continue with Phase 3c (audio automation precedence, lifecycle, and master protection) from the implementation plan while preserving the verified launch model, shared semantic contracts, and production GC2/GC3 behavior. Two observations remain open in completed work: the Phase 1 direct-file two-fixture restart, and the Phase 3 audible acceptance — no sound has been heard from any build. Workload measurements and release soak tests remain later explicit gates.

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 authoring contract — all sixteen graph node types, routing and modulation, graph legality, authoring limits, components, sounds and recipes, and buses — together with pure validation and expansion, deterministic instantiation, and Web Audio realization. Later Phase 3c, visual, cadence, scenario, UI, library-hardening, benchmark, and soak gates remain explicit in the implementation plan.

Repository configuration

The storage-failure evidence 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 is preserved.

Phase 1–2 runtime

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

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:

npm run test:phase1

Run the Phase 2 common-grammar conformance suite with:

npm run test:phase2

Run the Phase 3 audio subsystem suite with:

npm run test:phase3

Run every suite with npm test.

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.

No sound has yet been heard from a build: the audio acceptance challenge, peak and finite-sample capture, and listening observations are open Phase 3 gates, and audio automation precedence, the lifecycle state machine, unlock behavior, voice ceilings, and master protection are Phase 3c contracts. 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:

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.