hemx/.agents/skills/idiomatic-hemx/SKILL.md

---
name: idiomatic-hemx
description: >-
  Use when a user explicitly asks how to design, implement, review,
  productionize, or scale an application built with hemx and hemplate,
  including deciding whether or where microservices belong. Preserve hemx's
  generated-resource and server-owned effect model, then choose the smallest
  evidence-backed scale stage. Do not use for generic Rust/Axum architecture,
  generic microservice advice, or development of the hemx framework itself.
---

# Idiomatic hemx

## One job

Choose, explain, or implement the smallest production architecture that keeps a
hemx/hemplate application boring as it grows. The high-leverage move is usually
to preserve one direction of travel:

```text
semantic .heml surface
  -> generated typed resources
  -> ordinary Rust domain/application code
  -> generated partial/page effects
  -> tiny browser runtime
```

Scale providers and deployment topology around that loop. Do not replace it
with selectors, a client state graph, raw wire operations, or speculative
services.

## Trigger boundary

Load this skill for explicit hemx/hemplate application usage, architecture,
production-readiness, scaling, or a review of those decisions. It also applies
when the user asks whether a hemx application should become microservices.

Do not load it for:

- generic Rust, Axum, HTML, CSS, database, or microservice questions with no hemx
  application decision;
- visual design alone;
- changing hemx/hemplate internals rather than using their public model;
- a tiny obvious application patch where no authoring or scaling judgment is at
  stake.

## Authority before taste

Inside the hemx repository, read `AGENTS.md`, then
`docs/v1-product-evidence.md` and `REQUIREMENTS.md`. Use `PLAN.md` only as the
mutable implementation cursor. Inspect only the nearest authoritative material
needed for the decision:

- `docs/hemplate-syntax.md` for real `.heml` syntax;
- `docs/tutorial-saas.md` for the production-shaped application boundary;
- `docs/recipes/reusable-partials.md` for composition;
- the auth, persistence, observability, deploy/versioning, offline, and local
  command-log recipes for their named concerns;
- the nearest maintained example and current public Rust API before naming an
  API in code.

Project requirements and observed code outrank this skill. Outside this
repository, establish the application's versions and elected contracts instead
of assuming current-main APIs. If auth, storage, transport, replay, deployment,
or service contracts are absent, identify the missing decision; do not invent a
provider or abstraction that makes the system look complete.

When invoked for a Hemx application repository, inspect its elected `AGENTS.md`
or equivalent instruction surface. Ensure it explicitly requires all HTML
surfaces and fragments to be authored as semantic `.heml` templates rendered
through Hemplate's generated typed resources, and explicitly forbids constructing,
concatenating, interpolating, or formatting HTML in Rust. If the current request
authorizes repository edits, patch that instruction surface before application
implementation; otherwise report the missing policy as a blocker. Do not copy the
rest of this skill into project instructions.

## Decision loop

### 1. Start with the user job and one load-bearing path

Name the concrete request, mutation, navigation, push update, or recovery path
that must work. Trace it end to end before discussing topology:

```text
HTTP/browser input
  -> normal auth, CSRF, and typed validation
  -> application command/query
  -> authoritative state transition
  -> rendered generated target/page
  -> EffectBatch response or canonical push bytes
  -> root-scoped runtime application
  -> visible success or explicit recovery
```

If this path is unclear, architecture diagrams and service boundaries are
premature.

### 2. Use the canonical authoring level

Default to:

- semantic `.heml` templates plus ordinary Rust; never construct, concatenate,
  interpolate, or format HTML strings in Rust, including fragments for source
  rendering, Markdown, errors, or test-facing pages;
- `#[hemx::app]`, plain `#[hemx::handler]`, generated components/resources,
  typed form models, view wrappers, render/page helpers, and `IntoEffect`;
- generated target, form, control, keyed-slot, and event helpers;
- typed partial swaps expressed as generated target + rendered partial + swap
  kind;
