Frame Components Reference

Every provider you can load into a Space — what each one shows, when to use it, and what the layout switcher does.

A frame component (also called a view provider) is the self-contained UI you load into any leaf of a Space. Every Space is divided into one or more leaves; each leaf holds exactly one frame component with its own toolbar, content area, and chrome. You can split a Space to run two frame components side by side, replace the one in a leaf through the frame menu's Empty frame action and the picker, and — for providers that support it — pop a leaf out into its own floating window.

The canonical entry point for choosing a frame component is the empty-leaf picker, which appears whenever a leaf is set to the Empty provider. Type to filter by name or description, then hover or use the arrow keys to explore a view before loading it. At wide and medium frame widths, a side pane explains what the selected view does, when to use it, its layouts, and its manual page. In narrow frames that explanation appears inside the selected row. Click a row or press Enter to load it; views requiring configuration start with Set up. Tab cycles through search, Load file, the current row, and the Manual button when available.

If you are building a new provider rather than choosing one, see the Frame Component Contract for the implementer-facing contract.

Note Tray (id: core.inbox)

Note Tray toolbar plus a swappable editor / preview / timeline view. Each split pane is its own Note Tray.

The Note Tray is the primary writing and browsing surface — it is the same provider for both the Inbox and the Archives, pointed at different directories via its directory prop ("inbox" by default; the Archives pin sets it to "archives"). It combines the Note Tray toolbar (the numbered-note carousel at the top) with a text editor and an optional rendered-markdown preview. Every Note Tray leaf on the same directory works off the same shared content pool — you can split the Space and have one leaf in edit mode while the other shows the rendered preview, and they stay in sync. A sweep button lets you quickly clear out empty numbered slots.

The frame header exposes Pile View, Find similar and History, with General settings controlling their visibility. These actions use the owning tray and move into the header overflow at narrow widths. An empty editable Markdown editor shows three-line guidance: start writing, right-click a table for Edit sheet…, and type @@ for inline AI. Read-only editors and code-mode editors omit this placeholder.

The Note Tray toolbar shows a numbered pill per note plus a pill for each "named" (non-numeric) .md document in the directory — named documents render after all numbered pills and open in the same editor, outside the numbered slot pool. Archived notes are stored as numbered N.md documents (1.md, 2.md, … — no upper bound): archiving moves the active note into a fresh N.md slot in archives/ (collision-safe max+1). Workspace metadata supplies creation and modification times unless your workspace schema declares its own auto fields (see Auto-managed frontmatter fields).

When to use:

• Any time you are writing, editing, or reviewing a note from scratch (Inbox) or browsing what you have already archived (Archives).

• When you want a side-by-side edit-and-preview layout for a long document.

• When you want to see your notes laid out as a scrollable timeline to review recent work.

• When you want to search — open Pile View from any Note Tray leaf for a local (this tray) or global (every tray) search.

Layouts:

Local files are separate: Note Tray directories belong to the cloud workspace. The External File Editor operates on local filesystem paths, so switching to it does not carry the Note Tray's workspace directory across.

Pop-out: Cannot be popped out into a separate window (per-window store; cross-window sync would require a separate layer).

Persistence: The directory prop, layout (text-editor / timeline-vertical / timeline-horizontal), view mode (edit / preview), and timeline sort/card-width preferences are each persisted per leaf. Two Note Tray leaves can independently be in edit mode and preview mode at the same time.

Singleton scope: Multiple OK — you can open as many Note Tray leaves as you like, each pointed at the same or a different directory; leaves on the same directory share content via a live-mirror store.

External File Editor (id: core.external-file-editor)

Open and edit files from anywhere on the filesystem. Supports multiple tabs.

The External File Editor is the only provider in the app that hosts a tab strip and embedded file tree. Each tab and the tree root hold local filesystem paths, independent of the cloud workspace. Edits are written back to disk with a short debounce. If a tab has unsaved changes the provider will veto closing the leaf until the changes are flushed.

When to use:

• Editing a config file, script, or reference document that lives outside the workspace.

• Keeping multiple files open in tabs within a single leaf, preserving the rest of the Space for other providers.

• Browsing the active file's directory in the embedded tree and opening text files as tabs.

Pop-out: Cannot be popped out into a separate window.

Persistence: Open paths, active path, tree root, and collapsed state are persisted in the leaf's props blob, so the tab set and embedded tree survive reload. The tree width is the global clamped directoryView.lastSidebarWidthPx setting.

Singleton scope: Multiple OK — several ExternalFileEditor leaves can exist in the same Space, each with its own tab set.

Embedded file tree: A named edge tab on the seam expands or collapses the EFE file tree; there is no panel button in the toolbar or tab strip. The button reports aria-expanded, responds to pointer and native keyboard activation, has a visible focus outline, and changes its label between Collapse directory tree and Expand directory tree. The pane remains mounted while collapsed so its root, expansion, scroll, and session state survive. When a file is active, expanding an unrooted tree roots it at that file's directory. Clicking any text file calls the containing EFE session directly and adds the file as a new tab — this includes code and data files (.json, .tsx, .ts, .yaml, …) in addition to Markdown. The Edit|Preview toggle appears only for Markdown tabs (.md, .mdx, .markdown); code file tabs open in editor-only mode.

The former standalone Directory View provider has been retired. There is no separate file-tree frame, cross-frame open-file event, or Directory View picker entry. Pre-release pins/settings that still name the retired provider are not migrated and may require a settings reset; local files themselves are never deleted. treeRoot is part of EFE pin identity, while treeCollapsed is not.

External-change detection

The ExternalFileEditor watches the active tab's file for modifications by external programs (another editor, a script, a version-control operation). When such a change is detected, a yellow conflict banner appears below the tab strip:

File modified externally — Show Diff · Keep Mine · Load Incoming

Three resolution options are available:

The watcher runs only while the tab is active. Switching to another tab stops the watcher for the previous file and starts one for the newly active file. When you switch back, the editor immediately compares the file on disk against your buffer to catch any changes that happened while the tab was inactive — even if no watcher event fired. If the contents differ a conflict banner appears straight away.

Self-writes (your own Cmd+S saves) do not trigger the banner: the backend records the write mtime and suppresses the watcher event, and the frontend also guards with a content-equality check (disk === buffer → bail).

Doc Cloud (id: core.doc-cloud)

Browse and author zudo-doc-cloud projects in one unified frame.

Doc Cloud contains its Projects list, project overview and activity, service-style outline, page tabs, editor, labelled Content preview, checkpoints, and publishing inside one provider. The outline is a collapsible pane, not another frame. Opening a page creates or activates a tab in the same frame; the frame id and frameset leaf count do not change.

When to use:

• Editing a zudo-doc-cloud page through the guarded Personal authoring API.

• Reviewing hosted status, history, activity, or publication progress.

• Keeping several remote pages in tabs without allocating another frameset leaf.

Layouts: Edit, Preview, and Split live in Doc Cloud's own toolbar. Preview is explicitly labelled Content preview: it follows the service Markdown, admonition, asset, and sanitization pipeline, but does not promise published-site theme parity.

Outline seam: The named Collapse/Expand Doc Cloud outline edge tab reports aria-expanded, supports pointer and keyboard activation, shows visible focus, and keeps the outline DOM node mounted while hidden.

Persistence: The leaf stores only projectSlug, initial surface, editor layout, and outline collapse as safe seeds. Loaded projects, tabs, source text, save guards, queries, activity, and hosted state stay in the sole frameId-keyed Doc Cloud session cache. The calling token is never settings or provider state.

Pop-out: Cannot be popped out.

Singleton scope: One per frameset. A pin for Doc Cloud is a one-leaf template, never a split outline/editor template.

See Doc Cloud Unified Frame for transport, credential, state, preview, vendoring, and open-question contracts.

Kanban Board (id: core.kanban-board)

Visualise a directory as a kanban board with swimlanes.

The Kanban Board provider renders a workspace directory as a kanban board. A directory is a board if and only if it contains a KANBAN.md manifest file. The manifest carries board properties (columns, labels, groupBy) in YAML frontmatter and lists each card as a markdown link under its column heading. Each card is its own .md file in the directory. Drag cards between columns; edits write back to KANBAN.md automatically. Card files are only written when card content (title, body, labels, priority, due, notify) changes — move and reorder operations write only the manifest. The board data is parsed by the @takazudo/kanban-parser package.

