Stream
A build is one JSON node, so nothing shows until all of it is written. The same design can be written as lines, one layer each. Every line that has arrived is a design that builds, so it appears as it is written:
my-agent | facet --doc f.facet build --stream # lines on stdin
facet --doc f.facet build --stream @card.sxl # or from a file
facet build --stream @card.sxl --print # the JSON the lines stand for; no document
A line
kind#Name key=value key=value | text
column#Card width=320 padding=[16,20] gap=12 fill=#FFFFFF cornerRadius=12 font="Inter 14 400"
row#Header width=fill gap=8 align=center
icon size=16 | lucide:bell
text#Title font="Inter 16 700" | Reminders
space | fill
text#Count color=@muted | 3
text#Body width=fill | Call the bank before noon.
Button#Done Kind=Quiet Label="Mark done" width=fill
- kind is a key of the language (
row,column,text,rectangle,icon,space…) or a name: a preset, a part or a component. - **
#Name** names the layer. A layer that is changed later needs one; a top-level layer without one is given one. A name with spaces is quoted:text#"Due date". - Indentation puts a line inside the nearest line above it that is indented less.
- Keys are the language's, written
key=value. A value with spaces is quoted; a list or a map is written as JSON (padding=[16,20]); a number,trueandfalseare themselves; a barekeyiskey=true. - **After
|** comes the text of atext, or the value of aniconor aspace, to the end of the line.\nis a line break and\|a bar. - On a component, keys of the language sit beside it (
width=fill) and every other key is one of its properties (Kind=Quiet). - A component set is
set#Namewith itsvariants(andprops,behavior) as JSON values and one line inside it, which every variant starts from:set#Switch variants={"State":{"Off":{},"On":{"fill":"#6E56CF"}}} behavior=toggle. Lines after it use it by name, in the same stream. - A line that starts with
#is a comment.
Changes
Change lines are not indented and name a layer by its name. They follow the design in the same stream, or come later in a stream of their own that starts with the design as it was written.
| Line | Does |
|---|---|
PATCH Count color=#DC2626 | sets keys of a layer (a component's properties too) |
REPLACE Body | Call the bank at 3. | replaces a text |
TEXT Body | Ask for Meera. | adds to the end of a text |
INSERT text#Note after=Body | … | a new layer after (or before=) a sibling, or the last one inside parent=NAME; lines indented under it go inside it |
DELETE Count | removes a layer and what is inside it |
END | nothing after it is read |
What happens
The stream writes what its lines changed and no more. Layers the document does not hold yet are built where they go (a new top-level layer on the page; a line under a layer that is already there, inside that layer, at its place); a PATCH, REPLACE or TEXT on a layer that is there changes that one layer; a DELETE removes it. So a page of thousands of layers takes one more card for the cost of the card. Lines that arrive while a write is under way are written together in the next.
A change that is not a write to one layer (new text on a container's own line, a set changed after it was built, a layer the document knows only by a name several layers share) syncs its top-level layer whole by name, as [build --sync](update.md) does, and so does a stream run again over a page that already holds its layers. The builder, its warnings and its replies are the ones every build has; at the end the command says how many builds, changes, deletions and whole syncs it made.
A line that cannot be read is noted with its number and a code, and left out; the stream goes on. What the builder warns about a batch is said when that batch is built, with the line it ends at. A set waits for its first line inside before it is built, and a component's name may be written with its spaces and no quotes (Laptop card#Mac). With --strict the command fails at that line.
| Code | Means |
|---|---|
E_BAD_LINE | not kind#Name key=value | text, or a quote left open |
E_DUPLICATE_ID | the name was already there: the line takes the earlier layer's place, with what is written inside it (an author that starts a part over means the new one); PATCH changes a layer without writing it again |
E_UNKNOWN_NODE | a change names a layer that is not there |
E_BAD_INSERT | INSERT without one of before=, after=, parent= |
E_IMMUTABLE | a name does not change: DELETE the layer and write it again |
E_NEEDS_VALUE | an icon or a space without its value after the bar |
Each write is an undo step, so a stream leaves many.
Hearing back
A screen whose components have behavior can be used while its author still writes it: facet act --follow prints each event a person (the Use tool) or an agent (facet act) sends, one line each, and the author answers in the stream it already has open.
The stream follows what its instances were moved to: a press that took Save to Saving is kept by the builds that come after, though its line first said State=Idle.
EVENT Save PRESS from=Idle to=Saving number=3 read from `facet act --follow`
REPLACE Status | Saving your changes… written to `facet build --stream`