- real links and GET forms for navigation and history;
- `data-hemx-revealed-ahead` for viewport-ahead loading while the observed sentinel remains in normal document flow; never move the observed target with CSS to fake prefetch distance;
- plain CSS/SCSS for appearance;
- shared runtime paths and Axum adapters supplied by `hemx-axum`.

Keep domain types, authorization, persistence, routing, sessions, flags,
observability, and transport policy in the application or integration crate.
Keep `hemx-core` about typed resources and the closed effect/wire contract.
Compose reusable UI from templates, generated components, and ordinary Rust
functions rather than creating a client component framework.

Use advanced layers only when the job proves the need:

- opaque island JavaScript is a leaf adapter for high-frequency local behavior;
- client-local/wasm handlers are explicit opt-ins, not the default state model;
- atoms are addressable bootstrap/sync resources, not a general reactive store;
- SSE/WebSocket transport carries canonical versioned `EffectBatch` bytes; it
  does not define domain policy.

### 3. Keep truth on the right side of the boundary

The browser DOM, stored HTML patches, and stored `EffectBatch` values are not
business truth. Keep authoritative state in ordinary application/domain models
and durable providers. Derive UI effects from that state.

For local/offline products, use explicit commands, events, and projections.
Replay, deletion, conflict resolution, reconciliation, and export semantics are
product contracts; stop when they have not been chosen. For server products,
normal HTTP security semantics remain authoritative even when interactions are
enhanced.

Expected failures must become typed, local, useful outcomes: generated field
errors/focus for validation, a root-scoped error outlet for recoverable request
failure, and fail-closed handling for malformed or incompatible responses.
Never turn infrastructure failure into a success-looking empty effect.

Prefer a **functional core with an imperative shell**. Keep validation,
normalization, authorization decisions, command application, state transitions,
and view-model/projection derivation as deterministic functions over explicit
inputs where that is honest. A useful shape is `state + command -> outcome` or
`facts -> view model`, with typed errors rather than hidden mutation. This makes
the largest behavior space cheap to unit-test and mutation-test.

Keep HTTP extraction, sessions, database I/O, clocks, randomness/IDs, queues,
push connections, and host capabilities in a thin handler/application shell.
Read their results once, pass ordinary values into the core, persist the returned
outcome, then render generated effects. Pass time, identity, or policy as data
when only the value matters; do not create a trait for every function merely to
mock it. Use a real adapter boundary when ownership or side effects are real.
Purity is a locality tool, not a religion: orchestration and I/O are inherently
effectful, and `EffectBatch` remains UI output rather than domain state.

### 4. Scale one pressure at a time

Use this ladder. Enter a stage only when measured load, availability goals,
ownership, compliance, or a distinct failure/resource profile requires it.

| Stage | Default shape | Required proof before moving on |
| --- | --- | --- |
| One process | One deployable; app-owned adapters; simplest durable store that meets the product contract | The real product path, restart behavior, backup/recovery needs, and current bottleneck are known |
| Production monolith | One release unit for server, generated output, and runtime asset; external durable database/session providers as required | Integration tests cover auth, persistence, failures, migration, fingerprint mismatch, and rollback/reload behavior |
| Horizontal web tier | Stateless request replicas around shared authoritative providers; process memory is cache/ephemeral only unless affinity and loss semantics are explicit | Load evidence shows replica scale helps; migrations, readiness, draining, cache invalidation, and session/CSRF behavior work across replicas |
| Push/fan-out tier | Server-owned ongoing SSE/WebSocket connections; add a broker/backplane only when updates must cross processes | Reconnect, ordering, duplicate, authorization, backpressure, and replay expectations are explicit and tested at the required level |
| Worker or read-model split | Isolate a measured CPU, latency, queue, or failure domain while the application remains one understandable product | Job ownership, idempotency, timeout, retry, deduplication, observability, and recovery contracts exist |
| Microservices | Split an independently owned bounded capability with its own release/scaling/SLO pressure and explicit data/API/event contract | The boundary removes a demonstrated constraint and its distributed failure modes are cheaper than the monolith |

