# 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.3; Phase 0 shared contracts complete, subsystem contracts in dependency order |
| [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 | Phase 0 complete; Phase 1 runtime skeleton ready |
| [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

Phase 0 is complete. Begin implementation with Phase 1 from the implementation plan, preserving the verified launch model and shared semantic contracts. Carry workload measurements and release soak tests as later explicit gates; they are not prerequisites for the runtime skeleton.

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.

Phase 0 is complete. All 10 direct-file checks in GC1 are verified, including worklet loading, full-browser restart persistence, offline behavior, and directory fallback. GC2 shared format/schema validation passes its 12-case matrix. Format Specification Revision 0.3 closes GC3 resolution, GC4 clock/PRNG, and GC5 ownership/failure contracts with deterministic executable traces; see the [combined evidence](docs/evidence/phase0/2026-09-05-gc3-gc5-contracts.md). The implementation plan schedules GC6 measurements and maps GC7 library/build verification. Phase 1 may begin; later production, browser/audio, benchmark, and soak gates remain explicit.

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

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