Events & File Watching

A module reacts to the world through host.events.on(event, handler). The set of events it may subscribe to is a whitelist — kept deliberately narrow.

Why the whitelist

The list of subscribable events is a trust surface. A module should only receive notifications it has a legitimate reason to act on, and nothing carrying sensitive state. So subscriptions are checked against an explicit set in eventWhitelist.ts; anything not listed is simply not deliverable. New entries are added deliberately, not by default.

Subscribable events

These events are forwarded with their payload. They either carry nothing sensitive (booleans, theme, module ids) or carry the single path/items a module legitimately needs to act on.

setup(host) {
  host.events.on("directory:changed", () => {
    // re-read state, re-render a panel, etc.
  });
}

Notify-only events

A second, smaller set of events is delivered as a bare ping — the event fires, but its payload is stripped to undefined. The occurrence is useful (cache-bust, trigger a re-render), but the payload is profiling-grade: it would expose the full clipboard contents or every open tab's path.

setup(host) {
  host.events.on("clipboard:changed", () => {
    // the payload is undefined — the event is just a signal
    // to get the actual clipboard contents, use a capability:
    const files = await host.board.readFiles();
  });
}

How directory watching works

The host watches only the directory currently in view — not the whole disk, and not arbitrary module-requested paths.

Rust FSEvents watcher (one, re-armed on each navigation)
  → emits "directory-changed"
  → core/file-watch/DirectoryWatcher.ts debounces it
  → re-broadcasts as the whitelisted "directory:changed" event
  → core.auto-refresh re-reads the list; your module reacts too

Why current-directory-only

Two reasons, one cost and one correctness:

• Bounded cost. There is exactly one watcher. read_dir re-arms it on every navigation (unwatch old + watch new on a persistent watcher) instead of dropping and recreating it — dropping a macOS FSEvents watcher joins its run-loop thread, which previously stalled every listing. Modules cannot request their own watchers, so the watching cost can never grow with the number of modules.
• Listing is never blocked by watching. Rendering folder content is the priority, so the re-arm runs on a detached thread. Access events are ignored so that merely reading a directory can't loop back into a refresh.

The practical consequence for module authors: you get notified about changes to the folder the user is looking at, which is what a file explorer actually needs. If you need to know about other locations, poll them yourself with host.fs.readDir.

Custom events from community modules

A module can declare its own events via TypeScript declaration merging on EventMap (the interface in src/core/event-bus/events.ts):

declare module "../../core/event-bus/events" {
  interface EventMap {
    "acme.git-status:repo-changed": { path: string };
  }
}

Note that a sandboxed (worker) module cannot reach the EventBus directly — it has no core reference. It only receives the whitelisted events the host forwards to it, and emits side effects through host.* capabilities. Cross-module event broadcasting from within a worker is not a supported path today; custom events are primarily useful for built-in modules that run in-process and can import the EventBus.