docs(requirements): tighten public api rows

Add explicit northstar ring fields to public_api requirements, remove planning wording, and split page-boundary guidance from beginner escape-hatch guidance.

req: public_api/001

req: public_api/002

req: public_api/003

req: public_api/004

req: public_api/005

req: public_api/006
This commit is contained in:
slhx agent
2026-06-25 15:07:44 +02:00
parent 99bc734297
commit b32ee3ee0a
2 changed files with 9 additions and 6 deletions
+1 -1
View File
@@ -57,7 +57,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file
- Use the same Workout command surface for tests, production build, and mobile release: `cargo run -p hemx-xtask -- workout test`, `cargo run -p hemx-xtask -- workout build`, `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-release`, and `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-verify`; Android/iOS SDKs, store submission targets, and signing remain external blockers, not repo-owned secrets. req: examples/006 req: examples/011
- hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus EffectBatch ops. req: laws/001
- Routing, auth, sessions, transport, transitions, sync, and storage belong in integration/user crates.
- Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003
- Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, render/page helpers, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, raw render/lower calls, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: public_api/001 req: public_api/002 req: public_api/003 req: public_api/005 req: public_api/006 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003
- Typed partial swaps should stay expressed as generated target plus rendered partial plus swap kind, not selector-driven rerendering; HTTP, page navigation, push, and island behavior adapt around that loop, and docs should layer new primitives progressively. req: canonical_authoring/002 req: canonical_authoring/014 req: modes/001 req: progressive_disclosure/004 req: page_swap/001 req: page_swap/002 req: page_swap/003
- `examples/html_examples` is the copy-paste HTML pattern gallery for htmx-style examples; keep exact htmx URL slugs visible while translating behavior to boring `.heml`, generated resources, and server-owned Rust state, not HTMX syntax or selector targeting. Boost containers enhance same-origin descendants only and preserve native external/download/new-tab behavior. req: htmx_equivalents/001 req: htmx_equivalents/003 req: htmx_equivalents/005 req: examples/007 req: page_swap/007 req: page_swap/008
- 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; do not treat it as a mobile framework or store-submission bot. req: ceremony/005 req: ceremony/006 req: ceremony/007
+8 -5
View File
@@ -350,19 +350,22 @@ a `data-*` handle param is statically known or runtime-extracted. [north_star]
## public_api
### req: public_api/001
001 The generated API is the primary public authoring API. Most user code should return generated partial, text, keyed-row, form, page, nav, or island/event commands, not raw `Effect` constructors or raw render/lower calls.
0 001 The generated API is the primary public authoring API. User code returns generated partial, text, keyed-row, form, page, nav, or island/event commands, not raw `Effect` constructors or raw render/lower calls. [north_star]
### req: public_api/002
002 `Effect`, `EffectWriter`, `ResourceId`, `ResourceRef`, and raw opcodes are advanced APIs. They must not appear in beginner docs, generated examples, or common diagnostics.
0 002 `Effect`, `EffectWriter`, `ResourceId`, `ResourceRef`, and raw opcodes are advanced APIs. They must not appear in beginner docs, generated examples, or common diagnostics. [north_star]
### req: public_api/003
003 Every generated command returns `impl IntoEffect` and composes through tuple composition.
0 003 Every generated command returns `impl IntoEffect` and composes through tuple composition. [north_star]
### req: public_api/004
004 If a common UI operation requires raw `EffectWriter`, the public API is considered incomplete.
0 004 If a common UI operation requires raw `EffectWriter`, the public API is incomplete. [north_star]
### req: public_api/005
005 Beginner-facing page/template composition uses generated render or page helpers. Direct `SafeHtml` construction, raw `html(...)`, raw `target(...)`, raw route fragments, `hemx::advanced::render(...)`, and explicit `ui::render(...)` calls are advanced escape hatches and must not appear in beginner examples or docs. Server-rendered page boundaries may use `hemx::page(...)`; handlers and ordinary partial updates must use generated target/form/page commands.
0 005 Beginner-facing page/template composition uses generated render or page helpers. Direct `SafeHtml`, raw `html(...)`, `target(...)`, route fragments, `hemx::advanced::render(...)`, and explicit `ui::render(...)` are advanced escape hatches. [north_star]
### req: public_api/006
0 006 Server-rendered page boundaries may use `hemx::page(...)`; handlers and ordinary partial updates must use generated target/form/page commands. [north_star]
---