Prefer vertical resource tuning, query/index fixes, caching with explicit
freshness, bounded concurrency, and horizontal replicas before service
splitting. A large codebase is a module-boundary problem before it is a network
boundary problem.

### 5. Preserve the hemx boundary across services

When microservices are justified:

- keep hemplate rendering, generated resources, and UI `EffectBatch` creation in
  the presentation/application edge that owns the page;
- exchange typed domain requests, responses, and events across services—not CSS
  selectors, DOM instructions, raw hemx opcodes, or app-authored JSON versions
  of the hemx wire format;
- name one authority for each write model and do not let services casually share
  mutation ownership;
- version service contracts independently, while deploying each hemx server,
  its generated metadata, build fingerprint, and runtime asset as a compatible
  release unit;
- preserve end-user credentials, authorization, CSRF, tenancy, deadlines, and
  trace context explicitly at each real trust boundary;
- make partial failure visible. Define timeout, idempotency, retry,
  deduplication, ordering, compensation, and replay only where the chosen
  interaction requires them—never as generic middleware theater.

Do not put a network hop between a handler and its renderer merely to claim
microservices. Do not use `EffectBatch` as a business event bus or durable event
log.

### 6. Organize by cohesive product responsibility

Start small; do not pre-create an architecture directory tree. A production app
usually needs only these durable seams:

```text
build.rs                    # hemx-build/global code generation only
src/main.rs                 # config, concrete providers, process/bootstrap
src/lib.rs                  # app/router composition and a testable app surface
src/<feature>/              # add only when a feature is already a real seam
templates/app_shell.heml    # document shell
templates/<feature>.heml    # feature surface
templates/partials/         # genuinely reused or independently swapped pieces
tests/<journey>.rs          # process/integration behavior
tests/browser_<journey>.rs  # only browser-dependent behavior
```

Treat that as a responsibility map, not mandatory scaffolding. A small cohesive
app can remain in `lib.rs`; file count is not architecture. When a feature has
its own state/commands, handlers, rendering, and tests, move that whole seam
together. Keep its domain model, typed input, application operation, handler,
and generated view calls near one another. Do not spread every request across
generic `controllers/`, `services/`, `repositories/`, `dto/`, and `utils/`
directories.

Keep `main.rs` boring and hard to test because it contains almost no policy.
Expose app construction or mounting from `lib.rs` so integration tests can use
the real router with controlled concrete providers. Put normal routing,
auth/session, persistence, queues, and transport adapters at the app boundary;
do not move them into hemx core or generated template modules. Keep generated
artifacts in the build output rather than copying them into source control.

Put tiny unit tests beside the responsible module, especially around pure
transitions, validation, authorization decisions, and projections. Put
cross-module HTTP, persistence, and process tests in `tests/`, named for behavior
rather than implementation. Keep browser journeys few and load-bearing. Extract
a shared partial or helper only after actual reuse or independent swap identity
appears.
If a microservice boundary becomes real, that service owns its contract,
provider/migrations, operational entry point, and contract tests; do not mirror
hypothetical services in the source tree first.

### 7. Prove behavior at the cheapest authoritative boundary

Choose the tool by what must be observed:

| Boundary | Default tool | What it proves |
| --- | --- | --- |
| Domain/state | Rust `#[test]` / `#[tokio::test]` | Parsing, invariants, commands, projections, and failure classes |
| Template/build | Compiler plus hemx-build diagnostics | Real `.heml` syntax, generated resources/forms, and cross-file references |
| Handler/effect | `hemx_test` | Generated targets/handles, rendered partials, form bodies, and effect batches without raw ids |
| Router/integration | Real Axum router, usually `tower::ServiceExt`, plus concrete test providers | HTTP status/headers/body, auth, CSRF, sessions, persistence, and malformed requests |
| Static rendered HTML | Rust `scraper` crate (HTML parser + CSS-selector queries) | Escaping, semantic structure, links/forms/attributes, and server-rendered fragments without launching a browser |
| Process lifecycle | `hemx_test::TestProcess` | Readiness, real sockets, child cleanup, restart, and production-binary behavior |
| Browser runtime | Rust `thirtyfour` crate (WebDriver client) with the repository-owned browser smoke | Delegated events, history, focus, polling/revealed bindings, keyed DOM identity, SSE, and recovery |
| Test quality/release | hemx xtask mutation/full-test commands | Mutation resistance and the elected bounded workspace verification path |

