Skip to content

Make executable document grids use <Grid> and <Pane> #781

Description

@taras

Story

As an executable-document author, I want interactive layouts to use <Grid> and <Pane>, so the document describes presentation cells rather than committing every cell to a terminal implementation.

Example

<Grid columns={2}>
  <Pane title="Architect">
    <Agent name="codex">
      <Session.Launch session="architect">
        Work on the current issue.
      </Session.Launch>
    </Agent>
  </Pane>
  <Pane title="Existing session">
    <Agent name="claude">
      <Session.Tail session="session-id" />
    </Agent>
  </Pane>
  <Pane title="Workspace" />
</Grid>

The paired panes contain ordinary executable document flow. A self-closing pane retains the existing default-shell behavior. <Session.Tail> is shown as the intended consumer owned by its separate Story; this Story does not implement it.

Current gap

The unmerged #717 stack exposes <Terminal.Grid> and <Terminal>, and names its neutral packages @executablemd/terminal and @executablemd/terminal-tmux. That accurately described the first tmux implementation, but it makes a physical terminal the identity of every presentation cell. A read-only session viewer is pane content without being the terminal capability itself, and another multiplexer should not require a second document language.

No released XMD version contains this surface, so preserving the old names would create compatibility work for a contract the product has rejected.

Contract

<Grid> and <Pane> replace <Terminal.Grid> and <Terminal> as core-owned structural syntax. The existing forms, static direct-child validation, columns, title, authored row-major order, paired-pane isolation, self-closing default shell, foreground ownership, concurrency, durability, replay, cancellation, and complete teardown remain unchanged.

Grid and pane describe provider-neutral presentation structure. Terminal remains the correct technical term only for a PTY, foreground-terminal lease, terminal process observation, and a pane capability required by an interactive native process or shell.

The neutral workspace package is @executablemd/grid. The tmux implementation is @executablemd/grid-tmux. The dependency direction remains:

@executablemd/grid-tmux ──> @executablemd/grid
@executablemd/core      ──> @executablemd/grid
@executablemd/cli       ──> core + runtime + grid + grid-tmux

The neutral package imports neither core, runtime, CLI, nor the tmux adapter. The tmux adapter imports neither core, runtime, nor CLI. POSIX terminal and process observation remains reusable provider infrastructure behind the neutral boundary; Deno and compiled entrypoints install it, while Node and Bun retain their existing refusal.

The old component names, package names, implementation paths, exports, aliases, and compatibility re-exports are deleted. Every repository consumer uses the new canonical surfaces, with one definition for each contextual API and public error constructor.

Tmux remains an xmd run grid provider. This Story adds no Workflow component, provider, effect, journal behavior, or replay authority. The provider name, hidden worker transport, exact argv/cwd/environment delivery, pane readiness, layout, identities, settlement, and bounded teardown behavior remain those already accepted under #717.

Acceptance

  • Syntax inspection, validation, execution, examples, and diagnostics expose <Grid> and <Pane>; the old authored names are absent.
  • One through five panes retain the exact existing row-major layout and static placement rules.
  • Paired panes retain isolated concurrent document execution; a self-closing pane retains the host default shell.
  • Native <Session.Launch> still reaches the selected pane terminal, and root launch behavior is unchanged.
  • The neutral and tmux packages publish under their grid names, every repository import is canonical, and the former terminal package and implementation paths are absent.
  • Static dependency evidence proves the accepted direction and absence of core/grid cycles.
  • Controlled provider, tmux worker, replay, cancellation, terminal-quiescence, Deno/compiled host, and Node/Bun refusal evidence passes unchanged apart from the rejected names.
  • A mutation restoring either old authored name or an old package import makes the boundary evidence fail.

Relationships

Out of scope

  • Implementing <Session.Tail>, a session viewer, or a REPL.
  • Building the XMD-owned multiplexer.
  • Changing provider-private tmux mechanics or weakening terminal ownership.
  • Adding grids to Workflow.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentsExecutable documents, authored workflows, and reader-facing document behaviorenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions