Module layout_file 

Layout files — the agentmux.layout v1 format and its writer (docs/specs/SPEC_LAYOUT_FILES_2026_09_25.md, Phase 1).

A layout file describes a window’s tabs, their split trees (as ratios) and each pane’s typed views, so it can be read, diffed, shared and — in Phase 2 — reopened. It is not a dump of the store: every view is written through a per-type allowlist (view_from_block), never by copying block meta. The session-restore snapshot (server/service/session_restore.rs) copies meta verbatim, which is fine for an internal blob and wrong for a file a user hands to someone else: session ids, instance ids, absolute paths and env would all leak.

Every struct carries an extra map, so a reader keeps fields it doesn’t know and writes them back unchanged (spec §3.1).

Structs

ApplyPlan

A layout file turned into panes, plus everything the user should see before it opens.

ExportContext

Everything the exporter reads from outside the store, injected so tests are deterministic.

Exported

The result of exporting: the document, plus anything the user should be told before it is written (spec §3.4).

LayoutDoc

LayoutPane

LayoutTab

LayoutView

LayoutWindow

PlanBuilder 🔒

PlanOptions

How to turn a file into panes.

PlanTab

One tab ready for session_restore::replay_tabs: block metas, and a tree whose leaves name them by session_restore::placeholder(i).

SavedBy

TabBuilder 🔒

Pane ids are minted per tab in tree order; node ids are the tree’s own, used only to map focus/magnify onto them.

TreeChild

Enums

TreeNode

A split ({split, children}) or a leaf ({pane}).

Truncated 🔒

A per-tab limit the file hit. Each is noted once per tab, however many panes or branches it cuts off.

Constants

LAYOUT_EXTENSION

Every layout file ends with this (spec §3.1): filterable in dialogs, highlighted as JSON in any editor.

LAYOUT_FORMAT

The format discriminator. A reader refuses any other value.

LAYOUT_VERSION

The format version this build writes and the newest it reads.

MAX_LAYOUT_FILE_BYTES

A layout file larger than this is refused unread — real ones are a few KB.

MAX_PANES_PER_TAB 🔒

MAX_TABS 🔒

MAX_TREE_DEPTH 🔒

META_LAYOUT_AGENT

Block meta key naming the agent definition a layout’s agent pane should launch. Set on the empty {view:"agent"} placeholder the plan creates; agent_open::open_agent_into_block launches into it and clears the key.

PLAIN_VIEWS 🔒

Views that need no config to open, beyond their type.

Functions

armory_target 🔒

Where a saved Armory pane goes, by its section (and, for the old Memory section, its Global/Personal subsection): its pane, connectors or memory, and that pane’s section. The same mapping m0037_retire_old_pane_names.rs applied to stored blocks; layout files live outside AgentMux, so their import still needs it.

cfg_str 🔒

expand_home 🔒

~ / ~/x resolved under home; anything else unchanged.

export_tab 🔒

export_window

Export one window — every tab of its workspace — as a layout document.

home_relative 🔒

A path under home as ~/… (forward slashes); anything else unchanged.

is_layout_path

Whether path is somewhere a layout may be written: absolute, and named *.agentmux-layout.json.

is_trusted

Whether a file counts as trusted (spec §3.5): saved by this install and sitting in its default layouts folder. Only trusted files start terminal commands without the user’s say-so.

meta_str 🔒

parse_layout

Parse a layout document, refusing another format or a newer version (spec §3.1). Unknown fields are kept in extra.

plan_from_doc

Build the plan. Never touches the store beyond reading agent definitions.

ratios 🔒

Flex sizes → ratios summing to exactly 1, rounded to 4 places for a readable file (the last sibling absorbs the rounding). Non-positive sizes share equally.

read_layout_file

Read and parse a layout file, refusing anything too large to be one.

resolve_agent 🔒

A user agent (not a template) matching the file’s slug, else its display name — only if exactly one matches, so a name shared by two agents never launches the wrong one.

strip_query 🔒

A URL with its query string and fragment removed (spec §3.3/§3.4) — they are where tokens, session ids and tracking live.

view_from_block 🔒

One pane tab, written from the per-type allowlist (spec §3.3). Anything not named here — session ids, instance ids, env, runtime state, CLI paths, failure records — is never written. An unknown view type is written as {type} alone.

write_layout_file

Write doc to path atomically: a temp file beside it, then a rename, so a crash or a full disk never leaves half a layout behind.