Dynamic UI and verification
24. Dynamic UI through graph updates
HLD — Arrows follow graph activation, binding and UI publication. Graph execution capability is separate from the two renderer targets. Open the diagram for full size.
24.1 The update mechanism is outside Surface
This chapter describes the planned UI boundary for checked replacement of eligible graph regions. Where a qualified Reaktor execution profile supplies activation through reaktor-graph, reaktor-ffi or Hermes, Surface consumes the activated result. That assumption is not proof that every Manna host can load executable updates. Ordinary state binding, graph authoring and the React/CMP renderer paths do not require this capability. Surface does not implement another deployment pipeline, code-delivery service or authority for structural application change.
The UI-facing requirement is concise: a supported update activates a coherent definition and capability binding for a region. Surface identifies the affected mounts, reconciles or replaces their presentation according to the boundary contract, and prevents stale work from the retired generation from entering the new one.
Figure 45. A supported subgraph update changes the affected composition while retaining declared state owners and boundary contracts. Surface responds to activation; it does not duplicate the update mechanism. See the illustrated PDF for the diagram.
The installed renderer must still be able to realize the activated component contracts. Describing a new native capability in a graph does not install an unavailable native implementation. The activation system's compatibility result remains the prerequisite for presentation.
24.2 Three kinds of change remain different
An application-state update can change the text or availability of existing controls. A composition update can add or remove instances inside one owned boundary. A graph-definition or implementation update can replace a supported feature region.
These changes can all affect the screen, but they do not need the same heavyweight path. A keystroke is not a graph topology rewrite. A local animation sample is not a feature update. A new generated workflow region is more than a hover observation.
Surface therefore observes normal state changes through bindings and receives activated structural changes through the graph integration. This preserves the fast local loop while keeping application evolution governed by the graph.
24.3 A generated region is still graph-owned
A runtime agent can select known components, provide content and propose a supported arrangement within an approved region. The proposal refers to the application's catalogue and available action contracts. It cannot create authority merely by naming a port or rendering a persuasive button.
Figure 46. The agent observes a scoped view and proposes a change to an approved region. Validation and activation use the existing graph mechanisms. The resulting interface is realized by CMP or React web/JS and retains ordinary direct controls. See the illustrated PDF for the diagram.
The graph change can update a region's configuration or its supported implementation. The renderer then performs normal composition. There is no second AI-only component library and no independent runtime tree that the agent may mutate while the frontend owner continues writing to it.
Executable generated code is not made harmless by a component allowlist. Such code requires the execution system's supported trust and capability profile. Surface's catalogue and input validation are necessary constraints, not a claim of complete hostile-code isolation.
24.4 Protect the interaction already in progress
A generated proposal may arrive while the person is editing. The existing draft remains associated with its owner and field identity. A new summary can fill an approved supporting slot without replacing that field.
Figure 47. A generated supporting region can change without acquiring ownership of a field already being edited. Stable identity and revision policy preserve the person's work while new content appears. See the illustrated PDF for the diagram.
If a structural change must replace the editing control itself, the boundary has an explicit handoff or defer policy. Active gestures and input-method composition cannot simply be discarded. The host provides a stable loading, error or fallback region that does not depend on the generated code being able to render itself successfully.
24.5 Authorization remains at the application operation
An enabled appearance is not authorization. An action reference is not authorization. When the person or agent invokes the operation, the graph-owned application capability checks the current principal, resource and arguments at the appropriate authoritative boundary.
Trusted authentication, consent, payment and safety regions remain protected from arbitrary generated replacement. A model may suggest content or populate a draft without acquiring the ability to approve its own high-risk action.
Generation is optional. Every essential workflow retains a direct manual path, and generation failure preserves existing user work. This keeps dynamic composition an extension of the application rather than a dependency that ordinary interaction cannot survive without.
25. Custom interfaces and specialized engines
HLD — Arrows describe the island boundary. Focus/command wrapping exists on CMP; packaged editor sessions need additional proof. Open the diagram for full size.
25.1 Not every interface should be built from ordinary boxes
A graph editor, waveform timeline, map or rich-text editor can need a specialized rendering and interaction model. Forcing its internals into a generic component tree may reduce performance and obscure its domain behavior.
Surface supports three levels of extension. Ordinary custom components compose existing catalogue entries. Custom layout and drawing components supply their own measurement and presentation. Embedded engines own substantial internal structures behind a registered boundary.
Figure 48. The shared shell supplies themes, navigation, focus coordination and graph capabilities. The specialized engine retains its scene and frame machinery behind an explicit lifecycle and semantic boundary. See the illustrated PDF for the diagram.
These extensions remain part of the architecture. They are not escape hatches from resource ownership, accessibility or application policy.
25.2 The extension contract describes the boundary
A custom engine specifies its sizing requirements, input and focus behavior, supported resource capabilities and cleanup. It exposes semantic actions and an inspectable representation or usable alternative for operations that cannot be understood from pixels alone.
A code editor can retain its mature editing engine. Its integration exposes document state, selection operations, focus, diagnostics and resource lifetime. It does not need to serialize every caret movement into a generic graph transaction.
A graph canvas can retain spatial indexes and geometry caches. Its committed application topology still belongs to Reaktor Graph. A local scene representation is a rendering projection, not a second source of valid service connections.
25.3 Distinguish document change from presentation change
Dragging a graph node can show immediate local feedback. Committing the authored position is a separate operation on the document or graph owner. Hovering the same node should not change its saved coordinates.
A tactile theme may move a tool palette slightly. It must not distort the person's artwork unless that distortion is an explicit document operation. A scientific visualization must not substitute decorative motion for numerical results.
This distinction is essential for undo and collaboration. A committed document change has history and conflict semantics. Pointer samples and decorative offsets usually do not. They can be observed or shared at a bounded rate without being treated as durable authored content.
25.4 Semantic operation enables more than agents
A custom canvas should expose actions such as select object, move by a specified amount, inspect a port or propose a connection. These support keyboard users, assistive interfaces, tests and agents.
An agent can then operate the same capability as a person rather than guessing coordinates from a screenshot. It still follows authorization and review policy. A proposed connection is checked before it becomes authoritative, even if a local preview draws a tentative line.
When a required capability is unavailable, the extension selects an explicit alternate flow or reports the limitation. An empty rectangle that silently omits an essential control is not a valid degraded implementation.
26. Verification and implementation boundaries
HLD — Evidence accumulates across levels. A release qualifies a particular renderer, host, engine and version combination. Open the diagram for full size.
26.1 Test the contract at several levels
The behavior kernel has headless tests. The renderer adapter has input and semantics tests. Recipes have supported-theme checks. Layout policies have constraint tests. Complete application workflows verify that these pieces cooperate while state changes and resources fail.
A button reducer test does not prove screen-reader operation. A screenshot does not prove cancellation. A successful host commit does not prove that an application action is authorized. Each test answers a specific question.
The catalogue can generate the component laboratory from the same definitions used by production code. The laboratory includes unusual but valid states: long labels, missing images, busy controls, larger text, right-to-left layout and reduced motion. Examples should be composable into actual workflows rather than confined to an attractive default gallery.
26.2 Preserve reference paths for optimizations
An incremental host projection can be compared with full recomputation. A compact encoded batch can be decoded and compared with its readable equivalent. A field response can be evaluated with a deterministic test clock and bounded inputs.
These reference paths help distinguish faster execution from changed semantics. If an optimization skips a necessary update, its improved timing is not a success. If a pool retains several large images indefinitely, fewer allocations do not imply a better resource policy.
Formal models can help with small state-transition questions, such as whether a retired generation can admit new events. They do not automatically prove arbitrary component code or perceptual quality. The scope and assumptions of the model remain explicit.
26.3 Use real failure scenarios
Representative scenarios include a theme switch while editing, an image arriving above the read anchor, a window resizing during a transition, a permission being revoked while a dialog is open, and a generated region arriving after the person changes its draft.
The bridge adds malformed values, stale generations and missing base revisions. Resource testing adds low memory, decode cancellation and graphics loss. Repeatedly opening and closing a heavy editor tests whether lifetime rules are actually implemented rather than merely documented.
A valid failure outcome can be a preserved last-known-good region, a deferred update or a clear unavailable capability. The system must not replace an unsupported path with an untested one while presenting the result as success.
26.4 Keep dependency direction acyclic
The shared model contains neutral values and behavioral contracts. Renderer integrations depend on that model. Graph integration connects those contracts to the existing application runtime. Product composition depends on the public Surface API and its chosen realization.
Toolkit-specific graph rendering must be separated before establishing a dependency direction that would otherwise make graph and UI depend on each other. The Reaktor graph and UI build definitions identify this concrete integration boundary. 5152
Physical modules are introduced when they provide real dependency, compilation or distribution isolation. A separate module per atom, animation or metric is unnecessary. Logical packages can establish the boundaries first, while a small number of modules enforce the relationships that matter.
26.5 The release criterion is a supported combination
A release is qualified for particular component, theme, renderer and environment combinations. Passing one Android example does not establish all desktop or React web/JS behavior. A shader working on one backend does not establish a portable material profile.
The evidence should show that required state and semantics survive supported variation, that local feedback meets its target profile, and that resource ownership remains bounded. The final Compose-first task plan turns these obligations into staged implementation work rather than requiring every future realization at once.