astrolabe/docs/spec/01-application-shell.md

01 · Application Shell & Navigation

This section describes the overall workspace structure, the header toolbar, the modal system, keyboard shortcuts, URL-based navigation, transient notifications, and the offline/installable nature of the app. Feature-specific behavior lives in the sections referenced inline.

A. Workspace Layout

Astrolabe is a single-screen workspace. Below a fixed top header sits a three-pane working area, each pane dedicated to one part of the snippet-editing workflow:

• Snippet library (left) — browse, search, select, and manage saved snippets (see Snippet Library).
• Spec editor (center) — edit the Vega-Lite spec of the selected snippet (see Spec Editor & Draft/Published Workflow).
• Live preview (right) — render the current spec (see Live Preview).

Behavior:

• All three panes are visible by default, laid out side by side in the order library, editor, preview.
• Adjacent panes are separated by a vertical drag handle. The user can drag a handle left/right to resize the two panes it sits between; the rest of the layout is unaffected.
• Each pane enforces a minimum width while resizing, so a pane cannot be dragged to nothing.
• Each pane can be individually shown or hidden via a persistent toggle strip (a narrow vertical strip of toggle buttons, one per pane, each indicating whether its pane is currently shown). The toggle strip also contains a shortcut button that opens the Datasets manager.
• When a pane is hidden, the remaining visible panes expand to fill the freed space, redistributing proportionally to their remembered widths. When a previously hidden pane is shown again, it returns at its remembered width.
• Hiding all panes is permitted; the toggle strip remains available to bring panes back.
• Pane widths and per-pane visibility persist locally across sessions and are restored on next load. The app remembers a pane's preferred width even while it is hidden, so re-showing it restores that width rather than an arbitrary one.

B. Header / Toolbar

A fixed header spans the top of the app.

• Left side: the app icon, the app title ("Astrolabe"), and a version badge showing the current app version.
• Right side: a row of text entry points. Each opens a destination:

Entry point	Opens
Import	A file-picker dialog to choose a previously exported file; the chosen file is imported (see Import & Export).
Export	Immediately produces a downloaded file containing all snippets and datasets (see Import & Export).
Datasets	The Datasets manager modal (see Datasets).
Settings	The Settings modal (see Settings).
About & Privacy	The About & Help modal (keyboard shortcuts, about, and privacy information).
Donate	The Donate modal.

Notes:

• Import and Export act directly (file dialog / file download); they do not open in-app modals.
• The Datasets, Settings, About & Privacy, and Donate entry points each open a modal (see Modal System).

C. Modal System

The app shows at most one modal at a time. The modal set is: Datasets, Settings, About & Help, Donate, Chart Builder, and Extract-to-Dataset.

• Opening any modal closes whichever modal was previously open; the two never overlap.
• Every modal can be dismissed by: clicking its close button, pressing Escape, or clicking the backdrop outside the modal body.
• Clicking inside the modal body does not dismiss it.
• The Chart Builder and Extract-to-Dataset modals are opened from within the Datasets / snippet workflows (see Chart Builder and Datasets), not from the header.
• Dismissing a modal returns the user to the underlying workspace unchanged.

D. Keyboard Shortcuts

Shortcuts are platform-aware: the modifier is Cmd on Mac and Ctrl on other platforms (shown below as Cmd/Ctrl).

Shortcut	Action
Cmd/Ctrl + Shift + N	Create a new snippet (see Snippet Library)
Cmd/Ctrl + K	Toggle the Datasets manager open/closed
Cmd/Ctrl + S	Publish the current snippet's draft (see Spec Editor & Draft/Published Workflow)
Cmd/Ctrl + ,	Open the Settings modal
Escape	Close the active modal

Notes:

• Cmd/Ctrl + K is a toggle: if the Datasets manager is already open it closes it; otherwise it opens it.
• Escape only acts when a modal is open; with no modal open it does nothing.
• The shortcut actions override the browser's default behavior for those key combinations.

E. Navigation & Shareable URL State

The app reflects its current location in the URL hash so that reloading restores the same view and the browser's Back/Forward buttons move between prior states. The user can copy the URL to share or bookmark a specific location.

States and their hash forms:

State	Hash
A selected snippet	#snippet-<id>
Datasets manager (list)	#datasets
A specific dataset	#datasets/dataset-<id>
New-dataset form	#datasets/new
Chart Builder for a dataset	#datasets/dataset-<id>/build

Behavior:

• Selecting a snippet updates the URL to that snippet; reloading reopens that snippet.
• Opening the Datasets manager updates the URL to #datasets; opening a specific dataset, the new-dataset form, or the Chart Builder for a dataset updates the URL to the corresponding form above.
• Browser Back/Forward navigate between these states (e.g. closing a modal via Back returns to the previously selected snippet).
• On load, the app reads the hash and restores the corresponding state (selected snippet, Datasets list, a specific dataset, the new-dataset form, or the Chart Builder).
• An empty/absent hash opens the default snippets view with no modal.

F. Toast Notifications

Transient toast messages appear in a corner of the screen to confirm actions or report problems, without interrupting the workflow.

• Four kinds, each visually distinct: success, error, warning, info.
• Each toast auto-dismisses after a few seconds, and can also be dismissed manually via its close control.
• Multiple toasts stack rather than replacing one another, and appear/disappear with a brief fade.

Events that raise toasts include:

• Snippet actions: creating, duplicating, deleting, publishing a draft, and reverting/discarding a draft.
• Dataset actions: creating, deleting, and extracting inline data into a dataset.
• Import/Export: results of an import (success/partial/failure) and confirmation of an export.
• Errors: spec/data validation failures and local-storage capacity warnings.

G. Offline & Installable

Astrolabe is local-first and usable without a network connection.

• After the first successful load, the app works fully offline; the interface and previously loaded content remain available with no connection.
• All snippets, datasets, and settings are stored locally and remain accessible offline (see Data Model).
• The app is installable as a standalone application from a supporting browser and, once installed, launches in its own window.