From 4bca046ed18a796e976f2fd73966119ed2ec20d0 Mon Sep 17 00:00:00 2001 From: slhx agent Date: Fri, 12 Jun 2026 18:15:30 +0200 Subject: [PATCH] docs: bound optional heml editor overlays Make hemx-build diagnostics and the documented .heml syntax surface the authority for any editor overlay, while rejecting a second template language, selector model, formatter, or custom editor framework. req: diagnostics/004 --- AGENTS.md | 1 + REQUIREMENTS.md | 3 +++ docs/diagnostics.md | 10 ++++++++++ 3 files changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6c81923..253e2f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,6 +57,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file - Use `cargo run -p hemx-xtask -- app new PATH` for the generic page/form/keyed-row/notice starter, and `cargo run -p hemx-xtask -- app new --mobile PATH` for the phone-first starter with host capabilities, recovery truth, and release-kit commands. req: ceremony/005 req: ceremony/006 - The public component-reuse explanation lives in `docs/recipes/reusable-partials.md`; do not grow a client component framework to explain partial composition. - 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`; do not create a second template language, selector model, formatter, or custom editor framework. req: diagnostics/004 - JS runtime changes must preserve root-scoped lookup and avoid selectors, VDOM, expressions, and per-node listeners. - 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 diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index 703fca5..6a85cb7 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -675,6 +675,9 @@ what a valid business email is. ### req: diag/003 003 Internal terms (`ResourceId`, `ScopeKey`, `EffectBatch`) must not appear in beginner-facing diagnostics unless `--verbose` is enabled. +### req: diag/004 +004 Optional `.heml` editor overlays must treat `hemx-build` diagnostics and the documented `.heml` syntax surface as authority; they may present compiler-shaped diagnostics, completion, hover, and navigation, but must not own a second template language, formatter, selector model, or custom editor framework. [north_star] + --- ## test diff --git a/docs/diagnostics.md b/docs/diagnostics.md index 0f36302..318bbbc 100644 --- a/docs/diagnostics.md +++ b/docs/diagnostics.md @@ -57,6 +57,16 @@ Avoid beginner-facing messages that suggest `ResourceId`, `ResourceRef`, raw escape hatch is genuinely required, say that it is advanced and name the safer normal path first. req: public_api/002 req: public_api/005 +## Editor overlay boundary + +A `.heml` editor overlay is optional and subordinate to the compiler. It may read +`docs/hemplate-syntax.md`, run or reuse `hemx-build` diagnostics, and present +compiler-shaped diagnostics, completion, hover, and navigation for documented +syntax and generated targets. It must not define a second template language, +formatter, selector targeting model, JavaScript expression layer, or custom editor +framework. If editor feedback disagrees with `hemx-build`, `hemx-build` wins. +req: diagnostics/004 + ## Verification anchors Current recurring checks cover the most common classes: