docs: add XZBT project page and initial development log

2026-09-04 20:32:33 -07:00
parent 7b2e486095
commit ca2830174f
7 changed files with 274 additions and 0 deletions
@@ -0,0 +1,42 @@
 # Instructions for Labyricorn publishing content
 These instructions apply to the entire `.labyricorn/` directory. More specific
 instructions in `project/AGENTS.md` and `devlog/AGENTS.md` also apply within
 those directories.
 ## Purpose and ownership
 - This directory is the repository-owned source for the project's exhibition
  page and development log on Labyricorn.
 - This project repository is authoritative for the content. The Labyricorn site
  imports it as read-only content.
 - Read `.labyricorn/README.md` and the nearest scoped `AGENTS.md` before editing
  a publishing record.
 - Keep publishing changes focused. Do not alter application code merely to
  support an exhibition or devlog edit unless the user separately requests it.
 ## Authorization and content contract
 - Preserve unrelated and uncommitted work. Never discard changes to obtain a
  clean working tree.
 - Do not commit or push unless the user explicitly requests publication.
 - Use native Lektor records named `contents.lr` and preserve `schema_version: 1`
  until a coordinated schema migration is approved.
 - Keep attachments inside the record subtree that owns them.
 - Use UTF-8 text, `YYYY-MM-DD` dates, and stable lowercase hyphenated slugs.
 - Do not add templates, models, plugins, workflows, executable files, builds,
  application state, credentials, raw HTML, scripts, or active third-party
  content below `.labyricorn/`.
 - Treat published URLs as durable. Ask before renaming or removing a published
  record; redirects or archival behavior may be required first.
 ## Security, synchronization, and review
 - Never store or print passwords, API tokens, refresh credentials, private keys,
  `.netrc` contents, or other secrets in this directory.
 - Do not claim content is public merely because a push succeeded. Report push
  status and Labyricorn synchronization status separately.
 - Parse changed records, confirm referenced source commits exist, run
  `git diff --check`, and review the exact publishing diff before committing.
 - At handoff, report changed publishing records, validation performed, commit
  and push status, and synchronization status if known.
@@ -0,0 +1,38 @@
 # Labyricorn publishing content
 This directory is the repository-owned source for Labyricorn Site's project
 exhibition and development log on Labyricorn. The project repository remains
 the source of truth; the Labyricorn site imports this content as read-only.
 The content uses native Lektor records:
 ```text
 .labyricorn/
 ├── AGENTS.md
 ├── README.md
 ├── project/
 │   ├── AGENTS.md
 │   ├── contents.lr
 │   └── <optional image>
 └── devlog/
    ├── AGENTS.md
    ├── contents.lr
    └── <entry-slug>/
        ├── contents.lr
        └── <optional images>
 ```
 Rules:
 - `project/contents.lr` uses the `project` model.
 - `devlog/contents.lr` uses the `devlog` model.
 - Each entry is a directory below `devlog/` containing a `contents.lr` record
  using the `devlog-entry` model.
 - Entry directory names are stable public slugs. Do not rename a published entry
  without arranging a redirect on the Labyricorn site.
 - Dates use `YYYY-MM-DD`; `source_commit` uses the full relevant commit ID.
 - Publishing attachments stay inside the record subtree that owns them.
 - Do not put credentials, builds, application state, or executable code here.
 Editing these records does not itself prove that the public site synchronized.
 Report repository publication and Labyricorn synchronization separately.
@@ -0,0 +1,57 @@
 # Instructions for the Labyricorn development log
 These instructions apply to `.labyricorn/devlog/` and help coding assistants
 maintain the project's public development narrative safely.
 ## Format and ownership
 - Keep the devlog index at `devlog/contents.lr` using `_model: devlog` and
  `schema_version: 1`.
 - Store each entry at `devlog/<stable-slug>/contents.lr` using
  `_model: devlog-entry` and `schema_version: 1`.
 - Use lowercase hyphenated entry slugs. Published slugs are durable public URLs;
  do not rename or delete them without explicit approval and a redirect or
  archival decision.
 - Every entry must contain `title`, `date`, `author`, `summary`, `tags`,
  `source_commit`, and Markdown `body` fields.
 - Keep entry attachments in that entry's directory. Only PNG, JPEG, and WebP
  images are accepted by the Labyricorn importer.
 - Do not add templates, models, plugins, executable code, builds, application
  state, credentials, or active third-party content below this directory.
 ## Content guidance
 - Base entries on verifiable repository history, project documentation, and
  implemented behavior. Do not invent motivations, results, release status,
  user feedback, or completion claims.
 - Explain the milestone, why it mattered, and what changed. Keep one main
  milestone per entry and write a summary that works in a chronological list.
  Do not merely expand a commit message or enumerate every changed file.
 - Distinguish design and schema contracts from completed runtime behavior.
 - Link to the relevant canonical commit using the repository's HTTPS web URL.
 - Use the referenced commit's actual `YYYY-MM-DD` calendar date for retrospective
  entries, not the date on which the prose was drafted.
 - Set `source_commit` to the full lowercase 40-character commit ID most directly
  associated with the milestone. It must be an ancestor of the published branch.
 - Topics are comma-separated display labels. Unknown topics are allowed: the
  site keeps them visible but unlinked. Do not create or edit the site's tracked
  tag registry from this project repository.
 - Use Markdown without raw HTML, scripts, embedded credentials, or active
  external content.
 - Multiple entries may share a date. The site resolves ties from source history;
  do not invent timestamps or manual next/previous links.
 - Do not rewrite older entries merely because the implementation later changed.
  Add a new entry or a clearly labelled correction when historical context is
  needed.
 ## Safety and review
 - Preserve unrelated project files and uncommitted work. The devlog owns only
  `.labyricorn/devlog/`.
 - Do not commit or push unless the user explicitly requests publication.
 - Before publication, verify claims against the referenced commit, validate all
  records, check that the source-commit link uses the same full commit ID, review
  the exact devlog diff, and confirm unrelated files are not staged in the
  publishing commit.
 - Prefer the repository-root `devlog_editor.py` for routine validation and safe
  publication when it is available.
@@ -0,0 +1,7 @@
 _model: devlog
 ---
 schema_version: 1
 ---
 title: XZBT development log
 ---
 summary: Design decisions, feasibility experiments, implementation milestones, and verified limits from the development of XZBT.
