Story
As an executable-document author, I want terminal grids to be a defined part of
the XMD language, so I can write, inspect, and validate a static pane layout
before any terminal provider exists or any pane starts.
This is the first implementation Story under #717. It owns the authored
structure only. Concurrent execution belongs to the next Story.
Surface
The public syntax is frozen by architecture.md § Interactive terminal grids
and specs/executable-mdx-spec.md §6.21:
<Terminal.Grid columns={2}>
<Terminaltitle="Agent">...</Terminal>
<Terminaltitle="Shell" />
</Terminal.Grid><Terminal.Grid> is reserved core structural syntax with one paired form. Its
closed props contain one required positive integer, columns. It contains at
least one direct <Terminal> child.
<Terminal> is reserved core structural syntax with paired and self-closing
forms. Its closed props contain one required non-empty title. Titles are
display labels, may repeat, and do not identify panes. A pane's structural
identity is its ordinal among the grid's direct children. Rows are derived in
authored row-major order; the last row may be incomplete.
Only whitespace may appear between the direct panes. Ordinary text, another
element, a control structure that would produce panes dynamically, an empty or
self-closing grid, a nested grid, and a pane outside a grid are invalid. Neither
construct accepts as, provider selection, a shell, an executable, or a layout
identifier.
The paired pane's body remains ordinary document source for the later execution
Story. This Story parses and describes it but does not expand it concurrently or
start anything. Until #717's execution Story is installed, attempting to execute
a valid grid refuses before pane content or a default shell runs.
Ownership boundary
Core owns these constructs because an ordinary component receives content only
after that content has rendered and therefore cannot validate static direct
children or establish their concurrent boundary. The names are not registrable,
repository-overridable, or supplied by a host provider.
Syntax inspection and document validation use the same structural rules that
execution will use. They do not open a terminal, resolve an Agent, choose a
shell, contact a session coordinator, inspect tmux, or install an operational
provider. Every runtime reports the same language even when it has no terminal
provider.
Acceptance
- The grammar accepts exactly a paired grid with a positive integer
columns
and one or more direct panes, and accepts exactly paired and self-closing pane
forms with a non-empty title. - Unknown props,
as, invalid authored forms, empty grids, direct text,
non-pane direct elements, dynamic direct panes, nested grids, and panes outside
a grid are rejected before provider contact or pane-body effects. - One through five panes under two and three columns produce the exact row-major
positions. Duplicate titles remain valid, and pane identity follows ordinal
rather than title or scheduling. xmd syntax reports both reserved structural entries, their exact forms, and
their contracts on Deno, Node, and Bun without probing terminal capability.- Document validation returns deterministic diagnostics for every invalid form
above without executing expressions, pane content, a shell, tmux, or an
Agent. - A valid grid executed before an operational terminal-grid provider exists
fails closed before any pane body or shell begins.
These are terminal-grid evidence rows TG1–TG4 in
specs/executable-mdx-spec.md. Later Stories must reuse these rules rather than
restate them.
Focused evidence
Add focused coverage for the structural grammar and layout, and extend the
existing shared catalog and validation suites:
deno task test packages/core/tests/terminal-grid-structure.test.ts
deno task test packages/core/tests/syntax-catalog.test.ts
deno task test packages/core/tests/document-validation.test.ts
deno task test packages/cli/tests/syntax-cli.test.ts
The new structural test owns TG1, TG2, and TG4. The existing catalog and
validation suites own TG3. Tests assert provider non-observation; they do not
use absence of tmux on the test machine as evidence.
Dependencies and exclusions
Story
As an executable-document author, I want terminal grids to be a defined part of
the XMD language, so I can write, inspect, and validate a static pane layout
before any terminal provider exists or any pane starts.
This is the first implementation Story under #717. It owns the authored
structure only. Concurrent execution belongs to the next Story.
Surface
The public syntax is frozen by
architecture.md§ Interactive terminal gridsand
specs/executable-mdx-spec.md§6.21:<Terminal.Grid columns={2}> <Terminaltitle="Agent">...</Terminal> <Terminaltitle="Shell" /> </Terminal.Grid><Terminal.Grid>is reserved core structural syntax with one paired form. Itsclosed props contain one required positive integer,
columns. It contains atleast one direct
<Terminal>child.<Terminal>is reserved core structural syntax with paired and self-closingforms. Its closed props contain one required non-empty
title. Titles aredisplay labels, may repeat, and do not identify panes. A pane's structural
identity is its ordinal among the grid's direct children. Rows are derived in
authored row-major order; the last row may be incomplete.
Only whitespace may appear between the direct panes. Ordinary text, another
element, a control structure that would produce panes dynamically, an empty or
self-closing grid, a nested grid, and a pane outside a grid are invalid. Neither
construct accepts
as, provider selection, a shell, an executable, or a layoutidentifier.
The paired pane's body remains ordinary document source for the later execution
Story. This Story parses and describes it but does not expand it concurrently or
start anything. Until #717's execution Story is installed, attempting to execute
a valid grid refuses before pane content or a default shell runs.
Ownership boundary
Core owns these constructs because an ordinary component receives content only
after that content has rendered and therefore cannot validate static direct
children or establish their concurrent boundary. The names are not registrable,
repository-overridable, or supplied by a host provider.
Syntax inspection and document validation use the same structural rules that
execution will use. They do not open a terminal, resolve an Agent, choose a
shell, contact a session coordinator, inspect tmux, or install an operational
provider. Every runtime reports the same language even when it has no terminal
provider.
Acceptance
columnsand one or more direct panes, and accepts exactly paired and self-closing pane
forms with a non-empty
title.as, invalid authored forms, empty grids, direct text,non-pane direct elements, dynamic direct panes, nested grids, and panes outside
a grid are rejected before provider contact or pane-body effects.
positions. Duplicate titles remain valid, and pane identity follows ordinal
rather than title or scheduling.
xmd syntaxreports both reserved structural entries, their exact forms, andtheir contracts on Deno, Node, and Bun without probing terminal capability.
above without executing expressions, pane content, a shell, tmux, or an
Agent.
fails closed before any pane body or shell begins.
These are terminal-grid evidence rows TG1–TG4 in
specs/executable-mdx-spec.md. Later Stories must reuse these rules rather thanrestate them.
Focused evidence
Add focused coverage for the structural grammar and layout, and extend the
existing shared catalog and validation suites:
The new structural test owns TG1, TG2, and TG4. The existing catalog and
validation suites own TG3. Tests assert provider non-observation; they do not
use absence of tmux on the test machine as evidence.
Dependencies and exclusions
736b909de8a52216a2ff88ff9edade86181d19a1, committed directly on currentorigin/mainrevisionbc6e68da5548b1c33d17d6b28060390b33a3b949.architecture.md§ Interactive terminal grids andspecs/executable-mdx-spec.md§6.21 and Tier TG.execution, native Agent integration, tmux process, durability, or replay is
implemented here.