hot_reload/

hot_reload.rs

//! Edit a running SwiftUI app's screen in a text editor and watch it change.
//!
//! No recompile, no relaunch, no Swift toolchain — the process keeps running
//! and the view tree is rebuilt from the file each time it changes. A SwiftUI
//! app cannot do this: its view types are fixed when the app is compiled, and
//! changing a `VStack { … }` means building a new binary.
//!
//! ```sh
//! # Writes a starter file, opens a window, and watches it.
//! cargo run -p swiftui-native --example hot_reload
//!
//! # …then, in another terminal, edit it and the window follows:
//! $EDITOR target/hot_reload.ui
//! ```
//!
//! `--frames` is the same thing without a window: it applies a series of edits
//! and writes a PNG after each, which is what makes the behaviour testable
//! rather than only demonstrable.
//!
//! ```sh
//! cargo run -p swiftui-native --example hot_reload -- --frames
//! ```

// As `dynamic_ui`: the iOS `main` watches and runs, and the offscreen frame
// writer the macOS one offers has no caller there.
#![allow(dead_code)]

use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Mutex, OnceLock};
use std::time::{Duration, SystemTime};
use swiftui_native::prelude::*;

#[path = "common/spec.rs"]
mod spec;

/// Where the watched file lives. Under `target/` so the repository is not
/// dirtied by running the example.
fn path() -> String {
    std::env::args()
        .skip(1)
        .find(|a| !a.starts_with("--"))
        .unwrap_or_else(|| format!("{}/../../target/hot_reload.ui", env!("CARGO_MANIFEST_DIR")))
}

const STARTER: &str = r#"// Edit this file and save. The window follows — and the
// controls below keep their values across the reload.
// Names: vstack hstack zstack text spacer divider button color image
//        rect circle capsule progress gauge group_box list scroll form label

vstack spacing=14 pad=24 align=leading {
  text "Hot reload" style=large_title bold
  text "Change this file; the app does not restart." color=secondary size=13
  divider
  hstack spacing=10 {
    circle color=green frame=12x12
    text "watching" size=13
    spacer
    text "edit me" color=blue size=13
  }

  // `@name` binds a control to a slot that outlives the view tree. Change
  // these, then edit anything above, and they keep what you set.
  toggle "Dark mode" @dark
  stepper "Copies" @copies min=0 max=20
  slider @level min=0 max=100

  spacer
}
"#;

/// What the screen is built from, and what the last attempt did.
///
/// `last_good` is the point. A file being edited is invalid most of the time —
/// half a brace, a string that is not closed yet — and a hot reloader that
/// replaced the screen with an error message every time would be unusable. So
/// the last version that *parsed* stays on screen, and the error is shown over
/// it. Losing the screen is how you lose your place.
#[derive(Default)]
struct Reloader {
    last_good: String,
    error: Option<String>,
    generation: u64,
    /// How long the last reload took, end to end.
    micros: u64,
}

fn state_cell() -> &'static Mutex<Reloader> {
    static CELL: OnceLock<Mutex<Reloader>> = OnceLock::new();
    CELL.get_or_init(|| {
        Mutex::new(Reloader { last_good: STARTER.to_string(), ..Default::default() })
    })
}

static GENERATION: AtomicU64 = AtomicU64::new(0);

fn body() -> View {
    let (src, error, generation, micros) = {
        let g = state_cell().lock().expect("state");
        (g.last_good.clone(), g.error.clone(), g.generation, g.micros)
    };

    // The last version that parsed. It cannot fail — it parsed before — but a
    // spec that builds views from slots could in principle, so the fallback is
    // still handled rather than unwrapped.
    let screen = spec::parse(&src)
        .and_then(|nodes| spec::build(&nodes))
        .unwrap_or_else(|e| text(&e).fg_system(SystemColor::Red).padding(20.0));

    vstack_spacing(&[screen, status(error.as_deref(), generation, micros)], 0.0)
}