@@ -0,0 +1,62 @@
 _model: devlog-entry
 ---
 schema_version: 1
 ---
 title: Establishing XZBT and testing direct-file feasibility
 ---
 date: 2026-09-04
 ---
 author: Labyricorn
 ---
 summary: The planning baseline is committed, and manual browser tests have resolved the worklet-loading problem. Phase 0 remains stalled on conditional directory fallback evidence and unfinished shared contracts.
 ---
 tags: Project Planning, Browser Testing, Procedural Audio
 ---
 source_commit: 7b2e48609548da287f120e453e5c675de60e4cf6
 ---
 body:
 XZBT began with a declarative audiovisual runtime proposal: one generic `XZBT.html` supplies capabilities, while `.xzbt` exhibits define the experience. The first milestone was to turn that vision into an MVP requirements document, explicit gap-closure decisions, a partial format specification, and verification gates.
 The [planning baseline](https://git.labyricorn.com/Labyricorn/XZBT/commit/05fe2b4e021ba86e4a290d05b63c7cae0e386128) was committed on September 4, 2026. The entry date follows the Phase 0 evidence commit's local calendar date. The later manual captures have September 5 UTC timestamps, still September 4 in the project's America/Los_Angeles time zone.
 ## What exists now
 A disposable Phase 0 probe exercises direct-file import, IndexedDB caching, settings, user-initiated audio, worklet packaging, and storage-failure handling. Amber Study and Blue Study are minimal import fixtures. The probe has its own database and no authored network requests. It is not the XZBT runtime and does not constitute Phase 1.
 The [Phase 0 evidence commit](https://git.labyricorn.com/Labyricorn/XZBT/commit/7b2e48609548da287f120e453e5c675de60e4cf6) contains the probe, regression tests, and manual evidence described here. Results are recorded in `docs/evidence/phase0`, with the current stop and checklist in `docs/IMPLEMENTATION_STATUS.md` and `docs/XZBT_0-1_Verification_Gates.md`. This entry references that implementation and evidence revision; the planning baseline remains linked separately.
 ## Browser investigation
 The agent's browser tool rejected navigation to the local HTML under its URL policy. That prevented automated direct-file testing; it was not a failure of the runtime design. No security-policy workaround was used. The user performed the browser checks manually in regular, non-Incognito Chrome 152 on Windows.
 Probe versions 1 and 2 failed to load an engine-owned Blob-URL AudioWorklet module with `AbortError`. Version 2 separated the tone test from worklet loading and improved diagnostics, confirming that native audio still worked. Version 3 embedded the same fixed processor through a data URL. The user then observed successful module loading, node construction, and connection. That packaging issue is resolved in the tested environment.
 ## Testing completed so far
 | Check | Observed result |
 | --- | --- |
 | Ordinary file import and selection | The user confirmed importing both fixtures through the ordinary file input and selecting each worked. |
 | Directory import | Completed successfully in the manual storage-failure run. |
 | IndexedDB persistence | Both definitions, selection, activity settings, and master volume were saved and restored. |
 | Full browser restart | Following the full-exit procedure, Blue Study activity restored to 0.37 and volume to 0.19 with zero new saves. Earlier reload-only captures remain classified separately. |
 | Native audio | User-initiated tone was heard; tone nodes disconnected after completion. AudioContext suspend and resume states were observed. The captured sample rate was 48,000 Hz. |
 | Embedded worklet | Version 3 loaded and connected its engine-owned data-URL processor without reported errors. |
 | Renamed and relocated copies | The user confirmed both copies restored exhibits and settings before further import or edits. This does not guarantee portability between browsers or profiles. |
 | Injected storage failure | Sixteen expected injected save errors occurred while activity changed in memory and directory import remained usable. The user heard the tone and confirmed the session-only warning. No successful saves occurred during that run. |
 | Offline operation | Restoration, heard tone, and worklet loading succeeded. The user explicitly confirmed browser-scoped Offline mode was enabled throughout the run. |
 | Static and stubbed checks | Probe JavaScript and fixture JSON parsed. Three Node regression tests passed using stubbed browser/audio APIs; these are not browser acceptance tests. |
 The offline capture used a Pixel 9 mobile user-agent string while reporting Win32 and the original Windows file path. It is consistent with device emulation, not evidence from a physical Android device. Its `onlineFlag` remained true; the offline result rests on the user's explicit developer-tool setting confirmation, not on that flag or the count of authored requests.
 Injected write failure verifies the application's session fallback. It does not establish behavior under actual browser permission denial or real quota exhaustion. A silent worklet loading successfully also does not establish production audio quality, timing, or output protection.
 ## Where Phase 0 is stalled
 Phase 0 remains incomplete at GC1. The outstanding browser check is ordinary-picker fallback when directory access is actually denied or the directory API is unavailable. Successful directory import and successful ordinary import were observed separately; neither demonstrates that conditional failure path. Remembered source handles are optional and are not implemented in this probe.
 After that evidence is obtained, Phase 0 still needs shared document/value/reference and ownership contracts, precise resolution and clock behavior, expected semantic traces, and milestone preparation. The format specification is deliberately marked partial. Passing GC1 alone will not complete Phase 0.
 Phase 1, the runtime skeleton, has not started. Neither have Phases 2 through 9. There is no completed production schema, integrated audiovisual runtime, reference benchmark, or soak result. The two-hour development soak and eight-hour release soak remain later acceptance requirements.
 Work stopped in accordance with the request to report problems before advancing. The next step is to obtain the remaining conditional fallback evidence, complete the Phase 0 contracts and traces, and then review the gate before beginning Phase 1. The resolved Blob-module failure does not need to be repeated unless relevant code changes.
@@ -0,0 +1,33 @@
 # Instructions for the Labyricorn project record
 These instructions supplement `.labyricorn/AGENTS.md` and apply to the
 `project/` directory.
 ## Record structure
 - Maintain exactly one project record at `project/contents.lr` using
  `_model: project` and `schema_version: 1`.
 - Keep `project_id` stable. It is the durable identity used by the importer and
  public URL.
 - Ask before changing the repository URL, default branch, project status,
  author, start date, or project identity.
 - Store project-owned images in this directory and reference them by filename
  from `contents.lr`. Only PNG, JPEG, and WebP images are accepted.
 ## Editorial guidance
 - Write the exhibition page as a concise project narrative, not as a copy of
  the repository README or as release documentation.
 - Verify technical and status claims against the repository before editing.
 - Distinguish completed work, formal design work, experiments, and future work.
 - Do not manually add repository-derived commit, license, language, release,
  issue, star, or fork metadata. The Labyricorn importer owns those values.
 - Keep the summary suitable for listings and social previews.
 ## Review requirements
 - Confirm all required project fields are present and any image reference stays
  inside `project/`.
 - Check Markdown links are intentional HTTPS links and prose makes no unsupported
  claims.
 - Validate the record and run `git diff --check` before committing.
@@ -0,0 +1,35 @@
 _model: project
 ---
 schema_version: 1
 ---
 project_id: xzbt
 ---
 title: XZBT
 ---
 summary: A planned single-file browser runtime for declarative procedural visuals and soundscapes. Development is stalled in Phase 0 feasibility and contract preparation.
 ---
 status: active
 ---
 started: 2026-09-04
 ---
 author: Labyricorn
 ---
 repository_url: https://git.labyricorn.com/Labyricorn/XZBT
 ---
 default_branch: main
 ---
 tags: Generative Art, Procedural Audio, Browser Applications
 ---
 body:
 XZBT is being built around a simple distinction: the runtime knows how; the exhibit defines what. A self-contained `XZBT.html` will interpret declarative `.xzbt` JSON exhibits to create procedural visuals, soundscapes, and evolving audiovisual performances without exhibit-authored JavaScript.
 The intended experience is to open the HTML directly in a desktop Chromium browser, import exhibits, and run them offline. Parameters, state, audio and visual primitives, events, cadence, and scenarios will provide reusable building blocks for very different exhibits. The engine is intended to stay independent of any particular theme.
 The MVP requirements and seven gap-closure decisions are documented. Implementation currently consists of a disposable Phase 0 feasibility probe and two minimal fixtures, Amber Study and Blue Study. This is an experiment in browser capabilities, not the production runtime or a completed MVP.
 Manual Chrome testing has demonstrated ordinary import, exhibit selection, saved settings restored after a browser restart, native audio, embedded data-URL AudioWorklet loading, offline operation, and continued session operation during injected storage failures. Renamed and relocated copies also restored data in the tested environment; that behavior is not a general browser compatibility guarantee.
 Development is stalled in Phase 0 at the GC1 feasibility gate. Directory-permission-denial or API-unavailability fallback remains unverified. Shared format contracts, semantic traces, and milestone preparation are also unfinished. Phase 1 and every subsequent implementation phase have not started. Performance benchmarks and the required development and release soaks remain future work.
 The [project repository](https://git.labyricorn.com/Labyricorn/XZBT) contains the product requirements and planning baseline. The initial development log links the planning baseline and the subsequent probe and manual-evidence commit separately.