From 91e02352a2a38fe6a935a1e24de55b2e355b4638 Mon Sep 17 00:00:00 2001
From: Geoff Johnson <geoff.jay@gmail.com>
Date: Fri, 31 Jul 2026 21:51:26 -0700
Subject: [PATCH 1/2] doc: add screenshot plugin plan

---
 docs/knowledgebase/index.md                   |   1 +
 docs/knowledgebase/log.md                     |   1 +
 docs/knowledgebase/plans/index.md             |   1 +
 .../plans/screenshot-as-plugin.md             | 256 ++++++++++++++++++
 4 files changed, 259 insertions(+)
 create mode 100644 docs/knowledgebase/plans/screenshot-as-plugin.md

diff --git a/docs/knowledgebase/index.md b/docs/knowledgebase/index.md
index afabdc3..b9092f0 100644
--- a/docs/knowledgebase/index.md
+++ b/docs/knowledgebase/index.md
@@ -80,6 +80,7 @@ to touch the KB on every edit.
 * [Roadmap](plans/roadmap.md) - current capabilities, phase-2 status, remaining roadmap items, and pointers to full planning docs.
 * [Declarative children over JSON-string properties](plans/declarative-children-migration.md) - migrate collection components from JSON-string attributes to nested child elements, piloted on accordion.
 * [Headless renderer and screenshots](plans/headless-screenshots.md) - `nemo screenshot` implemented on macOS via gpui's offscreen `Window::render_to_image`; Linux capture remains open.
+* [Screenshot as a plugin](plans/screenshot-as-plugin.md) - move `nemo screenshot` off the feature-gated host build onto a stock release binary via an OS-native capture plugin; needs `Capability::Command` (plugin-contributed CLI subcommands) + a host `capture_app_window` bootstrap primitive. **Planned.**
 * [Devtools inspector](plans/devtools-inspector.md) - what a nemo-devtools crate would take; the introspection surfaces already exist, in-process panel recommended over an external client.
 * [Design tokens and active redesign](plans/design-tokens.md) - centralized spacing/radius/typography/semantic-color tokens (gpui-free `nemo-tokens` crate); full chrome migration with screenshot verification.
 * [Design-system export](plans/design-system-export.md) - `cargo xtask design-export` emits tokens + themes + component structure as a pencil.dev-friendly JSON intermediate.
diff --git a/docs/knowledgebase/log.md b/docs/knowledgebase/log.md
index c1ce31e..06df638 100644
--- a/docs/knowledgebase/log.md
+++ b/docs/knowledgebase/log.md
@@ -1,6 +1,7 @@
 # Knowledge Base Update Log
 
 ## 2026-07-31