/// A strip along the bottom: which generation is on screen, how long the last
/// reload took, what the slots hold, and the error if there is one.
///
/// In the window rather than the terminal because that is where you are
/// looking. Watching a reloader work from a log means watching two things.
fn status(error: Option<&str>, generation: u64, micros: u64) -> View {
    let slots = spec::slot_summary();
    let slot_line = if slots.is_empty() {
        String::new()
    } else {
        slots
            .iter()
            .map(|(k, v)| format!("{k}={v}"))
            .collect::<Vec<_>>()
            .join("  ")
    };

    // The error row is *always* present, empty when there is nothing wrong.
    // An error that appears and disappears would otherwise reflow the screen
    // above it on every save — which looks exactly like the reloader having
    // replaced the view, and makes "did the screen survive this?" impossible
    // to answer by looking.
    let rows = vec![
        divider(),
        hstack_spacing(
            &[
                circle_shape()
                    .fill_system(if error.is_some() {
                        SystemColor::Orange
                    } else {
                        SystemColor::Clear
                    })
                    .frame(8.0, 8.0),
                text(error.unwrap_or(""))
                    .font_size(11.0)
                    .fg_system(SystemColor::Orange),
                spacer(),
            ],
            6.0,
        )
        .padding(6.0)
        .frame(348.0, 24.0),
        hstack_spacing(
            &[
                circle_shape()
                    .fill_system(if error.is_some() {
                        SystemColor::Orange
                    } else {
                        SystemColor::Green
                    })
                    .frame(8.0, 8.0),
                text(&format!("gen {generation}"))
                    .font_size(11.0)
                    .fg_system(SystemColor::Secondary),
                // Microseconds below a millisecond: a reload of a short spec
                // really is that fast, and "0.0 ms" reads as "not measured".
                text(&if micros < 1000 {
                    format!("{micros} \u{b5}s")
                } else {
                    format!("{:.1} ms", micros as f64 / 1000.0)
                })
                .font_size(11.0)
                .fg_system(SystemColor::Secondary),
                spacer(),
                text(&slot_line).font_size(11.0).fg_system(SystemColor::Secondary),
            ],
            8.0,
        )
        .padding(6.0)
        .frame(348.0, 24.0),
    ];
    vstack_spacing(&rows, 0.0)
}

fn content_view() -> swiftui_native::ViewHandle {
    swiftui_native::state::root_view(|_| body().into_handle())
}

/// Read the file, parse it, and keep it if it parsed.
///
/// Returns whether the screen should be rebuilt. Three things make this more
/// than a read:
///
/// * The text is **parsed here**, not in the body. A file that does not parse
///   leaves `last_good` alone, so the screen survives being edited.
/// * A failed *read* is not a failed reload. Editors save atomically — write a
///   temporary file, rename it over the target — so for a moment the path may
///   not exist. Treating that as "no change" and waiting is right; treating it
///   as an error would flash a message on every save in vim or VS Code.
/// * Identical text is not a change. `touch` and some editors rewrite a file
///   byte for byte, and rebuilding for that would discard nothing but would
///   log a reload that did not happen.
fn reload(p: &str) -> bool {
    let started = std::time::Instant::now();
    let Ok(text) = std::fs::read_to_string(p) else { return false };

    let mut g = state_cell().lock().expect("state");
    if g.last_good == text && g.error.is_none() {
        return false;
    }
    match spec::parse(&text).and_then(|nodes| spec::build(&nodes)) {
        Ok(_) => {
            g.last_good = text;
            g.error = None;
        }
        Err(e) => {
            // Same error as last time means the file has not usefully changed;
            // saying so again would be noise.
            if g.error.as_deref() == Some(e.as_str()) {
                return false;
            }
            g.error = Some(e);
        }
    }
    g.generation += 1;
    g.micros = started.elapsed().as_micros() as u64;
    GENERATION.store(g.generation, Ordering::Relaxed);
    true
}

/// How long to wait after a change before reading, so a half-written file is
/// not parsed. Long enough to cover an editor's write, short enough that a
/// person does not notice.
const SETTLE: Duration = Duration::from_millis(60);

/// Watch the file on a background thread.
///
/// Polling rather than FSEvents: the trigger is a person saving a file, so the
/// interval only has to beat their reaction time, and a callback-based watcher
/// would be more machinery than this example is about. What it does need to get
/// right is *what counts as a change* —
///
/// * **Size as well as mtime.** A write inside the same coarse mtime tick — an
///   editor that saves twice quickly, or a script — changes the size, and
///   watching mtime alone would miss it.
/// * **Disappearance.** An atomic save unlinks the old file; the watcher waits
///   for it to come back rather than giving up on the path.
/// * **Settling.** A change is acted on `SETTLE` later, so a file caught
///   mid-write is read once it is whole rather than parsed in two halves.
///
/// `state::refresh` has to run on the main thread, so this only raises a flag.
fn watch(p: String) {
    std::thread::spawn(move || {
        let mut seen: Option<(SystemTime, u64)> = None;
        let mut settle_at: Option<std::time::Instant> = None;
        loop {
            let stamp = std::fs::metadata(&p)
                .and_then(|m| Ok((m.modified()?, m.len())))
                .ok();
            match (stamp, seen) {
                // Gone for the moment, as during an atomic save: wait.
                (None, _) => {}
                (Some(now), Some(before)) if now == before => {}
                (Some(now), _) => {
                    seen = Some(now);
                    settle_at = Some(std::time::Instant::now() + SETTLE);
                }
            }
            if let Some(at) = settle_at {
                if std::time::Instant::now() >= at {
                    settle_at = None;
                    if reload(&p) {
                        PENDING.store(true, Ordering::Relaxed);
                    }
                }
            }
            std::thread::sleep(Duration::from_millis(30));
        }
    });
}

