Workspace

The workspace is a plain serialisable document. Everything the window shows is derived from it, and everything an agent reads is a bounded summary of it.

Model

interface WorkspaceState {
  version: 1;
  active: string;                 // active tab id
  tabs: Tab[];
  pinned: string[] | null;        // null = every extension pinned
  installedExtensions?: string[];
  seededCore?: string[];
  extensions?: Record<string, unknown>; // state saved by each extension
  theme: "dark" | "light" | "transparent";
}

type Mode = "side" | "tiling" | "stack";

interface Tab {
  id: string;
  name: string;
  mode: Mode;
  tiles: Tile[];
  layouts: Partial<Record<Mode, unknown>>;
  focused?: string;
}

interface Tile {
  id: string;
  type: string;
  data: Record<string, string>;
}
  • Tile.data holds strings only, so the whole document stays serialisable and bounded.
  • extensions is keyed by extension id; it stores whatever the extension saved through api.state.save().
  • Installed packages and registry sources are not in the workspace: they live in extensions.json.

Three layout modes

  • Side — tiles next to each other.
  • Tiling — free dockview layout: drag a tab to an edge to split, to the centre to group, drag a separator to resize.
  • Stack — tiles stacked vertically.

Each tab keeps one layout per mode, so switching modes never recreates a tile — which matters, because a terminal session dies with its tile.

Tile lifecycle

  • prepare(data) normalises the initial data when a tile is opened.
  • dataKeys restricts which keys the tile accepts.
  • describe(tile, surface) returns a one-line summary for the brief; it must not throw.
  • canClose(tile, closing) can refuse a close, for instance when a document is unsaved.
  • close(tile) releases what the tile holds: a session, a file, a listener.

Disabling an extension removes it from installedExtensions but leaves its tiles in the workspace; their view becomes unavailable. Re-enabling restores them with their data intact.

Journal

src/core/journal.ts keeps 512 entries in memory. Each entry carriesseq, at, source (human,agent or system), a kind, and optionallytabId, tileId and data.

The journal does not replace the state: it recounts changes. It is bounded bysummarize — strings cut at 160 characters, depth 2 — so a log entry can never carry a document or a terminal output.

An agent resumes from a sequence number with spark_events_since.

Brief

src/core/brief.ts builds a summary of a tab: its tiles, their titles, theirdescribe lines, recent events and the other tabs. The whole text is capped at 1,400 characters and each summary at 120. Noisy events such astile.focus and tab.reorder are filtered out.

Persistence

~/Library/Application Support/fr.spark.desktop/
  workspace-v1.json      tabs, tiles, layouts, extension state, theme
  workspace-recovery.json backup written on an invalid-format recovery
  settings-v1.json       { "dev": boolean }
  extensions.json        installed packages, versions, registry sources
  extensions/<id>/<version>/
  markdown-access.json   tokens for allowed Markdown files
  explorer-access.json   tokens for allowed folders
  run/mcp.sock           MCP socket
  run/tools.json         tool list cache for the bridge
  ~/Library/Caches/fr.spark.desktop/pdf/<id>.pdf
  • workspace-v1.json is written after a 180 ms debounce.
  • Writes are serialised: an older write can never overwrite a newer one.
  • On an invalid format, the runtime starts from a fresh workspace and marks recovery; the first save copies the old file to workspace-recovery.json instead of destroying it.
  • Closing the window waits for persistence.flush() before destroying it.
  • The pre-rename fr.lab.desktop folder is adopted on first launch without overwriting existing files.

Undo

⌘Z and ⇧⌘Z undo and redo layout operations: moves and resizes, including the ones an agent performed through spark_tile_move andspark_tile_resize. History is per tab and per mode, and never touches tile content.