The mutation protocol
.
Every call on a tree has a form as plain data: a
mutation
. A client that cannot call the tree directly sends mutations instead and gets the same event records back.That covers a host written in JavaScript, a client in another process, a recording to replay, and the window host's clients on the previous page.
A tree as data

The tree the batches below describe. Where the browser has WebGPU it is running: click the button, and the second batch is applied.
examples/src/tree/remote.silk
Copy
//! The same kind of tree, described as data. A client that cannot call the tree directly (a
//! JavaScript host, another process, a recording) sends mutations: it chooses the node
//! numbers itself and gets event records with those numbers back.
import
tree.card { rgb }
import
ui_tree.css
import
ui_tree.css { px, percent, Keyword
}
import
ui_tree.lib { Align
, Batch
, EventKind
, Mutation
, NodeKind
, StyleState
}
import
ui_tree.event { listenFlags }
import
silk.collections.list { List
}
import
silk.mem.allocator { Allocator
, OutOfMemoryError
}
// The client's own numbers.
pub
const
SANS
: u32 = 1
pub
const
ROOT
: u32 = 1
pub
const
BUTTON
: u32 = 2
pub
const
LABEL
: u32 = 3
/// Everything the first frame needs, as one batch.
pub
effect
fn
first
() -> List
<Mutation
>
! OutOfMemoryError
? &mut
Allocator
{
let
mut
batch = Batch
.make
()
run
batch.fontFamily
(SANS
, "Noto Sans, sans-serif"
)
run
batch.create
(ROOT
, NodeKind
.Box
)
run
batch.style
(
ROOT
,
&[
css.display
(Keyword
.Flex
),
css.height
(percent
(100.0
)),
css.alignItems
(Align
.Center
),
css.justifyContent
(Align
.Center
),
css.fontFamily
(SANS
),
css.fontSize
(px
(16.0
)),
css.backgroundColor
(rgb
(0xF3F4F6
)),
],
)
run
batch.root
(ROOT
)
// `box` is create, style and append in one call; `text` is create, set text and append.
run
batch.box
(
ROOT
,
BUTTON
,
&[
css.padding
(px
(12.0
)),
css.borderRadius
(px
(10.0
)),
css.color
(rgb
(0xFFFFFF
)),
css.backgroundColor
(rgb
(0x0F766E
)),
],
)
run
batch.styleFor
(BUTTON
, StyleState
.Hover
, &[css.backgroundColor
(rgb
(0x0D5F58
))])
run
batch.testId
(BUTTON
, "send"
)
run
batch.listen
(BUTTON
, listenFlags
(&[EventKind
.Click
]))
run
batch.text
(BUTTON
, LABEL
, "Send"
)
return
run
batch.take
()
}
/// What the client sends after a click: one mutation.
pub
effect
fn
sent
() -> List
<Mutation
>
! OutOfMemoryError
? &mut
Allocator
{
let
mut
batch = Batch
.make
()
run
batch.setText
(LABEL
, "Sent"
)
return
run
batch.take
()
}The client chooses the numbers
With direct calls, the tree hands out handles. With the protocol, the client names its nodes itself:
Silk
Copy
pub
const
ROOT
: u32 = 1
pub
const
BUTTON
: u32 = 2
pub
const
LABEL
: u32 = 3
That is what lets a remote client work without waiting for answers. It never has to ask "which id did my node get", so it can send a whole screen in one batch. Font families and image resources are numbered by the client in the same way.
A batch
examples/src/tree/remote.silk
Copy
/// Everything the first frame needs, as one batch.
pub
effect
fn
first
() -> List
<Mutation
>
! OutOfMemoryError
? &mut
Allocator
{
let
mut
batch = Batch
.make
()
run
batch.fontFamily
(SANS
, "Noto Sans, sans-serif"
)
run
batch.create
(ROOT
, NodeKind
.Box
)
run
batch.style
(
ROOT
,
&[
css.display
(Keyword
.Flex
),
css.height
(percent
(100.0
)),
css.alignItems
(Align
.Center
),
css.justifyContent
(Align
.Center
),
css.fontFamily
(SANS
),
css.fontSize
(px
(16.0
)),
css.backgroundColor
(rgb
(0xF3F4F6
)),
],
)
run
batch.root
(ROOT
)
// `box` is create, style and append in one call; `text` is create, set text and append.
run
batch.box
(
ROOT
,
BUTTON
,
&[
css.padding
(px
(12.0
)),
css.borderRadius
(px
(10.0
)),
css.color
(rgb
(0xFFFFFF
)),
css.backgroundColor
(rgb
(0x0F766E
)),
],
)
run
batch.styleFor
(BUTTON
, StyleState
.Hover
, &[css.backgroundColor
(rgb
(0x0D5F58
))])
run
batch.testId
(BUTTON
, "send"
)
run
batch.listen
(BUTTON
, listenFlags
(&[EventKind
.Click
]))
run
batch.text
(BUTTON
, LABEL
, "Send"
)
return
run
batch.take
()
}Batch
is a builder for a list of mutations. Each method adds one, or a few that usually go together:Method
Adds
create(id, kind)
A new node
style(id, declarations)
, styleFor(id, state, declarations)
Style for the base look, or for a state
append(parent, child)
, insertBefore(parent, child, before)
Structure
box(parent, id, declarations)
Create, style and append, in one
text(parent, id, value)
Create a text, set it and append it
setText(id, value)
New text for a text or an input
attribute(id, attribute)
, testId
, label
Attributes
listen(id, flags)
Which events a node wants
root(id)
, openRoot
, closeRoot
Roots
fontFamily(family, names)
, image(resource, bytes)
, icon(resource, bytes)
Resources
batch.take()
hands over the list and leaves the builder empty for the next one.Applying it
Silk
Copy
run
tree.apply
(run
remote.first
())apply
runs the mutations in order. If one fails, it stops there and says which:Output
Copy
mutation 5: node #99 does not exist (it was destroyed, or never created)
The mutations before it stay applied.
Records come back with the client's numbers
tests/src/tree.silk
Copy
effect
fn
treeBody
() -> ()
! AssertionError
<'static
> | TreeError
| ProtocolError
| OutOfMemoryError
? &mut
Allocator
{
let
fonts = run
fixtures.fonts
()
// Queries: find a node by its test id, and read where layout put it.
let
mut
tree = run
Tree
.make
(&fonts)
let
sans = run
tree.fontFamily
("Noto Sans, sans-serif"
)
let
built = run
card.build
(&mut
tree, sans)
drop
run
tree.frame
(viewport
(), 0.0
)
let
found = run
tree.find
("refresh"
)
run
Testing
.expect
(found.length
() == 1
&& found.get
(0
).is
(built.button), "find reads test ids"
)
let
text = run
tree.describe
(DescribeOptions
.plain
())
run
Testing
.expect
(String
.contains
(String
.view
(&text), "Tide tables"
), "describe writes the tree"
)
// Events: input in, records out, and the client changes the tree.
let
mut
second = run
Tree
.make
(&fonts)
let
family = run
second.fontFamily
("Noto Sans, sans-serif"
)
let
mut
counter = run
clicker.build
(&mut
second, family)
run
click
(&mut
second, counter.button.id
())
run
click
(&mut
second, counter.button.id
())
run
counter.pump
(&mut
second)
run
Testing
.expect
(counter.clicks == 2
, "two clicks were recorded"
)
let
after = run
second.find
("Clicked 2 times"
)
run
Testing
.expect
(after.length
() == 1
, "and the label says so"
)
// Text: the tree edits, the client hears the new value.
let
mut
third = run
Tree
.make
(&fonts)
let
face = run
third.fontFamily
("Noto Sans, sans-serif"
)
let
mut
greeting = run
field.build
(&mut
third, face)
run
third.focus
(greeting.name)
run
third.dispatch
(run
Input
.text
("Ada"
))
run
greeting.pump
(&mut
third)
run
Testing
.expect
((run
third.find
("Hello, Ada."
)).length
() == 1
, "typing reaches the greeting"
)
// The protocol: the client's own numbers come back in the records.
let
mut
fourth = run
Tree
.make
(&fonts)
run
fourth.apply
(run
remote.first
())
run
click
(&mut
fourth, NodeId
.of
(remote.BUTTON
))
let
records = run
fourth.events
()
run
Testing
.expect
(records.length
() == 1
, "one click"
)
run
Testing
.expect
(records.asSlice
()[0
].target.raw
() == remote.BUTTON
, "on the client's node 2"
)
if
let
Event
.Click
{ .. } = &records.asSlice
()[0
].event {
run
fourth.apply
(run
remote.sent
())
}
run
Testing
.expect
((run
fourth.find
("Sent"
)).length
() == 1
, "the answer is one mutation"
)
}The last part of that test is the protocol's round trip. A click is dispatched, the record's target is
2
, the client's own number for its button, and the client answers with a batch of one mutation.Both at once
Direct calls and protocol numbers can share one tree.
NodeId.of(7)
names the client's node 7 for a direct call, and a node made with tree.box
takes a number that is not in use.Silk
Copy
let
extra = run
tree.box
(&[])
run
tree.append
(BoxNode
.of
(NodeId
.of
(7
)), extra)Why it matters
Because the boundary is data, the tree does not care who is on the other side.
•
Silk UI
computes the difference between two views and sends it as one batch per update.•
The window host
hands its clients the same batches and records.•
The inspector
reads the tree and replays input through the same door, which is why devtools work on any client.•
A host in another language
needs only a way to send mutations and receive records. It does not have to bind every function.