Documentation

This documentation is the operating map for agents and maintainers. It explains where behavior belongs, which contract is authoritative, what must change together, and how to verify the result.

Documentation is organized by reader intent instead of implementation history.

Start Here

1. Read ../AGENTS.md for repository-wide rules.
2. Read architecture.md for the end-to-end execution model.
3. Use repository-map.md to find the owning crate, source path, and tests.
4. Use maintainers/coding-guidelines.md for modularity and dependency decisions.
5. Use verification/testing.md before handing off a change.

Task Index

Change	Read first	Primary code owners	Verification
Primitive, attribute, style, native state, event, focus, text, or mutation	renderer/surface.md, renderer/workflow.md, renderer/concepts.md	reui_core, reui_elements, bevy_reui_renderer	Renderer tests and structural analyzer
Low-level Rust primitive composition	authoring/primitives.md, renderer surface	reui_elements, consumer code	reui_core, reui_elements, renderer tests
Maintained widget or layout	authoring/widgets.md	reui_widgets, root widget adapter	reui_widgets tests and showcase
Rust component props, events, or children contract	Widget authoring, authoring/file-rsx.md	reui_macros, reui_elements, root component registry	Macro, component, runtime, and integration tests
.rsx syntax or semantics	File RSX authoring, internals/rsx-language.md	reui_rsx, reui_rsx_core, reui_runtime	Language, core, runtime, and example tests
.rsxb format or loading	RSX internals, architecture	reui_rsxb, root RsxView adapter	Codec and root asset tests
File component resolution, signals, handlers, imports, or reload	File RSX authoring, RSX internals, architecture	reui_runtime, root component graph	Runtime and root integration tests
Typed or generated view props, derived roots, BSN mounting, or build integration	File RSX Typed Props Codegen, Root Derive, repository map	reui_macros, bevy_reui_build, root view props and scene adapter	Macro, root props and mount, build crate, and showcase tests
UiView, RsxView, plugin, status, or action delivery	Architecture, repository map	root bevy_reui crate	Root crate and showcase tests
Application system ordering or view update timing	authoring/scheduling.md, architecture	root plugin, props sync, renderer animation system	Root scheduling tests and workspace gate
Showcase or production example	verification/showcases.md, testing guide	examples/showcase	Explicit example package tests
Module boundary or dependency change	Coding guidelines, repository map, architecture	Affected crate owners	Workspace check, Clippy, and tests
Performance work	RSX internals or renderer concepts, testing guide	bevy_reui_benchmarks plus measured owner	Explicit benchmark command and correctness tests

Document Map

Orientation

• architecture.md: execution flow, state ownership, and architectural invariants.
• repository-map.md: crate responsibilities, important source paths, dependencies, and test locations.

Authoring

• authoring/scheduling.md: public view sets, same-frame input writes, action timing, and native UI scheduling boundaries.

• authoring/primitives.md: direct lowercase primitive composition and extension rules.

• authoring/widgets.md: maintained typed widgets, layouts, and application components.

• authoring/file-rsx.md: supported .rsx and .rsxb mounting, syntax, props, actions, imports, and codegen.

Renderer

• renderer/concepts.md: renderer mental model, hierarchy, state, and reconciliation.
• renderer/surface.md: human-readable supported primitive, attribute, child, style, and event contract.
• renderer/workflow.md: required implementation sequence for renderer changes.

Internals

• internals/rsx-language.md: parser, compiler, canonical module, bytecode, RSXB, runtime, component resolution, and lowering boundaries.

Maintenance And Verification

• maintainers/coding-guidelines.md: modularity, dependency direction, API shape, diagnostics, and test placement.
• verification/testing.md: validation levels, package commands, structural analysis, and benchmarks.
• verification/showcases.md: example ownership and integration-fixture policy.

Sources Of Truth

Documentation describes contracts; executable definitions enforce them.

Contract	Executable source of truth	Human reference
Primitive names, capabilities, attributes, child policy	reui_core::schema and reui_core catalogs	Renderer surface
Dioxus primitive namespace and event attributes	reui_elements	Primitive authoring and renderer surface
Native Bevy recipes and reconciliation	bevy_reui_renderer	Renderer concepts and workflow
Maintained widget catalog and props	reui_widgets	Widget authoring
Source grammar, semantic diagnostics, and source compilation	reui_rsx	File RSX authoring and RSX internals
Canonical module and executable program	reui_rsx_core	Architecture and RSX internals
RSXB wire compatibility	reui_rsxb	RSX internals
Runtime resolution and evaluation	reui_runtime	Architecture and RSX internals
Bevy assets, mounts, actions, generated props sync	root bevy_reui crate	Architecture and File RSX authoring
Build-time generated API	bevy_reui_build generated-output tests	File RSX Typed Props Codegen

When code and prose disagree, verify behavior in the executable owner, fix the documentation in the same change, and add or strengthen a contract test when the mismatch was not already detectable.

Documentation Rules

• Write in English for future agents.
• Link from this index whenever a canonical document is added, moved, or replaced.
• Keep one canonical explanation for each concept; link to it instead of copying it into several documents.
• Keep authoring guides focused on supported public behavior.
• Keep internal documents focused on implementation ownership and invariants.
• Keep examples tied to implemented and tested behavior.
• Delete stale migration notes and obsolete names.
• Update commands when package names, workspace membership, or test ownership changes.

For a documentation-only change, run the checks listed in verification/testing.md.