> Published subset: four reviewed demos beside the original Celebration.js. The historical full-source development record below also describes packages that are not part of this deployment.

# Zyel Lab engineering handoff

Author-facing tutorials: **Chason Arthur**. The byline identifies the tutorial series; it does not claim Chason manually authored every generated line or operated the examples at production scale.

## Source and scope

Base: `8e573b8` from `chasonarthur/zyel.io` origin/main, fetched 2026-10-25. Integration branch `codex/lab-four-demos-20261025` retains its original name after the owner added the fifth input-resilience story. The original working checkout was dirty and is intentionally separate. Nothing from the concurrent CRM/admin changes was staged. No project AGENTS.md or .agents/skills existed in the base tree; standing user prohibition on OpenAI Sites was followed.

Six demo stories with companion tutorials, a supporting architecture field note, and one shared foundation. The Gateway keeps its independently reviewed standalone presentation and public-reference corpus; the five shared-shell demos retain the synthetic operations dataset. A synthetic 72-location dataset uses approximate city centers and deterministic offsets. Revenue and ticket counts are invented. No CRM records, credentials, private documents, model conversations or real orders belong in these fixtures.

## Reproduce the static UI

Use Node 24 (tested 24.19.0). From the repository root:

```sh
node lab/tools/serve.mjs
```

Visit `http://127.0.0.1:4173/lab/`. The preview serves only static public assets and refuses backend/PHP/source/test/tool paths. Each demo's tutorial documents its separate backend/test workflow. The public browser demos are explicitly synthetic where the backend is not connected. A static mock is not evidence of real authorization.

Run shared unit tests with `node --test lab/shared/tests/storage.test.mjs`. Browser tests need Playwright 1.62.1 and its Chromium browser. Run `node lab/tools/foundation-browser.mjs` with the preview running. `PLAYWRIGHT_MODULE` can identify an existing local Playwright ESM module; `LAB_ORIGIN` overrides the loopback URL. Set `PLAYWRIGHT_BROWSERS_PATH` if installed browser binaries live elsewhere. Do not run attack traffic against public URLs.

## Shared contracts

- `shared/data.mjs`: frozen synthetic dealers and provenance.
- `shared/storage.mjs`: `createStore(scope, defaults, validate)` exposes cloned get/set/reset/status/subscribe. Values must pass a strict boolean validator, JSON depth/size/key checks and a version envelope. Namespace `zyel.lab:v2:<scope>`, 30-day expiration, validated v1 migration, reset corrupted data, memory-only fallback on denied/full storage. This is device/browser-local and offers no account sync. Browser clearing loses preferences.
- `shared/runtime.mjs`: an allowlist controls theme, typography, scale, spacing, density, navigation, radius, focus and motion. It never accepts raw CSS, URLs, HTML or templates. Global preferences affect the five new owned shells; Celebration keeps its existing dedicated effects playground and controls.
- `shared/table.mjs`: lazy self-hosted DataTables **3.1.4**, ColReorder **3.1.2** (official npm metadata checked 2026-10-25). Table namespace includes route + table ID; column names stable. A custom state callback validates named DataTables 3 sorts, searches, visibility, paging and column permutation. `stateDuration` is intentionally 30 days instead of default 7200 seconds. Column filtering is bounded, regex disabled. Use DataTables API for rows, never Vue `v-for` on the same table body.
- Header/footer slots `[data-lab-header]` and `[data-lab-footer]`; call `initShell({project,title,description})` once. Heavy frameworks/map code belong on their demo routes and load only when used.

## Architecture and provenance

```mermaid
flowchart LR
  Lab[Existing Zyel Lab / Celebration] --> Routes[Six isolated demo routes]
  Routes --> Shell[Owned Zyel shell and appearance allowlist]
  Routes --> Fixture[Synthetic operations / articles / OTP challenges]
  Shell --> Local[Versioned browser preferences only]
  Routes --> Review[Human review and explicit integration boundaries]
  Review -. separately enabled only after approval .-> Backend[Laravel / AI / AWS adapters]
```

GIS hosting has separate responsibilities: static app assets, public/synthetic FeatureLayer data or an authorized hosted feature service, and a controlled data publication/update job. Query fixtures show record-limit recovery; they are not a hosted service SLA. The prototype is not the three-dashboard ARC828 deliverable.

## Security and storage boundary

Keep backend source, `.env`, tools, tests, package managers, database fixtures and logs outside the public document root in a release package. Do not copy whole demo source folders into a production web root. The release manifest must allowlist static files and separately deploy backend services only with exact approved configuration. PHP provider endpoint stays disabled unless approved. No new credentials or access grants were created. OTP is a synthetic verifier, not a replacement for real MFA. Format regex does not authenticate anyone or prove an attack. No browser preferences store credentials, private records or conversations by default.

## Verification and release gates

Prepared, tested, reviewed and live are different states. Evidence generated under `lab/evidence/` is local test evidence and never itself confirms publication. Each independent reviewer inspects UI/code/tutorial/tests in three bounded passes; defects and rechecks are saved in the release evidence bundle. Unresolved engine/browser/provider limitations remain named.

Before publication: review the complete source diff and evidence; ensure MySQL engine plans/integration are actually executed or visibly marked pending; authorize any live adapter or infrastructure separately; build a static allowlist package; verify no secrets/backend files are served; back up the existing deployed Lab; stage and check the six routes and Celebration on the same server configuration. Open a draft PR only. No production action is authorized by tests alone.

Rollback: preserve the prior Lab directory/release hash; switch the server's release pointer or restore the backed-up Lab files, leaving CRM/admin intact. Backend migrations need their own reversible procedure and backup; do not run them as part of a static release. Browser preference version bumps must retain validated migration or reset controls. Verify deployed URLs and file hashes/readbacks before marking live.

## Maintenance

Pin and retest each dependency upgrade. Refresh source citations and provider compatibility limits. Re-run bounded adversarial cases and keyboard/mobile checks. Rebaseline measured benchmarks with machine/runtime, seed, data size, warmups, sample count and p50/p95. Synthetic repeated rows are load fixtures, not production traffic claims. Review local-only persistence, expiration and schema migrations with every table/data-contract change.

Official references: [DataTables stateSave](https://datatables.net/ref/core/option/stateSave), [stateDuration](https://datatables.net/ref/core/option/stateDuration), [callbacks](https://datatables.net/ref/core/option/stateSaveCallback), [Vue integration](https://datatables.net/manual/components/vue/), [MDN Web Storage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API), [ArcGIS component transition](https://developers.arcgis.com/javascript/latest/components-transition-plan/), [feature queries](https://developers.arcgis.com/documentation/portal-and-data-services/data-services/feature-services/query-features/), [Vue security](https://vuejs.org/guide/best-practices/security).