49 lines
4.6 KiB
Markdown
49 lines
4.6 KiB
Markdown
# 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.
|