Changing designs
Three ways to change what is there, from smallest to largest.
| Change | Use | Keeps |
|---|---|---|
| a few values | modify NODE '{...}' | everything else |
| a tree, by writing it again | build @tree.json --sync | ids, instances, comments of every layer that still matches |
| a component set | build @set.json --replace | its instances and what they set |
Read it back first
source prints a layer as you would write it: the shortest form, with containers as {"row": [...]}, plain texts as strings, the font and color a container passes down lifted back to it, kit colors and styles by name, instances as {"Component": {...}}.
$ facet source Library
{"row":[{"Raga/Card":{}},{"Raga/Card":{"State":"New","Hour":"AFTERNOON","Name":"राग भीमपलासी"}},{"Raga/Card":{"State":"Locked","Hour":"LATE NIGHT","Name":"राग मालकौंस"}}],"gap":20,"name":"Library","at":[1020,0]}
--depth N stops after N levels and counts the children it left out.
source prints what is there. Parts come back expanded, because a part leaves no link, and values equal to their defaults are left out. So for a screen you built from parts, keep editing your own JSON and send it with --sync; read with source what you did not write, or what someone changed by hand. A kit tint prints as you write it (@rose/20%). Variable bindings print as their variables, numbers and strings as well as colors ("width": "@Probe/size", "gap": "@Probe/gap", "text": "@Probe/label"), and a layer that sets a mode prints it ("mode": {"Probe": "B"}), so what source prints builds a tree that still follows its modes. A layer in a plain frame or a stack that is pinned other than to the top left prints its place ("at": "center", or ["bottom right", -8, -8] when it sits off it), which keeps both its spot and how it follows the frame's size.
Sync
build --sync matches what you write against the existing tree and changes only what differs:
- a written node matches the existing child with the same
keyor name (unnamed nodes match the next unnamed child of the same kind; several children with the same name match in order, so give repeated parts akey: insideeach,"key": "{id}"is filled per item like any other text, and the layer keeps its key with the document, so a sync finds it after its name, text or order changed); - a match of the same kind is updated in place; a match of another kind, and anything new, is built;
- existing children that nothing matches are deleted;
- children end in the written order.
Keys you write are applied. A key you leave out keeps its value; write "none" to clear a fill or stroke. The whole sync is one undo step, and the reply counts what it did: Synced: 2 changed, 1 added, 0 removed; 14 other layers were already as written. --preview renders the synced tree as it does a build.
To add one child, build @child.json --parent ID appends it last in its parent. To put it anywhere else, sync the parent with the child where it belongs.
Modify
modify takes the same keys as a node, for one layer and, with $nodes, its named descendants:
facet --doc f.facet modify Card '{"fill": "@paper", "$nodes": {"Title": {"text": "Tuesday", "font": "Inter 20/26 700"}}}'
On an instance, "props" or "properties" sets its component properties. On any other layer, the layer's own keys inside them apply as if given directly ({"properties": {"gap": 12}} sets a row's gap), keys given directly win, and anything else is reported. A layer whose size changes (a row gaining a child, a bound size, a mode switch) keeps the point its constraints pin: a centered row stays centered, where a fresh build puts it.
Replace a set
build @set.json --replace builds the set again in the old one's place. Instances move to the new variants with the same names and keep the properties they set.
Replays
A script that animates a design by syncing it again and again (a step every second or two) is not followed by the agent's cursor or the outlines of what changed: a sync that repeats the same agent's sync of the same layers within five seconds shows neither, so the cursor does not sit over what the replay shows. Its first step, and any one-off edit, show them as usual. --quiet ("presence": false) hides them for one call; "presence": true shows them for a call that would otherwise be quiet.
Copying to another file
source writes an instance by its component's name ({"Chip": {"Label": "Shipped"}}), which builds only in a file that has that component. facet --doc A.facet source Row --detach writes each instance as the layers it shows instead, so facet --doc B.facet build of that source shows the same layers in a file without the components (as plain layers, no longer linked to them).