For the full directory model specification, see Kanban Directory Model.

When to use:

• Tracking the status of a batch of messages or tasks in a visual board.

• Managing a project checklist in kanban format inside the app.

• Keeping a kanban board visible alongside an editor or preview leaf while you work through tasks.

Layouts:

Pop-out: Can be popped out into a separate window.

Persistence: The directory path and active layout id are persisted in the leaf's props blob.

Singleton scope: Multiple OK.

Mind Map (id: core.mindmap-board)

Visualise a markdown mind map file as an interactive diagram.

The Mind Map provider reads a Markdown file and renders it as an interactive mind-map diagram. Nodes can be collapsed, expanded, and navigated. Edits to the diagram write back to the underlying Markdown file with a debounce, and you can drop a .md file onto the leaf to switch files. The outline view and the diagram view stay in sync — they represent the same Markdown tree.

When to use:

• Planning the structure of a long document or email campaign as a branching outline.

• Reviewing a hierarchical note visually instead of reading it line by line.

• Keeping a mind map visible while composing a related note in a split Inbox leaf.

Layouts:

Pop-out: Can be popped out into a separate window.

Persistence: The path of the loaded Markdown file and active layout id are persisted in the leaf's props blob.

Singleton scope: Multiple OK.

TODO Board (id: core.todo-board)

Manage a markdown TODO file with interactive checkboxes.

The TODO Board provider reads a Markdown file containing a task list and renders it with interactive checkboxes and inline editing. Checking or unchecking a task writes back to the Markdown file immediately. You can reorder tasks, add new ones, and edit titles inline. Drop a .md file onto the leaf to load a different TODO file. The file stays plain Markdown throughout — no proprietary format.

When to use:

• Tracking to-do items for a project alongside a kanban or editor leaf.

• Reviewing and ticking off a checklist before archiving a note.

• Maintaining a shared task list file that also stays readable in a plain text editor.

Pop-out: Can be popped out into a separate window.

Persistence: The path of the loaded Markdown file is persisted in the leaf's props blob.

Singleton scope: Multiple OK.

Empty (id: core.empty)

An empty frame — pick a view to load here.

The Empty provider is the default state of a newly created leaf. Its content area shows the empty-leaf picker — a searchable list of every registered provider with name, description, and icon. Typing filters the list. Clicking an entry replaces the Empty provider with the selected one. A "Load file" button at the bottom opens the SpotlightPicker (or a native OS dialog if Spotlight is disabled in Settings → General) to open a file directly into the first provider that accepts file drops (typically ExternalFileEditor).

The explanation pane follows the frame width, not the window width: wide and half-width panes show a separate detail area; narrow panes expand the selected row. Descriptions remain searchable at every size.

When to use:

• Starting a new leaf from scratch and browsing what views are available.

• Replacing the current view in a leaf with a different one.

• Opening an arbitrary file from the filesystem into a compatible provider.

Pop-out: Cannot be popped out.

Persistence: No persistent props — the picker itself has no saved state.

Singleton scope: Multiple OK — any number of empty leaves can coexist in a Space.

Dashboard (id: core.dashboard)

Dashboard is a workspace overview containing six configurable widget types: Recent notes, Calendar, Upcoming events, Quick actions, Tip of the day, and What's new. Its built-in pin precedes Inbox and Archives; /dashboard also opens it when the pin is hidden. A fresh workspace still boots into Inbox.

Edit in place: use the header's Edit dashboard action, then Add widget, drag handles or keyboard sorting, size choices, and each widget's settings. Done leaves edit mode. The grid adapts from four columns to one, clamps rendered spans to the available columns, and preserves saved sizes. Removing a widget has a short Undo affordance.

Persistence: AppSettings.dashboard stores the workspace's widget order, dimensions and type-specific settings. Updates use the board's debounced save and workspace-boundary flush. Edit mode is transient. Dashboard has no per-leaf cache and no Dashboard section in the Settings dialog. It is a frameset singleton and cannot pop out.

For schedule widgets, boards: null selects all boards and boards: [] selects none. DashboardFrameContext supplies the explicit source frameId for dashboard:open-note; consumers must not infer it from the active frame. The host revalidates workspace and provider identity after reading the note before splitting.