`scraper` is a Rust HTML parsing and CSS-selector library, not a browser or web
framework. Use it when inspecting final server-rendered HTML is enough. It does
not run JavaScript, apply `EffectBatch`, maintain focus/history, or prove
SSE/runtime behavior. `thirtyfour` is a Rust WebDriver client crate; use it only
when an actual browser semantic is the subject;
do not turn every handler assertion into a WebDriver journey. In this repository
`thirtyfour` is the elected Rust browser adapter, so do not add Playwright,
Fantoccini, or another competing browser stack merely from preference. Outside
this repository, preserve the application's existing runner unless a concrete
missing capability justifies migration.

For WebDriver tests, start the real process through the RAII `TestProcess`
harness, keep selectors in test adapters, and prefer generated-resource or
stable semantic helpers over copied implementation selectors. Browser selector
helpers are not authoring APIs. Avoid sleeps when the runner can wait for the
observable condition.

Match proof to risk:

1. Let compilation reject broken templates and generated contracts.
2. Unit-test ordinary domain parsing and state transitions without a browser.
3. Test handlers through `hemx_test` with useful generated-resource assertions.
4. Test route/auth/session/CSRF/persistence and wire failure behavior at the app
   integration boundary.
5. Parse static HTML with `scraper` only for facts that do not require runtime
   execution.
6. Use focused repository-owned browser smoke for dynamic attributes,
   navigation/history, keyed reconciliation, polling/revealed behavior,
   no-reload interaction, and runtime recovery.
7. Add compatibility, rolling-deploy, process-restart, multi-replica, load, or
   fault tests only when the selected scale stage makes those behaviors part of
   the contract.

In this repository, prefer the stable commands named by `AGENTS.md`, especially
focused crate tests and `cargo run -p hemx-xtask -- test`; use
`cargo run -p hemx-xtask -- html-examples-smoke` for the pattern gallery and
runtime behavior, and the xtask mutation command rather than direct `mutest`.
Do not substitute a passing literal lowering fixture, static HTML parse, or
mocks-only test for proof at the rendered/runtime consumer boundary.

## Refuse fake sophistication

Do not introduce:

- handwritten resource ids, selector retargeting, raw effect constructors, raw
  registries, runtime opcodes, manual wire parsing, or hard-coded runtime URLs in
  normal app code;
- a VDOM, client router, general client state graph, expression runtime,
  per-node listeners, or handwritten JavaScript for ordinary forms/lists/swaps;
- core-owned auth, sessions, persistence, routing, multipart, transport, sync,
  analytics, flags, or provider policy;
- a generic repository/service/provider interface before a concrete second use
  or required external contract exists;
- microservices by entity name, team aspiration, file count, or hypothetical
  scale;
- shared process memory presented as durable or cross-replica state;
- retries, caches, queues, brokers, sagas, event sourcing, CQRS, Kubernetes, or a
  service mesh without a named failure/load contract and verification path.

“Suckless” here means fewer authorities and mechanisms, not fewer safety checks.
The elegant design keeps HTML semantics, typed boundaries, explicit ownership,
and failure truth while deleting accidental layers.

## Handoff

For architecture or review requests, report compactly:

- the user-visible path and current bottleneck/risk;
- the selected scale stage and why the previous stage is insufficient;
- state, rendering, transport, and service ownership;
- the smallest end-to-end change;
- complexity explicitly refused;
- proof run and any unresolved provider/product contract.

For implementation, make that slice reachable and verify it; do not leave a
“scalable” abstraction that no real path uses.