static PENDING: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Apply a series of edits with no window, writing a PNG after each.
///
/// The point of the example is that the *same process* renders different
/// screens as the file changes, so each frame here is written after a real
/// write-and-reload rather than by calling the builder with different text.
fn frames() {
    let p = path();
    let edits: &[(&str, &str)] = &[
        ("1_start", STARTER),
        (
            "2_recoloured",
            r#"vstack spacing=14 pad=24 align=leading {
  text "Hot reload" style=large_title bold color=blue
  text "Same process. Second version." color=secondary size=13
  divider
  hstack spacing=10 {
    circle color=orange frame=12x12
    text "reloaded once" size=13
    spacer
  }
  progress 0.6
  spacer
}"#,
        ),
        (
            "3_restructured",
            r#"// A different shape entirely: the Swift type changes with it.
zstack align=center frame=320x220 {
  color #24303f frame=300x200 corner=18
  vstack spacing=12 pad=20 align=leading {
    text "Third version" style=title2 bold color=white
    text "No recompile happened between these frames." color=white size=12 opacity=0.75
    spacer
    gauge 0.8 label="done"
  }
}"#,
        ),
        ("4_broken", "vstack { text \"unclosed"),
    ];

    for (name, text_src) in edits {
        std::fs::write(&p, text_src).expect("write spec");
        // Through the same path the watcher uses, so the frame proves the
        // reload, not just the builder.
        reload(&p);
        let handle = content_view();
        let out = format!("{}/../../target/hot_reload_{name}.png", env!("CARGO_MANIFEST_DIR"));
        let ok = swiftui_native::render::render(&handle, 360, 400).write_png(&out);
        let built = body().into_handle();
        println!(
            "{name:16} {}",
            swiftui_native::diag::type_name(swiftui_native::views::meta_of(&built))
                .chars()
                .take(72)
                .collect::<String>()
        );
        println!("{:16} {}", "", if ok { out } else { "render failed".into() });
    }
    // Leave the starter behind so a following run with a window has something
    // valid to open, rather than the deliberately broken last frame.
    std::fs::write(&p, STARTER).expect("restore spec");
}