+* **Plan**: Added [Screenshot as a plugin](/docs/knowledgebase/plans/screenshot-as-plugin.md) — a design to make `nemo screenshot` deployable on a **stock release binary** by moving it out of the feature-gated host build into an **OS-native capture plugin**. Grounded the blocker in code: capture today calls gpui's `Window::render_to_image()` (`commands/screenshot.rs:85`), gated `#[cfg(feature="test-support")]` inside gpui and kept out of release by decision; a native plugin only ever receives `PluginContext` (`nemo-plugin-api/src/lib.rs:285`) — no `&mut Window`, and it can't flip a host compile-time feature — so a plugin **must capture at the OS level** (ScreenCaptureKit / `CGWindowListCreateImage`), not through gpui. Two new host primitives designed: (1) **`Capability::Command`** + `CommandSpec`/`register_command`/`PluginCommandFn` so plugins contribute CLI subcommands — requires a two-phase parse ahead of the static clap match (`main.rs:66`, `args.rs`) with **built-ins taking precedence**; (2) a host **`capture_app_window`** `PluginContext` method (default `Unsupported`, matching the `navigate` pattern at `:327`) that owns the gpui run loop + `build_app_window`/`BootstrapParams` (`main.rs:246/265`) and returns a `CapturedFrame` of raw RGBA — recommended split is host-captures/plugin-encodes, which lets the OS-capture backend ship in the **default binary** (no `test-support`) while the plugin supplies CLI surface + PNG/permission policy. Open questions logged: TCC permission UX for CI, discovery cost, native ABI versioning (no check today, `:538`), WASM parity. Registered in both plan indexes. Planning only — nothing implemented.
 * **Fix**: Wired `<menu-item on-click>` inside `<dropdown-button>` ([issue #83](https://github.com/geoffjay/nemo/issues/83)). The build path in `app.rs` collected only each menu item's `label` into a `Vec<String>`, so `DropdownButton` rendered click-less `PopupMenuItem`s and every entry was a silent no-op. Now `app.rs` collects a `Vec<MenuItem { id, label, on_click }>` (new struct in `components/dropdown_button.rs`, re-exported from `components/mod.rs`), carrying each item's `handlers.get("click")`, and passes `runtime` + `entity_id` into `DropdownButton` (same as `<button>`). `DropdownButton::render` attaches `PopupMenuItem::on_click` that calls `runtime.call_handler(&handler, &item_id, "click")` + `cx.notify(entity_id)`, mirroring the button path. No registry change — `on-*` handler attributes are generic (already passed `nemo validate`). Updated the component doc-comment to show `on-click`.
 
 ## 2026-07-30
diff --git a/docs/knowledgebase/plans/index.md b/docs/knowledgebase/plans/index.md
index eb8f28c..e9adafd 100644
--- a/docs/knowledgebase/plans/index.md
+++ b/docs/knowledgebase/plans/index.md
@@ -5,6 +5,7 @@ Forward-looking plans for the project.
 * [Roadmap](roadmap.md) - current capabilities, phase-2 status, remaining roadmap items, and pointers to full planning docs.
 * [Declarative children over JSON-string properties](declarative-children-migration.md) - migrate collection components from JSON-string attributes to nested child elements, piloted on accordion.
 * [Headless renderer and screenshots](headless-screenshots.md) - implemented on macOS via gpui's offscreen `Window::render_to_image` (`nemo screenshot`); Linux capture remains open.
+* [Screenshot as a plugin](screenshot-as-plugin.md) - make `nemo screenshot` distributable on a stock release binary by moving it into an OS-native capture plugin; requires two new host primitives (`Capability::Command` for plugin-contributed CLI subcommands + a host `capture_app_window` bootstrap primitive). **Planned / not implemented.**
 * [Devtools inspector](devtools-inspector.md) - what a nemo-devtools crate would take; the introspection surfaces already exist, in-process panel recommended over an external client.
 * [Design tokens and active redesign](design-tokens.md) - centralized spacing/radius/typography/semantic-color tokens (gpui-free `nemo-tokens` crate); full chrome migration with screenshot verification.
 * [Design-system export](design-system-export.md) - `cargo xtask design-export` emits tokens + themes + component structure as a pencil.dev-friendly JSON intermediate.
diff --git a/docs/knowledgebase/plans/screenshot-as-plugin.md b/docs/knowledgebase/plans/screenshot-as-plugin.md
new file mode 100644
index 0000000..72a7401
--- /dev/null
+++ b/docs/knowledgebase/plans/screenshot-as-plugin.md
@@ -0,0 +1,256 @@
+---
+type: Plan
+title: Screenshot as a plugin (CLI-subcommand plugins + a window-bootstrap primitive)
+description: Move `nemo screenshot` out of a feature-gated host build into a distributable, OS-specific native plugin — requires two new host capabilities (plugins that register CLI subcommands, and a host primitive that launches an app window and hands back a capture-ready handle).
+tags: [screenshots, plugins, cli, native, macos, bootstrap, plan]
+timestamp: 2026-07-31T00:00:00Z
+---
+
+**Status: Planned / not implemented.** This plan supersedes the deployment
+problem noted in [screenshot via test-support feature](../decisions/screenshot-via-test-support-feature.md):
+today's `nemo screenshot` only works in a locally-built binary compiled with
+`--features screenshot`, so it ships in no release artifact. The goal here is to
+make screenshot capture **installable as a plugin** onto a stock release binary,
+deployed as an OS-specific component.
+
+# Motivation
+
+The current capture path calls gpui's `Window::render_to_image()`, which is
+`#[cfg(any(test, feature = "test-support"))]` **inside the gpui crate** — a
+compile-time gate baked into the host binary at link time. The decision doc is
+explicit that `test-support` must stay out of `default`/release builds (it can
+change gpui codegen). Net effect: the feature exists but is undeployable — you
+must rebuild locally to use it.
+
+Reframing screenshot as a plugin lets it be built and distributed on its own
+cadence, per-OS, without touching the host's release codegen. It also generalizes
+two capabilities the plugin system is missing today, which are useful well beyond
+screenshots.
+
+# The core blocker (why a plugin can't just do this today)
+
+A plugin cannot reach the current capture path:
+
+* **WASM / Rhai** — sandboxed; no OS graphics or gpui access. Out.
+* **Native `cdylib`** — "full Rust, no sandbox," but it only receives
+  `PluginContext` (`get_data`/`set_data`, `emit_event`, component-property
+  accessors, `navigate`…; `crates/nemo-plugin-api/src/lib.rs:285`). It never gets
+  a `&mut Window` or the Metal context, and it cannot flip a compile-time gpui
+  feature that lives in the host binary. A plugin that linked its own
+  gpui-with-`test-support` would instantiate a *separate* gpui — it could not
+  touch the host's live window.
+
+So "plugin calls `render_to_image()`" only works if the host was already compiled
+with the feature, which defeats the purpose. **A plugin-hosted screenshot must
+capture at the OS level, not through gpui's render path.**
+
+# Approach: OS-native capture + two new host primitives
+
+## Capture mechanism (per-OS, in the plugin)
+
+Instead of rendering the scene to a texture, the plugin captures the on-screen
+window through an OS API:
+
+* **macOS** — ScreenCaptureKit (`SCScreenshotManager` / `SCContentFilter` on
+  window id), or legacy `CGWindowListCreateImage`.
+* **Linux** (later) — the portal/`XShmGetImage` route; deferred, matching the
+  existing Linux-capture "still open" status.
+
+Trade-offs vs. the gpui path (all inherent to OS capture, all acceptable for a
+deployable variant):
+
+* The window must be **visible** — no invisible/offscreen capture.
+* Needs **screen-recording permission** (macOS TCC prompt). The `render_to_image`
+  path deliberately avoided this; the plugin path reintroduces it.
+* Output is at native pixel resolution (retina-scaled), same as today.
+* Native plugins are unsandboxed and ABI-locked to the host's compiler +
+  `nemo-plugin-api` version (`crates/nemo-plugin-api/src/lib.rs:538` safety
+  contract).
+
+## Primitive 1 — `Capability::Command`: plugins that register CLI subcommands
+
+Today subcommand dispatch is a static `clap`-derived enum matched in
+`main.rs::main` (`match args.command.take()`, `crates/nemo/src/main.rs:66`), and
+plugin discovery happens *later*, during app launch (driven by the `<plugins>`
+whitelist in config). To let a plugin own a subcommand, discovery must move
+**ahead of** (or beside) arg parsing, and dispatch must fall through to plugins.
+
+Sketch — additive to `nemo-plugin-api`:
+
+```rust
+// crates/nemo-plugin-api/src/lib.rs
+pub enum Capability {
+    Component(String),
+    DataSource(String),
+    Transform(String),
+    Action(String),
+    EventHandler(String),
+    Settings(String),
+    Command(CommandSpec),   // NEW
+}
+
+/// Describes a CLI subcommand a plugin contributes. Kept declarative and
+/// FFI-safe (no clap types cross the boundary).
+pub struct CommandSpec {
+    pub name: String,               // e.g. "screenshot"
+    pub about: String,              // one-line help
+    pub args: Vec<CommandArgSpec>,  // flags/positionals, rendered into clap host-side
+}
+
+pub struct CommandArgSpec {
+    pub name: String,               // "out"
+    pub long: Option<String>,       // "--out"
+    pub short: Option<char>,        // 'o'
+    pub takes_value: bool,
+    pub required: bool,
+    pub help: String,
+}
+```
+
+And a new entry point the host calls once it has matched a plugin command —
+runnable from a **background thread** (`context_arc` is already `Send + Sync`),
+receiving the parsed argv as `PluginValue::Object`:
+
+```rust
+pub trait PluginRegistrar {
+    // …existing register_* methods…
+    fn register_command(&mut self, spec: CommandSpec);
+}
+
+// Invoked when the host dispatches this plugin's subcommand.
+// Returns a process exit code. Runs outside the gpui run loop unless the
+// command opts into a window via Primitive 2.
+pub type PluginCommandFn =
+    unsafe extern "C" fn(ctx: &dyn PluginContext, argv: &PluginValue) -> i32;
+```
+
+Host-side wiring (`crates/nemo/src/main.rs`, `crates/nemo/src/args.rs`):
+
+* Two-phase parse. Phase A: a permissive pre-parse that pulls global flags
+  (`--extension-dirs`, `--verbose`) and the first positional (candidate
+  subcommand name) *without* rejecting unknown subcommands
+  (`clap`'s `allow_external_subcommands` / `ignore_errors`, or a hand-rolled
+  first-token peek before `Args::parse`).
+* Discover plugins from the extension dirs (reuse `ExtensionLoader`; no config/app
+  needed for the discovery scan). If the candidate name matches a built-in
+  `Command` variant, dispatch as today. Otherwise, look for a plugin whose
+  manifest declares `Capability::Command { name }`.
+* If matched, build a `clap::Command` dynamically from the plugin's `CommandSpec`,
+  parse the remaining argv against it, marshal into `PluginValue::Object`, and
+  call the plugin's `PluginCommandFn`. Unmatched → the existing clap "unrecognized
+  subcommand" error.
+* Precedence: **built-ins win** over plugin commands (a plugin cannot shadow
+  `run`/`dev`/`validate`/…), and this must be covered by a test alongside the
+  existing `args.rs` parse tests.
+
+## Primitive 2 — a window-bootstrap handle exposed to the command
+
+Screenshot is not pure logic: it must (1) launch a real app window, (2) wait for
+settle, (3) capture, (4) quit. The host already has the shared bootstrap —
+`build_app_window(cx, BootstrapParams)` returning `WindowHandle<Root>`
+(`crates/nemo/src/main.rs:265`, `BootstrapParams` at `:246`) — but none of it is
+reachable from a plugin, and it must run **inside** `gpui_platform::application().run(...)`.
+
+A plugin cannot own the gpui run loop (gpui types can't cross the FFI boundary).
+So the host drives the loop and calls back into the plugin at defined lifecycle
+points. Add a host-side capture hook the command declares it needs:
+
+```rust
+// Host-owned; the plugin never sees gpui types. The plugin asks the host to
+// "launch this app config, settle N ms, then hand me raw pixels to encode."
+pub trait PluginContext: Send + Sync {
+    // …existing methods, all with Unsupported default impls…
+
+    /// Launch an app window, wait `settle_ms`, and return the captured frame as
+    /// raw RGBA + dimensions. The host owns the gpui run loop and window
+    /// lifecycle; capture backend is host- and OS-defined. Default: Unsupported.
+    fn capture_app_window(
+        &self,
+        _spec: &PluginValue,   // { app_config, size, settle_ms, theme, mode, route }
+    ) -> Result<CapturedFrame, PluginError> {
+        Err(PluginError::Unsupported("capture_app_window".into()))
+    }
+}
+
+pub struct CapturedFrame {
+    pub width: u32,
+    pub height: u32,
+    pub rgba: Vec<u8>,   // row-major, width*height*4
+}
+```
+
+Two viable splits of responsibility — decide during implementation:
+
+* **(a) Host captures, plugin encodes/writes.** `capture_app_window` returns
+  `CapturedFrame`; the plugin does PNG encoding, path handling, and any OS
+  permission prompting it wants. Keeps gpui + window lifecycle entirely
+  host-side; the plugin stays a thin, portable consumer. **Recommended** — it
+  also means the OS-capture backend can live in the host behind a small
+  always-compiled surface (no `test-support`), and different capture backends
+  (OS-native now, gpui-`render_to_image` later) are swappable without changing
+  the plugin.
+* **(b) Host launches + hands the plugin a window id; plugin captures.** The host
+  exposes only the native window handle/id; the plugin owns the OS capture call.
+  Maximizes plugin control (custom regions, multi-window) but leaks a platform
+  handle across FFI and duplicates capture code per plugin.
+
+If (a) is chosen, note the OS-native capture backend added to the host does **not**
+need `gpui/test-support` at all — it reads pixels from the OS compositor, not the
+Metal drawable — so it can ship in the **default release binary**. That is the
+crux of the whole plan: the *host* gains a permissionful OS-capture path in
+release, and the *plugin* supplies the CLI surface + policy on top.
+
+# End-to-end flow (recommended shape: Command plugin + `capture_app_window`)
+
+1. User installs `nemo-screenshot` (a native `cdylib`) into an extension dir.
+2. `nemo screenshot --app-config app.xml --out out.png --size 1200x800`.
+3. Host pre-parses, discovers the plugin, matches `Capability::Command("screenshot")`,
+   builds the clap command from `CommandSpec`, marshals argv → `PluginValue`.
+4. Host calls the plugin's `PluginCommandFn(ctx, argv)`.
+5. Plugin calls `ctx.capture_app_window({app_config, size, settle_ms, …})`.
+6. Host runs `gpui_platform::application().run(...)`, `build_app_window`, waits
+   `settle_ms` on the real dispatcher, captures via the OS backend, quits, and
+   returns `CapturedFrame`.
+7. Plugin encodes PNG, writes `--out`, returns exit code.
+
+# What this removes / keeps
+
+* **Removes** the `screenshot` cargo feature and the `test-support` gate from the
+  screenshot path (the `dispatch_screenshot` feature-split in
+  `crates/nemo/src/main.rs:86-98` goes away, or becomes a thin built-in that
+  delegates to the plugin if present).
+* **Keeps** the option to *also* offer the gpui `render_to_image` backend behind
+  the host capture surface for callers who want the no-permission/offscreen path
+  in a purpose-built binary — the plugin doesn't care which backend the host uses.
+
+# Open questions
+
+* **Permission UX.** ScreenCaptureKit triggers a TCC prompt on first use; a
+  headless/CI run needs the permission pre-granted (tccutil / MDM profile). Document
+  and, if possible, detect-and-explain rather than hang.
+* **Discovery cost.** Scanning extension dirs before every command adds startup
+  work to *all* invocations; gate the plugin-command lookup to the
+  "candidate name is not a built-in" branch so the common path is unaffected.
+* **ABI fragility.** Native plugins have no ABI-version check
+  (`crates/nemo-plugin-api/src/lib.rs:538`). A screenshot plugin shipped as a
+  binary must be pinned to a host version; consider adding a version handshake to
+  `nemo_plugin_manifest` as part of this work.
+* **WASM parity.** `capture_app_window` and `Command` would need WIT additions to
+  reach WASM guests; likely out of scope (capture is inherently native), but the
+  `Command` capability could be WASM-friendly for non-graphical subcommands.
+
+# Files this touches (when built)
+
+* `crates/nemo-plugin-api/src/lib.rs` — `Capability::Command`, `CommandSpec`,
+  `register_command`, `PluginCommandFn`, `capture_app_window`/`CapturedFrame`.
+* `crates/nemo/src/args.rs` + `crates/nemo/src/main.rs` — two-phase parse,
+  plugin-command discovery/dispatch, built-in precedence, host OS-capture backend
+  wired to `build_app_window`/`BootstrapParams`.
+* `crates/nemo-extension/src/plugin.rs` — load + expose the new entry point;
+  extend `RuntimeContext` (`crates/nemo/src/runtime.rs`) to implement
+  `capture_app_window`.
+* `plugins/screenshot/` (new) — the macOS OS-native capture plugin (example +
+  reference).
+* Update [screenshot via test-support feature](../decisions/screenshot-via-test-support-feature.md),
+  [Extensions](../concepts/extensions.md), and
+  [three-tier extensions](../decisions/three-tier-extensions.md) once implemented.

From f8d4a589f101dcb0b2a9a4fb36770b20409d627a Mon Sep 17 00:00:00 2001
From: Geoff Johnson <geoff.jay@gmail.com>
Date: Fri, 31 Jul 2026 22:15:33 -0700
Subject: [PATCH 2/2] fix: apply live data bindings in nemo screenshot (#82)

`nemo screenshot` rendered the initial layout but bound values
(`<binding>`/`bind-*`) stayed at their placeholders in the captured PNG,
even though they populate correctly in the running app.

Root cause is startup ordering. A data source's `start()` broadcasts its
initial `full` value immediately, and a tokio `broadcast` channel drops
messages sent while no receiver is attached. The runtime subscribed its
update loops *after* `data_engine.start_all()`, so each source's first
value was lost and the repository was never seeded. Interactive runs
recover via a later event (e.g. a file-watcher change); a one-shot
capture never does.

Fix (two parts):
- runtime.rs: subscribe the update loops (`start_data_update_loop`)
  before `data_engine.start_all()`, so receivers are attached before
  sources broadcast. This is the root-cause fix and benefits every
  one-shot / early-read path, not just screenshots.
- commands/screenshot.rs: pump the data->binding loop across the
  `--settle-ms` window in 50ms slices, then do a final refresh + one
  executor-yield before `render_to_image()` (which reads the last-drawn
  frame; `refresh()` only marks the window dirty).

Verified: examples/data-binding screenshot now shows live timer/HTTP
values; 233 nemo + 18 macro tests pass; --features screenshot builds
clean. Updated the data-flow KB doc and log.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 crates/nemo/src/commands/screenshot.rs   | 46 +++++++++++++++++++++++-
 crates/nemo/src/runtime.rs               | 15 +++++---
 docs/knowledgebase/concepts/data-flow.md | 10 ++++++
 docs/knowledgebase/log.md                |  1 +
 4 files changed, 67 insertions(+), 5 deletions(-)

diff --git a/crates/nemo/src/commands/screenshot.rs b/crates/nemo/src/commands/screenshot.rs
index dce8d65..f1e312b 100644
--- a/crates/nemo/src/commands/screenshot.rs
+++ b/crates/nemo/src/commands/screenshot.rs
@@ -19,6 +19,7 @@ use anyhow::{bail, Context as _, Result};
 
 use crate::args::ScreenshotArgs;
 use crate::config::NemoConfig;
+use crate::project::ActiveProject;
 use crate::workspace::WorkspaceArgs;
 use crate::{build_app_window, theme, BootstrapParams};
 
@@ -75,10 +76,53 @@ pub fn run(args: ScreenshotArgs) -> Result<()> {
             let _ = window.update(cx, |_, w, _| w.refresh());
         }
 
+        // `render_to_image` reads the window's *last drawn* frame, and
+        // data-source values arrive asynchronously and reach the UI only once
+        // their bindings are propagated into the layout. In the interactive run
+        // loop `App`'s data task applies those on every `data_notify` and marks
+        // the view dirty; the one-shot capture path must drive the same loop
+        // itself, or bound values stay at their placeholders in the PNG
+        // (issue #82). Grab the active project's runtime to pump it.
+        let runtime = cx
+            .has_global::<ActiveProject>()
+            .then(|| cx.global::<ActiveProject>().runtime.clone());
+
         let out = out.clone();
         let capture_err_task = capture_err_run.clone();
         cx.spawn(async move |cx| {
-            cx.background_executor().timer(settle).await;
+            // Pump data → binding propagation across the settle window in small
+            // slices rather than sleeping it all at once. Each `timer` await
+            // yields to the executor, giving the async data sources time to
+            // deliver and letting any refresh-requested redraw actually land.
+            let tick = Duration::from_millis(50);
+            let mut remaining = settle;
+            loop {
+                let slice = remaining.min(tick);
+                cx.background_executor().timer(slice).await;
+                remaining = remaining.saturating_sub(slice);
+
+                if let Some(rt) = runtime.as_ref() {
+                    let navigated = rt.apply_pending_navigations();
+                    let updated = rt.apply_pending_data_updates();
+                    if navigated || updated {
+                        let _ = cx.update(|cx| {
+                            let _ = window.update(cx, |_, w, _| w.refresh());
+                        });
+                    }
+                }
+
+                if remaining.is_zero() {
+                    break;
+                }
+            }
+
+            // Ensure the last-applied state is committed to the drawn frame
+            // before we read it back: refresh, then yield once more so gpui
+            // draws the dirty window into `rendered_frame`.
+            let _ = cx.update(|cx| {
+                let _ = window.update(cx, |_, w, _| w.refresh());
+            });
+            cx.background_executor().timer(tick).await;
 
             let result: Result<()> = cx.update(|cx| {
                 let img = window
diff --git a/crates/nemo/src/runtime.rs b/crates/nemo/src/runtime.rs
index 05e224d..ad59e02 100644
--- a/crates/nemo/src/runtime.rs
+++ b/crates/nemo/src/runtime.rs
@@ -763,7 +763,17 @@ impl NemoRuntime {
                 }
             }
 
-            // Start all registered sources
+            // Subscribe the update loops *before* starting sources. A source's
+            // `start()` broadcasts its initial `full` value immediately, and a
+            // tokio broadcast channel drops messages sent while no receiver is
+            // attached — so subscribing after `start_all()` loses the first
+            // value, leaving the repository unseeded until some later event
+            // (e.g. a file-watcher change) re-delivers it. Interactive runs
+            // usually get such a follow-up; a one-shot `nemo screenshot` does
+            // not, so bound values render as placeholders (issue #82).
+            self.start_data_update_loop().await;
+
+            // Start all registered sources (now that receivers are attached).
             let results = self.data_engine.start_all().await;
             for (id, result) in &results {
                 match result {
@@ -772,9 +782,6 @@ impl NemoRuntime {
                 }
             }
 
-            // Start the data update loop for each source
-            self.start_data_update_loop().await;
-
             Ok::<(), anyhow::Error>(())
         })?;
 
diff --git a/docs/knowledgebase/concepts/data-flow.md b/docs/knowledgebase/concepts/data-flow.md
index afe099e..91ce098 100644
--- a/docs/knowledgebase/concepts/data-flow.md
+++ b/docs/knowledgebase/concepts/data-flow.md
@@ -34,6 +34,16 @@ created via `nemo_data::create_source()`, registered and started by the
 `DataFlowEngine`, then consumed by tokio tasks the runtime spawns
 (`crates/nemo/src/runtime.rs`, source setup ~520, update loop ~594).
 
+**Startup ordering is load-bearing.** A source's `start()` broadcasts its
+initial `full` value *immediately*, and a tokio `broadcast` channel drops
+messages sent while no receiver is attached. So the runtime subscribes the
+update loops (`start_data_update_loop()`) **before** `data_engine.start_all()`;
+subscribing afterward loses each source's first value, leaving the repository
+unseeded until some later event (e.g. a file-watcher change) re-delivers it.
+Interactive runs usually get such a follow-up and appear to recover, but a
+one-shot `nemo screenshot` does not — that was the root cause of issue #82
+(bound values rendered as placeholders in captures).
+
 # Transforms
 
 The `Transform` trait (`crates/nemo-data/src/transform.rs:31`) and a `Pipeline`
diff --git a/docs/knowledgebase/log.md b/docs/knowledgebase/log.md
index 06df638..1d711ae 100644
--- a/docs/knowledgebase/log.md
+++ b/docs/knowledgebase/log.md
@@ -93,4 +93,5 @@
 * **Plan**: Authored [page router](/docs/knowledgebase/plans/page-router.md) — a design for a general, chrome-free `<router>`/`<route>` primitive to replace the fragile visibility-toggle page-switching pattern (per-page `<panel visible>` + hand-maintained hide-all Rhai handlers; `examples/components` hard-codes 34 hide-calls). Chosen shape: URL-style path routes with `:param` capture + `*` fallback, declarative `<nav-link>`s, a Rhai `navigate()`/`back()`/`forward()` API, host-side per-router state (`RouterRegistry` on `NemoRuntime`, keyed by id) projected into the `DataRepository` at `data.route.<id>.*` for Rhai/binding reads, `on-enter`/`on-leave` lifecycle hooks, and nested routers. Modeled on the existing `app_shell` render pattern (`containers/app_shell.rs`, `app.rs:1099`) but decoupled from its chrome; `app-shell` left unchanged. **Key design constraint captured:** `call_handler` holds the `extension_manager` write lock (`runtime.rs:508`), so navigation must be **deferred** through a `NavIntent` queue drained by the `App` poll loop (`apply_pending_navigations()` beside `apply_pending_data_updates`) to avoid a re-entrant deadlock when `navigate()` fires hooks from inside a handler. No code written yet; registered in the plans indexes.
 
 ## 2026-07-31
+* **Fix**: Issue #82 — `nemo screenshot` rendered the initial layout but bound values (`<binding>`/`bind-*`) stayed at their placeholders in the PNG even though they populate in the running app. **Root cause:** startup ordering. A data source's `start()` broadcasts its initial `full` value immediately, and a tokio `broadcast` channel drops messages sent while no receiver is attached; the runtime subscribed the update loops *after* `data_engine.start_all()`, so each source's first value was lost and the repository was never seeded. Interactive runs recover via a later event (e.g. a file-watcher change); a one-shot capture never does. **Fix (two parts):** (1) `runtime.rs` `initialize()` now calls `start_data_update_loop().await` **before** `data_engine.start_all().await`, so receivers are attached before sources broadcast — the actual root-cause fix, benefits every one-shot/early-read path, not just screenshots. (2) `commands/screenshot.rs` capture task now *pumps* the data→binding loop across the `--settle-ms` window in 50ms slices (grabbing `ActiveProject`'s runtime, calling `apply_pending_navigations()`/`apply_pending_data_updates()` and `window.refresh()` when anything changed), then does a final refresh + one executor-yield timer before `render_to_image()` — because `render_to_image` reads the window's *last drawn* frame and `refresh()` only sets a dirty flag; the interactive `App` data task drives this on every `data_notify`, so the one-shot path must drive it itself. Verified: `examples/data-binding` screenshot now shows live timer/HTTP values instead of placeholders; 233 nemo + 18 macro tests green; `cargo build -p nemo --features screenshot` clean. Updated [data flow](/docs/knowledgebase/concepts/data-flow.md) (new startup-ordering note under Data sources).
 * **Feature**: Opt-in **header-bar dropdown menu**. Apps declare `<menu-item label icon on-click separator>` children under `<header-bar>`; when present, a far-left hamburger icon opens a native dropdown, each entry invoking a Rhai handler via `runtime.call_handler(handler, "header-bar", "click")`. Parser: added `process_header_bar` (`crates/nemo-config/src/xml_parser.rs`) so repeated `<menu-item>` children survive as a `menu_items` array at `app.window.header_bar.menu_items` (the generic `process_nested_block` would collapse them; note `__type__` is already snake-cased, so the special-case matches `header_bar`/`menu_item`). Render: `HeaderBar` (`crates/nemo/src/workspace/header_bar.rs`) gained `menu_items`/`runtime` fields + a `menu_items_from_config` helper, building `DropdownButton` + `PopupMenuItem` (reusing `components::icon::map_icon_name` for item icons); both construction sites (`main.rs`, `workspace/mod.rs::create_header_bar`) pass them. Declared `menu-item` in the schema surface (`crates/nemo-registry/src/schema_surface.rs`). Demoed in `examples/basic`. Verified: new parser test `test_parse_header_bar_menu_items` + `cargo build -p nemo` clean. Updated [configuration](/docs/knowledgebase/concepts/configuration.md) and the nemo-xml-reference skill.