From 867c730ce95ea67cdaeca492ab550436abd043e2 Mon Sep 17 00:00:00 2001 From: slhx agent Date: Thu, 25 Jun 2026 13:46:35 +0200 Subject: [PATCH] docs(requirements): split generated helper escape hatches Split the oversized dx/006 row into preferred helper, hidden render/lower, and escape-hatch surface requirements. req: dx/006 req: dx/009 req: dx/010 --- AGENTS.md | 1 + REQUIREMENTS.md | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index eebefb2..d559822 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file ## Requirements-first TDD - Write requirements as desired behavior, not as a snapshot of current behavior. +- Keep each requirement row to one checkable obligation; split oversized examples, escape hatches, or negative cases into separate IDs. - First split intent into broad error classes: what can go wrong, and what outcome must hold. - Test the largest risky classes before narrow examples. - Add adversarial tests for malformed, hostile, ambiguous, missing, duplicated, and boundary inputs. diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index 42db5b0..e1f1f95 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -112,7 +112,13 @@ client app state framework. 005 Error messages must explain fixes in author language, not internal language. Say “add `h-key="todo.id"` to this `h-for`”, not “missing ScopeKey for ResourceRef”. ### req: dx/006 -006 Generated object-like helpers are the preferred authoring API and are re-exported at the component root: `todos.append(todo)`, `todo_row.replace(todo)`, `todo_row.remove(todo_id)`, `summary.set(text)`, `new_todo.clear()`, `new_todo.focus("title")`, `page.replace(view)`, and `game.emit(event)`. These helpers hide hemplate rendering and resource lowering in the common path. Namespaced `targets`, `handles`, `forms`, and raw `advanced::slots` modules remain compatibility/organization and escape-hatch surfaces, not the ordinary call-site shape. The public facade may expose explicit `render(view)`, `target(name)`, `html(value)`, `lower(html)`, or raw effect constructors only as named escape hatches; they must not appear in beginner-prelude exports, canonical handler examples, or ordinary docs. [north_star] +006 Generated object-like helpers are the preferred authoring API and are re-exported at the component root, e.g. `todos.append(todo)`, `todo_row.replace(todo)`, `summary.set(text)`, `new_todo.clear()`, and `page.replace(view)`. [north_star] + +### req: dx/009 +009 Generated object-like helpers hide hemplate rendering and resource lowering in the common path. [north_star] + +### req: dx/010 +010 Namespaced `targets`, `handles`, `forms`, raw `advanced::slots`, explicit `render(view)`, `target(name)`, `html(value)`, `lower(html)`, and raw effect constructors are compatibility or escape-hatch surfaces, not beginner-prelude exports, canonical handler examples, or ordinary docs. [north_star] ### req: dx/007 007 Tuple composition of `IntoEffect` is the canonical batch syntax: `(a, b, c)` implements `IntoEffect` up to arity 12. `Effect::batch((...))` is available but not required for the happy path.