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
Refs
Introduced by #136. Files: maestro-ui/src/platform/ptyProtocol.ts,
maestro-ui/src/__tests__/ptyProtocol.test.ts; consumer-to-be: maestro-web.
Context
#136 introduces
maestro-ui/src/platform/ptyProtocol.ts— a provider-neutral, transport-agnosticparser for the server→client
/ptyTEXT control frames (exit,size,attached{base,gap,next,hasReplay}). It is deliberately free of connection-lifecycle concerns andunit-tested in isolation (
ptyProtocol.test.ts).Problem
The
/ptywire contract is defined in three places that must agree byte-for-byte: the serverproducer (
PtyWebSocketServer), the Tauri/UI consumer (ptyProtocol.ts), and the browser POC(
maestro-web). Today only the UI side has an extracted, tested parser. Beforemaestro-webgrowsto 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
ptyProtocolas the single shared source of truth for the/ptycontrol-frame contractbefore
maestro-webreaches terminal parity, somaestro-webconsumes it rather than forkinga copy. Options to evaluate: promote the parser (and the frame type definitions) to a location both
maestro-uiandmaestro-webimport, or a small shared package; keep it dependency-free so it canbe shared without pulling in UI/transport code.
Acceptance criteria
/ptycontrol-frame parsing + frame types live in one module consumed by bothmaestro-uiand
maestro-web(no duplicated parser).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-dataoffset rule.maestro-webterminal-parity work so parity isbuilt 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.