hemx/REQUIREMENTS.md

slhx — Semantic, Laterally HX

slhx does not compete with React by becoming a better frontend framework. slhx competes with React by making frontend frameworks unnecessary for most apps.

hemplate owns syntax. hemplate emits surface. slhx consumes surface. slhx owns semantics. JS executes bytecode.

---

pitch

req: pitch/001

001 slhx is checked hypermedia for Rust. Write .heml, write #[slhx::handler], return commands. The compiler checks every cross-file reference. The browser runtime only sees ids and effect bytes. No JS app code required. [north_star]

req: pitch/002

002 No CSS selectors. No hx-* strings. No virtual DOM. No client framework. No hidden global proxy magic. No hydration. No user-authored JavaScript for standard forms, lists, navigation, or server push. [north_star]

req: pitch/003

003 slhx replaces React/Vue not with a UI framework, but with a compiler contract: hemplate knows the surface, Rust knows the types, slhx knows the effects, the browser only executes commands. [north_star]

req: pitch/004

004 The north-star feel: Svelte at the call site, Rust at the boundary. Short handler bodies, compile-checked HTML contracts, one language for server and client logic. [north_star]

---

dx

req: dx/001

001 The common case must feel like writing a Svelte/Vue component: template, state, handlers, and targeted updates. Users should not need to understand Surface IR, ResourceId, EffectWriter, postcard, or runtime opcodes for basic apps. [north_star]

req: dx/002

002 The happy path is: write .heml, write #[slhx::handler], return generated slot/atom commands. No manual ids, no manual registry, no manual serialization, no manual JavaScript. [north_star]

req: dx/003

003 Public APIs are generated around the user's names. If the template declares data-slhx-slot="todo_list", the user gets slots::todo_list, not SlotId(12).

req: dx/004

004 Common handlers must fit in a small function. Advanced contexts (EffectWriter, raw ops, custom encoders) exist but are not part of the beginner path.

req: dx/005

005 Error messages must explain fixes in author language, not internal language. Say “add key todo.id to this loop”, not “missing ScopeKey for ResourceRef”.

req: dx/006

