diff --git a/AGENTS.md b/AGENTS.md index 7db1b10..9c3725a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,7 +55,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file - Example behavior tests should prefer `hemx_test` generated-resource assertions over raw slot constants or raw effect/payload matching; keep browser selector helpers as test adapters only, not authoring APIs. req: test/008 req: test/009 req: test/010 - Run the workout product exemplar with `cargo run -p hemx-xtask -- workout dev` and open `http://127.0.0.1:3028`; set `HEMX_WORKOUT_ADDR=127.0.0.1:3030` if the default port is busy. Its durable visual direction and recovery expectations live in `examples/workout/DESIGN.md`. req: examples/008 - 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, and do not imply a broad `hemx-mobile` framework. req: examples/006 req: examples/011 req: examples/013 -- hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus the closed EffectBatch op set, and treat DOM details as runtime lowering. Public identifiers should flow through typed wrappers over internal `ResourceId`/`ResourceRef`, not special-case opcodes. Wire output lowers symbolic authoring names to compact metadata and postcard/form-encoded envelopes, not JSON. ABI/schema versions and build fingerprints must guard runtime/server compatibility. v0 scope is the checked hypermedia core plus page/runtime/wire/diagnostic/test/axum proof, not optional sync/wasm/query/auth/router breadth. req: v0_scope/001 req: v0_scope/002 req: v0_scope/005 req: laws/001 req: invariant/001 req: invariant/005 req: typed_id/001 req: typed_id/003 req: effect_algebra/001 req: effect_algebra/006 req: wire/001 req: wire/002 req: wire/003 req: wire/004 req: wire/005 req: wire/006 req: abi/001 req: abi/002 req: abi/003 req: abi/004 req: abi/005 +- hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus the closed EffectBatch op set, and treat DOM details as runtime lowering. Workspace crates stay separated, stable-Rust-compatible, and free of kitchen-sink boundaries; new primitives must delete special cases. Public identifiers should flow through typed wrappers over internal `ResourceId`/`ResourceRef`, not special-case opcodes. Wire output lowers symbolic authoring names to compact metadata and postcard/form-encoded envelopes, not JSON. ABI/schema versions and build fingerprints must guard runtime/server compatibility. v0 scope is the checked hypermedia core plus page/runtime/wire/diagnostic/test/axum proof, not optional sync/wasm/query/auth/router breadth. req: v0_scope/001 req: v0_scope/002 req: v0_scope/005 req: laws/001 req: invariant/001 req: invariant/005 req: typed_id/001 req: typed_id/003 req: effect_algebra/001 req: effect_algebra/006 req: wire/001 req: wire/002 req: wire/003 req: wire/004 req: wire/005 req: wire/006 req: abi/001 req: abi/002 req: abi/003 req: abi/004 req: abi/005 req: misc/001 req: misc/002 req: misc/003 req: misc/004 req: misc/005 req: misc/006 req: misc/007 req: misc/008 req: misc/009 req: misc/010 - Routing, auth, sessions, transport, transitions, sync, async data helpers, and storage belong in integration/user crates; hemx-axum preserves normal HTTP auth, credentials, CSRF, and progressive-enhancement semantics rather than defining policy in core. Sync is optional integration state reconciliation over push/transport, not core. req: auth/001 req: auth/002 req: auth/003 req: auth/004 req: auth/005 req: async_data/001 req: async_data/002 req: async_data/003 req: sync/001 req: sync/008 - Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, view wrappers, render/page helpers, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, raw render/lower calls, raw HTML construction, imperative DOM mutation, 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: invariant/003 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: view/001 req: view/002 req: html_safety/001 req: html_safety/003 req: html_safety/005 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. Navigation is an effect/page-swap concern, not a core router framework, and enhanced links preserve real anchors/history semantics. Push streams carry postcard EffectBatch over server-owned SSE/WebSocket transport and keep `data-hemx-sse` root-scoped/same-origin by default. Preserve keyed/optional scope identity for addressable loop nodes and prefer generated keyed-slot helpers over low-level keyed calls. req: canonical_authoring/002 req: canonical_authoring/014 req: modes/001 req: scope/001 req: list/001 req: list/002 req: list/003 req: list/004 req: list/005 req: nav/001 req: nav/002 req: nav/003 req: nav/004 req: nav/005 req: push/001 req: push/002 req: push/003 req: push/004 req: push/005 req: push/006 req: push/007 req: progressive_disclosure/004 req: page_swap/001 req: page_swap/002 req: page_swap/003 diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index b5e7f6d..fb54dfd 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -1060,31 +1060,34 @@ what a valid business email is. [north_star] ## misc ### req: misc/001 -001 Workspace layout: `hemx-core` (types + postcard schema, no_std), `hemx-derive` (proc-macros), `hemx-build` (surface consumer + code generation), `hemx-axum` (integration), `hemx-js` (runtime single file), `hemx-transition` (optional), `hemx-sync` (optional), `hemx-wasm` (optional). No kitchen-sink crate. +0 001 Workspace layout separates `hemx-core`, `hemx-derive`, `hemx-build`, `hemx-axum`, `hemx-js`, and optional transition/sync/wasm crates; no kitchen-sink crate. ### req: misc/002 -002 All crates compile on stable Rust. MSRV 1.80. `hemx-core` has zero proc-macro dependencies. +0 002 All crates compile on stable Rust. MSRV 1.80. `hemx-core` has zero proc-macro dependencies. ### req: misc/003 -003 Three execution modes supported: server-first (request/response), client-local WASM (requestAnimationFrame, no round-trip), and hybrid sync (local + remote via `hemx-sync`). Modes are opt-in per handler, not global. +0 003 Three execution modes are supported: server-first, client-local WASM, and hybrid sync. Modes are opt-in per handler, not global. ### req: misc/004 -004 The only required user-facing proc-macro in hemx core is `#[hemx::handler]`. -Optional ergonomic macros may exist: `#[hemx::surface]`, `#[hemx::component]`, -`#[hemx::app]`, and integration-crate macros such as `#[hemx::island]` or -`#[hemx_sync::presence]`. No `!` call-syntax macros. +0 004 The only required user-facing proc-macro in hemx core is `#[hemx::handler]`; optional ergonomic macros may exist, but no `!` call-syntax macros. ### req: misc/005 -005 Source spans are present on every Surface node, attribute, and scope. Error messages cite file, line, and column. This is non-negotiable for DX. +0 005 Source spans are present on every Surface node, attribute, and scope. Error messages cite file, line, and column. This is non-negotiable for DX. ### req: misc/006 -006 Authoring hemx attributes use the `data-hemx-*` prefix. Runtime lowering may emit compact `data-hid`, `data-sid`, `data-key`, atom ids, and control ids. No unprefixed custom attributes. +0 006 Authoring hemx attributes use the `data-hemx-*` prefix. Runtime lowering may emit compact ids. No unprefixed custom attributes. ### req: misc/007 -007 Id allocation is deterministic from canonical symbol paths. Ids are stable across builds unless the symbol path changes. Deploy mismatch between server and client is caught by a build-schema version check, not silent failure. +0 007 Id allocation is deterministic from canonical symbol paths. Ids are stable across builds unless the symbol path changes. Deploy mismatch is caught by a build-schema version check. ### req: misc/008 -008 Core design rule: add one primitive only if it deletes five special cases. `ScopeKey` deletes: loop keying, component scoping, modal instances, nested forms, portal boundaries. `ResourceId` deletes: special opcodes per kind, separate registries, separate wire formats, separate test APIs. `Effect::event` deletes: plugin API, custom JS bridges, chart adapters, map SDK wrappers. +0 008 Core design rule: add one primitive only if it deletes five special cases. `ScopeKey` deletes loop keying, component scoping, modal instances, nested forms, and portal boundaries. + +### req: misc/009 +0 009 `ResourceId` deletes special opcodes per kind, separate registries, separate wire formats, and separate test APIs. + +### req: misc/010 +0 010 `Effect::event` deletes plugin APIs, custom JS bridges, chart adapters, and map SDK wrappers. ---