/// Open the window, edit the file underneath it, and capture the *window*
/// after each edit.
///
/// `--frames` renders offscreen, which shows the builder produces different
/// pictures. This shows the stronger thing: a window that is already on screen
/// changing because a file changed. The captures come from the live hosting
/// view, so nothing here could pass by rendering a fresh tree on the side.
#[cfg(target_os = "macos")]
fn drive() {
    let p = path();
    std::fs::write(&p, STARTER).expect("write starter");
    reload(&p);
    watch(p.clone());

    let window = swiftui_native::Window::new(&content_view(), "Hot reload", 360.0, 420.0);
    let shot = |n: &str| {
        let out = format!("{}/../../target/hot_reload_live_{n}.png", env!("CARGO_MANIFEST_DIR"));
        let r = swiftui_native::render::render_hosting(window.hosting(), 360, 420);
        r.write_png(&out);
        (out, r)
    };

    // Pixels differing *above* the status strip.
    //
    // The strip reports the generation, so it changes on every reload whether
    // or not the screen did — comparing whole frames would make "the screen
    // survived a file that does not parse" indistinguishable from "the screen
    // changed".
    fn screen_diff(
        a: &swiftui_native::render::Rendered,
        b: &swiftui_native::render::Rendered,
    ) -> u32 {
        if a.width != b.width || a.height != b.height {
            return u32::MAX;
        }
        // Measured, not estimated: with a 420-point capture the strip's own
        // pixels start at row 294, so everything from 290 down is excluded.
        // Guessing 90 left part of the strip in the comparison and reported a
        // screen that had not moved as having moved.
        const SCREEN_ROWS: u32 = 290;
        let keep = (SCREEN_ROWS.min(a.height) * a.width * 4) as usize;
        a.pixels[..keep]
            .chunks_exact(4)
            .zip(b.pixels[..keep].chunks_exact(4))
            .filter(|(x, y)| x != y)
            .count() as u32
    }

    // Let the window settle before the first capture, or it is caught blank.
    swiftui_native::render::pump_events(1.0);
    let (first_path, first) = shot("1_start");

    // A user changes the toggle. Everything after this checks it stays
    // changed, which is what separates reloading from restarting.
    spec::set_flag("dark", true);
    swiftui_native::state::refresh();
    window.set_root(&content_view());
    swiftui_native::render::pump_events(0.4);

    /// One edit, and whether the screen should follow it.
    struct Edit {
        name: &'static str,
        src: &'static str,
        /// `false` for a spec that does not parse: the screen must *not*
        /// change, because the last good one has to stay put.
        expect_change: bool,
    }

    let edits = &[
        Edit {
            name: "2_edited",
            src: "vstack spacing=10 pad=20 align=leading {\n  \
                  text \"Edited while running\" style=title bold color=red\n  \
                  text \"the process never restarted\" color=secondary size=12\n  \
                  toggle \"Dark mode\" @dark\n  \
                  gauge 0.9 label=\"reloaded\"\n}",
            expect_change: true,
        },
        Edit {
            name: "3_restructured",
            src: "zstack align=center frame=300x200 {\n  \
                  color #223344 frame=280x180 corner=14\n  \
                  text \"a different shape entirely\" color=white size=14\n}",
            expect_change: true,
        },
        Edit {
            // Mid-edit: a brace that is never closed. The screen must survive.
            name: "4_broken",
            src: "zstack align=center frame=300x200 {\n  color #223344",
            expect_change: false,
        },
    ];

    let mut shots = vec![(first_path, first)];
    let mut ok = true;
    for e in edits {
        std::fs::write(&p, e.src).expect("write edit");
        let deadline = std::time::Instant::now() + Duration::from_secs(4);
        while !PENDING.load(Ordering::Relaxed) && std::time::Instant::now() < deadline {
            swiftui_native::render::pump_events(0.05);
        }
        if !PENDING.swap(false, Ordering::Relaxed) {
            eprintln!("{}: the watcher never fired", e.name);
            std::process::exit(1);
        }
        swiftui_native::state::refresh();
        window.set_root(&content_view());
        swiftui_native::render::pump_events(0.6);
        let (path_now, shot_now) = shot(e.name);

        let (prev_path, prev) = shots.last().expect("a previous shot");
        let d = screen_diff(prev, &shot_now);
        println!("{prev_path}\n  -> {path_now}\n     {d} pixels differ above the status strip");
        match (e.expect_change, d) {
            (true, 0) => {
                eprintln!("     the window did not follow the edit");
                ok = false;
            }
            (false, n) if n > 0 => {
                eprintln!("     a file that does not parse replaced the screen");
                ok = false;
            }
            _ => {}
        }
        shots.push((path_now, shot_now));
    }

    // …and the toggle is still on, after every reload and a broken file.
    let dark = spec::slot_summary().into_iter().find(|(k, _)| k == "dark").map(|(_, v)| v);
    println!("slot `dark` after every reload: {dark:?}");
    if dark.as_deref() != Some("true") {
        eprintln!("  a reload reset the slot");
        ok = false;
    }

    std::fs::write(&p, STARTER).expect("restore spec");
    if !ok {
        std::process::exit(1);
    }
    println!("followed every valid edit, survived an invalid one, kept its state");
}

#[cfg(target_os = "macos")]
fn main() {
    let p = path();
    if std::env::args().any(|a| a == "--frames") {
        return frames();
    }
    if std::env::args().any(|a| a == "--drive") {
        return drive();
    }

    if !std::path::Path::new(&p).exists() {
        std::fs::write(&p, STARTER).expect("write starter");
        eprintln!("wrote {p}");
    }
    reload(&p);
    watch(p.clone());
    eprintln!("watching {p} — edit it and save");

    // `Window::run` enters AppKit's loop and never comes back, which leaves
    // nowhere to notice the file changed. Pumping the loop in slices instead
    // keeps the window live *and* gives this thread a turn between them —
    // `state::refresh` has to happen on the main thread, so the watcher only
    // raises a flag and the work is done here.
    let window = swiftui_native::Window::new(&content_view(), "Hot reload", 360.0, 420.0);
    loop {
        swiftui_native::render::pump_events(0.05);
        if PENDING.swap(false, Ordering::Relaxed) {
            // Two mechanisms, because the screen may be either shape: the
            // synthesised root re-evaluates its body on `refresh`, and
            // `set_root` hands SwiftUI a fresh tree to diff against. The first
            // alone leaves a structural change — a `VStack` becoming a
            // `ZStack` — with nothing to diff.
            swiftui_native::state::refresh();
            window.set_root(&content_view());
            eprintln!("reloaded (generation {})", GENERATION.load(Ordering::Relaxed));
        }
    }
}

#[cfg(not(target_os = "macos"))]
fn main() {
    let p = path();
    reload(&p);
    watch(p);
    swiftui_native::app::run(content_view)
}