From 05fe2b4e021ba86e4a290d05b63c7cae0e386128 Mon Sep 17 00:00:00 2001 From: Labyricorn Date: Fri, 4 Sep 2026 18:42:21 -0700 Subject: [PATCH] docs: establish XZBT 0.1 MVP planning baseline --- .env.example | 3 + .gitignore | 4 + README.md | 31 +- XZBT_0-1_MVP_Product_Requirements_Document.md | 4209 +++++++++++++++++ docs/XZBT_0-1_Format_Specification.md | 104 + docs/XZBT_0-1_Gap_Closure_Decisions.md | 109 + docs/XZBT_0-1_Verification_Gates.md | 123 + 7 files changed, 4582 insertions(+), 1 deletion(-) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 XZBT_0-1_MVP_Product_Requirements_Document.md create mode 100644 docs/XZBT_0-1_Format_Specification.md create mode 100644 docs/XZBT_0-1_Gap_Closure_Decisions.md create mode 100644 docs/XZBT_0-1_Verification_Gates.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..5ad37ae --- /dev/null +++ b/.env.example @@ -0,0 +1,3 @@ +repo=https://git.labyricorn.com/Labyricorn/XZBT +user=your-username +pass=your-access-token diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8a2a722 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +# Local repository configuration and credentials +.env +.env.* +!.env.example diff --git a/README.md b/README.md index c6c102e..7fd62c8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,32 @@ # XZBT -Immersive visuals and creative soundscapes. \ No newline at end of file +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.2; format version remains 0.1 | +| [Format Specification 0.1](docs/XZBT_0-1_Format_Specification.md) | Runtime semantics, contract inventory, and required authoring examples | Partial specification; identified contracts still require completion | +| [Gap Closure Decisions](docs/XZBT_0-1_Gap_Closure_Decisions.md) | Decisions and rationale for the seven pre-implementation gaps | Decisions incorporated for planning; feasibility is not yet verified | +| [Verification Gates](docs/XZBT_0-1_Verification_Gates.md) | Evidence required before architecture commitment, subsystem work, and release | All checks pending; no implementation results 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 + +Begin the implementation plan with Phase 0 from the verification gates. Complete the launch-model prototype and shared semantic contracts before committing dependent architecture and detailed estimates. Carry workload measurements and release soak tests as later explicit gates; they are not prerequisites for drafting a plan. + +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. + +No runtime, schema implementation, benchmark, or completed feasibility test is supplied by this documentation revision. + +## Repository configuration + +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. diff --git a/XZBT_0-1_MVP_Product_Requirements_Document.md b/XZBT_0-1_MVP_Product_Requirements_Document.md new file mode 100644 index 0000000..8e3c074 --- /dev/null +++ b/XZBT_0-1_MVP_Product_Requirements_Document.md @@ -0,0 +1,4209 @@ +# XZBT 0.1 MVP Product Requirements Document + +**Product:** XZBT +**Document version:** 0.2 +**XZBT format version:** 0.1 +**Status:** MVP specification +**Date:** September 4, 2026 + +**Revision 0.2:** Incorporates the seven gap-closure decisions from pre-implementation review. The XZBT format version and full MVP completion scope remain 0.1. Decisions are recorded; browser feasibility, conformance, performance, and soak verification remain pending. + +Companion resources: + +- [Planning resource index](README.md) +- [Format Specification 0.1](docs/XZBT_0-1_Format_Specification.md): shared runtime semantics and the incomplete contract register +- [Gap Closure Decisions](docs/XZBT_0-1_Gap_Closure_Decisions.md): numbered decisions and rationale +- [Verification Gates](docs/XZBT_0-1_Verification_Gates.md): Phase 0 prerequisites and later implementation/release evidence + +This PRD defines product scope and acceptance. The format specification defines exact runtime semantics where completed. Historical conversation proposals must be reconciled into these local documents before implementation. Unfinished contracts are explicit planning tasks, not permission to invent behavior silently. + +--- + +# 1. Executive Summary + +XZBT is a single-file, browser-based procedural visualization and sonification runtime. + +The runtime is distributed primarily as `XZBT.html`. Audiovisual experiences are defined in separate `.xzbt` files containing declarative JSON. These files are called **exhibits**. + +An exhibit describes what should exist, how it should behave, how it should sound, how it should respond to state and user configuration, and what longer-form events or scenarios may occur. XZBT itself contains the generic systems required to interpret those instructions. + +The architectural rule is: + +> **XZBT knows how. The exhibit defines what.** + +XZBT must not contain exhibit-specific concepts such as spacecraft, machines, forests, alarms, planets, rain, control rooms, stations, or other thematic subjects. Instead, it exposes reusable visual, audio, timing, state, modulation, and orchestration primitives from which those experiences can be constructed. + +The MVP must prove that one generic `XZBT.html` can load multiple radically different `.xzbt` exhibits and generate rich audiovisual experiences without modifying the runtime or embedding arbitrary JavaScript in the exhibit. + +--- + +# 2. Product Vision + +XZBT should function as a lightweight declarative audiovisual runtime that sits somewhere between procedural art software, an ambient display engine, an audiovisual scripting environment, and a configurable exhibit player. + +Potential uses include: + +- procedural visual art +- generative soundscapes +- ambient displays +- fictional environments +- tabletop and VTT backgrounds +- streaming backgrounds +- meditation and relaxation environments +- scientific visualization +- scientific sonification +- abstract dashboards +- educational displays +- installation art +- generative instrument displays +- simulated environments + +The runtime should remain content-neutral enough that an exhibit depicting an abstract particle field, a fictional machine room, rainfall, biological activity, a data visualization, or an animated geometric composition can all run through the same engine. + +--- + +# 3. Core Product Principles + +## 3.1 Declarative exhibits + +`.xzbt` files describe audiovisual behavior using JSON. + +They do not contain executable JavaScript. + +The runtime interprets the declaration. + +--- + +## 3.2 Generic engine, specific exhibit + +Subject-specific behavior belongs in `.xzbt`. + +Generic capability belongs in `XZBT.html`. + +If creating an ordinary new sound, visual effect, behavior, or scenario requires editing `XZBT.html`, the first question should be whether the engine is missing a generic primitive. + +--- + +## 3.3 Procedural by default + +XZBT 0.1 emphasizes runtime-generated content. + +The MVP should not depend on external images, audio recordings, video, or other media assets. + +This forces the 0.1 engine to prove that its procedural systems are genuinely expressive. + +--- + +## 3.4 Portable single-file runtime + +The canonical runtime remains a functional standalone HTML file. + +Opening `XZBT.html` directly in a supported desktop Chromium browser is the primary launch method. The delivered artifact must work without a server, installation, or network connection. Separate development source modules are built into that single artifact; direct-file operation must be tested independently of a development server. + +Primary distribution: + +```text +XZBT.html +ExhibitOne.xzbt +ExhibitTwo.xzbt +ExhibitThree.xzbt +``` + +The same runtime architecture must also support exhibits embedded directly into a standalone HTML document. + +--- + +## 3.5 Long-running stability + +XZBT is intended to remain active for long periods. + +Memory leaks, abandoned Web Audio nodes, uncontrolled timers, accumulating canvas objects, and persistent scenario resources are unacceptable. + +Every runtime subsystem must have explicit lifecycle and cleanup behavior. + +--- + +## 3.6 Controlled randomness + +Procedural variation should produce related performances rather than uncontrolled chaos. + +Random behavior should be: + +- bounded +- seedable +- reproducible when requested +- locally scoped +- distinct from continuously evolving modulation + +--- + +## 3.7 User configuration remains user-owned + +Scenarios and events may temporarily override user settings, but temporary behavior must not destructively rewrite the user's configuration. + +--- + +# 4. Terminology + +## XZBT + +The runtime and specification. + +## Exhibit + +A declarative audiovisual experience defined by a `.xzbt` document. + +## Runtime + +The executing `XZBT.html` application. + +## Parameter + +A user-configurable exhibit value. + +## State + +A mutable value owned by the simulation rather than directly by the user. + +## Signal + +A read-only runtime value such as elapsed time, audio energy, pointer position, or viewport size. + +## Component + +A reusable audio or visual subgraph. + +## Sound + +A named procedural audio recipe plus metadata. + +## Cadence + +The automatic scheduling policy used by the Sound Director. + +## Event + +A reusable named bundle of actions. + +## Scenario + +A finite declarative performance that orchestrates state, audio, visuals, events, and temporary overrides over time. + +## Binding + +A one-way relationship between a source value and a target property. + +## ValueSpec + +The common XZBT grammar for literal, referenced, random, selected, or calculated values. + +--- + +# 5. MVP Goal + +The MVP must prove the following statement: + +> **One generic HTML runtime can load declarative `.xzbt` documents and generate substantially different procedural audiovisual experiences without exhibit-specific JavaScript.** + +Success is measured primarily through working reference exhibits rather than the sheer number of features. + +--- + +# 6. MVP Non-Goals + +XZBT 0.1 does not need to provide: + +- graphical exhibit editor +- visual node editor +- DAW-style audio editor +- arbitrary JavaScript +- external plugins +- external audio samples +- external image assets +- video playback +- full 3D meshes +- WebGL-only content +- network access +- cloud accounts +- marketplace +- collaborative authoring +- MIDI +- OSC +- Streamer.bot integration +- multi-user synchronization +- DRM +- native desktop packaging +- mobile-native packaging +- automatic directory scanning without user authorization +- sophisticated publishing or storefront management + +These may be considered in later versions. + +--- + +# 7. Distribution Modes + +XZBT should ultimately support three related distribution models using the same runtime. + +## 7.1 Runtime/library mode + +```text +XZBT.html +*.xzbt +``` + +Users import one or more `.xzbt` files or a directory containing exhibits. + +This is the primary reusable XZBT application model. + +--- + +## 7.2 Embedded collection + +One HTML file contains several fixed embedded exhibit definitions. + +The user may switch among those exhibits, but cannot necessarily import arbitrary external exhibits unless that capability is enabled. + +This model is appropriate for free collections or curated products. + +--- + +## 7.3 Standalone exhibit + +One `.xzbt` exhibit is embedded into the runtime. + +Example: + +```text +ProceduralMachineRoom.html +``` + +The resulting file retains: + +- visualization +- sonification +- configuration +- cadence +- scenarios +- soundboard +- dynamic UI + +but presents itself as a dedicated exhibit rather than a general library player. + +Standalone packaging automation is not required for initial MVP completion, but the runtime architecture must allow it. + +--- + +# 8. MVP Runtime Architecture + +`XZBT.html` should contain the following major systems: + +1. Exhibit Loader +2. Library Manager +3. Schema Validator +4. Reference Validator +5. Value Resolver +6. Parameter Manager +7. State Manager +8. Signal Provider +9. Binding Engine +10. Audio Graph Engine +11. Audio Bus Manager +12. Sound Director +13. Visual Renderer +14. Visual System Manager +15. Event Engine +16. Scenario Director +17. Action Executor +18. Dynamic UI Renderer +19. Soundboard +20. Persistence Manager +21. Seeded Random Number Generator +22. Runtime Scheduler +23. Performance/Safety Manager +24. Diagnostics System + +The runtime should prefer centralized directors and schedulers over numerous independent browser timers. + +--- + +# 9. Canonical `.xzbt` Document Structure + +The canonical format is UTF-8 JSON. + +Top-level model: + +```json +{ + "xzbt": "0.1", + + "meta": {}, + "runtime": {}, + + "parameters": {}, + "ui": {}, + "state": {}, + + "components": { + "audio": {}, + "visual": {} + }, + + "visuals": {}, + "audio": {}, + + "sounds": {}, + "cadence": {}, + + "modulators": {}, + "bindings": [], + + "events": {}, + "scenarios": {} +} +``` + +Only `xzbt`, `meta.id`, and `meta.name` are structurally required for a valid document. + +A valid exhibit may technically do nothing. + +--- + +# 10. Document Versioning + +```json +{ + "xzbt": "0.1" +} +``` + +identifies the XZBT schema version. + +It is separate from the exhibit's own version: + +```json +{ + "meta": { + "id": "machine-study", + "name": "Machine Study", + "version": "1.4.2" + } +} +``` + +Future runtimes may support multiple XZBT schema versions. + +Unsupported schema versions must fail validation clearly rather than being interpreted approximately. + +--- + +# 11. Metadata + +Recommended metadata: + +```json +{ + "meta": { + "id": "machine-study", + "name": "Machine Study", + "version": "1.0.0", + "author": "Labyricorn", + "description": "Procedural machinery visualization and sonification.", + "license": "All Rights Reserved", + "tags": [ + "industrial", + "ambient", + "procedural" + ] + } +} +``` + +Required: + +- `id` +- `name` + +Optional: + +- `version` +- `author` +- `description` +- `license` +- `tags` + +Metadata does not contain runtime behavior. + +--- + +# 12. Identifier Rules + +IDs must follow: + +```text +^[a-z][a-z0-9_-]*$ +``` + +Valid examples: + +```text +particle-field +relay_click +storm-01 +machine-load +``` + +Invalid examples: + +```text +Particle Field +2storm +deep.bus +my/event +``` + +Dots are reserved for reference paths. + +--- + +# 13. Reference Model + +Canonical references use dot-separated paths: + +```text +parameters.activity +state.machine-load +modulators.slow-pulse +sounds.console-confirm +events.power-spike +visuals.systems.particles.opacity +audio.buses.deep.gain +``` + +All references must resolve during validation unless explicitly documented as runtime-generated namespaces. + +--- + +# 14. Runtime Configuration + +Initial runtime section: + +```json +{ + "runtime": { + "seed": "random" + } +} +``` + +or: + +```json +{ + "runtime": { + "seed": 12345 + } +} +``` + +A numeric seed must reproduce procedural decisions for the same runtime version and logical input sequence. Record the resolved numeric seed when `"random"` is requested. Isolate random streams for cadence, scenarios, visual systems, sound instances, and manual SAMPLE playback. Rendering frequency and manual sampling must not perturb unrelated choices. Pixel-identical rendering or sample-identical audio across devices is not promised; deterministic tests supply recorded or synthetic analysis signals where required. + +The exhibit may not disable engine safety systems. + +--- + +# 15. Parameter Model + +Parameters are user-owned values. + +Example: + +```json +{ + "parameters": { + "activity": { + "type": "number", + "default": 0.5, + "min": 0, + "max": 1, + "step": 0.01 + }, + + "dnr": { + "type": "number", + "default": 0, + "min": 0, + "max": 1 + }, + + "show-grid": { + "type": "boolean", + "default": true + }, + + "motion-mode": { + "type": "enum", + "values": [ + "still", + "drift", + "flow" + ], + "default": "drift" + } + } +} +``` + +Initial parameter types: + +```text +number +integer +boolean +string +enum +color +``` + +Scenario `set` actions may not directly mutate parameters. + +Temporary changes use `override`. + +--- + +# 16. State Model + +State is simulation-owned. + +Example: + +```json +{ + "state": { + "machine-load": { + "type": "number", + "initial": 0.3 + }, + + "warning-active": { + "type": "boolean", + "initial": false + }, + + "mode": { + "type": "string", + "initial": "normal" + } + } +} +``` + +State may be changed by actions. + +Persistent `set` changes remain after a scenario ends. + +Temporary scenario behavior should use an override rather than mutation. + +--- + +# 17. Runtime Signals + +Signals are provided by XZBT and are read-only. + +Initial signal namespace should include: + +```text +signals.time.elapsed +signals.time.delta + +signals.audio.low +signals.audio.mid +signals.audio.high +signals.audio.energy + +signals.pointer.x +signals.pointer.y + +signals.viewport.width +signals.viewport.height + +signals.scenario.active +``` + +Signals may be extended later without requiring exhibit structure changes. + +--- + +# 18. ValueSpec 0.1 + +A ValueSpec may be a literal: + +```json +440 +``` + +a reference: + +```json +{ + "ref": "parameters.activity" +} +``` + +a random range: + +```json +{ + "random": { + "min": 420, + "max": 470 + } +} +``` + +an integer random range: + +```json +{ + "random": { + "min": 2, + "max": 8, + "integer": true + } +} +``` + +a weighted selection: + +```json +{ + "choose": [ + { + "value": "sine", + "weight": 6 + }, + { + "value": "triangle", + "weight": 3 + }, + { + "value": "square", + "weight": 1 + } + ] +} +``` + +or a safe calculation: + +```json +{ + "op": "multiply", + "args": [ + { + "ref": "parameters.base-frequency" + }, + 2.01 + ] +} +``` + +Supported 0.1 numeric operators: + +```text +add +subtract +multiply +divide +min +max +clamp +abs +negate +round +floor +ceil +lerp +``` + +No arbitrary expressions, functions, callbacks, or JavaScript are permitted. + +--- + +# 19. Random Value Semantics + +Random and weighted-choice ValueSpecs are normally sampled when their containing runtime object is instantiated or invoked. + +They do not automatically change every rendering or audio frame. + +Continuous randomness belongs in modulators such as: + +```text +sample-hold +random-walk +noise +``` + +This distinction must remain consistent across audio, visuals, events, and scenarios. + +--- + +# 20. ConditionSpec 0.1 + +Basic comparisons: + +```text +eq +ne +gt +gte +lt +lte +``` + +Example: + +```json +{ + "op": "gt", + "left": { + "ref": "state.machine-load" + }, + "right": 0.8 +} +``` + +Logical composition: + +```json +{ + "and": [ + { + "op": "gt", + "left": { + "ref": "state.machine-load" + }, + "right": 0.7 + }, + { + "op": "eq", + "left": { + "ref": "state.warning-active" + }, + "right": false + } + ] +} +``` + +Supported logical operators: + +```text +and +or +not +``` + +--- + +# 21. DurationSpec and TimeSpec + +Canonical literal durations use one unit: + +```text +250ms +4s +2.5m +1.5h +``` + +Compound forms such as: + +```text +1h30m +``` + +are not part of 0.1. + +Internally all durations are normalized to milliseconds. + +Where procedural timing is permitted, TimeSpec may contain a bounded random duration: + +```json +{ + "random": { + "min": "20s", + "max": "50s" + } +} +``` + +--- + +# 22. Action Model 0.1 + +Supported actions: + +```text +set +override +sound +event +spawn +remove +control +``` + +Common optional properties: + +```text +id +when +chance +critical +``` + +Actions in an array execute in document order during the same scheduler cycle. + +Later actions observe earlier state changes. + +--- + +# 23. `set` Action + +Changes simulation state. + +```json +{ + "type": "set", + "target": "state.machine-load", + "value": 0.9 +} +``` + +`set` may target state but not user parameters. + +Numeric changes may include transitions. + +--- + +# 24. `override` Action + +Temporarily changes a resolved value without mutating its underlying source. + +```json +{ + "type": "override", + "target": "parameters.activity", + "value": 0.9, + "scope": "scenario" +} +``` + +Supported scopes: + +```text +scenario +duration +``` + +Duration example: + +```json +{ + "type": "override", + "target": "audio.buses.deep.gain", + "value": 0.25, + "scope": "duration", + "duration": "12s" +} +``` + +--- + +# 25. TransitionSpec + +Basic numeric transition: + +```json +{ + "duration": "8s", + "easing": "ease-in-out" +} +``` + +Scenario override transitions may use: + +```json +{ + "in": "30s", + "out": "1m", + "easing": "ease-in-out" +} +``` + +Supported easing: + +```text +linear +ease-in +ease-out +ease-in-out +``` + +--- + +# 26. Sound Action + +```json +{ + "type": "sound", + "sound": "console-confirm" +} +``` + +Inputs: + +```json +{ + "type": "sound", + "sound": "warning-tone", + "with": { + "pitch": 880, + "intensity": 0.8 + } +} +``` + +Continuous sounds invoked by scenarios may specify ownership. + +--- + +# 27. Event Action + +```json +{ + "type": "event", + "event": "minor-disturbance" +} +``` + +Events reuse Action Model 0.1. + +--- + +# 28. Spawn and Remove + +Spawn: + +```json +{ + "type": "spawn", + "target": "visuals.systems.energy-pulse", + "with": { + "intensity": 0.8 + }, + "lifetime": "8s" +} +``` + +Remove: + +```json +{ + "type": "remove", + "target": "instances.warning-glow" +} +``` + +Runtime-generated instance IDs occupy the `instances.*` namespace. + +--- + +# 29. Control Action + +```json +{ + "type": "control", + "target": "visuals.systems.traffic", + "command": "disable" +} +``` + +Initial commands: + +```text +start +stop +enable +disable +pause +resume +reset +``` + +Not every command is valid for every target. + +Unsupported combinations are validation or runtime errors. + +--- + +# 30. Critical Actions + +```json +{ + "type": "event", + "event": "primary-failure", + "critical": true +} +``` + +Default: + +```text +critical = false +``` + +Failure of a noncritical action is logged and execution continues. + +Failure of a critical action propagates to the containing event or scenario. + +--- + +# 31. Value Resolution Precedence + +XZBT must preserve underlying values rather than destructively replacing them. + +Resolution order for each target, using only stages supported by its contract: + +```text +BASE VALUE + ↓ +BINDING + ↓ +AUTOMATION + ↓ +WINNING OVERRIDE + ↓ +MODULATION + ↓ +SAFETY CLAMP + ↓ +RESOLVED RUNTIME VALUE +``` + +Parameters store user configuration separately from exhibit defaults. State stores simulation values separately from parameters; it is not an implicit layer above all user values. References ordinarily read resolved values. Configuration controls read and edit stored user parameters and indicate active overrides. + +Where multiple overrides compete for one target: + +1. highest explicit or inherited priority wins +2. if priorities tie, most recently activated override wins + +Scope determines lifetime, not precedence. Duration overrides do not automatically outrank scenario overrides. Bindings and automation continue evaluating while masked. A release transition approaches the currently resolved lower value, including user changes made during the override, rather than a stale snapshot. + +Reject conflicting ordinary bindings and unsupported dependency cycles. Exact target capabilities, priority defaults, smoothing, and interrupted transition rules must be completed in the [format specification](docs/XZBT_0-1_Format_Specification.md) before resolver implementation. + +--- + +# 32. Binding Model 0.1 + +Bindings are one-way. + +Example: + +```json +{ + "source": "parameters.activity", + "target": "visuals.systems.particles.activity" +} +``` + +Optional transformation: + +```json +{ + "source": "state.machine-load", + "target": "audio.buses.deep.gain", + "scale": 0.5, + "offset": 0.5, + "clamp": [ + 0, + 1 + ], + "smoothing": "50ms" +} +``` + +Binding fields: + +```text +source +target +scale +offset +clamp +smoothing +when +``` + +Defaults: + +```text +scale = 1 +offset = 0 +smoothing = engine default +``` + +Numeric transformation: + +```text +output = +clamp( + source × scale + offset +) +``` + +Multiple ordinary bindings may not independently write the same scalar target in 0.1 unless that target explicitly supports additive input. + +This avoids ambiguous precedence. + +--- + +# 33. Modulators + +Reusable evolving values live under: + +```json +{ + "modulators": { + "slow-breath": { + "type": "lfo", + "waveform": "sine", + "frequency": 0.04, + "min": 0.75, + "max": 1 + }, + + "machine-jitter": { + "type": "random-walk", + "rate": 0.7, + "min": -0.1, + "max": 0.1 + } + } +} +``` + +Core runtime modulators should include at least: + +```text +lfo +random-walk +sample-hold +noise +``` + +Visual and general modulators are distinct from audio graph control nodes even when they share mathematical behavior. + +--- + +# 34. Audio Architecture + +Audio consists of: + +```text +Audio primitives + ↓ +Audio graphs + ↓ +Reusable components + ↓ +Sound recipes + ↓ +Sound instances + ↓ +Declared buses + ↓ +Bus processing + ↓ +Engine master protection + ↓ +Output +``` + +Sound-specific meaning exists only in the exhibit. + +XZBT should never implement functions named after thematic sounds. + +--- + +# 35. Audio Units + +Canonical units: + +| Quantity | Unit | +|---|---| +| frequency | Hz | +| detune | cents | +| gain/amplitude | linear scalar | +| filter/compressor gain | dB | +| pan | -1 to +1 | +| normalized controls | 0 to 1 | +| Q | unitless | +| time | DurationSpec | +| modulation depth | target property's unit | + +Maximum useful audio frequency: + +```text +min(24000 Hz, sampleRate × 0.45) +``` + +--- + +# 36. Audio Graph Node Set 0.1 + +## Sources + +```text +oscillator +noise +impulse +``` + +## Control sources + +```text +constant +lfo +sample-hold +``` + +## Processing + +```text +gain +filter +compressor +waveshaper +delay +reverb +stereo-pan +resonator +``` + +## Routing + +```text +mixer +``` + +--- + +# 37. Oscillator Contract + +```json +{ + "type": "oscillator", + "waveform": "sine", + "frequency": 440, + "detune": 0 +} +``` + +Waveforms: + +```text +sine +triangle +square +sawtooth +custom +``` + +Frequency: + +```text +0.1 Hz to runtime maximum +default 440 Hz +``` + +Detune: + +```text +-4800 to +4800 cents +default 0 +``` + +Custom waveforms may specify up to 64 harmonic partials. + +--- + +# 38. Noise Contract + +```json +{ + "type": "noise", + "color": "pink" +} +``` + +Supported: + +```text +white +pink +brown +``` + +Default: + +```text +white +``` + +Noise sources do not contain their own volume control. Use `gain`. + +--- + +# 39. Impulse Contract + +```json +{ + "type": "impulse", + "color": "white", + "duration": "10ms", + "amplitude": 1, + "decay": "exponential" +} +``` + +Duration: + +```text +1ms to 500ms +``` + +Amplitude: + +```text +0 to 1 +``` + +Decay: + +```text +flat +linear +exponential +``` + +--- + +# 40. Constant Contract + +Control-only source. + +```json +{ + "type": "constant", + "value": 1 +} +``` + +Range: + +```text +-1000 to 1000 +``` + +It may modulate numeric properties but may not route to audible output. + +--- + +# 41. LFO Contract + +```json +{ + "type": "lfo", + "waveform": "sine", + "frequency": 1, + "amplitude": 1, + "polarity": "bipolar" +} +``` + +Frequency: + +```text +0.001 to 40 Hz +``` + +Polarity: + +```text +bipolar +unipolar +``` + +LFO is control-only. + +Audio-rate modulation uses an ordinary oscillator. + +--- + +# 42. Sample-Hold Contract + +```json +{ + "type": "sample-hold", + "rate": 2, + "min": -1, + "max": 1, + "slew": "0ms" +} +``` + +Rate: + +```text +0.01 to 100 Hz +``` + +Slew: + +```text +0 to 1s +``` + +Sample-hold is control-only. + +--- + +# 43. Gain Contract + +```json +{ + "type": "gain", + "gain": 1 +} +``` + +Range: + +```text +0 to 4 +``` + +Values above 1 are permitted for synthesis workflows but remain subject to master safety protection. + +--- + +# 44. Filter Contract + +Modes: + +```text +lowpass +highpass +bandpass +notch +peaking +lowshelf +highshelf +allpass +``` + +Properties: + +```text +frequency: 10 Hz to runtime maximum +q: 0.0001 to 100 +gain: -40 to +40 dB +detune: -4800 to +4800 cents +``` + +--- + +# 45. Compressor Contract + +Properties: + +```text +threshold: -100 to 0 dB +knee: 0 to 40 dB +ratio: 1 to 20 +attack: 0 to 1s +release: 10ms to 1s +``` + +Audio-rate modulation of compressor parameters is not required in 0.1. + +--- + +# 46. Waveshaper Contract + +Shapes: + +```text +soft-clip +hard-clip +saturation +``` + +Amount: + +```text +0 to 1 +``` + +Oversampling: + +```text +none +2x +4x +``` + +--- + +# 47. Delay Contract + +```json +{ + "type": "delay", + "time": "250ms", + "feedback": 0.2, + "mix": 0.5 +} +``` + +Ranges: + +```text +time: 0 to 10s +feedback: 0 to 0.95 +mix: 0 to 1 +``` + +Feedback is internally controlled by XZBT. + +Authors may not create unrestricted graph feedback loops. + +--- + +# 48. Reverb Contract + +```json +{ + "type": "reverb", + "size": 0.5, + "decay": "2s", + "damping": 0.5, + "predelay": "0ms", + "mix": 0.25 +} +``` + +Ranges: + +```text +size: 0 to 1 +decay: 50ms to 30s +damping: 0 to 1 +predelay: 0 to 500ms +mix: 0 to 1 +``` + +Implementation is runtime-defined. + +The exhibit describes desired acoustic behavior, not Web Audio implementation details. + +--- + +# 49. Stereo Pan Contract + +```text +-1 = full left +0 = center ++1 = full right +``` + +--- + +# 50. Mixer Contract + +A mixer accepts multiple audio inputs and exposes one audio output. + +It has no gain controls in 0.1. + +Gain staging uses explicit `gain` nodes. + +--- + +# 51. Resonator Contract + +```json +{ + "type": "resonator", + "fundamental": 120, + "modes": [ + { + "ratio": 1, + "gain": 1, + "decay": "1.2s" + }, + { + "ratio": 2.7, + "gain": 0.4, + "decay": "800ms" + } + ], + "mix": 1 +} +``` + +Maximum modes: + +```text +16 +``` + +Each mode specifies either: + +```text +frequency +``` + +or: + +```text +ratio +``` + +but not both. + +Resonator exists to provide generic acoustic resonance, not a themed sound. + +--- + +# 52. Audio Routing + +Audio connection: + +```json +{ + "from": "tone", + "to": "filter" +} +``` + +Parameter modulation: + +```json +{ + "from": "vibrato", + "to": "tone.frequency", + "depth": 18 +} +``` + +Routing to a node ID means audio routing. + +Routing to `node.property` means modulation. + +--- + +# 53. Audio Modulation Semantics + +Modulation depth uses the target parameter's unit. + +Example: + +```text +frequency target → depth in Hz +detune target → depth in cents +gain target → depth in linear gain +pan target → depth in pan units +``` + +Multiple legal modulation routes are summed. + +--- + +# 54. Audio Automation Precedence + +Numeric audio resolution: + +```text +BASE ValueSpec + ↓ +BINDING (where supported) + ↓ +AUTOMATION + ↓ +WINNING OVERRIDE + ↓ +MODULATION SUM + ↓ +SAFETY CLAMP + ↓ +ENGINE PARAMETER +``` + +Automation modes: + +```text +absolute +offset +scale +``` + +Interpolation: + +```text +step +linear +exponential +smooth +``` + +Only one automation track may directly control a property in a recipe instance. + +This is the audio application of section 31, not a separate competing precedence system. Underlying automation continues while overridden. Modulation and all other stages are permitted only where the target contract supports them. + +--- + +# 55. Audio Graph Legality + +The final expanded audio graph must satisfy: + +- unique node IDs +- all references resolve +- `output` is reserved +- `output` is sink-only +- control sources cannot enter audible routing +- invalid source inputs are prohibited +- ordinary audio graph is acyclic +- unrestricted feedback is prohibited +- modulation dependency cycles are prohibited +- at least one audible path reaches output +- component recursion is prohibited +- graph limits are respected + +--- + +# 56. Audio Components + +Reusable components live in: + +```text +components.audio.* +``` + +Components may declare: + +- inputs +- internal nodes +- internal routing +- automation +- exposed parameters +- optional audio input +- audio output + +Component instances are encapsulated. + +External graphs may access only: + +- component input +- component output +- explicitly exposed parameters + +Component nesting limit: + +```text +8 levels +``` + +--- + +# 57. Audio Lifecycle + +Runtime states: + +```text +CREATED +SCHEDULED +ACTIVE +RELEASING +FINISHED +DISPOSED +FAILED +``` + +Recipe modes: + +```text +oneshot +continuous +``` + +One-shots must have a determinable ending. + +Continuous sounds run until explicitly stopped. + +Default release: + +```text +50ms +``` + +XZBT must provide an internal release gain even when the exhibit did not author one. + +Finished sounds must release nodes, connections, automation, buffers, and subscriptions. + +--- + +# 58. Audio Safety Limits + +Initial target limits: + +```text +expanded nodes per sound: 128 +routes per sound: 256 +automation tracks: 64 +automation points: 256 +component nesting depth: 8 +resonator modes: 16 +approximate one-shot voices: 64 +approximate continuous sounds: 16 +``` + +Actual active voice ceilings may be runtime/device dependent. + +Every audible signal passes through engine-controlled master protection. + +The exhibit cannot bypass it. + +Before audio acceptance, specify the digital output peak ceiling, numerical tolerance, release behavior, and finite-sample handling. Verify worst-case overlapping recipes and audible release artifacts. These settings are pending measurement under verification gate GC6; the presence of a compressor alone does not establish that the protection contract passes. + +--- + +# 59. Sound Definition + +A sound separates semantic metadata from synthesis: + +```json +{ + "sounds": { + "relay-click": { + "name": "Relay Click", + "tags": [ + "mechanical", + "electrical" + ], + "usage": [ + "automatic", + "manual", + "scenario" + ], + "cadence": { + "class": "routine" + }, + "bus": "effects", + "recipe": {} + } + } +} +``` + +--- + +# 60. Audio Buses + +Example: + +```json +{ + "audio": { + "buses": { + "ambient": { + "gain": 1 + }, + "effects": { + "gain": 1 + }, + "deep": { + "gain": 1 + }, + "alerts": { + "gain": 1 + } + } + } +} +``` + +`master` is engine-provided. + +Potential bus processing includes filters, gain, compression, and other generic processors supported by the engine. + +--- + +# 61. Cadence Classes + +Canonical classes: + +```text +ambient +routine +intermittent +occasional +rare +scenario +``` + +Meaning: + +- `ambient`: persistent automatically maintained audio +- `routine`: normal frequent automatic activity +- `intermittent`: recurring activity with noticeable gaps +- `occasional`: infrequent noticeable activity +- `rare`: unusual activity +- `scenario`: never selected by the automatic cadence scheduler + +--- + +# 62. Usage and Cadence Separation + +Usage values: + +```text +automatic +manual +scenario +``` + +`usage` determines which invocation systems may call the sound. + +`cadence` determines automatic scheduling behavior. + +Manual soundboard SAMPLE behavior is separate from actual runtime sound actions. + +--- + +# 63. Default Cadence Intervals + +Engine defaults: + +```text +routine: +10s to 45s + +intermittent: +45s to 4m + +occasional: +3m to 15m + +rare: +15m to 60m +``` + +Exhibits may override these ranges. + +Each automatic class uses its own independent scheduler. + +--- + +# 64. Cadence Selection + +At each class firing: + +1. determine eligible sounds +2. remove cooldown-blocked sounds +3. enforce overlap policy +4. apply base weight +5. apply anti-repetition modifier +6. choose weighted random sound +7. start sound +8. update history +9. schedule next class interval + +--- + +# 65. Cadence Anti-Repetition + +Default history depth: + +```text +4 +``` + +Suggested multipliers: + +```text +immediately previous: 0 +2 selections ago: 0.25 +3 selections ago: 0.5 +4 selections ago: 0.75 +older: 1 +``` + +History penalties must relax if the pool would otherwise become unusable. + +--- + +# 66. Cadence Intensity + +Exhibit-wide automatic activity: + +```json +{ + "cadence": { + "intensity": { + "ref": "parameters.activity" + } + } +} +``` + +Range: + +```text +0 to 1 +``` + +Effective interval: + +```text +base interval / intensity +``` + +At zero, automatic one-shot scheduling stops. + +Ambient sounds are unaffected unless explicitly bound to the parameter. + +--- + +# 67. Minimum Automatic Gap + +Default: + +```text +1.5s +``` + +If multiple classes become due simultaneously, priority is: + +```text +rare +occasional +intermittent +routine +``` + +Deferred classes retain their opportunity. + +--- + +# 68. Manual SAMPLE Semantics + +Soundboard SAMPLE playback: + +- does not advance cadence clocks +- does not alter cooldown +- does not alter recency history +- does not affect automatic weighting +- does not count as actual exhibit activity + +A real user-triggered exhibit sound should use a normal `sound` Action. + +--- + +# 69. Visual Architecture + +Visual composition: + +```text +PRIMITIVES + ↓ +COMPONENTS + ↓ +PROCEDURAL SYSTEMS + ↓ +LAYERS + ↓ +CAMERA + ↓ +POST EFFECTS + ↓ +DISPLAY +``` + +The schema should remain renderer-neutral. + +XZBT 0.1 should primarily use Canvas 2D. + +--- + +# 70. Scene Model + +Example: + +```json +{ + "scene": { + "coordinateSpace": "virtual", + "width": 1600, + "height": 900, + "fit": "contain", + "background": "#020308" + } +} +``` + +Coordinate modes: + +```text +normalized +viewport +virtual +``` + +Fit modes: + +```text +contain +cover +stretch +``` + +--- + +# 71. Visual Depth + +XZBT 0.1 should support 2.5D depth through optional `z`. + +It does not require full 3D meshes or a full 3D lighting system. + +Depth should support: + +- parallax +- perspective scaling +- depth sorting +- approach/recede effects +- depth-sensitive fogging where supported + +--- + +# 72. Visual Geometry Primitives + +XZBT 0.1 should support: + +```text +point +line +polyline +polygon +rectangle +rounded-rectangle +ellipse +arc +ring +path +bezier +spline +text +group +``` + +No semantic objects such as planet, tree, ship, or machine are runtime primitives. + +--- + +# 73. Common Visual Properties + +Where applicable: + +```text +position +size +transform +style +behaviors +visible +lifetime +layer +depth +``` + +Numeric fields may accept ValueSpecs. + +--- + +# 74. Visual Transform Model + +Common transforms: + +```text +translate x/y/z +rotation +scale x/y +skew x/y +origin x/y +``` + +Transforms should be hierarchical when applied to groups. + +--- + +# 75. Visual Appearance + +Supported appearance features: + +- solid fill +- linear gradient +- radial gradient +- conic gradient where available +- stroke +- opacity +- glow +- shadow +- blur +- filters +- masks +- clipping +- blend modes + +Safe blend set: + +```text +normal +add +screen +multiply +overlay +lighten +darken +difference +``` + +--- + +# 76. Paths and Splines + +Path commands: + +```text +move +line +quadratic +cubic +arc +close +``` + +Spline modes: + +```text +catmull-rom +bezier +linear +``` + +Spline points must be independently mutable so behaviors such as slow point wandering and morphing can create evolving organic geometry. + +--- + +# 77. Visual Components + +Reusable visual components live in: + +```text +components.visual.* +``` + +A component may combine primitives, groups, styles, transforms, and behaviors. + +Components may declare inputs. + +Procedural systems and spawn actions may instantiate components with different input values. + +--- + +# 78. Particle Systems + +Particle systems should support: + +```text +count +position +velocity +acceleration +drag +lifetime +age +size +rotation +opacity +color +depth +trail +``` + +Particle properties may use ValueSpecs. + +--- + +# 79. Placement Distributions + +Supported initial distributions: + +```text +point +uniform +line +rectangle +ellipse +ring +path +grid +depth +``` + +These may be used by particles, repeaters, and other systems. + +--- + +# 80. Emitters + +Emitters create objects over time. + +Typical properties: + +```text +rate +component +position +distribution +velocity +lifetime +inputs +``` + +Emitters should support procedural bursts as well as continuous generation. + +--- + +# 81. Repeaters + +Repeaters create persistent copies of a component. + +Use cases include: + +- panel arrays +- building-like structures +- instrument grids +- repeating indicators +- abstract cells +- windows +- machinery patterns + +--- + +# 82. Visual Behaviors + +Initial behavior vocabulary: + +```text +drift +rotate +oscillate +orbit +wander +follow-path +point-wander +pulse +twinkle +noise-displace +face-motion +wrap +bounce +attract +repel +field-follow +morph +``` + +Behaviors remain generic and subject-neutral. + +--- + +# 83. Procedural Fields + +Supported field types: + +```text +directional +radial +vortex +attractor +repulsor +noise +``` + +Noise fields should support seeded coherent noise with configurable: + +```text +scale +speed +octaves +persistence +``` + +Other systems may follow or react to fields. + +--- + +# 84. Trails, Ribbons, and Links + +Trail systems should support historical position rendering and fading. + +Ribbon systems should render a continuous strip or path based on movement history. + +Link systems connect items based on generic rules such as: + +```text +distance +nearest +index +``` + +At minimum, 0.1 requires distance-based links. + +--- + +# 85. Visual Automation + +Visual automation uses: + +```text +step +linear +exponential +smooth +``` + +where applicable. + +Automation may target numeric properties. + +Loop modes: + +```text +repeat +ping-pong +``` + +Loop count may be finite or infinite for persistent visual behavior. + +--- + +# 86. Visual Lifecycle + +Visual systems may be: + +```text +persistent +spawned +``` + +Spawned systems may define: + +```text +lifetime +ownership +inputs +cancelWithScenario +``` + +Scenario-owned persistent visuals are removed or released during scenario cleanup. + +--- + +# 87. Camera + +Camera properties should include: + +```text +x +y +zoom +rotation +projection +focalLength +``` + +Projection modes: + +```text +orthographic +perspective +``` + +Camera properties may be automated or bound to state/modulators. + +--- + +# 88. Post-Processing + +Initial post-effect vocabulary: + +```text +vignette +scanlines +grain +color-adjust +blur +bloom +fade +``` + +Post-effects must be performance constrained. + +The runtime may approximate effects differently depending on renderer capabilities. + +--- + +# 89. Visual Safety Limits + +Runtime-controlled limits should cover: + +- active particles +- emission rate +- active spawned systems +- path points +- spline points +- repeater instances +- nested groups +- link count +- trail history +- blur radius +- post-processing passes +- rendering resolution +- animation records + +Clearly excessive values should normally fail validation rather than be silently transformed into something materially different. + +--- + +# 90. Event Model 0.1 + +Events are reusable named bundles of actions. + +Example: + +```json +{ + "events": { + "minor-disturbance": { + "inputs": { + "intensity": { + "type": "number", + "default": 0.5 + } + }, + + "actions": [ + { + "type": "sound", + "sound": "relay-click" + } + ] + } + } +} +``` + +Events may accept inputs. + +Event invocation: + +```json +{ + "type": "event", + "event": "minor-disturbance", + "with": { + "intensity": 0.8 + } +} +``` + +Inside the event: + +```text +inputs.intensity +``` + +is available. + +--- + +# 91. Event Semantics + +Events: + +- execute actions in order +- may invoke other events +- emit an event notification when invoked +- may trigger event-based scenarios +- do not return values in 0.1 +- may not recursively invoke themselves +- may not participate in cyclic event dependency graphs + +Maximum event nesting depth: + +```text +16 +``` + +Event completion occurs when its immediate action dispatch is complete. + +Long-running behavior belongs in audio, visuals, or scenarios. + +Nested events inherit the invoking action's ownership context. Event-to-event acyclicity alone is insufficient: validate event/scenario trigger feedback where detectable and enforce a per-update dispatch budget with diagnostics. Budget exhaustion must not prevent cleanup. + +--- + +# 92. Scenario Model 0.1 + +Scenarios are finite declarative performances. + +Structure: + +```json +{ + "scenarios": { + "power-disturbance": { + "name": "Power Disturbance", + "enabled": true, + "priority": 70, + "group": "major-events", + "trigger": {}, + "eligibility": {}, + "concurrency": {}, + "cooldown": "30m", + "duration": "12m", + "onStart": [], + "timeline": [], + "onComplete": [], + "onCancel": [], + "tags": [] + } + } +} +``` + +--- + +# 93. Scenario Lifecycle + +```text +DEFINED +ELIGIBLE +SCHEDULED +STARTING +ACTIVE +COMPLETING +COMPLETED +``` + +Alternative termination: + +```text +CANCELLING +CANCELLED +FAILED +``` + +Scenario instances own their temporary resources and cleanup obligations. + +--- + +# 94. Scenario Triggers + +Condition triggers fire once after the qualifying hold interval and require the condition to become false before rearming after a firing. + +Supported: + +```text +manual +once +interval +random-interval +probability +condition +event +``` + +Examples: + +```json +{ + "type": "random-interval", + "min": "30m", + "max": "2h" +} +``` + +```json +{ + "type": "probability", + "every": "10m", + "chance": 0.15 +} +``` + +```json +{ + "type": "condition", + "when": {}, + "for": "20s" +} +``` + +--- + +# 95. Scenario Eligibility + +Trigger means: + +> A start opportunity exists. + +Eligibility means: + +> The scenario is currently permitted to start. + +Example: + +```json +{ + "eligibility": { + "when": { + "op": "eq", + "left": { + "ref": "state.mode" + }, + "right": "normal" + }, + "timeout": "5m" + } +} +``` + +--- + +# 96. Scenario Timeline + +Absolute: + +```json +{ + "id": "warning", + "at": "2m", + "actions": [] +} +``` + +Relative: + +```json +{ + "after": "warning", + "delay": "30s", + "actions": [] +} +``` + +Random relative timing: + +```json +{ + "after": "warning", + "delay": { + "random": { + "min": "20s", + "max": "50s" + } + }, + "actions": [] +} +``` + +Timeline entries execute in non-decreasing time order. + +Entries at the same time execute in document order. + +--- + +# 97. Scenario Branching + +A timeline entry may choose among weighted branches: + +```json +{ + "at": "5m", + "choose": [ + { + "weight": 3, + "actions": [ + { + "type": "event", + "event": "minor-failure" + } + ] + }, + { + "weight": 1, + "actions": [ + { + "type": "event", + "event": "major-failure" + } + ] + } + ] +} +``` + +An entry may contain `actions` or `choose`, not both. + +--- + +# 98. Scenario Repeated Beats + +```json +{ + "at": "1m", + "repeat": { + "count": 5, + "every": "20s" + }, + "actions": [] +} +``` + +Random repeated interval: + +```json +{ + "repeat": { + "count": 5, + "every": { + "random": { + "min": "15s", + "max": "30s" + } + } + } +} +``` + +No unrestricted loop, goto, or arbitrary flow-control language exists in 0.1. + +--- + +# 99. Scenario Priority and Concurrency + +Priority range: + +```text +0 to 100 +``` + +Default: + +```text +50 +``` + +Concurrency: + +```text +parallel +exclusive +``` + +Exclusive scope: + +```text +group +global +``` + +Conflict policies: + +```text +defer +reject +replace +``` + +`replace` requires higher priority than the scenario being replaced. + +Each scenario definition may have at most one pending deferred start request. Requests expire and recheck eligibility at dispatch. Exact expiry defaults and queue ordering are required format contracts before implementation. + +--- + +# 100. Scenario Ownership + +Scenario-created resources may be: + +```text +scenario +persistent +``` + +Default for continuous sounds and persistent spawned visuals started by scenarios: + +```text +scenario +``` + +Scenario-owned resources are cleaned automatically when the scenario finishes or is cancelled. + +Ownership propagates through nested events and indirect resource creation. Persistent ownership must be explicitly requested and supported by the resource contract. Scenario-created duration overrides expire at their deadline or when the owner terminates, whichever occurs first, apart from bounded release cleanup. + +Persistent state changes are not reverted unless explicitly changed. + +This also applies after critical failure: scenarios are not transactions and prior `set` mutations are not rolled back. + +--- + +# 101. Scenario Cleanup + +When a scenario ends, XZBT must: + +- cancel future timeline entries +- cancel pending repeats +- cancel pending relative actions +- remove scenario-scoped overrides +- release scenario-owned continuous audio +- remove scenario-owned persistent visual systems +- clear subscriptions +- clear scheduler records +- release references to runtime objects + +A scenario must be safe to run repeatedly during multi-hour sessions. + +Termination first stops ordinary dispatch and cancels future work, then runs the applicable termination hook and guarantees cleanup even if that hook fails. A bounded cleanup owner may finish release fades before disposal. Hook ordering, allowed hook actions, and cleanup deadlines must be finalized in the format contract; this requirement does not introduce an undeclared failure-hook field. + +--- + +# 102. Scenario Scheduling Architecture + +Scenario Director must use: + +```text +elapsed scenario active time ++ +ordered timeline cursor +``` + +It must not implement long scenarios as thousands of unrelated `setTimeout()` calls. + +The runtime uses a shared logical simulation clock, initially stepping at 1/60 second, independently of rendering. Audio scheduling maps logical time to the audio clock with a bounded scheduling horizon. Tick ordering, long-stall handling, and audio synchronization are explicit contracts to complete under GC4. + +Required in 0.1: + +```text +pause +resume +accelerated testing +``` + +Future inspection capabilities: + +```text +timeline inspection +developer seeking +``` + +Inspection and seeking need not be user-facing in MVP. Pause/resume and accelerated testing are required by the corresponding acceptance criteria. + +--- + +# 103. Dynamic UI Model 0.1 + +The exhibit describes required controls. + +XZBT controls their appearance. + +Example: + +```json +{ + "ui": { + "groups": [ + { + "id": "environment", + "label": "Environment", + "controls": [ + { + "parameter": "activity", + "label": "Activity", + "widget": "slider" + } + ] + } + ] + } +} +``` + +Supported control types: + +```text +slider +number +toggle +select +text +color +button +scenario +``` + +--- + +# 104. UI Control Contract + +Common fields: + +```text +parameter +label +description +widget +order +visibleWhen +disabledWhen +``` + +`visibleWhen` and `disabledWhen` use ConditionSpec. + +Parameter controls show and edit stored user values rather than overwriting them with resolved scenario values. Indicate when an override is active. + +The UI may not contain raw exhibit-authored HTML. + +--- + +# 105. UI Groups + +Controls should be organized into authored groups. + +Example: + +```text +Environment +Audio +Motion +Display +Scenarios +``` + +Group visibility may also use ConditionSpec. + +Empty groups are hidden. + +--- + +# 106. Scenario UI + +The UI schema may expose scenarios with controls such as: + +```text +START +CANCEL +``` + +The runtime should display status for active scenarios. + +Scenario UI does not alter Scenario Model semantics. + +--- + +# 107. Soundboard + +The configuration page should include a soundboard when sounds permit manual sampling. + +Sounds should be grouped primarily by cadence: + +```text +Ambient +Routine +Intermittent +Occasional +Rare +Scenario +``` + +The action label should be: + +```text +SAMPLE +``` + +not: + +```text +TRIGGER +``` + +Sampling does not affect runtime cadence. + +Sounds may also show their semantic tags. + +Empty cadence groups are hidden. + +--- + +# 108. Exhibit Selection UI + +The main application must provide an exhibit library. + +Selecting an exhibit: + +1. validates and prepares the selected exhibit without starting audible or visible activity +2. retains the current exhibit if validation or preparation fails +3. shuts down the current exhibit safely and releases its audio, visual, and scenario resources +4. activates the selected exhibit with compatible saved parameters +5. rebuilds configuration UI, starts ambient systems, schedules cadence, and renders +6. if activation fails, disposes of the candidate and attempts to restart the previous exhibit with saved configuration + +Recovery starts a fresh performance; it does not promise restoration of the previous scenario clock. Report failure if recovery also fails. + +No full page reload should be required. + +--- + +# 109. Library Import + +The reusable XZBT application should support: + +```text +IMPORT LIBRARY +IMPORT FILES +REFRESH SOURCE +``` + +Primary library import should allow a user to choose a directory where supported. + +Fallbacks: + +- multiple `.xzbt` file picker +- drag and drop + +The user must explicitly initiate filesystem access. + +Identical imports are no-ops. Changed content with an existing exhibit ID requires an explicit replacement choice. Invalid imports or source refreshes must preserve the last valid cached exhibit and its configuration. Exact content-equality rules are specified before library implementation. + +--- + +# 110. Persistence + +XZBT should cache imported exhibit JSON locally. + +Persisted data should include: + +- exhibit definitions +- exhibit metadata +- source information where available +- last selected exhibit +- user parameters per exhibit +- master volume +- basic UI preferences + +Scheduler clocks should not persist across application restarts. + +Each launch begins a fresh procedural performance. + +Use IndexedDB for the local cache and verify restoration after fully closing and reopening the browser at the same supported direct-file launch location. Remembered source handles are optional enhancements, not prerequisites for startup. + +If storage is unavailable, allow session playback and explain that exhibits must be imported again on a later launch. This fallback does not waive normal-mode persistence acceptance. Moving or renaming the HTML is a separate compatibility test; cached data following the file is not guaranteed. See GC1 before committing the deployment architecture. + +--- + +# 111. Remembered Source Handles + +Where browser support permits, XZBT may persist a previously selected file or directory handle. + +The local exhibit cache remains authoritative for immediate startup. + +Refreshing the source should be a distinct user action. + +This provides: + +```text +open XZBT + ↓ +cached library appears immediately + ↓ +optional REFRESH SOURCE +``` + +rather than forcing filesystem selection every time. + +--- + +# 112. Embedded Exhibits + +Embedded `.xzbt` JSON should use the same schema and parser as imported external exhibits. + +The runtime must not maintain a separate implementation for embedded products. + +A possible implementation is an `application/json` script block, but the packaging mechanism is not part of the exhibit schema itself. + +--- + +# 113. Validation Pipeline + +Maintain an internal JSON Schema for structural checks and separate semantic validation for types, references, graphs, ownership, and resource limits. Unknown fields in behavior-bearing objects are errors. Complete and reconcile the authoring contracts in the companion format specification before implementing dependent validation rules. + +Before activation: + +```text +1. JSON parse +2. XZBT version validation +3. structural schema validation +4. type/range validation +5. ID validation +6. reference validation +7. component dependency validation +8. audio graph expansion +9. audio graph legality validation +10. visual structure validation +11. event dependency validation +12. scenario validation +13. resource-limit validation +14. warnings/errors report +15. activation decision +``` + +--- + +# 114. Validation Severity + +Three levels: + +## Error + +Exhibit or affected system cannot safely run. + +Examples: + +- malformed JSON +- unknown required target +- illegal audio cycle +- recursive component +- invalid scenario reference +- unsupported node type + +## Warning + +Exhibit can run but likely contains an authoring problem. + +Examples: + +- unreachable audio node +- empty UI group +- unused state value +- unused component +- exceptionally expensive visual configuration + +## Info + +Diagnostic or normalization message. + +--- + +# 115. Failure Philosophy + +XZBT must fail predictably. + +It must never silently execute malformed semantics differently from the documented specification. + +When safe partial degradation is possible, the runtime may disable only the affected optional feature. + +When the exhibit's core graph or document is unsafe or structurally invalid, activation must fail clearly. + +--- + +# 116. Diagnostics + +Developer-facing diagnostics should identify: + +```text +exhibit ID +section +object ID +property +error class +human-readable explanation +``` + +Example: + +```text +Exhibit: machine-study +Scenario: power-disturbance +Timeline entry: warning +Action: start-alarm +Error: Unknown sound "primary-alarm" +``` + +Avoid errors such as: + +```text +undefined at object 17 +``` + +--- + +# 117. Pause and Resume + +XZBT must provide application-level pause/resume. + +Explicit pause and document visibility loss pause the entire performance: + +- pause scenario progression +- suspend new cadence activity +- pause visual simulation and animation +- suspend audio +- preserve user configuration +- avoid catch-up bursts + +Resume continues logical simulation and scenario time from their previous position. Do not replay elapsed wall-clock time. Visibility restoration must not undo an explicit user pause. Background playback is outside the default 0.1 behavior and requires a separate future contract. + +Cadence resumes its logical pending schedule; it must not resample solely because a pause occurred. Rendering is independent of the initial 1/60-second logical update step. Audio lookahead and long-stall policies must be specified and verified under GC4. + +--- + +# 118. Audio Unlock + +Because browsers may require user interaction before producing audio, XZBT should treat the first user interaction that engages the exhibit as the point at which audio is initialized or resumed. + +Visual rendering may begin before audio authorization if necessary. + +The UI should represent muted/unavailable audio state clearly. + +When audio is unlocked after visual startup, align it to the current logical position without replaying expired one-shot invocations. Continuous ambience and partially elapsed sound initialization require an explicit audio contract before implementation. + +--- + +# 119. Performance Targets + +MVP target: + +```text +60 FPS when reasonable +30 FPS minimum graceful target on weaker systems +``` + +The runtime should monitor frame timing and avoid runaway work. + +Exact device-independent guarantees are not required. + +The runtime must remain usable when performance degrades. + +Record a real reference computer, browser version, device-pixel ratio, audio sample rate, and 1920 x 1080 viewport. Fix a representative exhibit combining particles, links, trails, post-processing, and overlapping audio. The provisional benchmark acceptance threshold is a 95th-percentile frame interval below 33.3 ms, with 60 FPS as the target. Define measurement windows before acceptance and derive supported workload ceilings from early combined-load measurements. See GC6; no benchmark has yet passed. + +--- + +# 120. Runtime Resource Ceilings + +Engine-enforced ceilings should exist for: + +- particles +- emit rates +- active visual instances +- visual links +- path complexity +- audio voices +- audio graph nodes +- audio routing edges +- component nesting +- resonator modes +- scenario instances +- timeline expansions +- event recursion depth +- post effects +- rendering resolution + +Limits should be centralized rather than scattered through individual subsystems. + +--- + +# 121. Security Model + +`.xzbt` 0.1 must not permit: + +- JavaScript +- `eval` +- dynamic code generation +- DOM access +- arbitrary URL fetches +- filesystem access +- arbitrary network access +- executable event handlers +- external scripts +- arbitrary CSS injection + +Exhibit behavior is restricted to documented declarative primitives. + +--- + +# 122. Browser Target + +MVP should be developed and validated primarily against a current Chromium-based desktop browser. + +Other browsers are desirable but are not required to block the first functional MVP. + +The runtime must retain reasonable fallback behavior for exhibit import when advanced filesystem features are unavailable. + +The canonical direct-file launch must pass the GC1 feasibility prototype. Testing only through a development server is insufficient. Record the browser version actually tested rather than treating Chromium support as an unverified universal guarantee. + +--- + +# 123. Accessibility + +Configuration controls should use native accessible HTML controls whenever possible. + +Requirements: + +- keyboard navigation +- visible labels +- focus indication +- semantic buttons +- meaningful disabled state +- sufficient text contrast +- reduced-motion support where practical +- pause control for continuous motion +- volume control +- clear audio mute state + +Visual exhibits themselves may be artistic and not inherently accessible, but the application UI must remain operable. + +--- + +# 124. MVP Primary User Flow + +```text +User opens XZBT.html + ↓ +XZBT restores cached exhibit library + ↓ +last exhibit or library screen appears + ↓ +user selects exhibit + ↓ +XZBT validates exhibit + ↓ +dynamic configuration page is built + ↓ +visual exhibit starts + ↓ +audio starts after authorized interaction + ↓ +ambient audio begins + ↓ +cadence clocks begin + ↓ +scenarios become eligible + ↓ +user adjusts configuration + ↓ +state and bindings respond + ↓ +user may SAMPLE sounds + ↓ +user may manually start eligible scenarios +``` + +--- + +# 125. Initial Empty-State Flow + +If no cached exhibits exist: + +```text +XZBT + +No exhibits loaded. + +[ IMPORT LIBRARY ] +[ IMPORT XZBT FILES ] +``` + +After successful import, exhibits appear without requiring a restart. + +--- + +# 126. Configuration Persistence + +Per-exhibit parameter values should be stored separately from the exhibit definition. + +Example: + +```text +machine-study + activity = 0.35 + dnr = 0.70 + +abstract-field + density = 0.80 + trails = true +``` + +Updating or refreshing the source file should not automatically erase compatible user configuration. + +Preserve compatible values. Clamp compatible numeric settings to changed bounds with notice; reset incompatible settings, including values no longer permitted by an enum, to declared defaults. Exact type and value compatibility rules must be completed before persistence implementation. + +Parameters removed from the exhibit should be discarded. + +New parameters use their declared defaults. + +--- + +# 127. Exhibit Switching + +Switching exhibits must perform a complete controlled teardown. + +Validate and prepare the candidate before beginning this teardown. A preparation failure leaves the running exhibit intact. After an activation failure, dispose of the candidate and attempt a fresh restart of the previous exhibit with saved configuration, as specified in section 108. + +Required sequence: + +```text +stop scenario scheduling +stop cadence +cancel pending actions +release scenario-owned resources +release continuous sounds +release one-shot audio safely +destroy visual instances +disconnect bindings +clear state runtime +activate new exhibit +``` + +Old exhibit resources must not survive unintentionally. + +--- + +# 128. Reference Exhibit Suite + +XZBT 0.1 should not be declared complete without a deliberately varied reference suite. + +Develop the suite alongside the engine. Begin with two contrasting integrated exhibits that exercise parameters, audio, visuals, and a temporary scenario override as soon as those capabilities are available. These are development milestones; all required exhibits and challenge criteria remain part of release acceptance. + +At minimum: + +## Exhibit A: Procedural Machine Environment + +Must test: + +- multiple audio buses +- oscillator/noise/impulse synthesis +- resonator +- continuous ambience +- routine through rare cadence +- mechanical-style geometry +- repeaters +- moving components +- DNR-style low-frequency control +- scenario orchestration + +--- + +## Exhibit B: Deep Abstract Field + +Must test: + +- particles +- coherent noise fields +- links +- splines +- morphing +- gradients +- bloom/glow +- audio-reactive bindings +- evolving procedural ambience + +--- + +## Exhibit C: Natural Environment + +Should depict something clearly non-science-fiction such as: + +- rain +- wind +- water +- biological activity +- forest abstraction + +Its purpose is to reveal hidden thematic assumptions in the engine. + +--- + +## Exhibit D: Instrument/Data Display + +Must test: + +- text +- paths +- grids +- indicators +- state-driven animation +- dynamic values +- sonification +- UI-like vector composition + +--- + +## Exhibit E: Long Scenario + +Must include a scenario of approximately 30 to 60 minutes containing: + +- random trigger timing +- relative delays +- repeated beats +- branching +- temporary overrides +- persistent state mutation +- cadence interaction +- continuous audio +- visual spawning +- recovery +- cleanup + +Development mode should permit accelerated execution for testing. + +--- + +# 129. Audio Acceptance Challenge + +Audio Graph 0.1 must be capable of producing, solely through `.xzbt`: + +1. electronic chirp +2. relay or switch click +3. alarm/siren +4. airflow loop +5. machinery drone +6. pressure release +7. structural groan +8. electrical buzz/arcing texture +9. impact transient +10. tonal sequence +11. organic pulse or breathing-like sound +12. evolving atmospheric texture + +No challenge item may require a themed runtime function. + +--- + +# 130. Visual Acceptance Challenge + +Visual System 0.1 must be capable of producing: + +1. deep parallax starfield +2. fog or smoke-like flow field +3. evolving spline network +4. rain or weather-like particles +5. rotating mechanical abstraction +6. organic pulsing structure +7. instrument or radar-like display +8. constellation/network visualization +9. persistent landscape-like composition +10. transient impact or energy burst +11. morphing geometric art +12. audio-reactive visualization +13. window-like scene containing procedural moving traffic +14. clearly non-science-fiction natural or abstract exhibit + +No challenge item may require a subject-specific renderer. + +--- + +# 131. Scenario Acceptance Challenge + +Scenario Director must demonstrate: + +- 5-second scenario +- multi-minute scenario +- 30 to 60-minute scenario +- manual trigger +- random interval trigger +- condition trigger +- event trigger +- branching +- randomized relative timing +- repeated beats +- temporary overrides +- persistent state changes +- scenario priority +- exclusive groups +- parallel scenarios +- conflict defer +- cleanup after completion +- cleanup after cancellation +- repeated execution without leakage + +--- + +# 132. Persistence Acceptance Tests + +The MVP should demonstrate: + +1. user imports exhibits +2. exhibits are cached +3. browser/application is closed +4. `XZBT.html` is reopened +5. cached library reappears +6. previous user configuration is restored +7. exhibits run without requiring source re-selection +8. user may explicitly refresh source files +9. refresh updates exhibit definitions +10. compatible user preferences remain intact + +--- + +# 133. Reliability Tests + +Required real-duration test sessions: + +```text +2 hours during development +8 hours for release acceptance +overnight where practical +``` + +Testing should monitor: + +- memory growth +- active audio node count +- active visual instance count +- scenario resource count +- scheduler queue growth +- frame timing +- audio glitches +- stale references +- accumulated event listeners + +A stable exhibit should reach a bounded operating state rather than consuming resources indefinitely. + +Expose counters for active audio nodes/voices, visual instances, subscriptions, and scheduler records. Repeated completion, cancellation, and failure tests must return to expected baseline after bounded releases finish. Retained memory must plateau after warm-up using a recorded measurement method. Accelerated scenario tests do not replace these real-duration soaks. Environment, workload, and results are recorded under GC6. + +--- + +# 134. Development Architecture Guidance + +The runtime should avoid building one giant monolithic controller. + +Recommended major classes/modules in the development source: + +```text +XZBTApp +ExhibitLoader +ExhibitValidator +LibraryManager +PersistenceManager + +ValueResolver +StateManager +ParameterManager +SignalManager +BindingEngine + +AudioEngine +AudioGraphCompiler +AudioBusManager +SoundDirector + +VisualEngine +VisualComponentFactory +ParticleSystem +FieldSystem +VisualPostProcessor + +ActionExecutor +EventEngine +ScenarioDirector + +UIRenderer +Soundboard + +SeededRNG +RuntimeScheduler +Diagnostics +SafetyManager +``` + +Develop separate source modules and build them reproducibly into one self-contained `XZBT.html`. The delivered file must have no external runtime scripts, modules, assets, fonts, or CDN dependencies. Single-file distribution does not require single-file development. + +## Development Phase 0: Contract and Feasibility Preparation + +Use the [verification gates](docs/XZBT_0-1_Verification_Gates.md) before committing dependent architecture and detailed estimates: + +- verify direct-file import, persistence, restart, audio startup, and worklet loading if needed (GC1) +- complete shared format contracts and expected semantic traces (GC2-GC5) +- schedule early combined visual/audio workload measurements before fixing expensive subsystem choices (GC6) +- map integrated reference-exhibit milestones and library/build behavior (GC7) + +The implementation plan may be drafted now with these prerequisites explicit. Complete remaining subsystem contracts before their implementation. Full conformance and two/eight-hour soaks are later development/release gates, not prerequisites for drafting the plan. All verification is currently pending. + +--- + +# 135. Development Phase 1: Runtime Skeleton + +Deliver: + +- application shell +- exhibit loader +- JSON parsing +- schema version check +- metadata +- library list +- exhibit activation/deactivation +- diagnostics shell +- seeded RNG +- persistence foundation +- reproducible modular-source build producing the standalone artifact + +Acceptance: + +Two minimal exhibits can be imported, cached, selected, and restored. + +--- + +# 136. Development Phase 2: Common Grammar + +Deliver: + +- parameters +- state +- signals +- ValueSpec +- ConditionSpec +- Action executor +- Binding Model +- override stack + +Acceptance: + +A parameter can drive state/visual placeholders, conditions evaluate correctly, and scenario-style overrides can temporarily supersede user configuration without destroying it. + +--- + +# 137. Development Phase 3: Audio Engine + +Deliver: + +- all Audio Graph 0.1 nodes +- graph compiler +- routing +- modulation +- automation +- components +- buses +- lifecycle +- safety +- voice management + +Acceptance: + +Audio challenge suite passes without custom JavaScript. + +--- + +# 138. Development Phase 4: Visual Engine + +Deliver: + +- core primitives +- layers +- transforms +- gradients +- splines +- particles +- emitters +- repeaters +- fields +- behaviors +- links +- trails/ribbons +- camera +- post-processing + +Acceptance: + +Visual challenge suite passes without subject-specific renderer code. + +--- + +# 139. Development Phase 5: Events and Cadence + +Deliver: + +- Event Model 0.1 +- sound metadata +- sound usage +- cadence pools +- weighted selection +- cooldown +- overlap policy +- anti-repetition +- global intensity +- minimum automatic gap +- ambient maintenance + +Acceptance: + +An exhibit can run automatically for an extended period without repetitive or collision-heavy sound behavior. + +--- + +# 140. Development Phase 6: Scenario Director + +Deliver: + +- trigger engine +- eligibility +- timeline scheduler +- branching +- relative timing +- repeated beats +- priority +- concurrency +- ownership +- cleanup +- cancellation +- accelerated developer time + +Acceptance: + +Scenario acceptance challenge passes. + +--- + +# 141. Development Phase 7: Dynamic UI + +Deliver: + +- configuration groups +- slider +- number +- toggle +- select +- text +- color +- conditional visibility +- scenario controls +- soundboard +- SAMPLE behavior +- master volume +- pause/resume + +Acceptance: + +Each reference exhibit generates a different configuration surface without runtime-specific UI code. + +--- + +# 142. Development Phase 8: Library and Persistence Hardening + +Deliver: + +- directory import where supported +- multi-file import +- drag/drop +- IndexedDB exhibit cache +- remembered user settings +- remembered source handles where supported +- refresh source +- update reconciliation +- graceful error handling + +Acceptance: + +Library persistence tests pass. + +--- + +# 143. Development Phase 9: Reference Exhibits + +Complete and audit all required reference exhibits using only `.xzbt`. Exhibit development begins alongside supporting engine phases; this is not the first phase in which representative content is authored or tested. + +Every missing generic capability discovered during this phase must be evaluated using: + +> Is this genuinely required for 0.1, or can the exhibit be expressed through the existing grammar? + +Only genuinely generic capability blockers should expand the frozen 0.1 feature set. Corrections to disproven technical assumptions follow section 145 and must preserve or explicitly revise the affected product requirement. + +--- + +# 144. MVP Completion Criteria + +XZBT 0.1 MVP is complete when all of the following are true: + +- `XZBT.html` operates as one self-contained runtime +- external `.xzbt` JSON can be imported +- imported exhibits are cached +- cached exhibits reopen later +- dynamic UI is generated from exhibit definitions +- parameters persist per exhibit +- ValueSpec works +- ConditionSpec works +- Action Model works +- Binding Model works +- Audio Graph 0.1 passes challenge suite +- Visual System 0.1 passes challenge suite +- Event Model works +- Cadence 0.1 works +- Scenario Model 0.1 passes challenge suite +- soundboard SAMPLE works without disturbing cadence +- exhibit switching leaves no stale audio/visual/scenario resources +- seeded exhibits can reproduce procedural behavior +- malformed exhibits fail safely +- reference exhibits require no exhibit-specific runtime JavaScript +- long-running stability tests are acceptable +- the direct-file launch and normal-mode persistence gate passes +- structural and semantic contracts have conformance evidence +- the fixed reference benchmark and required real-duration soaks pass +- the built artifact runs directly and offline without external runtime dependencies + +--- + +# 145. 0.1 Change-Control Rule + +Once the relevant format contracts and feasibility decisions are completed, treat them as frozen during implementation unless a reference exhibit exposes a genuine generic capability gap or verification disproves a required technical assumption. Record corrections across the PRD, format specification, decision record, and verification gates. Do not silently reinterpret unsupported semantics or replace a product promise. + +Completing an explicitly tracked contract is planned specification work, not an opportunity to expand 0.1 scope. Early demonstrations do not reduce the full MVP completion criteria. + +Every proposed new feature should answer: + +> **Does the MVP require this to prove the XZBT runtime concept, or does it belong in XZBT 0.2?** + +Convenience alone is not sufficient reason to expand 0.1. + +--- + +# 146. Likely Post-MVP 0.2 Candidates + +Potential later features include: + +- graphical exhibit authoring +- live node graph editor +- external images +- external audio samples +- media packaging +- WebGL renderer +- richer 3D +- custom shaders +- asset bundles +- MIDI +- OSC +- gamepad input +- Streamer.bot integration +- network signals +- external data feeds +- live scientific data +- standalone HTML exporter +- collection builder +- exhibit dependency packages +- richer color mathematics +- advanced spatial audio +- custom synthesis curves +- advanced physics +- timeline editor +- scenario debugger +- exhibit profiling +- adaptive quality +- authoring schema autocomplete +- formal JSON Schema distribution + +Public schema distribution is optional post-MVP work. An internal structural schema and semantic validator are required for 0.1. + +--- + +# 147. Product Position After MVP + +The MVP should establish XZBT as more than an ambient display application. + +It becomes a declarative procedural audiovisual runtime whose content exists independently from the engine. + +The engine can remain a single HTML application while `.xzbt` files operate as portable exhibit definitions. + +That separation enables a future ecosystem in which: + +```text +one runtime ++ +many exhibits ++ +fixed standalone collections ++ +portable authored experiences +``` + +all use the same underlying specification. + +--- + +# 148. Final Architectural Contract + +XZBT 0.1 can be summarized by the following rules. + +```text +XZBT.html contains capability. + +.xzbt contains intent. + +Parameters belong to the user. + +State belongs to the simulation. + +Signals belong to the runtime. + +Bindings connect systems. + +Audio graphs synthesize sound. + +Visual systems synthesize imagery. + +Cadence creates ambient activity. + +Events define reusable occurrences. + +Scenarios create finite performances. + +Overrides are temporary. + +State mutation is persistent. + +Randomness is controlled and seedable. + +No exhibit contains arbitrary JavaScript. + +Every runtime object has a lifecycle. + +Every temporary resource has an owner. + +Every owned resource has cleanup behavior. + +The runtime remains subject-neutral. + +A new exhibit should normally require only a new .xzbt file. +``` + +The MVP succeeds when that final sentence is demonstrably true. diff --git a/docs/XZBT_0-1_Format_Specification.md b/docs/XZBT_0-1_Format_Specification.md new file mode 100644 index 0000000..f3847a8 --- /dev/null +++ b/docs/XZBT_0-1_Format_Specification.md @@ -0,0 +1,104 @@ +# XZBT Format Specification 0.1 + +**XZBT format version:** 0.1 +**Document revision:** 0.1 +**Status:** Partial normative specification; contract completion required before dependent implementation +**Related resources:** [PRD](../XZBT_0-1_MVP_Product_Requirements_Document.md), [decisions](XZBT_0-1_Gap_Closure_Decisions.md), [verification](XZBT_0-1_Verification_Gates.md) + +This document defines shared semantic decisions and tracks the contracts still needed to implement the PRD. Existing PRD examples remain design inputs; a list of supported feature names is not a complete JSON grammar. No validator or complete JSON Schema has yet been produced. + +## 1. Format foundation + +Documents are UTF-8 JSON with `xzbt: "0.1"`, `meta.id`, and `meta.name` required. Unsupported format versions fail activation. Exhibit version and format version are separate. IDs use `^[a-z][a-z0-9_-]*$`; dots delimit reference paths. + +The following is a complete minimal exhibit. An exhibit that performs no audio or visual work is valid: + +```json +{ + "xzbt": "0.1", + "meta": { + "id": "empty-study", + "name": "Empty Study" + } +} +``` + +Validate structure before activating resources. Follow structural validation with type, reference, graph, ownership, and resource-limit checks. Unknown fields in behavior-bearing objects are errors. Do not coerce strings to numbers or silently invent semantics for unsupported constructs. + +A structurally valid minimal exhibit does not prove expressive capability. Complete audiovisual examples and invalid fixtures remain required under GC2. + +## 2. Shared value resolution + +For each supported target, evaluate: + +```text +base -> binding -> automation -> winning override -> modulation -> safety clamp +``` + +Skip stages not exposed by the target contract. A target cannot accept automation or modulation merely because it is numeric. Additive modulation is summed only where explicitly supported. + +Parameters store user configuration separately from exhibit defaults. State stores simulation values separately from parameters. A property may obtain its base through ValueSpec. State is not an implicit layer overwriting every parameter. + +References ordinarily read resolved values. Parameter controls read and edit stored user values, and display an override indicator when appropriate. Underlying bindings and automation continue to evaluate while masked by an override. + +Override lifetime and priority are independent. Use explicit priority when supported, otherwise inherit the originating scenario's priority; equal priorities resolve by activation order. Duration scope confers no additional priority. The complete action contract must define non-scenario default priority, permitted explicit priority fields, and ordering identifiers before implementation. + +On release, blend toward the current lower resolved value rather than a snapshot taken when the override started. User edits and changing bindings remain visible to that lower evaluation. Numeric release interpolation, interruptions by another override, and nonnumeric release behavior require exact contracts below. + +Reject conflicting ordinary bindings and dependency cycles that cannot be evaluated under documented semantics. Do not introduce an implicit previous-frame delay to make a cycle appear legal. + +### Required resolution examples + +| Case | Expected behavior | +| --- | --- | +| Bus gain is bound to activity, then directly overridden | The override supplies the pre-modulation value until release; the binding continues underneath | +| Activity is overridden and referenced by a binding | The binding observes resolved activity | +| User edits stored activity while its override is active | The stored edit persists; release approaches the updated lower value | +| Two overrides compete | Higher priority wins; equal priority uses activation order | +| Duration and scenario overrides compete | Priority and activation order decide, not scope | +| A target has legal additive modulation | Modulation follows the winning override, then the safety clamp applies | + +## 3. Time and random evaluation + +The initial logical simulation step is 1/60 second. Rendering does not own simulation time. Audio scheduling maps logical time to the audio clock with a bounded horizon. + +Application pause and document visibility loss suspend logical progression and audio. Resume continues the same logical performance without a wall-clock catch-up burst. Visibility resume does not clear a user pause. Audio unlock does not replay expired sound invocations. + +Random and weighted-choice ValueSpecs are sampled at the containing object's documented instantiation or invocation boundary, not every render frame. Evolving randomness belongs to modulators. Nested ValueSpec evaluation boundaries and random time sampling must be specified per construct. + +Separate random streams isolate cadence, scenario instances, visual systems, sound instances, and manual sampling. Reproducibility is scoped to a runtime version, recorded numeric seed, and logical input sequence. Tests that use external or analysed signals must supply deterministic input traces. + +## 4. Ownership and termination + +Ownership propagates through nested events and actions. Scenario resources inherit the scenario owner unless the resource type allows an explicit persistent owner. Scenario-created duration overrides cannot outlive the owner, apart from their bounded release cleanup. + +Persistent `set` changes survive scenario failure. Termination cancels future work and guarantees cleanup, including when a termination hook fails. Release work transfers to a bounded cleanup owner and ultimately disposes all temporary resources. + +Condition triggers require a false condition before rearming after a successful firing. Each scenario definition may hold at most one deferred start request. Requests expire and recheck eligibility when dispatched. Exact timeout and ordering contracts remain required. + +Statically check event/scenario feedback where possible and bound runtime dispatch. Resource cleanup must remain possible after the ordinary dispatch budget is exhausted. + +## 5. Contract completion register + +All rows below require work; none claims a completed implementation. Complete shared contracts before implementing dependent subsystems. Use PRD section numbers as stable lookup references. + +| Contract | Existing PRD input | Required completion | +| --- | --- | --- | +| Document/schema | 9-14, 113-116, 121 | All structural shapes, unknown-field policy, metadata extensions, size/depth limits, diagnostic paths, full internal schema | +| Values and conditions | 15-21, 33 | Operator arity and types, numerical errors, array/object literals, live versus sampled fields, seed algorithm and stream derivation | +| References and bindings | 13, 17, 31-32 | Target-capability table, instance/input scope, evaluation order, cycles, disabled bindings, exact smoothing | +| Actions and transitions | 22-30 | Fields and defaults per action, override priorities outside scenarios, target/command matrix, interrupted transitions, instance IDs | +| Audio | 34-60 | Complete recipe/component shapes, node defaults, automation timing, clamp implementation, one-shot endings and tails, unlock behavior, master protection contract | +| Cadence | 61-68 | Exact selection/cooldown/overlap fields, clocks, pool collisions, pending audio, manual sampling isolation and continuous-sample termination | +| Visuals | 69-89 | Primitive/system/behavior fields, angle and motion units, transform order, depth projection, field behavior, morph compatibility, effect approximation and limits | +| Events/scenarios | 90-102 | Trigger shapes, hooks and failure ordering, scope inheritance, deferred ordering/expiry, relative/repeated timeline semantics and termination boundaries | +| Generated UI | 103-107 | Widget compatibility, button actions, parameter validation and override display, group/control ordering | +| Runtime/library | 108-112, 117-127 | Clock/audio synchronization and stalls, import equality, update compatibility, transactions, failure recovery, persistence schema | + +## 6. Contract template and conformance artifacts + +Each construct must record its JSON shape; required and optional fields; types, units, ranges, and defaults; supported ValueSpec fields and evaluation timing; read/write namespaces; lifecycle and ownership; precedence; validation errors; runtime failure behavior; and resource costs or limits. + +Supply a valid minimal example, a meaningful composition example, invalid cases with expected diagnostics, and expected semantic traces where timing or ordering matters. Two contrasting complete exhibits must exercise parameters, sound, visuals, and a temporary scenario override early in development. + +Structural JSON Schema does not replace semantic validation. The internal schema and fixtures belong to 0.1 implementation work; public schema distribution and editor integration may follow later. diff --git a/docs/XZBT_0-1_Gap_Closure_Decisions.md b/docs/XZBT_0-1_Gap_Closure_Decisions.md new file mode 100644 index 0000000..abc6bb7 --- /dev/null +++ b/docs/XZBT_0-1_Gap_Closure_Decisions.md @@ -0,0 +1,109 @@ +# XZBT 0.1 Gap Closure Decisions + +**Record version:** 0.1 +**Status:** Incorporated into the planning baseline; implementation verification pending +**Related resources:** [PRD](../XZBT_0-1_MVP_Product_Requirements_Document.md), [format specification](XZBT_0-1_Format_Specification.md), [verification gates](XZBT_0-1_Verification_Gates.md) + +Numbering preserves the seven gaps discussed during PRD preparation. Recording a decision closes a design question; it does not establish that a browser feature, performance target, or lifecycle guarantee has passed testing. + +| Gap | Primary PRD placement | Supporting verification | +| --- | --- | --- | +| 1 | 3.4, 109-111, 122, 132, Phase 0 | GC1 | +| 2 | Resource preface, 113, Phase 0, 145-146 | GC2 | +| 3 | 31-32, 54, 104 | GC3 | +| 4 | 14, 102, 117-118 | GC4 | +| 5 | 91, 94, 99-101 | GC5 | +| 6 | 58, 119-120, 133, 144 | GC6 | +| 7 | 108-110, 126-128, 134-135, 143-145 | GC7 | + +## 1. Standalone HTML deployment model + +**Decision:** Opening `XZBT.html` directly in a desktop Chromium browser is the primary 0.1 launch method. The distributed application needs no server, installation, or network connection. Development tooling may use a local server, but it cannot substitute for testing the delivered file directly. + +Use IndexedDB for the exhibit cache and saved configuration. Always provide ordinary file-picker import. Directory import and remembered source handles are optional enhancements where available. A source handle is not the startup dependency: cached definitions are. + +Verify file import, audio unlock, cache writes, browser restart, and cache restoration in the actual target environment. If the selected audio implementation needs AudioWorklet, verify loading engine-owned worklet code from the self-contained artifact. Exhibit-authored executable code remains prohibited. + +Moving or renaming the HTML is a separate compatibility case. Do not promise that browser storage follows it. When storage is unavailable, retain session playback and explain that exhibits must be imported again on a later launch. This fallback does not waive the ordinary-mode persistence acceptance requirement. + +**Gate:** GC1 in the verification checklist. A failure of direct-file persistence in the chosen supported environment reopens the deployment decision; do not silently replace the distribution promise with hosted-only operation. + +**Basis:** [MDN file-origin behavior](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Same-origin_policy#file_origins), [Chrome File System Access API](https://developer.chrome.com/docs/capabilities/web-apis/file-system-access), and [AudioWorklet requirements](https://developer.mozilla.org/en-US/docs/Web/API/AudioWorklet). These describe platform constraints, not evidence that the XZBT prototype has passed. + +## 2. One authoritative format specification + +**Decision:** Separate product requirements from exact authoring contracts. Maintain the companion Format Specification 0.1 and an internal structural JSON Schema, with additional semantic validation for references, graph legality, ownership, and limits. + +For each exposed construct, specify JSON shape, required fields, defaults, units, ranges, ValueSpec support and evaluation timing, readable/writable targets, lifecycle, errors, and examples. Reject unknown fields in behavior-bearing objects. Define any allowed metadata extensions explicitly rather than permitting arbitrary executable-looking configuration. + +Complete valid exhibits and invalid fixtures are required alongside each contract. Reconcile relevant details from the earlier discussion into the local specification. The current format document is a foundation and completeness register, not a claim that all grammar has been formalized. + +**Gate:** GC2. Exact shared contracts precede their implementations; remaining subsystem contracts may be completed in dependency order. Publishing the schema and editor autocomplete remain optional post-MVP work. Maintaining an internal schema is required for 0.1. + +## 3. Bindings, overrides, and automation + +**Decision:** Resolve each target through base value, binding, automation, winning override, modulation, and safety clamp, using only stages supported by that target. Parameters and state have separate storage; state is not a universal layer above user configuration. + +References ordinarily read resolved values. Configuration controls read and edit the user's stored parameter value and indicate an active override. Underlying bindings and automation continue evaluating while masked. + +Override scope controls lifetime; explicit or inherited priority controls precedence. Equal priorities use activation order. Duration overrides do not automatically outrank scenario overrides. Release transitions approach the currently resolved underlying value, including changes made while masked. Additive modulation may remain after an override only on targets whose contracts permit it. + +Reject competing ordinary bindings and unresolvable dependency cycles. The format specification must finish the target-capability and transition rules before the resolver is implemented. + +**Gate:** GC3. Expected traces cover direct target overrides, parameter overrides flowing through bindings, overlapping priorities, user edits, and release behavior. + +## 4. Clock and reproducibility + +**Decision:** Use a logical simulation clock with an initial fixed update step of 1/60 second. Rendering is independent. Map logical audio scheduling to the audio clock with a bounded scheduling horizon; the exact horizon and late-work policy require prototype measurements and a written contract. + +In 0.1, document visibility loss pauses the entire performance by default, including audio. Explicit application pause does the same. Resume from the previous logical position without replaying elapsed wall-clock time. Visibility return must not undo an explicit user pause. Background playback is a separately specified future capability. + +Visuals may start before audio is unlocked, as permitted by the PRD. On unlock, begin audio at the current logical position without replaying expired sounds; the format contract must specify how continuous ambience and partially elapsed sounds initialize. + +Derive isolated random streams from the exhibit seed for cadence, scenarios, visual systems, and sound instances. Manual SAMPLE playback has an independent stream. Record the actual numeric seed when the exhibit requests a random seed. + +Reproducibility means identical procedural decisions for the same runtime version, seed, and logical input sequence. It does not promise identical pixels or audio samples across devices. Deterministic tests use recorded or synthetic audio-analysis signals where such signals affect decisions. + +**Gate:** GC4. Render frequency, pause duration, and independent sound sampling must not perturb unrelated logical choices. + +**Basis:** [MDN Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) documents background frame/timer behavior. This decision supplies XZBT's product policy rather than relying on browser throttling as its scheduler. + +## 5. Scenario ownership and failure + +**Decision:** Propagate ownership through action execution and nested events. Indirectly created resources inherit the originating scenario unless a resource contract explicitly permits persistent ownership and the exhibit requests it. + +A duration override created under a scenario expires at its deadline or when the owner terminates, whichever happens first. State mutations are persistent and are not rolled back after completion, cancellation, or failure. Failure cleanup removes temporary effects; scenarios are not transactions. + +On termination, stop ordinary dispatch, cancel future work, run the applicable termination hook, and guarantee cleanup even when the hook fails. Bounded release fades may continue under a cleanup owner until final disposal. Hook execution order and permitted hook actions must be finalized in the format specification; no new failure-hook field is introduced by this record. + +Condition triggers fire once after the qualifying condition has held for the declared interval, then require a false condition before rearming. A scenario definition has at most one pending deferred request, with an expiry and an eligibility recheck at dispatch. Exact queue ordering and default expiry must be specified before implementation. + +Validate event/scenario trigger cycles where statically detectable. Enforce a per-update dispatch budget as a runtime backstop, with a visible diagnostic when exhausted. Cleanup must still run when ordinary dispatch is curtailed. + +**Gate:** GC5. Repeated completion, cancellation, and injected failures return resource counts to the expected baseline after bounded releases finish. + +## 6. Performance and audio acceptance + +**Decision:** Record a real reference computer, OS, browser version, device-pixel ratio, audio sample rate, and a 1920 x 1080 test viewport. Fix a benchmark exhibit combining particles, links, trails, post-processing, and overlapping procedural audio. + +Target 60 FPS. Use a provisional acceptance threshold of a 95th-percentile frame interval below 33.3 ms under the recorded benchmark workload. This is a reference-workload target, not a guarantee for every valid exhibit or device. Measure the workload before fixing final supported ceilings; do not silently reduce the workload between comparisons. + +Expose resource counters for nodes, voices, visual instances, subscriptions, and scheduler records. Repeated lifecycle tests must return to expected baseline after releases and queued disposal finish. Retained memory must plateau after warm-up; record sampling method and investigate sustained growth rather than treating a transient allocation peak as a leak. + +Require a two-hour development soak and an eight-hour release soak. Accelerated logical-time tests supplement, but do not replace, real-duration runs. + +Specify master protection as a tested output stage with finite samples, a defined digital peak ceiling, controlled release, and no bypass. The exact ceiling, tolerances, and release settings must be recorded before audio acceptance. Test worst-case overlapping recipes and listen for clicks and distortion. A digital peak ceiling is not a guarantee of physical listening volume. + +**Gate:** GC6. Early combined-load measurements inform architecture and limits; full benchmark acceptance and soak results are release gates. + +## 7. Release scope and library updates + +**Decision:** Preserve all PRD MVP completion criteria. Early integrated demonstrations are milestones, not a reduced definition of the finished MVP. Develop contrasting reference exhibits alongside supporting engine capabilities. Phase 9 completes and audits the suite. + +Identical imports are no-ops. Changed content with an existing exhibit ID requires an explicit replacement choice. Invalid source refreshes preserve the last valid definition and compatible settings. Compatible numeric preferences are clamped to changed bounds with notice; incompatible preferences revert to declared defaults. Removed parameters are discarded and new ones receive defaults. Define exact compatibility and content-equality rules before persistence implementation. + +Validate and prepare a replacement exhibit before stopping the working one. Preparation must not start audible or visible activity. If activation subsequently fails, dispose of the failed candidate and attempt to restart the previous exhibit with its saved configuration. A restarted exhibit is a fresh performance, not restoration of its prior scenario clock. Report failure if recovery also fails. + +Develop separate source modules and build them into a reproducible, self-contained `XZBT.html`. No runtime module, asset, font, or CDN dependency may be required outside the delivered file. Single-file distribution does not require single-file development. + +**Gate:** GC7. The implementation plan identifies integrated milestones, safe update paths, reference-exhibit coverage, and the single-file build check. diff --git a/docs/XZBT_0-1_Verification_Gates.md b/docs/XZBT_0-1_Verification_Gates.md new file mode 100644 index 0000000..31cd0f8 --- /dev/null +++ b/docs/XZBT_0-1_Verification_Gates.md @@ -0,0 +1,123 @@ +# XZBT 0.1 Verification Gates + +**Status:** Planning checklist; every check is pending +**Related resources:** [PRD](../XZBT_0-1_MVP_Product_Requirements_Document.md), [decisions](XZBT_0-1_Gap_Closure_Decisions.md), [format specification](XZBT_0-1_Format_Specification.md) + +No tests, browser prototypes, benchmark results, or soak results have been run as part of the gap-closure documentation. Mark a check complete only with linked evidence. A recorded design decision is not a passing test. + +## Phase 0 and later gates + +Drafting the implementation plan may proceed now. Before committing the deployment architecture, pass GC1. Before implementing shared runtime semantics, complete the shared portions of GC2 and GC3-GC5 contracts and their expected traces. Early GC6 measurements inform expensive subsystem design. Full conformance and real-duration soak results remain release requirements. + +Subsystem-specific format details can be completed in dependency order as planned tasks. Do not require the finished engine or eight-hour soak before creating the plan. + +| Gap | Decision | Evidence status | Gate placement | +| --- | --- | --- | --- | +| GC1 | Recorded | Not run | Phase 0, before deployment architecture commitment | +| GC2 | Recorded; format draft partial | Contracts and fixtures incomplete | Shared contracts in Phase 0; subsystem contracts before their implementation | +| GC3 | Recorded; transition details open | Traces and tests pending | Shared resolver contract before Phase 2; tests with implementation | +| GC4 | Recorded; audio mapping details open | Prototype and tests pending | Clock contract in Phase 0; synchronization tests in audio integration | +| GC5 | Recorded; hook/queue details open | Traces and tests pending | Ownership contract before actions/audio; full tests with scenarios | +| GC6 | Recorded; thresholds provisional | Reference setup and benchmark absent | Early combined-load prototype; development and release acceptance | +| GC7 | Recorded | Plan/build/library checks pending | Milestone planning, then library/build integration | + +## 1. GC1: Direct-file feasibility + +- [ ] Record OS, browser version/profile, launch path, and storage mode. +- [ ] Open the artifact directly from disk with network unavailable. +- [ ] Import two exhibits with the ordinary file picker and activate each. +- [ ] Save exhibit definitions, per-exhibit parameters, selection, and master volume to IndexedDB. +- [ ] Close the browser fully, reopen the same HTML, and restore the cached library and settings without selecting source files again. +- [ ] Verify user-initiated audio unlock and resumed playback. +- [ ] If needed by the audio design, load engine-owned AudioWorklet code from the single-file artifact. Otherwise document why this check is not applicable. +- [ ] Test renamed and moved HTML files; record observed storage behavior and the support boundary. +- [ ] Test unavailable/failed storage; session playback works and the UI explains lack of persistence. +- [ ] Test directory import/remembered handles where available and ordinary-picker fallback where unavailable or permission is denied. + +**Evidence:** prototype artifact, reproducible steps, environment record, observed results. If ordinary-mode persistence fails, reopen decision 1 before dependent architecture commitment. + +## 2. GC2: Format contract completeness + +- [ ] Complete shared document, type, reference, ValueSpec, ConditionSpec, time, and ownership contracts. +- [ ] Fill the format-specification contract register in subsystem dependency order. +- [ ] Implement an internal structural schema plus separate semantic validation. +- [ ] Provide complete valid and invalid fixtures with expected diagnostics. +- [ ] Reject unsupported versions, unknown behavior fields, invalid reference types, recursive components, illegal graph cycles, and excessive resources. +- [ ] Produce two contrasting complete audiovisual exhibits early; expand toward all PRD challenge cases. +- [ ] Reconcile prior conversation proposals into the local documents; resolve conflicts explicitly. + +**Evidence:** versioned specification/schema/fixtures and validation results. Naming a node or behavior does not close its contract. + +## 3. GC3: Resolution semantics + +- [ ] Record exact target capabilities, override defaults, smoothing, and interrupted transition rules. +- [ ] Define expected traces for a bound bus gain receiving a direct override. +- [ ] Define expected traces for a parameter override feeding a binding. +- [ ] Verify stored user edits during masking and release toward the updated lower value. +- [ ] Verify priority ties and competing duration/scenario overrides. +- [ ] Verify automation continues while masked and permitted modulation applies after an override. +- [ ] Verify numeric clamps and unsupported target/stage diagnostics. +- [ ] Reject conflicting bindings and dependency cycles without introducing undocumented delays. + +**Evidence:** contract examples and deterministic resolver tests when implemented. + +## 4. GC4: Time and reproducibility + +- [ ] Define logical tick ordering, maximum work per turn, long-stall behavior, audio lookahead, and audio unlock alignment. +- [ ] Define PRNG algorithm, seed normalization, and stream derivation for the runtime version. +- [ ] Compare simulation traces at different render frequencies using the same logical inputs. +- [ ] Hide/restore the document and explicitly pause/resume; no missed wall-clock work is replayed. +- [ ] Verify visibility restoration does not undo an explicit pause. +- [ ] Verify audio suspends/resumes consistently and expired pre-unlock one-shots are not replayed. +- [ ] Verify manual SAMPLE does not perturb cadence/scenario random streams. +- [ ] Use deterministic signal fixtures for audio-reactive decision tests. +- [ ] Distinguish accelerated logical tests from real-time audio behavior and soak tests. + +**Evidence:** clock/PRNG contract, logical traces, and browser/audio observations. No cross-device pixel or waveform equality claim is required. + +## 5. GC5: Ownership and failure + +- [ ] Define hook ordering, allowed hook actions, failure propagation, cleanup deadlines, deferred expiry/order, and dispatch-budget behavior. +- [ ] Start resources through nested events and confirm inherited scenario ownership. +- [ ] Verify duration overrides terminate with their owner and bounded releases eventually dispose. +- [ ] Verify persistent state mutations survive a later critical failure. +- [ ] Inject failures into startup, ordinary actions, and termination hooks; cleanup still completes. +- [ ] Verify condition triggers require a false condition before rearming. +- [ ] Verify at most one pending deferred request per definition, expiry, and eligibility recheck. +- [ ] Exercise event/scenario feedback and show bounded dispatch with diagnostics. +- [ ] Repeat completion/cancellation/failure cycles; counters return to baseline after releases finish. + +**Evidence:** lifecycle traces, resource-count samples, and failure-injection results. + +## 6. GC6: Performance and audio acceptance + +- [ ] Record CPU/GPU/RAM, OS, browser version, 1920 x 1080 viewport, device-pixel ratio, sample rate, and relevant power settings. +- [ ] Fix benchmark exhibit/version/seed and counts for particles, links, trails, effect passes, audio nodes, and concurrent voices. +- [ ] Prototype combined visual/audio load early and record supported limits. +- [ ] Define warm-up duration, measurement window, frame interval sampling, and retained-memory sampling method before collecting acceptance data. +- [ ] Check the provisional p95 frame interval threshold of less than 33.3 ms and report progress toward the 60 FPS target. +- [ ] Record active resource baselines and verify expected return after repeated lifecycle operations. +- [ ] Specify and test digital output peak ceiling, numerical tolerance, finite samples, release behavior, and unavoidable master routing. +- [ ] Stress overlapping recipes and listen for clicks, clipping, and objectionable release artifacts. +- [ ] Run a two-hour development soak and an eight-hour release soak; record retained-memory trends, resource counts, frame intervals, audio glitches, and scheduler growth. + +**Evidence:** fixed workload, environment, measurement method, results, and investigated anomalies. Any threshold revision must be recorded before rerunning acceptance; do not silently change the benchmark to produce a pass. + +## 7. GC7: Scope, updates, and build + +- [ ] Map all PRD completion criteria and challenge cases to milestones and evidence. +- [ ] Integrate two contrasting exhibits early; make Phase 9 the completion/audit phase for all five reference exhibits. +- [ ] Define import equality and parameter compatibility precisely. +- [ ] Verify identical imports are no-ops and changed same-ID content requires an explicit replacement choice. +- [ ] Verify invalid refreshes leave the last valid definition and configuration intact. +- [ ] Verify compatible parameter preservation, numeric bound changes with notice, removed/new parameters, and incompatible-type/enum resets. +- [ ] Validate and prepare a candidate without observable playback before stopping the working exhibit. +- [ ] Inject activation failure; dispose of the candidate and attempt a fresh restart of the previous exhibit with saved settings. +- [ ] Build separate source modules into one self-contained HTML artifact reproducibly. +- [ ] Test the delivered artifact directly and offline; no external runtime scripts, modules, assets, fonts, or CDN requests are required. + +**Evidence:** implementation-plan coverage, library failure tests, build instructions, and artifact verification. + +## Evidence record template + +For each result, record gate/check ID, date, specification revision, implementation revision or artifact hash, environment, fixture/seed, procedure, expected result, actual result, pass/fail/not-applicable status, linked logs or measurements, and unresolved limitations. A not-applicable result requires a reason. Do not prefill results from intended behavior.