Commands
Every command the model runs, with its payload and result types and how to run it from code or as JSON. Generated from the registry.
The model runs 15 commands. Each one takes a JSON payload, checked against its JSON Schema, and returns a CommandResult: { ok: true, value }, or { ok: false, error }. Run one with model.run(name, payload) (typed by your registry), or give it as untrusted JSON to model.dispatch({ command, payload }), which validates it first. model.get("commands") returns this same list with the schemas, ready to become tool definitions for an assistant.
Every command can return invalid_payload (the payload does not match its schema, with the path of each problem), vetoed (a middleware refused it), queued (a middleware ran it while another command was running) and middleware_error; each command lists the ones its own rules add: not_found (a group, panel or separator it names is missing) and refused (a rule of the splitter refuses the change).
Sizes in payloads follow React Resizable Panels: a number is pixels, a string carries its unit (%, px, em, rem, vh, vw), and a string without one is a percentage. A layout is always in percent. The payload types below use T, your registry of group and panel ids.
Groups
group.add
Registers a group: panels laid out side by side (horizontal) or stacked (vertical). Its panels are added with panel.add. A nested group names the panel it sits in. A group the loaded document saved takes its saved layout once all its saved panels are added.
Payload (GroupAddPayload<T>)
| field | type | required | description |
|---|---|---|---|
id | string | no | the new group's id (generated when absent) |
orientation | "horizontal" | "vertical" | no | how its panels are laid out (default horizontal) |
parentPanelId | string | no | the panel a nested group sits in |
disabled | boolean | no | no separator of the group can be used (default false) |
Result ({ groupId: string })
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the new group's id |
Errors: refused, besides those every command can return.
model.run("group.add", {
id: "main",
orientation: "horizontal"
});{ "command": "group.add", "payload": {"id":"main","orientation":"horizontal"} }group.update
Changes what a group's markup declares: its orientation, the panel it sits in (null: none), whether it is disabled.
Payload (GroupUpdatePayload<T>)
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the group to change |
orientation | "horizontal" | "vertical" | no | how its panels are laid out |
parentPanelId | string | null | no | the panel it sits in; null: it is not nested |
disabled | boolean | no | no separator of the group can be used |
Result ({ groupId: string })
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the group changed |
Errors: not_found, besides those every command can return.
model.run("group.update", {
groupId: "main",
disabled: true
});{ "command": "group.update", "payload": {"groupId":"main","disabled":true} }group.remove
Unregisters a group and its panels. Groups nested in its panels stay: they are removed on their own. With keepLayout, a layout the user changed is kept as a saved group (it stays in the JSON document) and comes back when the group registers again with the same panels: a view that unmounts and mounts again keeps its layout.
Payload ({ groupId: GroupIdOf<T>; keepLayout?: boolean })
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the group to remove |
keepLayout | boolean | no | keep the group's layout, when it is not the default one, until it registers again |
Result ({ groupId: string; panelIds: string[] })
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the removed group |
panelIds | string[] | yes | the panels removed with it |
Errors: not_found, besides those every command can return.
model.run("group.remove", {
groupId: "main"
});{ "command": "group.remove", "payload": {"groupId":"main"} }group.set-layout
Sets a group's whole layout: each panel's size in percent, by panel id (every panel of the group, no other). Sizes that do not sum to 100 are scaled; each is clamped to its panel's constraints (disabled panels included). Returns the layout applied.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload ({ groupId: GroupIdOf<T>; layout: Layout })
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the group to lay out |
layout | object | yes | each panel's size in percent, by panel id: every panel of the group |
Result ({ layout: Layout })
| field | type | required | description |
|---|---|---|---|
layout | object | yes | the group's layout after the command |
Errors: not_found, besides those every command can return.
model.run("group.set-layout", {
groupId: "main",
layout: {
nav: 25,
editor: 75
}
});{ "command": "group.set-layout", "payload": {"groupId":"main","layout":{"nav":25,"editor":75}} }group.reset
Resets a group to its default layout: each panel at its defaultSize, the others sharing the rest equally.
Payload ({ groupId: GroupIdOf<T> })
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the group to reset |
Result ({ layout: Layout })
| field | type | required | description |
|---|---|---|---|
layout | object | yes | the group's layout after the command |
Errors: not_found, besides those every command can return.
model.run("group.reset", {
groupId: "main"
});{ "command": "group.reset", "payload": {"groupId":"main"} }group.measure
Reports what a group measures on screen, so sizes in px, em, rem, vh and vw resolve without a DOM. The engine runs it as a transient step whenever the group resizes; it is not saved in the JSON. Panels with groupResizeBehavior preserve-pixel-size keep their pixels; the layout is clamped to the constraints the measure resolves.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload (GroupMeasurePayload<T>)
| field | type | required | description |
|---|---|---|---|
groupId | string | yes | the group measured |
axisSize | number | yes | the group's size along its orientation, in pixels (the sum of its panels' sizes) |
fontSize | number | no | the group's computed font size, in pixels (em) |
rootFontSize | number | no | the root element's font size, in pixels (rem) |
viewportWidth | number | no | the viewport's width, in pixels (vw) |
viewportHeight | number | no | the viewport's height, in pixels (vh) |
Result ({ layout: Layout })
| field | type | required | description |
|---|---|---|---|
layout | object | yes | the group's layout after the command |
Errors: not_found, besides those every command can return.
model.run("group.measure", {
groupId: "main",
axisSize: 1200,
fontSize: 16,
rootFontSize: 16,
viewportWidth: 1280,
viewportHeight: 800
});{ "command": "group.measure", "payload": {"groupId":"main","axisSize":1200,"fontSize":16,"rootFontSize":16,"viewportWidth":1280,"viewportHeight":800} }Panels
panel.add
Registers a panel in a group, with its constraints as declared (sizes: a number is px; a string carries its unit, %, px, em, rem, vh or vw; a string without one is %). Panels sort by order (their document position), so a panel rendered conditionally lands in its place. The group's layout becomes the saved one once the group holds exactly its saved panels, else the layout the group last had with its panels (the one it leaves is remembered for the panel set it had), else its default layout.
Payload (PanelAddPayload<T>)
| field | type | required | description |
|---|---|---|---|
id | string | no | the new panel's id (generated when absent) |
groupId | string | yes | the group the panel belongs to |
order | number | no | where the panel sits among its group's panels (its document position); default: after the others |
minSize | number | string | no | the smallest size the panel takes when expanded (default 0) |
maxSize | number | string | no | the largest size the panel takes (default 100%) |
defaultSize | number | string | no | the size the panel starts with when no saved layout has one (default: an equal share of what is left) |
collapsible | boolean | no | whether the panel can collapse below its minimum, to its collapsed size |
collapsedSize | number | string | no | the panel's size when collapsed (default 0) |
collapsedThreshold | number | string | no | how far past its minimum a drag goes before the panel collapses (default: halfway between collapsed and minimum) |
disabled | boolean | no | the panel is resized neither directly nor by resizing its neighbours (code still can) |
groupResizeBehavior | "preserve-relative-size" | "preserve-pixel-size" | no | when the group resizes, keep the panel's percentage (preserve-relative-size, default) or its pixels (preserve-pixel-size) |
Result ({ panelId: string })
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the new panel's id |
Errors: not_found, refused, besides those every command can return.
model.run("panel.add", {
id: "nav",
groupId: "main",
order: 0,
minSize: "15%",
defaultSize: 240,
collapsible: true
});{ "command": "panel.add", "payload": {"id":"nav","groupId":"main","order":0,"minSize":"15%","defaultSize":240,"collapsible":true} }panel.update
Changes what a panel's markup declares: its order or its constraints (null removes one, so its default applies). The layout is clamped to the new constraints.
Payload (PanelUpdatePayload<T>)
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the panel to change |
order | number | no | where the panel sits among its group's panels (its document position) |
minSize | number | string | null | no | the smallest size the panel takes when expanded (default 0); null removes it |
maxSize | number | string | null | no | the largest size the panel takes (default 100%); null removes it |
defaultSize | number | string | null | no | the size the panel starts with when no saved layout has one (default: an equal share of what is left); null removes it |
collapsible | boolean | null | no | whether the panel can collapse below its minimum, to its collapsed size; null removes it |
collapsedSize | number | string | null | no | the panel's size when collapsed (default 0); null removes it |
collapsedThreshold | number | string | null | no | how far past its minimum a drag goes before the panel collapses (default: halfway between collapsed and minimum); null removes it |
disabled | boolean | null | no | the panel is resized neither directly nor by resizing its neighbours (code still can); null removes it |
groupResizeBehavior | "preserve-relative-size" | "preserve-pixel-size" | null | no | when the group resizes, keep the panel's percentage (preserve-relative-size, default) or its pixels (preserve-pixel-size); null removes it |
Result ({ panelId: string })
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the panel |
Errors: not_found, besides those every command can return.
model.run("panel.update", {
panelId: "nav",
maxSize: "40%",
minSize: null
});{ "command": "panel.update", "payload": {"panelId":"nav","maxSize":"40%","minSize":null} }panel.remove
Unregisters a panel. Its group's layout becomes the saved one when the group now holds exactly its saved panels, else the layout the group last had with these panels (the one it leaves is remembered for the panel set it had, so the panel comes back to it), else the default layout of the panels left.
Payload ({ panelId: PanelIdOf<T> })
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the panel to remove |
Result ({ panelId: string })
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the panel |
Errors: not_found, besides those every command can return.
model.run("panel.remove", {
panelId: "nav"
});{ "command": "panel.remove", "payload": {"panelId":"nav"} }panel.resize
Resizes a panel to a size (a number is px; a string carries its unit, %, px, em, rem, vh or vw; a string without one is %). The nearest panels make room within their constraints, those after it first. A size other than % needs the group measured. Code may resize a disabled panel. Returns the size it got, in percent.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload ({ panelId: PanelIdOf<T>; size: SizeValue })
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the panel to resize |
size | number | string | yes | the size to give it |
Result ({ size: number })
| field | type | required | description |
|---|---|---|---|
size | number | yes | the panel's size after the command, in percent |
Errors: not_found, refused, besides those every command can return.
model.run("panel.resize", {
panelId: "nav",
size: "30%"
});{ "command": "panel.resize", "payload": {"panelId":"nav","size":"30%"} }panel.collapse
Collapses a collapsible panel to its collapsed size; the panel remembers its size to return to it on expand. Refused when the panel is not collapsible or the other panels cannot take its space. Returns its size, in percent.
Payload ({ panelId: PanelIdOf<T> })
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the panel to collapse |
Result ({ size: number })
| field | type | required | description |
|---|---|---|---|
size | number | yes | the panel's size after the command, in percent |
Errors: not_found, refused, besides those every command can return.
model.run("panel.collapse", {
panelId: "nav"
});{ "command": "panel.collapse", "payload": {"panelId":"nav"} }panel.expand
Expands a collapsed panel to the size it had before collapsing (its minimum when it has none), or to the largest size that fits when the other panels cannot make room for all of it. Refused when the panel is not collapsible or nothing can make room. Returns its size, in percent.
Payload ({ panelId: PanelIdOf<T> })
| field | type | required | description |
|---|---|---|---|
panelId | string | yes | the panel to expand |
Result ({ size: number })
| field | type | required | description |
|---|---|---|---|
size | number | yes | the panel's size after the command, in percent |
Errors: not_found, refused, besides those every command can return.
model.run("panel.expand", {
panelId: "nav"
});{ "command": "panel.expand", "payload": {"panelId":"nav"} }Separators
separator.move
Moves a separator by delta percent of its group: positive grows the panels before it (the start side), negative the panels after it. The panels on the shrinking side give space nearest first, within their constraints; a collapsible panel snaps collapsed or open at its threshold; disabled panels do not change. A drag sends every step from the layout it started from (origin), as a transient step, then once more to commit. Refused when the separator or its group is disabled. Returns the layout applied.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload (SeparatorMovePayload)
| field | type | required | description |
|---|---|---|---|
separatorId | string | yes | the separator to move: <beforePanelId>:<afterPanelId> |
delta | number | yes | how far to move it, in percent of the group: positive grows the panels before it |
origin | object | no | the layout the move is measured from (a drag's layout when it started); default: the layout now |
source | "pointer" | "keyboard" | no | what moves it (default pointer): the keyboard collapses or expands a collapsible panel in one step instead of at its threshold |
Result ({ layout: Layout })
| field | type | required | description |
|---|---|---|---|
layout | object | yes | the group's layout after the move |
Errors: not_found, refused, besides those every command can return.
model.run("separator.move", {
separatorId: "nav:editor",
delta: 5
});{ "command": "separator.move", "payload": {"separatorId":"nav:editor","delta":5} }separator.update
Changes what a separator's markup declares: whether it is disabled (it cannot resize its panels; they may still resize through another separator) and whether a double click resets its panel to its default size.
Payload (SeparatorUpdatePayload)
| field | type | required | description |
|---|---|---|---|
separatorId | string | yes | the separator to change: <beforePanelId>:<afterPanelId> |
disabled | boolean | no | the separator cannot be used |
resetOnDoubleClick | boolean | no | a double click resets its panel to its default size (default true) |
Result ({ separatorId: string })
| field | type | required | description |
|---|---|---|---|
separatorId | string | yes | the separator changed |
Errors: not_found, besides those every command can return.
model.run("separator.update", {
separatorId: "nav:editor",
resetOnDoubleClick: false
});{ "command": "separator.update", "payload": {"separatorId":"nav:editor","resetOnDoubleClick":false} }Batches
batch
Runs several commands in order as one atomic step: if any fails, none applies. Emits one change event. Nested batches are flattened. An adapter registers a group and its panels with one batch.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload ({ commands: BatchEntry<T>[] })
| field | type | required | description |
|---|---|---|---|
commands | object[] | yes | the commands to run, in order |
Result ({ results: unknown[] })
| field | type | required | description |
|---|---|---|---|
results | JSON[] | yes | each command's value, in order |
Errors: those of the commands it runs (the first failure, at its path in commands); nothing applies unless all succeed.
model.run("batch", {
commands: [
{
command: "group.add",
payload: {
id: "main"
}
},
{
command: "panel.add",
payload: {
id: "nav",
groupId: "main"
}
},
{
command: "panel.add",
payload: {
id: "editor",
groupId: "main"
}
}
]
});{ "command": "batch", "payload": {"commands":[{"command":"group.add","payload":{"id":"main"}},{"command":"panel.add","payload":{"id":"nav","groupId":"main"}},{"command":"panel.add","payload":{"id":"editor","groupId":"main"}}]} }The command bus
How the model runs commands, with run, can, check and dispatch, the result and its error codes, middleware that vetoes or rewrites, and listeners.
The JSON document
The saved layout as JSON, version 1, with every group's panel sizes, collapsed state and restore sizes, its JSON Schema, and how a document is validated.