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.
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.