more nwork on the design

docs/dd.md

@@ -165,8 +165,37 @@ counter that the button increments.
 
 Text inputs and scrolling follow in milestone 2, along with focus handling.
 
+## Context and ownership
+
+All state lives in an `rg_context`, which is created with `rg_create` and
+passed explicitly to every call. There are no hidden globals. A context owns
+its node tree, style data, data model, event queue, text atlas, layout state,
+and, when the Lua module is attached, its own `lua_State`. This allows
+headless tests, multiple windows, and multiple Lua states in one process.
+The user-supplied allocator is set in the config struct at creation and is
+used for all internal allocation, including Lua and Clay. A context is not
+thread safe. It is used from one thread at a time, and separate contexts are
+fully independent.
+
+## Main loop
+
+The host owns the main loop. Regolith never blocks and never creates a
+window loop of its own. Each frame the host pushes input events, calls
+`rg_update` with a delta time, then calls `rg_render` to get a draw list
+that it hands to a backend. This is the same shape on native and on WASM,
+where the browser calls the host back once per frame.
+
+## Input
+
+The core accepts platform-neutral input events and never polls a platform
+API. The event kinds are pointer move, pointer button, scroll, key, and text.
+Key codes are Regolith's own enum and the SDL3 backend translates into them.
+Gamepad navigation will be added as a semantic layer (up, down, left, right,
+accept, cancel) that drives focus movement, so a game can map any device to
+it.
+
 ## Open questions
 
-- Context and ownership of the `rg_context`.
+- Whether texture uploads travel inside the draw list.
-- Who owns the main loop.
+- Viewport and display scale handling.
-- The input event path and gamepad navigation.
+- Error reporting and logging.