Data binding in MeshWeaver connects your data objects to UI controls reactively and bidirectionally. The server pushes updates to the GUI; user edits flow back to the server. The whole pipeline is live — when the underlying node changes anywhere in the mesh, every subscribed view re-renders without a page refresh.

Native clients bind the same way. An external participant client (the React Native app, a SignalR/gRPC participant) reads with hub.GetMeshNodeStream(path) and writes with .Update(...) — identical rule, just marshalled to the device UI thread over the participant socket.

The Golden Rule: the GUI is fully data-bound

🚨 Backend layout areas declare what to render — they never fetch instances and never put concrete values into controls. All value resolution, every read of a MeshNode's content, and every write-back of user input happens on the GUI side via a per-node IMeshNodeStreamCache subscription.

This is non-negotiable, for three reasons:

1. No deadlocks. Backend rendering stays purely synchronous — no await, no Task<T>, no IAsyncEnumerable. Every async/await/QueryAsync chain put in a layout area has eventually deadlocked the hub or returned stale content. Removing the backend fetch removes the entire problem class.
2. Live updates. The GUI subscription stays open for the lifetime of the component. Backend-loaded values freeze on first render; cache-subscribed views never go stale.
3. CQRS-correct reads. Hub.GetMeshNodeStream(path) (backed by the process-wide IMeshNodeStreamCache) is the authoritative read path — it goes to the owning hub's workspace, never through the lagged read-side index. See CQRS — Queries, Reads, Writes, Operations.

Responsibility split

Backend: declare the binding, don't fetch the data

// ❌ ANTI-PATTERN — backend loads node, builds control with concrete values
var userNode = await meshQuery.QueryAsync<MeshNode>($"path:{userPath}").FirstOrDefaultAsync();
var card = MeshNodeThumbnailControl.FromNode(userNode, userPath);

// ✅ CORRECT — backend declares the binding path; GUI loads + displays
var card = new MeshNodeThumbnailControl { NodePath = userPath };

The backend layout-area method must not be async Task<UiControl>. Return UiControl directly. If it needs to rebuild reactively on workspace changes, return IObservable<UiControl?> and compose with Observable.Return / Select — never SelectMany(async ...), never await.

GUI: subscribe via the cache, re-render on emission

The canonical Blazor view template. Reads and writes both go through Hub.GetMeshNodeStream(path), which returns a MeshNodeStreamHandle backed by the process-wide IMeshNodeStreamCache. Multiple views on the same path share one upstream subscription; writes through the handle's .Update(...) are visible to every reader.

Access-checked. The stream is gated by the current user's effective Read permission on the node. The cache asks the owning hub via GetPermissionRequest, caches the answer per (path, userId) for 30 s, and terminates the observable with UnauthorizedAccessException if Read is not granted. Subscribers should handle that error (toast, navigate to AccessDenied, render empty state) rather than letting it propagate. See AccessContextPropagation.md.

public partial class MyView : BlazorView<MyControl, MyView>
{
    public string? Title { get; private set; }
    public string? ImageUrl { get; private set; }

    protected override void BindData()
    {
        base.BindData();

        // 1. Declare bindings from the control's own properties (DataContext / refs)
        DataBind(ViewModel.NodePath, x => x.NodePath);

        if (string.IsNullOrEmpty(NodePath)) return;

        // 2. Subscribe — every emission re-renders this component
        AddBinding(Hub.GetMeshNodeStream(NodePath)
            .Where(node => node is not null)
            .DistinctUntilChanged()
            .Subscribe(node =>
            {
                Title = node.Name;
                ImageUrl = MeshNodeThumbnailControl.GetImageUrlForNode(node);
                InvokeAsync(StateHasChanged);
            }));
    }
}

Key points to remember:

• Go through Hub.GetMeshNodeStream(path), not the raw cache. The handle supplies the hub's JsonSerializerOptions for you, so node.Content arrives as its registered domain type. The bare IMeshNodeStreamCache.GetStream(path) / Update(path, fn) overloads were deleted: without options the cache hands back Content as a raw JsonElement, so node.Content as MyType is null and the consumer silently no-ops — the wedged-thread / never-dispatching-watcher bug class. If you do resolve IMeshNodeStreamCache directly, you must pass Hub.JsonSerializerOptions to every call.
• Writers call Hub.GetMeshNodeStream(NodePath).Update(fn).Subscribe(...) to push edits; the write routes through the same shared handle, so the read subscription receives the echo. Update returns a cold observable — without Subscribe the write never happens.
• AddBinding(...) registers the subscription with the base class — it auto-disposes on component teardown. The cache's upstream handle stays alive for the process.
• No .Take(1) — that snapshots once and the view freezes. Stay subscribed for the lifetime of the component.
• Never open workspace.GetRemoteStream<MeshNode, MeshNodeReference>(addr, ...) directly in a Blazor view. That bypasses the cache; writes through the cache won't be observed by views that went around it.
• No try/catch swallowing — let errors propagate via Subscribe(onNext, onError) or the framework's binding error handler.

Writing user edits back

The same handle is the write path. Its Update takes a MeshNode → MeshNode lambda and returns a cold IObservable<MeshNode> — the write only happens on Subscribe:

private void OnTitleChanged(string newTitle)
{
    if (string.IsNullOrEmpty(NodePath)) return;
    Hub.GetMeshNodeStream(NodePath).Update(current => current with { Name = newTitle })
        .Subscribe(_ => { }, ex => Logger.LogWarning(ex,
            "Title update failed for {Path}", NodePath));
}

Because the write routes through the same shared upstream handle every reader is subscribed to:

1. The owning hub applies the patch and persists.
2. This view's Hub.GetMeshNodeStream(NodePath) subscription receives the echo and re-renders.
3. Every other GUI watching the same path sees the patch through their own subscription.

No separate DataChangeRequest is needed for own-node edits inside a bound view.

Server-side mirror. The same rule holds server-side: every mesh-node mutation goes through workspace.GetMeshNodeStream(path).Update(...) — which internally routes through the same IMeshNodeStreamCache. State machines (compile, thread execution, satellite operations) flip a RequestedX field on the node's content; the owning hub's watcher reacts. Full reference: Requesting Work via stream.Update().

🚨 ABSOLUTE: edit node content by binding to the node stream — NEVER replicate into /data + a save subscription

Editing a mesh node's content means binding the GUI client to the node's own stream and writing edits straight back to it. There is exactly ONE source of truth — Hub.GetMeshNodeStream(path) (the process-wide IMeshNodeStreamCache). Reads come from it; edits write back through GetMeshNodeStream(path).Update(...).

The forbidden antipattern (it has appeared in many editors and must not be added to new ones):

// ❌ FORBIDDEN — replicate-then-save. Two sources of truth glued by a debounced loop.
host.UpdateData(dataId, node.Content);                          // 1. copy the node into a /data replica
// ... controls bound to /data/{dataId} ...                      // 2. edit the replica
host.Stream.GetDataStream<object>(dataId)                        // 3. a SERVER-SIDE save subscription
    .Debounce(...).Subscribe(c => GetMeshNodeStream(path).Update(n => n with { Content = c }));

Why it's wrong: the /data/{id} copy and the node stream are two stores that drift (an out-of-band write to the node — e.g. a status field — never reaches the replica), and the debounced Subscribe(...Update...) is a hidden save loop that fires spurious writes, races the echo, and clobbers fields it didn't edit. OverviewLayoutArea.SetupAutoSave is this antipattern; do not call it and do not write your own variant (SetupNodeMetadataAutoSave, SetupNodeTypeConfigAutoSave, a hand-rolled GetDataStream(id).Throttle().Subscribe(...Update...), or a "Save" button that reads /data and writes the node).

The correct pattern — a node-bound editor. The backend layout area only DECLARES the editor with a node path; a Blazor view binds it to the node stream:

// ✅ Backend layout area — declare the binding, compute the fields from the content type:
stack.WithView(MeshNodeContentEditorControl.ForType(nodePath, typeof(MyContent)));

// ✅ The Blazor view (the ONLY place reads/writes live) — bind to the node stream:
AddBinding(Hub.GetMeshNodeStream(NodePath)
    .Where(n => n is not null)
    .Subscribe(node => { LoadValues(node); InvokeAsync(StateHasChanged); }));   // reads

// edit -> per-field read-modify-write straight to the node (set ONLY the edited field):
Hub.GetMeshNodeStream(NodePath)
    .Update(node => node with { Content = PatchOneField(node.Content, key, value) })
    .Subscribe(_ => { }, ex => Logger.LogWarning(ex, "persist failed for {Path}", NodePath));

