makepad/apps/vj/LIVECODING.md

Livecoding VJ effects — the coding-agent contract

You write a .splash file. A second later it is in the VJ's grid with a thumbnail. You edit that same file. The effect running on screen right now recompiles in place. You read one file to find out whether it compiled.

That is the whole loop. This document is how to drive it.

For what a document IS — engines, stages, shader hooks, signals, dials — read apps/vj/src/effects/CONTRACT.md first. This file only covers the edit → live cycle.

---

1. Where to put the file

Two directories are observed. Both behave identically.

directory	what it is for
local/vjfx/	the scratch origin. Untracked. Drop new documents here. Created on first run.
apps/vj/resources/effects/	the seed origin — the bundled preset library itself. Editing 42_whatever.splash here republishes that preset.

Override the scratch origin with VJ_FX_ORIGIN=<dir> (the compile answers move with it). Sub-directories are walked, up to four levels; hidden files and symlinks are skipped.

Nothing is copied. The store hashes your file where it lies and catalogues path + size + digest (libs/asset/store/src/blobrefs.rs), so the file you edit stays the one and only copy, and git sees exactly what you wrote.

2. Naming, and what the name means

The alias is the file stem. local/vjfx/91_ion_veil.splash publishes as vjfx/91_ion_veil.

Consequences worth internalising:

• Same stem = same asset. Save the file again and the store publishes a NEW REVISION of that same asset and re-points the alias at it. That is what the running slot watches for.
• A new stem = a new asset. Renaming a file makes a second library entry; the old one stays until somebody retires it.
• A bundled preset's stem is that preset. Editing apps/vj/resources/effects/09_synthwave.splash republishes vjfx/09_synthwave. The compiled-in copy in the binary stops being the head; a rebuild will not take it back (the seed pass never rewrites a head it did not itself publish). If you want the bundled bytes back, restore the file — the observer publishes whatever is on disk.
• Stems must be [a-z0-9._-]-ish and at most 64 characters (the alias charset). A file the store cannot name is skipped silently.
• Follow the library convention for new documents: NN_snake_name.splash.

Transitions. A document lands in the TRANSITION lane when it declares engine: "transition", "screen" or "tiles", or when it says transition: true at the top level. The tag is what the TRANSITION chip filters on and what the transition slot's type gate accepts.

3. What happens when you save

1. Debounce + stability. The origin watcher (FSEvents / inotify / ReadDirectoryChangesW) collects the editor's write burst for ~80 ms, then waits for the file's size and mtime to hold still for ~150 ms. A half-written document never becomes a revision.
2. Digest compare. If the head revision's Source blob already equals your file's sha256, nothing happens — no revision, no event, no thumbnail. Touching a file, or a git checkout that restores identical bytes, costs one hash.
3. Publish. Otherwise: a new revision under the same alias, published by reference. Tags: vjeffect, livecoded, plus transition when declared.
4. Event. The store's /v1/events journal carries the republish; the VJ's catalog subscriber picks it up within a poll.
5. Grid tile refreshes. The tile forgets the revision it remembered and re-resolves — keeping its current picture until the new manifest lands, so the grid never blanks.
6. Thumbnail regenerates. Animated thumbnails are cached by REVISION id, so a new revision has no cache and the offscreen bank re-renders a fresh 30-frame sheet.
7. Running slot reloads. If FX A, FX B or TRANSITION is running that asset, the VJ re-fetches the new head's Source blob and loads it into the same slot key — VjFxView::set_effect_source replaces the document in place, so the effect recompiles without the slot emptying, the knobs resetting under your hand, or the program mix moving.

Steps 1–3 are libs/asset/store/src/observe.rs; 4–7 are apps/vj/src/main.rs (pump_subscriber → reload_fx_slot_from_store → load_fx_slot).

4. Reading the compile result

Two files, both under the scratch origin (local/vjfx/ unless VJ_FX_ORIGIN moved it):

local/vjfx/status/<stem>.status   ← poll this
local/vjfx/compile.log            ← the stream, one line per outcome

<stem>.status is overwritten on every outcome and always starts with the verdict:

compile ok
doc: 91_ion_veil
revision: arev_9f3c…
t: 1787473982375

or

compile error: draw shader 'DrawVjFxParticles' failed to compile and will NOT be drawn:
  line 14: unknown function 'wobble'
doc: 91_ion_veil
revision: arev_9f3c…
t: 1787473983102

So the poll is grep -q '^compile ok' local/vjfx/status/91_ion_veil.status, and the diagnosis is the rest of the file.

compile.log is the same verdicts as one line each, appended, tail-capped:

1787473982375 91_ion_veil rev=arev_9f3c1b2d4e5f6a compile ok
1787473983102 91_ion_veil rev=arev_77aa11bb22cc33 compile error: draw shader …

What "ok" actually means

Two different failures can eat your edit, and both are covered:

• The document does not evaluate (script/parse error, bad engine name, malformed hook). Reported the instant it happens, straight from VjFxView::set_effect_source's error.
• The document evaluates but its draw shader does not compile. A draw shader compiles at DRAW time, not at load, and its failure is reported through error! — so compile ok is only ever written after the document has actually been drawn and a short settle window has passed with nothing to report. The mechanism is a tap on the app's own log (makepad_error_log::set_log_tap), not a second validator: whatever the app tells a human is what lands in your file.

A shader that fails to compile is skipped, so the on-screen symptom is a flat clear-color region — never a fallback that quietly renders something else. A black thumbnail is NOT by itself a verdict (an input-shaping screen/transition document renders black with no program behind it), which is why the answer comes from the compiler's own words.

