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.dataholds strings only, so the whole document stays serialisable and bounded.extensionsis keyed by extension id; it stores whatever the extension saved throughapi.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.dataKeysrestricts 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>.pdfworkspace-v1.jsonis 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 toworkspace-recovery.jsoninstead of destroying it. - Closing the window waits for
persistence.flush()before destroying it. - The pre-rename
fr.lab.desktopfolder 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.