006 Generated resource methods are the preferred authoring API: slots::todo_list.render(view), slots::card.replace(key, view), slots::count.text(42), atoms::user.set(user). These return impl IntoEffect. Raw Effect::render, Effect::set, and EffectWriter remain low-level. [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.

req: dx/008

008 User-authored JavaScript is never required for standard forms, lists, navigation, optimistic actions, or server push. Custom JS is only needed at opaque leaf boundaries such as charts, maps, editors, and Web Components.

---

ceremony

req: ceremony/001

001 A minimal counter app requires one .heml file, one Rust state struct, and one handler function. No manual registry, no manual route table, no manual JS. Under 50 lines of user-authored Rust plus one template.

req: ceremony/002

002 Generated modules are imported through a prelude or component namespace. Users should not manually include $OUT_DIR files in normal apps.

req: ceremony/003

003 build.rs must be a one-liner for the common case: fn main() { slhx_build::app().run().unwrap(); }

req: ceremony/004

004 No API may require users to write numeric ids, raw ResourceIds, raw opcodes, or serialized payloads in normal code.

---

progressive_disclosure

req: pd/001

001 A beginner can build CRUD with only: .heml, #[slhx::handler], Form<T>, generated slots::* methods, and impl IntoEffect.

req: pd/002

002 Atoms are not required for basic server-first apps. They appear only when client-local state, SSR bootstrapped state, or WASM handlers are used.

req: pd/003

003 Sync, transitions, resources/queries, islands, capabilities, and raw EffectWriter are advanced layers. They must not appear in starter examples.

req: pd/004

004 Documentation must present three levels: server-first, client-local, hybrid-sync. Each level introduces only the new primitive it needs.

---

component

req: component/001

001 The primary authoring unit is a hemplate component plus adjacent Rust handlers. A component owns a template root, generated slots, generated handles, generated form checks, and source spans.

req: component/002

002 slhx supports colocated layout: todo_list.heml beside todo_list.rs, with generated APIs namespaced by component to avoid global symbol soup.

req: component/003

003 Generated APIs are component-namespaced by default: ui::slots::todo_row, ui::handles::create, ui::forms::create. Global exports are opt-in only.

req: component/004

004 #[slhx::surface] bridges generated code into a user module. Users write #[slhx::surface] mod ui {} instead of include!(concat!(env!("OUT_DIR"), ...)). slhx-build emits slhx.generated.rs which the macro expands in place. No direct $OUT_DIR includes in user-authored source.

req: component/005

005 An optional #[slhx::component] macro may validate that every handle declared in the template Surface has a corresponding #[slhx::handler] within the annotated module. This is the only macro with cross-handler visibility inside a single module; it remains strictly local. Missing handlers without #[slhx::component] are caught at app mount or test time, not cargo check.

req: component/006

006 #[derive(Hemplate)] structs are natural component boundaries. slhx_build generates APIs per component/template namespace and may merge component Surfaces only at explicit app/root boundaries.

---

codegen

req: codegen/001

001 slhx_build generates three artifacts from the generic Surface IR: (a) slhx.generated.rs containing ergonomic resource modules (slots, handles, forms, atoms), (b) slhx.syms for proc-macro validation, (c) runtime id-lowering tables. slhx_build interprets tool-specific conventions (data-slhx-*, h-for, h-key, form controls) from the Surface. [north_star]

req: codegen/002

002 Generated module slots exposes ergonomic methods: Slot<T>::render(value), Slot<T>::text(value), KeyedSlot<K,T>::append(key, value), KeyedSlot<K,T>::replace(key, value), KeyedSlot<K,T>::remove(key). Methods return impl IntoEffect.

req: codegen/003

003 Generated module handles exports typed constants: Handle<I> where I is Form<T>, a param type, or (). Users rarely reference handles directly; they are consumed by #[slhx::handler] for validation.

req: codegen/004

004 Generated module forms exports FormContract metadata (field names, HTML control kinds, required). #[slhx::handler] compares the Form<T> type against the contract. Domain types (Email, TodoId) remain user-authored; no auto-generated structs.

req: codegen/005

005 Generated module atoms exports Atom<T> for values that must be addressable, hydrated, or synced. Ordinary Rust fields on app/components are not automatically atoms.

---

invariant

req: invariant/001

001 User-authored references are symbolic at author time and numeric at runtime.

req: invariant/002

002 The JS runtime never parses CSS selectors, expressions, or handler names.

req: invariant/003

003 Rust handlers return effects; they do not imperatively mutate DOM.

req: invariant/004

004 Cross-file references fail at cargo check with a precise span.

req: invariant/005

005 slhx core owns effects, typed ids, and registries only. Routing, auth, sessions, transport, transitions, and sync are integration concerns.

---

boundary

req: boundary/001

001 hemplate does not expose a slhx API. It exposes a stable, generic Template Surface IR. slhx is one consumer; a11y tools, test generators, and documentation generators are others.

req: boundary/002

002 hemplate never interprets data-slhx-* or any other tool-prefixed attribute. It records them as raw name: value pairs in the Surface.

req: boundary/003

003 slhx never parses .heml directly. It consumes hemplate.surface.postcard emitted by hemplate_build. slhx interprets tool-specific conventions (data-slhx-handle, data-slhx-slot, etc.) from the generic Surface.

---

surface

req: surface/001

001 hemplate_build scans .heml files and emits $OUT_DIR/hemplate.surface.postcard (postcard-encoded, deterministic, versioned).

req: surface/002

002 The Surface contains: nodes (NodeId, parent, scope, element, attrs, source span), scopes (ScopeKind: Root | If | For { binding, key_expr }), forms (form controls with raw HTML types), and component uses.

req: surface/003

003 Node identity is NodeId in a parent/scope graph. No css_path is used as a primary identifier. An optional debug_path string may exist for diagnostics only.

req: surface/004

004 Form controls in the Surface carry raw HTML facts: ControlKind::Text, ControlKind::Number { min, max, step }, ControlKind::Checkbox, ControlKind::Select { multiple, options }, etc. No Rust type mapping lives in hemplate.

req: surface/005

005 Loop scopes expose the binding name and an optional key_expr (e.g. todo.id). hemplate does not enforce key usage; it only records it for consumers.

req: surface/006

006 Surface schema is versioned (schema_version: u32). Postcard encoding, no JSON. no_std-compatible schema definition so any tool can read it without heavy dependencies.

req: surface/007

007 hemplate-derive does not write Surface files. Surface generation is a build.rs / hemplate_build concern, proc-macro side-effect free.

req: surface/008

008 The Surface records hemplate structural directives as first-class facts: h-for, h-key, h-if, h-else-if, h-else, dynamic +attr bindings, and interpolated attr/text expressions. slhx consumes these facts; it never parses .heml source directly.

req: surface/009

009 Raw/pre-rendered HTML insertions are opaque Surface holes. The parent Surface records the insertion point and source span, but nodes inside inserted HTML belong to the child component Surface or remain invisible to tools.

req: surface/010

010 Attribute values preserve their origin: static literal, dynamic +attr expression, or interpolated template string. slhx param inference consumes these from Surface and never reparses .heml.

---

build

req: build/001

001 Build order: .heml → hemplate_build → hemplate.surface.postcard → slhx_build → slhx.generated.rs + slhx.syms + diagnostics.

req: build/002

002 Proc-macros (#[slhx::handler], #[slhx::surface]) are side-effect free. They read generated artifacts (slhx.syms, slhx.generated.rs) but never parse .heml, never process generic Surface IR, and never write files. Global codegen lives only in build.rs invoked by slhx_build. [north_star]

req: build/003

003 slhx-derive (#[slhx::handler]) reads slhx.syms at expansion time to validate handle names, slot names, and form signatures. It generates only local glue (static fn-table entry) plus compile errors.

req: build/004

004 #[slhx::surface] reads slhx.generated.rs from $OUT_DIR and expands it into the annotated module. It is a pure include/bridge macro with no semantic analysis of its own.

req: build/005

005 A build.rs failure (missing Surface, version mismatch, stale hash) is a hard error before proc-macro expansion.

req: build/006

006 Proc-macros are considered local: they have knowledge of the item they annotate, plus pre-generated symbol tables. They do not have global knowledge of all handlers across the crate. Global checks (e.g. every declared handle has an implementation) are either deferred to app-mount tests or enabled by an optional #[slhx::component] macro.

---

effect

req: effect/001

001 Rust handlers return impl IntoEffect, not a concrete Vec<Effect>. IntoEffect::encode(self, &mut EffectWriter) may write directly into a response buffer, a test collector, or an event stream. Zero-allocation encoding is possible; allocation is not required.

req: effect/002

002 EffectWriter has a fixed canonical op set: Set, Patch, Insert, Remove, Move, Focus, Navigate, Emit. The DOM is one backend; core does not hardcode DOM operations. Wire format is canonical postcard opcodes; Rust API is flexible.

req: effect/003

003 Multiple effects are combined with tuple composition or a method chain on EffectWriter. No ! call-syntax macros.

req: effect/004

004 Effect::render(slot, value) is sugar for Effect::set on a Slot resource. Effect::text(slot, value) is sugar for Effect::set with a text payload.

req: effect/005

005 effects may carry an opaque transition token, but core never interprets or implements transitions. slhx-transition provides transition semantics as an orthogonal integration.

req: effect/006

006 Effect::event(name, payload) dispatches a native CustomEvent on the root element. Core interprets the payload as opaque bytes. Web Components, charts, editors, or legacy JS may listen without slhx knowing about them. [north_star]

req: effect/007

007 Effect::event is the raw escape hatch. Common UI events such as toast, dialog close, focus, and clipboard may have typed helper wrappers (toast("Saved"), nav::push("/dashboard")) in optional crates. Helpers compile to Effect::event or canonical ops.

req: effect/008

008 Small semantic helper types may implement IntoEffect: Toast, Nav, FormError, generated slot commands, generated atom commands. Users compose them by returning tuples.

---

state

req: state/001

001 Typed atoms with Atom<T> are explicit addressable state resources. Read via atom.get(), mutate via atom.set() / atom.update(), publish to the runtime via generated atom commands or Effect::set(atom, value). No hidden global proxy / reactive graph. Atoms are explicit values in struct App.

req: state/002

002 Atoms are not reactive by default. Updating an atom does not re-render anything unless the handler returns an effect targeting consumers. Subscriptions are explicit runtime/store APIs. No automatic component re-render graph.

req: state/003

003 The JS runtime maintains a client-side atom store keyed by AtomId. Runtime values are type-erased postcard bytes. Types are compile-time only. A deterministic TypeHash may be generated by slhx_build for diagnostics, but the JS runtime does not depend on Rust TypeId.

req: state/004

004 SSR pages carry a data-slhx-st base64url-encoded postcard blob on the document root. Runtime decodes it into the client atom store. Atoms computed from server state are immediately available to client-side handlers without a round-trip.

req: state/005

005 Not all state is an Atom. Ordinary Rust fields are preferred unless the value must be independently addressed, bootstrapped, synced, or subscribed. Atoms are explicit resources, not the default state container.

---

form

req: form/001

001 Forms are source of truth in HTML. hemplate Surface exports form shape (controls, names, required, types). slhx checks compatibility with the Rust handler's Form<T> type. No auto-generated structs; domain types (e.g. Email) are first-class. The Surface describes; Rust owns; slhx checks.

req: form/002

002 The handle id is carried as __h in POST application/x-www-form-urlencoded. A JSON body is allowed at the integration boundary (application/json) only if the handler accepts it; core uses form encoding.

req: form/003

003 Handler receives form: Form<CreateTodo>. Validation errors target (FormId, field_name) or generated control ids. The runtime maps them to originating form controls via control ids derived from Surface NodeId, not via slot ids.

---

list

req: list/001

001 Any data-slhx-slot or data-slhx-handle inside a hemplate h-for scope requires a stable key. Preferred syntax: <template h-for="item in &self.items" h-key="item.id"> ... </template>. Without a key, slhx-addressable nodes inside the loop are rejected at build time. Keyed identity is (SlotId, KeyValue).

req: list/002

002 Slots inside a keyed loop receive a composite identity: (SlotId, KeyValue), not a flat id. hemplate records key_expr in the Surface; slhx implements keyed slot lookups.

req: list/003

003 Effects on keyed slots: replace_keyed(slot, key, value), remove_keyed(slot, key), append_keyed(slot, key, value). Mismatch between key type and slot key type is compile-time error.

---

typed_id

req: typed_id/001

001 All public cross-page identifiers (Slot, Atom, Handle, Form) share a single internal primitive ResourceId { kind: ResourceKind, id: u32 }. A concrete runtime target is a ResourceRef { resource: ResourceId, scope: Option<ScopeKey> }. Typed wrappers (Slot<T>, KeyedSlot<K, T>, Atom<T>, Handle<I>, Form<T>) enforce kind safety at compile time. No special-case opcodes per resource kind; effects address resources uniformly. [north_star]

req: typed_id/002

002 ResourceKind is an internal closed enum (Slot, Atom, Handle, Form, Route). External crates may not add variants. Extensibility comes via Effect::event, Effect::emit, or custom IntoEffect implementations, never via new ResourceKind variants in core.

---

async_data

req: async_data/001

001 Async remote data lives in Resource<T> / Query<K, T> / Mutation<I, O>. These are optional, not core primitives. They provide loading/error/refresh semantics without client-side data libraries.

req: async_data/002

002 QueryEffect::reload(res) triggers a re-fetch and re-render. The server sends a new EffectBatch when data is ready. Query/Resource effects live in a separate API surface to keep core small.

---

scope

req: scope/001

001 Scope is a first-class primitive. Keyed loops (h-for), conditional branches (h-if), component instances, modals, tabs, nested forms — all are scopes. A slhx-addressable node inside any dynamic scope must carry a stable ScopeKey. Concrete runtime targets are addressed through ResourceRef { resource: ResourceId, scope: Option<ScopeKey> }. [north_star]

---

wire

req: wire/001

001 Authoring HTML uses symbolic data-slhx-* attributes. Rendered runtime HTML lowers these to compact numeric metadata: data-hid, data-sid, optional data-key, optional atom ids, optional form/control ids, and data-slhx-st for state bootstrap. The browser never sees handler or slot names. data-slhx-root marks a scoped root boundary.

req: wire/002

002 POST bodies carry application/x-www-form-urlencoded with distinguished field __h (handle id). Server routes by numeric id, not by URL path.

req: wire/003

003 Responses are text/html fragments (or application/slhx for push streams). Fragments may contain <template data-slhx> elements whose text content is a base64url-encoded postcard EffectBatch. JS decodes and applies.

req: wire/004

004 Server push is orthogonal: integration crates stream postcard EffectBatch over SSE or WebSocket connections. slhx core owns the effect bytes; transport and connection management are integration concerns.

req: wire/005

005 No JSON anywhere in slhx-internal artifacts. Public request/response envelopes use application/x-www-form-urlencoded; effects and symbols use postcard. application/json is acceptable only at integration boundaries.

---

runtime

req: runtime/001

001 Every slhx tree must declare a root boundary via data-slhx-root on an ancestor element. The JS runtime resolves lookups within that root only. Multiple independent slhx apps/widgets/modals may coexist on the same document without ID collision. [north_star]

req: runtime/002

002 JS runtime attaches a single delegated listener per event type on each data-slhx-root. No per-node listeners. Dispatch resolves target via data-hid / data-sid attributes on the event path scoped to its root.

req: runtime/003

003 The core JS runtime target is under 5KB minified+gzipped. It remains a tiny op interpreter (no selectors, no VDOM, no scheduler, no expressions). It reads postcard EffectBatch bytes and applies them as DOM operations. Optional sync/transition/WASM helpers are separate files.

req: runtime/004

004 RuntimeCaps { binary, wasm, sync, transitions } is exchanged once at init. Handlers may query capabilities and degrade gracefully (e.g. fall back to server request if WASM unavailable). Core does not know about these features; caps are opaque to the wire protocol and only consulted by integrations.

---

js

req: js/001

001 Runtime reads attributes data-hid and data-sid, delegates events on each data-slhx-root, and applies effects by direct DOM mutation scoped to that root.

req: js/002

002 No build step, no virtual DOM, no diffing, no scheduler. Receiving an effect = apply ops immediately in declared order.

req: js/003

003 The runtime implements the canonical EffectBatch opcode schema from slhx-core. DOM-specific operations such as ReplaceHtml, SetText, AddClass, or RemoveKeyed are lowering details generated from canonical resource ops.

---

check

req: check/001

001 All cross-file references verified at cargo check. Unknown handle → hard error. Unknown slot → hard error. Type mismatch between slot and atom → hard error.

req: check/002

002 Dead/missing handle diagnostics are best-effort by default. With #[slhx::component], dead/missing handlers inside the component are checked at cargo check. Without it, missing implementations are caught at app mount or in generated registry tests.

req: check/003

003 Renaming a slot or handle breaks cargo check immediately with a span pointing to the Rust handler or template source.

req: check/004

004 Page-scoped slot lookup: JS runtime resolves data-sid only within the current Page root element.

---

sync

req: sync/001

001 slhx-sync is an optional crate for collaborative / multiplayer state. Provides presence tracking, patch reconciliation, conflict resolution (server-authoritative), and offline queueing. Not part of core.

req: sync/002

002 SyncEffect::send_patch(atom, patch) queues a state diff for server sync. If offline, the patch is stored in a local queue and sent when connection resumes. If online, it is sent immediately via WebSocket/SSE.

req: sync/003

003 Server reconciliation of received patches produces a local EffectBatch only when state changes. Accepted mutations patch shared state without hard-coding specific effects.

req: sync/004

004 SyncEffect::broadcast(channel, effect_batch) sends an EffectBatch to all subscribers of a named channel. Used for presence updates and live collaboration. The server framework manages the transport (WS/SSE).

req: sync/005

005 #[slhx_sync::presence] is an attribute macro on functions that return impl IntoEffect when a user joins or leaves a shared session. Emits SyncEffect::broadcast over a presence channel scoped to the session.

req: sync/006

006 SyncEffect::ack(atom) acknowledges a successful server-side mutation, allowing the client to clear its local optimistic queue for that atom.

req: sync/007

007 slhx-sync uses a flat patch model per atom, not CRDT by default. Server is authoritative; clients apply server-canonical state on conflict. Optional CRDT backend may be provided by a future slhx-crdt crate.

---

interop

req: interop/001

001 Effect::event is the single bridge between slhx and third-party JS. External widgets, charts, and maps listen via native CustomEvent. slhx core does not inspect or manage them. [north_star]

req: interop/002

002 Web Components and custom elements are valid opaque leaf nodes. slhx does not inspect shadow DOM. Escape hatches are leaves, never app foundations.

req: interop/003

003 WASM islands (#[slhx::island]) compile handler code to WASM for client-local execution. The island is a leaf in the DOM; slhx core is unaware of WASM except via the same EffectBatch contract.

req: interop/004

004 Existing hx-* attributes are treated as ordinary raw attributes in the hemplate Surface without slhx semantics. An optional slhx-htmx-migrate tool may read Surface hx-* attrs and suggest equivalent data-slhx-* handlers/effects.

---

test

req: test/001

001 EffectWriter implements a test backend so handlers can be unit-tested without a browser: slhx_test::run(handler, input) returns an EffectInspector with contains(op), has_slot(slot), has_atom(atom), etc.

---

navigation

req: nav/001

001 Navigation is an effect, not a router framework: Effect::navigate(url, mode, scroll, title). Core supports Push, Replace, Redirect. Actual route matching, guards, loaders, and nested routes are outside core.

req: nav/002

002 Navigation modes: Push (history.pushState), Replace (replaceState), Redirect (server-side 302). Scroll behaviour: Preserve, Top, Element(ResourceId). Title is optional.

req: nav/003

003 Navigation enhancement preserves real anchors. Links keep valid href. slhx may intercept enhanced links through data-slhx-handle or data-slhx-nav, but without JS the browser performs normal navigation.

---

client_local

req: client_local/001

001 Client-local handlers use the same function shape as server handlers. Adding client changes the execution backend, not the authoring model.

req: client_local/002

002 Local UI state may live as ordinary fields on the app/component state. Atom<T> is required only when the value must be addressed by effects, synced, hydrated, or subscribed.

req: client_local/003

003 High-frequency UI handlers (drag, pointermove, animation tick) must not require server round-trips or handwritten JS.

---

escape_hatch

req: escape_hatch/001

001 Three sanctioned escape hatches exist: (1) Web Components as opaque leaf nodes, (2) Effect::event for imperative JS interop, (3) WASM islands for CPU-intensive client logic. All three are leaves in the slhx tree, never the app foundation.

---

view_model

req: view/001

001 Slots render view types, not necessarily domain types. Domain-to-view conversion is explicit Rust (From, Into, or constructor). slhx never assumes a domain object is its own view.

req: view/002

002 Generated slot types are allowed to target Display, Hemplate, or explicit view wrappers. Type errors should suggest the expected renderable view type.

---

diagnostics

req: diag/001

001 Every compile-time error must point to both sides of the mismatch when possible: the Rust handler span and the template Surface span.

req: diag/002

002 Diagnostics must include a suggested fix for common cases: missing key, unknown slot, missing form field, optionality mismatch, handler param mismatch, wrong keyed slot type.

req: diag/003

003 Internal terms (ResourceId, ScopeKey, EffectBatch) must not appear in beginner-facing diagnostics unless --verbose is enabled.

---

derive_handler

req: derive_handler/001

001 #[slhx::handler] validates: handle name exists in symbol table, params match form surface or data-* attributes, return type implements IntoEffect. Generate code registers the function in a static lookup table keyed by numeric handle id.

req: derive_handler/002

002 Handler param inference from data-* attributes: when a template declares data-card-id="{card.id}" on a node with data-slhx-handle, the handler may declare card_id: CardId as a parameter. slhx-build checks attribute → param name and type mapping.

req: derive_handler/003

003 Handler parameters are inferred from four sources: Form<T>, data-* attributes on the triggering node, route params supplied by integration crates, and explicit app/context parameters. Missing or incompatible params are compile-time errors with source spans.

req: derive_handler/004

004 The common handler signature forms are: fn h(form: Form<T>, app: &mut App) -> impl IntoEffect fn h(id: Id, app: &mut App) -> impl IntoEffect fn h(event: Event<T>, app: &mut App) -> impl IntoEffect fn h(ctx: Ctx, ...) -> Result<impl IntoEffect, Error>

---

derive_app

req: derive_app/001

001 #[slhx::app] marks an application/root state type and registry entry point. There may be one registry per app/root type, and multiple runtime instances may exist per process. slhx does not require a process-global singleton.

---

ts

req: ts/001

001 TypeScript definitions for slhx-js runtime are shipped as a single .d.ts file. Types mirror the postcard EffectBatch schema for advanced consumers. Tooling must not depend on these types for core functionality; they are developer convenience only.

---

examples

req: examples/001

001 The repository must contain canonical examples that act as API tests: counter, todo CRUD, form wizard, realtime dashboard, local-first kanban.

req: examples/002

002 Each example must have a maximum ceremony budget. The counter example must fit in under 50 lines of user-authored Rust plus one template. Todo CRUD must fit in under 150 lines excluding model definitions.

req: examples/003

003 If an example requires raw EffectWriter, manual ids, manual JS, or manual registry setup, the API is considered too complex.

---

milestone

req: ms/001

001 Milestone app: Local-first Multiplayer Kanban. A board with drag-and-drop cards, 60fps pointer-follow, optimistic updates, offline queue, conflict reconciliation, live presence, and SSR-first rendering — all without React/Vue/VDOM, in a single typed Rust codebase. This acts as the north-star integration test for slhx + hemplate + slhx-sync. [north_star]

---

misc

req: misc/001

001 Workspace layout: slhx-core (types + postcard schema, no_std), slhx-derive (proc-macros), slhx-build (surface consumer + code generation), slhx-axum (integration), slhx-js (runtime single file), slhx-transition (optional), slhx-sync (optional), slhx-wasm (optional). No kitchen-sink crate.

req: misc/002

002 All crates compile on stable Rust. MSRV 1.80. slhx-core has zero proc-macro dependencies.

req: misc/003

003 No auth, no routing, no session storage inside slhx core. slhx-axum provides typed route mounting; actual routing is axum/tower.

req: misc/004

004 Three execution modes supported: server-first (request/response), client-local WASM (requestAnimationFrame, no round-trip), and hybrid sync (local + remote via slhx-sync). Modes are opt-in per handler, not global.

req: misc/005

005 The only required user-facing proc-macro in slhx core is #[slhx::handler]. Optional ergonomic macros may exist: #[slhx::surface], #[slhx::component], #[slhx::app], and integration-crate macros such as #[slhx::island] or #[slhx_sync::presence]. No ! call-syntax macros.

req: misc/006

006 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/007

007 All slhx HTML attributes use data- prefix (data-slhx-handle, data-slhx-slot, data-slhx-atom, data-slhx-root). No unprefixed custom attributes. Valid HTML, tool-friendly, zero custom syntax.

req: misc/008

008 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.

req: misc/009

009 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.