When the answer arrives

An outcome is written whenever the document is loaded and drawn:

• as soon as its grid tile's animated thumbnail renders (this is the usual path for a brand-new document — the offscreen bank picks it up when the tile is in the video grid), or
• immediately when it is loaded into an FX slot, hot reload included.

Only documents that live in an observed origin get files written; the rest of the library rendering its own thumbnails is not news.

5. The fast cycle

# 1. host the store in the VJ itself, and drive it over HTTP
cargo build --release -p makepad-vj
VJ_ASSET_EMBED=always ./target/release/makepad-vj --remote > /tmp/vj.log 2>&1 &
P=$(grep -o 'listening on 127.0.0.1:[0-9]*' /tmp/vj.log | grep -o '[0-9]*$')

# 2. write a document
cat > local/vjfx/91_ion_veil.splash <<'EOF'
// ION VEIL — <what this teaches>.
{
    name: "Ion Veil"
    engine: "particles"
    ...
}
EOF

# 3. read the verdict (it lands within a second or two of the save)
cat local/vjfx/status/91_ion_veil.status

# 4. look at it. `/snap` only sees tiles that are ON SCREEN, so type the
#    name into the grid's filter box first, then click the tile (an FX
#    click with no slot armed lands on the faded-out side and fades in).
curl -s "http://127.0.0.1:$P/click?x=68&y=616&wait=1"   # the filter box
curl -s "http://127.0.0.1:$P/t?t=Ion"
curl -s "http://127.0.0.1:$P/snap?q=Ion"
curl -s "http://127.0.0.1:$P/click?x=…&y=…&wait=1"
curl -s "http://127.0.0.1:$P/g"

# 5. edit the SAME file — the running slot recompiles in place; grab again
#    to see the change, and re-read the .status file.

# 6. always
curl -s "http://127.0.0.1:$P/gq"

VJ_ASSET_EMBED=always is what makes the VJ host its own store, which is what makes it the process that observes your directories. See §7.

For look iteration WITHOUT the app, the gallery rig is still the sharper instrument — deterministic frames, whole-library sweeps, no store at all: VJFX_DOC=<name> ./target/release/examples/effect_gallery --remote and the VJFX_CAPTURE / VJFX_SWEEP / VJFX_INPUT levers in CONTRACT.md §"Verifying a look change". Use the gallery to get the look right; use livecoding to see it in the mix, on the beat, against real content.

6. The laws

These are not style notes. Both have shipped as bugs.

• A look must be a BOUNDED function of time and beat. beat is the host's SONG clock: an effect cued an hour into a set gets its first frame at beat ~6000 and time free-runs for as long as the slot holds the document. Anything steering geometry — a fold angle, a scale, a domain size — must be periodic (sin/cos/fract of the clock), clamped, or both. angle = 0.52 + beat * 0.010 looks lovely for the two seconds a capture runs and is a BLACK FRAME on the deck. "Never repeats" is still available honestly: sum two slow sines whose frequency ratio is not a simple fraction. Verify with VJFX_CAPTURE=600@1.0 (t = 0 / 60 / 600 / 3600 s) before calling a document done. A bundled preset that uses the raw beat count must be named in seed::registry_tests::every_beat_count_use_is_reviewed, with the reason.
• Never name an effect's inspiration source. Not in name:, not in the comment block, not in the file stem, not in the shader. Describe what the look IS — the motion, the material, the colour — not what it is "like". The comment block is the description the catalog shows; write it to teach the pattern the document demonstrates.
• A document carries its own shader. The pixel math goes IN THE FILE, as a shader: block subclassing the engine's draw shader. Self- containedness beats DRY: two documents of one family each carry their own copy of the same look function. This is what makes a file forkable, and it is what makes livecoding worth anything — an author who can only re-tune amp: 0.6 can only make a variation.

7. Who observes, and why it is off by default

Admitting content by reference means "read any file this process can read, then serve it by digest" — exactly the privilege of the process itself. That is fine for an app hosting its own store on loopback and is not fine for anything reachable off the box, so BlobRefPolicy is off unless an embedder turns it on, and refuses any non-loopback caller when it is.

Therefore: the process that HOSTS the store owns the watch.

you are running	observes?
VJ with VJ_ASSET_EMBED=always (or auto with nothing else up)	yes — it hosts
asset-ui holding the catalog root	yes — it hosts
VJ attached to asset-ui's store	no — asset-ui is doing it
VJ attached to a store on another machine	no. Local paths mean nothing there.

If you are livecoding and nothing appears, that is the first thing to check: the VJ's status line says which store it is on, and the app log carries [observe] watching … from whichever process started the watcher.

The VJ starts its observer on the same worker thread that seeds the bundled library, and starts it AFTER seeding — so a preset file you edited while the app was off wins over the compiled-in bytes without racing for it.

8. Where the code is

file	what
libs/asset/store/src/observe.rs	the watch service: debounce, write-stability, digest compare, publish-by-reference
libs/asset/store/tests/http/observe_http.rs	the end-to-end proof (drop, edit, republish, no copy, prompt stop)
libs/filesystem_watcher/	the per-platform directory watcher
apps/vj/src/livecode.rs	origins, the log tap, the .status / compile.log writer
apps/vj/src/main.rs	republish → slot reload (reload_fx_slot_from_store), observer start
apps/asset-ui/src/asset_store_state.rs	start_observe_loop, hosted-only
apps/vj/src/effects/CONTRACT.md	what a document is
apps/vj/src/effects/IDEAS.md	the look backlog