diff --git a/AGENTS.md b/AGENTS.md index 811c8a2..18aa165 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,6 +65,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file - The stable public `.heml` authoring surface lives in `docs/hemplate-syntax.md`; Hemlate examples must use that real hemplate syntax, not Vue/Handlebars sketches. - Optional `.heml` editor overlays must share authority with `hemx-build` diagnostics and `docs/hemplate-syntax.md`; `hemx-lsp` owns editor protocol glue for diagnostics/completion/hover and derive-known template facts, while VS Code/Cursor/Neovim keep normal HTML/tree-sitter tooling. Do not create a second template language, selector model, formatter, Rust type system, or custom editor framework. req: diagnostics/004 req: diagnostics/005 req: diagnostics/006 - JS runtime changes must preserve root-scoped lookup, fail-closed request handling, root-scoped error outlets, and tiny pending/failure/trigger-timing conventions without selectors, VDOM, expressions, or per-node listeners. req: runtime/005 req: convention/001 req: convention/003 req: convention/005 req: convention/007 +- Opaque island JavaScript is a leaf adapter for high-frequency local behavior only; it must not introduce a component runtime, client state graph, VDOM, or second UI model. req: canonical_authoring/017 - Host capability adapters must stay at the `hemx-host` boundary: they may call host APIs and return host events, but they must not mutate DOM or own app/domain state. req: host/002 - Local/offline app behavior should be commands/events/projections; do not add `hemx-local`, stored DOM patches, or stored `EffectBatch` truth without a proven reusable contract. req: local/001 req: local/002 - Axum apps should serve and load the shared runtime through hemx-axum helpers such as `runtime_js_path()` and `runtime_js()`, not hard-coded `/hemx.js` URLs or app-owned cache-busting strings. diff --git a/README.md b/README.md index ee10db9..fa28706 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ req: failure/004 req: derive_handler/004 checked, but hemx does not introduce a styling runtime. - Custom JavaScript belongs at explicit opaque leaf boundaries: charts, maps, editors, Web Components, or similar widgets. Islands communicate through - generated handles/events and do not create a second UI model. req: canonical_authoring/007 req: interop/003 + generated handles/events and do not create a second UI model. req: canonical_authoring/007 req: canonical_authoring/017 req: interop/003 ## Production boundary diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index 98f5868..f5f5269 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -92,7 +92,10 @@ client app state framework. 013 Explicit primitives, raw targets, raw HTML, raw effects, manual registries/form parsing, low-level ids/opcodes, wire formats, and raw routes remain named escape hatches or internals around the same render/target/effect/transport model. [north_star] ### req: canonical/007 -007 Opaque islands are explicit leaf adapters: templates declare `data-hemx-island` and optional generated handles/events; server code may emit snapshots/events such as `ui::game.emit(event)`, while island JS owns only high-frequency local behavior. Islands do not introduce a component runtime, client state graph, VDOM, or second UI model. [north_star] +007 Opaque islands are explicit leaf adapters: templates declare `data-hemx-island` and optional generated handles/events; server code may emit snapshots/events such as `ui::game.emit(event)`. [north_star] + +### req: canonical/017 +017 Island JavaScript owns only high-frequency local behavior and must not introduce a component runtime, client state graph, VDOM, or second UI model. [north_star] ### req: canonical/008 008 Offline/PWA support is opt-in adapter territory. Server-first hemx may fail interactions while offline; cached shells and local-sync queues live in crates such as `hemx-pwa` or `hemx-sync`, reuse generated slots/effects, queue explicit patches, and reconcile with server-canonical effects. Core hemx must not gain a mandatory client state graph, scheduler, CRDT, or local app runtime. [north_star]