No /data replica, no SetupAutoSave, no Save button, no debounce-and-save subscription. MeshNodeContentEditorControl (control in MeshWeaver.Graph, view MeshNodeContentEditorView in MeshWeaver.Blazor) is the reusable generic editor for simple scalar/bool content. For rich content (markdown, mesh-node picking) use the dedicated already-node-bound controls — MarkdownEditorControl.WithAutoSave(hubAddress, nodePath) (writes via the cache), MeshNodePickerControl, CollaborativeMarkdownView. Reference editor: MeshNodeEditorView (MeshWeaver.Blazor.Graph) via the MeshNodeEditor/IMeshNodeEditor client wrapper.

The same rule covers create-on-absent: a node the editor writes to must EXIST first — create it with meshService.CreateNode(...) (read existence via GetQuery, empty-on-absent), NEVER GetMeshNodeStream(path).Update on an absent path (it NotFound-storms). Update mutates; only a create brings a node into being.

🚨 READING is a different obligation, and it is the framework's, not yours. "Create it first" cannot cover the two states that actually happen: a bound node deleted while the page is still open, and one deliberately not written until the user acts (a learner's answers node, written by the first answer — creating it on render would write a node for everyone who merely looked). So MeshNodeBindingExtensions.Bind — the seam every node-bound control reads through — gates its point read on a live exact-path existence query and simply draws the control empty while the node is absent, staying subscribed so the node appearing populates it. You do not code around an absent node on the read side, and you must not catch the fault if one ever surfaces: swallowing it leaves the storm-breaker window open on the path, and that breaker fast-fails WRITES too — so the suppressed read suppresses the write your form is about to make. See CQRS and Content Access → An OPTIONAL node (Systemorph/MeshWeaver#3517).

Node-bound DataContext — reuse the rich form-gen, bound to the node

For a RICH editor (text + number + checkbox + markdown + [MeshNode] picker + [Dimension] select), you don't hand-roll controls — you let the framework's form generator (EditLayoutArea.BuildPropertyForm / MapToToggleableControl / the Edit macro) build them, then point their DataContext at the node instead of a /data/{id} replica. The generated controls then read each field straight from the node stream and write each edit straight back — ONE source of truth, no replica, no save subscription.

Encode the node-bound DataContext with LayoutAreaReference.GetMeshNodeDataContext(...):

// Field pointers resolve against the node's Content JSON (content-typed editors):
var ctx = LayoutAreaReference.GetMeshNodeDataContext(node.Path);                    // bindContent: true (default)

// Field pointers resolve against the WHOLE node JSON — for top-level fields
// (Name / Description / Icon / Category / Order — the "metadata" editors):
var ctx = LayoutAreaReference.GetMeshNodeDataContext(node.Path, bindContent: false);

// …optionally nested one level deeper (e.g. a Thread's inline composer object):
var ctx = LayoutAreaReference.GetMeshNodeDataContext(node.Path, bindContent: false, subPath: "content/composer");

// Pass it to the standard form generator (or set it as a control's DataContext directly):
stack.WithView(EditLayoutArea.BuildContentView(host, new ContentViewOptions {
    DataId = dataId, ContentType = contentType, CanEdit = canEdit, BoundDataContext = ctx }));

Mechanics (so you know what's load-bearing):

• The encoding is a reserved DataContext shape /$meshNode/{base64url(path)}/{c|n}[/base64url(subPath)] (LayoutAreaReference.MeshNodePrefix). It carries no /, ., or %9Y, so it survives the DispatchView decode hop and JSON-pointer parsing untouched.
• The binding primitive is MeshNodeBindingExtensions (in MeshWeaver.Mesh.Contract, next to GetMeshNodeStream — a control-level static extension, NOT a Blazor type, so it is unit-testable without a render host: see MeshNodeBindingExtensions.ResolveField and test/MeshWeaver.Layout.Test/MeshNodeBindingExtensionsTest). The GUI seams BlazorView.DataBind (read) and BlazorView.UpdatePointer (write) branch on a node-bound context via MeshNodeBindingExtensions.IsNodeBound: reads come from Hub.GetMeshNodeStream(path) and writes are a per-field read-modify-write through .Update(...) that touches ONLY the edited field. Every form control inherits this automatically — TextField, NumberField, CheckBox, DateTime, Select, MeshNodePicker, MarkdownEditor, Code.
• 🚨 A control that binds its Value pointer itself (the Monaco editor views — MarkdownEditorView / CodeEditorView / NotebookEditorView) must ALSO route node-bound reads through MeshNodeBindingExtensions (IsNodeBound + Bind), not through Stream.DataBind. A node-bound pointer fed to the layout Stream reaches LayoutExtensions.GetStream<T>, which treats the pointer's second segment as a JSON-encoded id and calls JsonSerializer.Deserialize<string>(segment). The segment is the Base64Url of the node path (e.g. QWdlbnRpY1BlbnNpb24 for AgenticPension) — a bare token, not a JSON-quoted string — so it throws 'Q' is an invalid start of a value' and tears down the whole Blazor circuit. The node's content lives on the node stream, not the layout-area /data store, so reading it via the layout Stream would be wrong even if it didn't crash. (Root-caused from the AgenticPension Settings → Display Description editor, 2026-06-14.)
• Field-pointer resolution against the node is case-insensitive, so a metadata DTO's PascalCase pointer (Name, Description) and a content editor's camelCase pointer (harness, messageContent) both bind without the layout area knowing the JSON casing.
• Edit-state stays in /data. The click-to-edit toggle (editState_…) is transient view state, not node content — it is never written to the node. Only field VALUES are node-bound.
• A few read-only display controls (the [Dimension] / options / formatted-date toggle labels) derive their text from the layout-area /data stream rather than a value pointer. When you node-bind a toggleable form, keep /data/{dataId} as a one-way live projection of the node content (GetMeshNodeStream(path).Select(n => n.Content).Subscribe(c => host.UpdateData(dataId, c))) so those labels stay correct. This is a pure read mirror — it follows the node, has no save loop, and never writes back, so it is NOT the forbidden replicate-then-save pattern.

Anti-patterns — never do these

Where to look for working examples

• src/MeshWeaver.Blazor/Components/MeshNodeThumbnailView.razor — the minimal read-only reference: one Hub.GetMeshNodeStream(NodePath) subscription.
• src/MeshWeaver.Blazor/Components/CollaborativeMarkdownView.razor.cs — read + write reference: a node-stream subscription for the markdown body, and .Update(fn) on the same handle to push edits.
• src/MeshWeaver.Blazor/Components/MarkdownEditorView.razor — auto-save via .Update(fn) on the node-stream handle from a debounced editor stream; canonical write-path pattern.
• src/MeshWeaver.Blazor/Components/ThreadMessageBubbleView.razor.cs — multiple sub-fields (Text, ToolCalls, UpdatedNodes, Role) extracted from node.Content as JsonElement inside the cache Subscribe(...).
• src/MeshWeaver.Blazor/BlazorView.razor.cs — the base class. Key API: AddBinding, DataBind<T>, BindData() lifecycle.

Layout Area Structure

A layout area has two conceptual sections: areas (the rendered UI controls) and data (the bound objects). Controls reference data locations using JsonPointerReference.

When the user types in the TextFieldControl, the value at /data/person/name updates. When server code calls UpdateData(...), every bound control reflects the new value automatically.

DataContext

DataContext sets the base path for data binding. All JsonPointerReference values are resolved relative to it.

// EditorControl with DataContext pointing to /data/person
new EditorControl { DataContext = "/data/person" }

When you call Edit(instance, "person"), the data is stored at /data/person and the generated controls automatically receive DataContext = "/data/person".

JsonPointerReference

JsonPointerReference points a control's value to a location in the data section. The pointer is relative to DataContext:

// TextFieldControl bound to the "name" property
new TextFieldControl(new JsonPointerReference("name"))

// NumberFieldControl bound to the "age" property
new NumberFieldControl(new JsonPointerReference("age"))

With DataContext = "/data/person":

• JsonPointerReference("name") resolves to /data/person/name
• JsonPointerReference("age") resolves to /data/person/age

🚨 An ABSENT DataContext does not disable the binding — it RE-ROOTS it

Worth knowing before you read the stack trace in #3711, because the exception there names a JSON parse and the fault is a lost context.

LayoutClientExtensions.GetPointer resolves a relative pointer against the data context — and when there is no context it does not refuse. It promotes the pointer to an absolute one:

if (pointer.StartsWith('/'))
    return pointer.TrimEnd('/');
if (string.IsNullOrWhiteSpace(dataContext))
    return string.IsNullOrEmpty(pointer) ? "/" : $"/{pointer}";   // ← relative becomes ABSOLUTE
return $"{dataContext}/{pointer.TrimEnd('/')}";

LayoutExtensions.GetStream then reads segment 0 as a COLLECTION and segment 1 as a JSON-encoded id. So what happens next depends on how many segments the pointer has, and the two cases are opposites:

🚨 The crash is the lucky case. The one-segment form reports nothing and reads — and through BlazorView.UpdatePointer, writes — against a ROOT path of the layout stream's own document (/answers, treated as a root collection) instead of the node the view was meant to be bound to.

Be precise about which wrong place that is: it is not the area's /data/{id} replica. LayoutAreaReference.GetDataPointer builds /data/"{id}"/…, so a value in the data section is two segments deeper and JSON-encoded. A context-less relative pointer lands beside /areas and /data, at a root key the layout stream does not define — which is why the read yields nothing and the write creates a sibling of the document's real sections. Same class as the replicate-then-save outcome this page forbids above (a write that leaves the node it was bound to untouched), reached by accident rather than by design — but a different address, and diagnosing it against the /data storage model sends the reader to the wrong place.

Two consequences:

1. Never "fix" such a crash by making the id decode tolerant. It converts the loud case into the silent one — for the quiz in #3711 that means a learner's pick written into the layout replica instead of their answer sheet.
2. A bind that reads nothing, or reads the wrong thing, with no error, is a DataContext question first. Check that the control's context reached the CLIENT — it is a [CascadingParameter] supplied by DispatchView, not a property the view reads off the control it renders — before you look at the pointer.

Updating Data from the Server

To push new data to bound controls from server code, use UpdateData:

// Push new data to the stream — all bound controls update automatically
host.UpdateData("person", new Person { Name = "Bob", Age = 25 });

This updates /data/person, and every control bound to that path reflects the change immediately.

The Edit Macro

Edit is the fastest way to create a data-bound editor. It inspects the object's properties and generates the appropriate controls automatically — no manual JsonPointerReference wiring required.

// Creates a fully bound editor for a Calculator record
host.Hub.Edit(new Calculator(), "calc");

Property-to-control mapping

Example

public record Calculator
{
    [Description("The X value")]
    public double X { get; init; }

    [Description("The Y value")]
    public double Y { get; init; }
}

// Produces an EditorControl with two NumberFieldControls
// bound to /data/calc/x and /data/calc/y
host.Hub.Edit(new Calculator(), "calc");

Live demo

The cell below shows the property-type mapping in action — a Calculator record rendered as a table of controls, with a computed result:

var rows = new[]
{
    ("X", "double", "NumberFieldControl", "/data/calc/x"),
    ("Y", "double", "NumberFieldControl", "/data/calc/y"),
};

var header = "<tr><th>Property</th><th>Type</th><th>Generated Control</th><th>Bound path (DataContext = /data/calc)</th></tr>";
var body = string.Join("", System.Linq.Enumerable.Select(rows, r =>
    $"<tr><td><code>{r.Item1}</code></td><td><code>{r.Item2}</code></td><td><code>{r.Item3}</code></td><td><code>{r.Item4}</code></td></tr>"));

MeshWeaver.Layout.Controls.Html($"<table>{header}{body}</table>")

Edit with a Result Callback

Add a result callback to compute derived values whenever user input changes:

// Editor that displays X + Y as the user types
host.Hub.Edit(new Calculator(), c => Controls.Markdown($"Result: {c.X + c.Y}"));

This creates:

1. Editor controls for X and Y (bound to /data/{id}/x and /data/{id}/y)
2. A result area that recalculates whenever either value changes

Two-Way Sync Details

Changes travel as JSON Patch (RFC 6902) for efficient delta updates:

[{"op": "replace", "path": "/data/calc/x", "value": 5}]

• Client → Server: User edits create patches sent to the server.
• Server → Client: Server updates create patches sent to all subscribed clients.

Control-Specific Bindings

Dimension Attribute

Properties marked [Dimension] generate a SelectControl whose options are loaded from the workspace:

public record MyForm
{
    [Dimension<Country>]
    public string CountryCode { get; init; }
}

Custom Control Attribute

Use [UiControl<T>] to override which control type is generated for a property:

public record MyForm
{
    [UiControl<RadioGroupControl>(Options = new[] { "chart", "table" })]
    public string DisplayMode { get; init; }

    [UiControl<TextAreaControl>]
    public string Notes { get; init; }
}

Best Practices

1. Use records. Immutable records with init properties work best for data binding.
2. Add metadata. [Description] and [Display] attributes improve generated UIs.
3. Prefer Edit for forms. Let Edit generate controls automatically — write JsonPointerReference by hand only for non-standard layouts.
4. Use callbacks for computed values. The result-callback pattern is the right way to derive values from user input.
5. Never fetch in the backend. Pass paths; subscribe in the GUI. See The Golden Rule above.