Skip to content

refactor(web): share the /pty ptyProtocol parser before maestro-web terminal parity #153

Description

@0xabstracted

Context

#136 introduces maestro-ui/src/platform/ptyProtocol.ts — a provider-neutral, transport-agnostic
parser for the server→client /pty TEXT control frames (exit, size,
attached{base,gap,next,hasReplay}). It is deliberately free of connection-lifecycle concerns and
unit-tested in isolation (ptyProtocol.test.ts).

Problem

The /pty wire contract is defined in three places that must agree byte-for-byte: the server
producer (PtyWebSocketServer), the Tauri/UI consumer (ptyProtocol.ts), and the browser POC
(maestro-web). Today only the UI side has an extracted, tested parser. Before maestro-web grows
to parity with the hosted UI terminal, it will re-implement the same frame parsing — a second,
untested copy of a load-bearing contract that can silently drift (e.g. mis-handling the
raw-offset-vs-sanitized-replay distinction and duplicating scrollback).

Proposal

Establish ptyProtocol as the single shared source of truth for the /pty control-frame contract
before maestro-web reaches terminal parity, so maestro-web consumes it rather than forking
a copy. Options to evaluate: promote the parser (and the frame type definitions) to a location both
maestro-ui and maestro-web import, or a small shared package; keep it dependency-free so it can
be shared without pulling in UI/transport code.

Acceptance criteria

  • /pty control-frame parsing + frame types live in one module consumed by both maestro-ui
    and maestro-web (no duplicated parser).
  • The shared module stays provider-/transport-agnostic and dependency-free (no xterm, no
    socket, no Tauri imports) so both consumers can use it.
  • ptyProtocol.test.ts (or its shared successor) covers the frames both consumers rely on,
    including the raw-next-vs-sanitized-data offset rule.
  • Documented as a prerequisite/blocker on the maestro-web terminal-parity work so parity is
    built on the shared contract, not a fork.

Refs

Introduced by #136. Files: maestro-ui/src/platform/ptyProtocol.ts,
maestro-ui/src/__tests__/ptyProtocol.test.ts; consumer-to-be: maestro-web.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions