Labyricorn/XZBT-NGN
1
0
Fork 0
generated from Labyricorn/labyricorn-project-template
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Step 5 Complete

Browse Source
This commit is contained in:
Labyricorn
2026-09-14 13:01:45 -07:00
parent 76928f7870
commit 961919e017
34 changed files with 3309 additions and 273 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+72 -241
View File
@@ -1,24 +1,41 @@
# XZBT-NGN Exhibit Engine
A minimal, single-exhibit engineering host for XZBT Exhibit Contract 5.2.
It discovers controls from `describe`, tracks the exhibit's reported state,
and exposes set/invoke operations, events, sessions, and protocol errors.
A single-exhibit host for XZBT Exhibit Contract 5.2. It negotiates sessions,
discovers descriptor-driven controls, inspects reported state, sends set/invoke
operations, and displays capabilities, events, revisions, and protocol errors.
Step 5 implementation and verification are recorded in
[the completion report](STEP5-MVP-COMPLETION-REPORT.md). The SciFi-XZBT argument
descriptors are corrected and both text invocations pass through the operator UI.
Step 5 is complete: 27 automated tests and all three browser reference checks
pass. Haunted House reports conformant values, and publishing validation passes.
Step 6 is planned but has not begun.
## Run locally
Requires Node.js 22 or later. No npm dependencies or build step are needed.
Requires Node.js 22 or later. No npm dependencies or build step.
```powershell
npm start
```
Open `http://127.0.0.1:4173`. Enter a same-origin exhibit path and select
**Load exhibit**. The host negotiates a real session, calls `describe` and
`state.get`, then renders the discovered catalog. **Reconnect** establishes
a new session without reloading the exhibit; **Refresh state** requests a
new authoritative snapshot. **Disconnect** removes the exhibit frame.
**Load exhibit**. The host sends `hello`, `describe`, and `state.get` and renders
the discovered controls. Enter another path and select **Load exhibit** to switch.
Included test fixture paths:
- **Reconnect** negotiates a new session with the current frame, preserving the
exhibit instance. After **Disconnect**, it reloads the remembered URL; the new
exhibit instance starts with its own initial state.
- **Disconnect** removes the frame and clears session, catalog, state and events.
- **Refresh state** reads a new authoritative snapshot.
- Controls are grouped by the exhibit's category (or Other when omitted).
Reported values and draft inputs are distinct; select **Set** or **Invoke**
to submit. Rediscovery resets drafts.
- Expand **Capabilities**, **State and metadata**, or **Protocol diagnostics**
details to inspect engineering information. The latest diagnostic is also
shown near the connection panel. **Clear log** dismisses historical diagnostics.
Included reference fixture paths:
```text
/test-fixtures/reference-exhibits/aquarium/index.html
@@ -26,12 +43,13 @@ Included test fixture paths:
/test-fixtures/reference-exhibits/haunted-house/index.html
```
These copied fixtures have documented compatibility corrections; see
[fixture provenance](test-fixtures/PROVENANCE.md). They are not NGN product
logic. Additional trusted HTML exhibits can be placed in a directory under
`public/` and loaded by their same-origin URL. The server exposes only
`public/`, `src/`, and `test-fixtures/`, and binds to `127.0.0.1`.
Set the `PORT` environment variable to change the default port.
These are locally corrected test/reference fixtures, not NGN product code or
pristine upstream conformance evidence. See [provenance](test-fixtures/PROVENANCE.md).
Place additional trusted HTML exhibits and their relative assets under `public/`
and enter their served URL. A filesystem path or a different server origin cannot
be attached directly. The server exposes only `public/`, `src/`, and
`test-fixtures/`, binds to `127.0.0.1`, and denies paths escaping those directories.
For a port conflict, set `$env:PORT='4175'` before `npm start` and use that origin.
## Verification
@@ -41,240 +59,53 @@ python devlog_editor.py --validate
git diff --check
```
With the server running, open
`http://127.0.0.1:4173/test-fixtures/host-verification.html` and select
**Run verification** for repeatable real-browser transport tests against all
three exhibits. Manual admin UI and native exhibit gesture checks are recorded
in [the Step 4 report](STEP4-MVP-REPORT.md).
Run the browser suite at `/test-fixtures/host-verification.html`; its timestamped
results appear on the page and in the browser console. The normal operator UI
checks and external SciFi-XZBT preparation are documented in
[Step 5 verification](test-fixtures/STEP5-VERIFICATION.md). Saved browser evidence
is under `test-fixtures/evidence/`. No source edits or dedicated harness are
needed for ordinary operation.
## Implementation boundaries
## Canonical documentation
- `src/host.js`: session/request correlation, catalog, state cache, events,
synchronization, and control operations.
- `src/validation.js`: descriptor, value, and clarified argument validation.
- `src/transport/post-message.js`: same-origin frame transport only.
- `src/ui.js` and `public/`: descriptor-driven engineering interface.
- `server/serve.js`: loopback static server with explicit served directories.
- `tests/`: focused automated host and server tests.
- `test-fixtures/`: copied reference exhibits and real-browser verification.
This repository is the canonical home for the shared
[XZBT Exhibit Contract Specification 5.2](docs/contract/XZBT-Exhibit-Contract-Specification-v5.2.md)
and [XZBT Exhibit Authoring Guide 5.2](docs/authoring/XZBT-Exhibit-Authoring-Guide-v5.2-Step3.7.md).
The [NGN Implementation Plan 5.2](docs/architecture/XZBT-NGN-Exhibit-Engine-Implementation-Plan-v5.2.md)
also belongs here. Its historical phase numbering describes the longer roadmap;
the current Step 5 completion pass does not authorize those later features.
SciFi-XZBT is an external exhibit implementation, not the NGN architecture.
`docs/reference/` contains external implementation context, not host requirements.
The state display is a cache of exhibit reports. Events update reported values;
editable fields are drafts and are submitted only when Set/Invoke is selected.
Draft fields start from the first snapshot and do not overwrite themselves on
each incoming event. Registry/capability rediscovery rebuilds the controls.
Logs retain the latest 200 entries in memory. The interface intentionally has
no persistence, accounts, MIDI, scenarios, webhooks, packaging, or orchestration.
## Implementation and MVP boundary
## Template and publishing records
- `src/host.js`: negotiation, requests, discovery, state cache, events and recovery.
- `src/connection.js`: URL validation and frame load/disconnect/reconnect lifecycle.
- `src/validation.js`: descriptor, state value and argument validation.
- `src/transport/post-message.js`: same-origin frame transport.
- `src/ui.js`, `public/`: generic operator interface.
- `server/serve.js`: loopback static server.
- `tests/`, `test-fixtures/`: automated checks, reference fixtures and browser evidence.
A starter template and baseline structure for projects compatible with
[Labyricorn](https://www.labyricorn.com).
The MVP supports one exhibit, Contract 5.2 discovery, generic target rendering,
state inspection, set/invoke, capabilities, events, session/revision/sequence
tracking, reconnect and synchronization recovery. It has in-memory state only;
logs retain 200 entries. Idle polling is not enabled. The last connection URL is
remembered only until the page is reloaded.
This template provides the required `.labyricorn/` publishing records, assistant
guidance files (`AGENTS.md`), devlog structure, and the standalone
`devlog_editor.py` management utility for local validation and GUI editing.
Not implemented: multi-surface presentation, casting/display endpoints, MIDI,
MCP/webhooks, scenarios/recording, telemetry acquisition, multi-exhibit
orchestration, persisted operator configurations, remote deployment, accounts,
databases, cloud services, plugins, commercial licensing or production branding.
---
## Publishing records
## Overview
Projects published on Labyricorn maintain their own exhibition pages and
development logs directly inside their Git repositories under the `.labyricorn/`
directory. The Labyricorn site importer periodically synchronizes these records
as read-only content.
This template includes:
- **`.labyricorn/` publishing structure**: Validated Lektor-format records for
project identity and development logs.
- **`devlog_editor.py`**: Standalone GUI and CLI tool for managing devlog entries,
validating publishing contracts, and safely publishing changes.
- **`AGENTS.md` instructions**: Scoped assistant instructions at repository root
and publishing directories to ensure AI assistants adhere to the publishing
contract.
- **`.gitignore`**: Configured exclusions for Python environments, caches, and build
artifacts.
---
## Directory Structure
```text
.
├── .gitignore
├── .labyricorn/
│ ├── AGENTS.md # Assistant instructions for publishing content
│ ├── README.md # Publishing structure documentation
│ ├── project/
│ │ ├── AGENTS.md # Instructions for the project exhibition record
│ │ ├── contents.lr # Project identity and exhibition narrative
│ │ └── <optional logo> # Project logo (PNG, JPEG, WebP)
│ └── devlog/
│ ├── AGENTS.md # Instructions for devlog records
│ ├── contents.lr # Devlog index record
│ └── <entry-slug>/ # (Optional) Devlog entry directories
│ ├── contents.lr # Devlog entry record
│ └── <optional img> # Entry attachments (PNG, JPEG, WebP)
├── AGENTS.md # Assistant instructions for the repository
├── devlog_editor.py # Standalone devlog editor & validator
├── LICENSE # License file
└── README.md # Project documentation
```
---
## Getting Started
### 1. Configure the Project Identity
Edit `.labyricorn/project/contents.lr` to set your project details:
```ini
_model: project
---
schema_version: 1
---
project_id: my-project-id
---
title: My Project Title
---
summary:
A concise summary of the project for listings and cards.
---
status: active
---
started: 2026-08-23
---
author: Author Name
---
repository_url: https://git.labyricorn.com/Owner/my-project
---
default_branch: main
---
tags: python, web, tool
---
body:
An exhibition narrative describing the project background, goals, and features.
```
#### Project Fields:
- `project_id`: Stable lowercase hyphenated slug (e.g. `my-project`).
- `title`: Display title for the project.
- `summary`: Short multi-line summary.
- `status`: One of `active`, `released`, `maintained`, or `archived`.
- `started`: Start date in `YYYY-MM-DD` format.
- `author`: Author or organization name.
- `repository_url`: Public credential-free HTTPS Git URL.
- `default_branch`: Target branch name (e.g. `main`).
- `logo`: (Optional) Local filename of an image inside `.labyricorn/project/`.
- `tags`: Comma-separated technology or topic labels.
- `body`: Markdown narrative of the project.
### 2. Configure the Devlog Index
Edit `.labyricorn/devlog/contents.lr` to customize the devlog title and summary:
```ini
_model: devlog
---
schema_version: 1
---
title: My Project development log
---
summary: Milestones and development updates for My Project.
```
### 3. Add Devlog Entries
To add an entry manually, create a directory under `.labyricorn/devlog/<entry-slug>/`
containing `contents.lr`:
```ini
_model: devlog-entry
---
schema_version: 1
---
title: Initial Project Milestone
---
date: 2026-08-23
---
author: Author Name
---
summary:
Overview of the milestone accomplishments.
---
tags: release, setup
---
source_commit: <40-character-commit-hash>
---
body:
Detailed Markdown description of the milestone, technical decisions, and progress.
```
Alternatively, use `devlog_editor.py` to create and edit entries interactively.
---
## Devlog Editor
The included `devlog_editor.py` script is a standalone utility with zero external
dependencies (uses Python standard library and Tkinter).
### CLI Validation
Validate all project and devlog records without opening a GUI:
```bash
python devlog_editor.py --validate
```
### Graphical Editor
Launch the Tkinter management interface to view repository status, draft entries,
and publish updates:
```bash
python devlog_editor.py
```
Features of the GUI editor:
- **Repository status**: Displays current branch, remote, and ahead/behind counts.
- **Entry manager**: Create, edit, and delete devlog entries with automatic slug and date handling.
- **Publishing safety**: Stages and commits only `.labyricorn/` publishing files, leaving application source files untouched.
---
## Publishing Rules & Constraints
The Labyricorn site importer enforces strict validation rules on imported repositories:
1. **Native Lektor Records**: Records must be named `contents.lr` and declare `schema_version: 1`.
2. **No Raw HTML**: HTML tags (`<script>`, `<style>`, `<div>`, etc.) are prohibited in text fields and Markdown bodies.
3. **Approved Images**: Attachments must be PNG, JPEG, or WebP files located within the record directory. Files must match their magic-byte signatures.
4. **Limits**: Up to 100 imported files, maximum 5 MiB per file, and maximum 20 MiB total per project snapshot.
5. **Source Commits**: Devlog `source_commit` values must be valid 40-character commit hashes existing on the branch history.
6. **No Symlinks or Executables**: Linked paths and executable scripts under `.labyricorn/` are rejected.
---
## Assistant Guidance (`AGENTS.md`)
This repository uses hierarchical `AGENTS.md` files to guide coding assistants:
- **`AGENTS.md` (Root)**: General project guidelines, authorization boundaries, and devlog practices.
- **`.labyricorn/AGENTS.md`**: Publishing boundary contract and security rules.
- **`.labyricorn/project/AGENTS.md`**: Rules for editing project exhibition metadata.
- **`.labyricorn/devlog/AGENTS.md`**: Standards for crafting verifiable devlog entries.
Coding assistants working in this repository should always review the nearest
applicable `AGENTS.md` before making changes.
---
`.labyricorn/` holds this project's Lektor exhibition and development records.
See [publishing guidance](.labyricorn/README.md) and scoped `AGENTS.md` files.
`python devlog_editor.py` opens the standalone publishing editor;
`python devlog_editor.py --validate` validates records without opening the GUI.
Application code lives outside `.labyricorn/`.
## License
This template is released into the public domain under the [Unlicense](LICENSE).
See [LICENSE](LICENSE).