@gurezo/web-serial-rxjs 2.4.0 → 3.1.0

package/dist/session/serial-session-options.d.ts

@@ -1,67 +1,15 @@
+import { type BaudRate, type MaxChars, type MaxLines, type ReceiveReplayBufferSize, type SerialPortBufferSize } from '../internal/branded-numbers';
+import type { SerialConnectionOptions } from '../types';
 import type { TerminalBufferOptions } from '../terminal/create-terminal-buffer';
 import { type LineBufferOptions } from './internal/line-buffer';
 /**
- * Options for creating a {@link SerialSession} via {@link createSerialSession}.
- *
- * These options configure the serial port connection parameters used when
- * calling `port.open` and `navigator.serial.requestPort`. All properties
- * are optional; omitted fields fall back to {@link DEFAULT_SERIAL_SESSION_OPTIONS}.
- *
- * @example
- * ```typescript
- * const session = createSerialSession({
- *   baudRate: 115200,
- *   dataBits: 8,
- *   stopBits: 1,
- *   parity: 'none',
- *   flowControl: 'none',
- *   filters: [{ usbVendorId: 0x1234, usbProductId: 0x5678 }],
- * });
- * ```
+ * Library-specific options for {@link createSerialSession} that are not passed
+ * to W3C `port.open`.
  *
- * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/199 | Issue #199}
- * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/200 | Issue #200}
+ * @see {@link SerialConnectionOptions} for W3C connection parameters
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/441 | Issue #441}
  */
-export interface SerialSessionOptions {
-    /**
-     * Baud rate for the serial port connection (bits per second).
-     *
-     * Common values include 9600, 19200, 38400, 57600, 115200, etc.
-     * Must match the baud rate configured on the connected device.
-     *
-     * @default 9600
-     */
-    baudRate?: number;
-    /**
-     * Number of data bits per character (7 or 8).
-     *
-     * @default 8
-     */
-    dataBits?: 7 | 8;
-    /**
-     * Number of stop bits (1 or 2).
-     *
-     * @default 1
-     */
-    stopBits?: 1 | 2;
-    /**
-     * Parity checking mode.
-     *
-     * @default 'none'
-     */
-    parity?: 'none' | 'even' | 'odd';
-    /**
-     * Buffer size for the underlying read stream, in bytes.
-     *
-     * @default 255
-     */
-    bufferSize?: number;
-    /**
-     * Flow control mode.
-     *
-     * @default 'none'
-     */
-    flowControl?: 'none' | 'hardware';
+export interface SerialSessionFeatureOptions {
     /**
      * Filters for port selection when requesting a port.
      *
@@ -96,6 +44,38 @@ export interface SerialSessionOptions {
      */
     lineBuffer?: LineBufferOptions;
 }
+/**
+ * Options for creating a {@link SerialSession} via {@link createSerialSession}.
+ *
+ * Composes {@link Partial}<{@link SerialConnectionOptions}> (W3C connection
+ * parameters passed to `port.open`) with {@link SerialSessionFeatureOptions}
+ * (library-specific session features). All connection fields are optional;
+ * omitted values fall back to {@link DEFAULT_SERIAL_SESSION_OPTIONS}
+ * (`baudRate` 9600, `dataBits` 8, `stopBits` 1, `parity` `'none'`,
+ * `bufferSize` 255, `flowControl` `'none'`).
+ *
+ * @example
+ * ```typescript
+ * const session = createSerialSession({
+ *   baudRate: 115200,
+ *   dataBits: 8,
+ *   stopBits: 1,
+ *   parity: 'none',
+ *   flowControl: 'none',
+ *   filters: [{ usbVendorId: 0x1234, usbProductId: 0x5678 }],
+ * });
+ * ```
+ *
+ * @see {@link SerialConnectionOptions}
+ * @see {@link SerialSessionFeatureOptions}
+ * @see {@link SerialOptions}
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/199 | Issue #199}
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/200 | Issue #200}
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/402 | Issue #402}
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/441 | Issue #441}
+ */
+export interface SerialSessionOptions extends Partial<SerialConnectionOptions>, SerialSessionFeatureOptions {
+}
 /**
  * Options for {@link SerialSessionOptions.receiveReplay}.
  *
@@ -136,16 +116,89 @@ export declare const MAX_RECEIVE_REPLAY_MAX_CHARS = 1048576;
  * @throws {@link SerialError} with {@link SerialErrorCode.INVALID_RECEIVE_REPLAY_OPTIONS}
  *         when `bufferSize` or `maxChars` are out of range.
  */
-export declare function resolveReceiveReplayOptions(options?: SerialSessionReceiveReplayOptions): Required<SerialSessionReceiveReplayOptions>;
+/** Resolved receive replay options with validated branded numeric fields. */
+export type ResolvedSerialSessionReceiveReplayOptions = {
+    enabled: boolean;
+    bufferSize: ReceiveReplayBufferSize;
+    maxChars: MaxChars;
+};
+export declare function resolveReceiveReplayOptions(options?: SerialSessionReceiveReplayOptions): ResolvedSerialSessionReceiveReplayOptions;
+/**
+ * Merge and validate {@link TerminalBufferOptions}.
+ *
+ * @throws {@link SerialError} with {@link SerialErrorCode.INVALID_TERMINAL_BUFFER_OPTIONS}
+ *         when `maxLines` or `maxChars` are out of range.
+ */
+/** Resolved terminal buffer options with validated branded numeric fields. */
+export type ResolvedTerminalBufferOptions = {
+    maxLines: MaxLines;
+    maxChars: MaxChars;
+    stripAnsi: boolean;
+};
+export declare function resolveTerminalBufferOptions(options?: TerminalBufferOptions): ResolvedTerminalBufferOptions;
+/**
+ * Merge and validate {@link LineBufferOptions}.
+ *
+ * @throws {@link SerialError} with {@link SerialErrorCode.INVALID_LINE_BUFFER_OPTIONS}
+ *         when `maxChars` is out of range.
+ */
+/** Resolved line buffer options with validated branded numeric fields. */
+export type ResolvedLineBufferOptions = {
+    maxChars: MaxChars;
+};
+export declare function resolveLineBufferOptions(options?: LineBufferOptions): ResolvedLineBufferOptions;
+/**
+ * Fully resolved session options after merging {@link SerialSessionOptions}
+ * with {@link DEFAULT_SERIAL_SESSION_OPTIONS}. All invariant fields are
+ * required; `filters` remains optional.
+ */
+export type ResolvedSerialSessionOptions = Required<Omit<SerialSessionOptions, 'filters' | 'receiveReplay' | 'terminalBuffer' | 'lineBuffer' | 'baudRate' | 'bufferSize'>> & {
+    baudRate: BaudRate;
+    bufferSize: SerialPortBufferSize;
+    filters?: SerialPortFilter[];
+    receiveReplay: ResolvedSerialSessionReceiveReplayOptions;
+    terminalBuffer: ResolvedTerminalBufferOptions;
+    lineBuffer: ResolvedLineBufferOptions;
+};
 /**
  * Default values applied to omitted {@link SerialSessionOptions} fields.
  *
  * @internal
  */
-export declare const DEFAULT_SERIAL_SESSION_OPTIONS: Required<Omit<SerialSessionOptions, 'filters' | 'receiveReplay' | 'terminalBuffer' | 'lineBuffer'>> & {
-    filters?: SerialPortFilter[];
-    receiveReplay: Required<SerialSessionReceiveReplayOptions>;
-    terminalBuffer: Required<TerminalBufferOptions>;
-    lineBuffer: Required<LineBufferOptions>;
+export declare const DEFAULT_SERIAL_SESSION_OPTIONS: {
+    baudRate: BaudRate;
+    dataBits: 8;
+    stopBits: 1;
+    parity: "none";
+    bufferSize: SerialPortBufferSize;
+    flowControl: "none";
+    receiveReplay: ResolvedSerialSessionReceiveReplayOptions;
+    terminalBuffer: ResolvedTerminalBufferOptions;
+    lineBuffer: ResolvedLineBufferOptions;
+};
+/** Resolved W3C connection fields for {@link ResolvedSerialSessionOptions}. */
+export type ResolvedSerialSessionConnectionOptions = Required<Omit<SerialConnectionOptions, 'baudRate' | 'bufferSize'>> & {
+    baudRate: BaudRate;
+    bufferSize: SerialPortBufferSize;
 };
+/**
+ * Merge and validate W3C connection fields from {@link SerialSessionOptions}.
+ *
+ * @throws {@link SerialError} with {@link SerialErrorCode.INVALID_CONNECTION_OPTIONS}
+ *         when `baudRate` is out of range.
+ */
+export declare function resolveConnectionOptions(options?: Partial<SerialConnectionOptions>): ResolvedSerialSessionConnectionOptions;
+/**
+ * Merge and validate {@link SerialSessionOptions} into a fully resolved
+ * options object for internal session use.
+ *
+ * @throws {@link SerialError} when option values are out of range:
+ *         {@link SerialErrorCode.INVALID_CONNECTION_OPTIONS},
+ *         {@link SerialErrorCode.INVALID_FILTER_OPTIONS},
+ *         {@link SerialErrorCode.INVALID_RECEIVE_REPLAY_OPTIONS},
+ *         {@link SerialErrorCode.INVALID_TERMINAL_BUFFER_OPTIONS}, or
+ *         {@link SerialErrorCode.INVALID_LINE_BUFFER_OPTIONS}.
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/403 | Issue #403}
+ */
+export declare function resolveSerialSessionOptions(options?: SerialSessionOptions): ResolvedSerialSessionOptions;
 //# sourceMappingURL=serial-session-options.d.ts.map

package/dist/session/serial-session-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serial-session-options.d.ts","sourceRoot":"","sources":["../../src/session/serial-session-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAIhF,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IAEjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAElC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAE7B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,iCAAiC,CAAC;IAElD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,qBAAqB,CAAC;IAEvC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iCAAiC;IAChD;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAErD,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,UAAY,CAAC;AAQtD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,CAAC,EAAE,iCAAiC,GAC1C,QAAQ,CAAC,iCAAiC,CAAC,CA+B7C;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CACnD,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,eAAe,GAAG,gBAAgB,GAAG,YAAY,CAAC,CAC1F,GAAG;IACF,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,aAAa,EAAE,QAAQ,CAAC,iCAAiC,CAAC,CAAC;IAC3D,cAAc,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAChD,UAAU,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;CAYzC,CAAC"}
+{"version":3,"file":"serial-session-options.d.ts","sourceRoot":"","sources":["../../src/session/serial-session-options.ts"],"names":[],"mappings":"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"}

package/dist/session/serial-session-state.d.ts

@@ -1,11 +1,9 @@
+import type { SerialError } from '../errors/serial-error';
 /**
- * Reactive lifecycle state for a {@link SerialSession}.
+ * Canonical status literals for a {@link SerialSession} lifecycle.
  *
- * This is the v2 API counterpart of the legacy `SerialState` used by
- * `SerialClient`. The runtime values are the same flat strings v1
- * consumers used for UI switches; the {@link SerialSessionState} const
- * object is the canonical source of those literals so call sites can
- * avoid string typos and get IDE completion.
+ * Use these constants when comparing {@link SerialSessionState.status}
+ * so call sites avoid string typos and get IDE completion.
  *
  * Lifecycle transitions:
  *
@@ -14,12 +12,12 @@
  *                                \-> error
  * (any)  -> unsupported   (when Web Serial API is unavailable)
  * (any)  -> error         (when an unrecoverable failure occurs)
+ * (any)  -> disposed      (when dispose$ completes)
  * ```
  *
- * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/199 | Issue #199}
- * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/200 | Issue #200}
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/406 | Issue #406}
  */
-export declare const SerialSessionState: {
+export declare const SerialSessionStatus: {
     readonly Idle: "idle";
     readonly Connecting: "connecting";
     readonly Connected: "connected";
@@ -29,8 +27,48 @@ export declare const SerialSessionState: {
     readonly Disposed: "disposed";
 };
 /**
- * String union of allowed {@link SerialSessionState} runtime values
- * (same set as the values on the {@link SerialSessionState} object).
+ * String union of allowed {@link SerialSessionStatus} runtime values
+ * (same set as the values on the {@link SerialSessionStatus} object).
  */
-export type SerialSessionState = (typeof SerialSessionState)[keyof typeof SerialSessionState];
+export type SerialSessionStatus = (typeof SerialSessionStatus)[keyof typeof SerialSessionStatus];
+/** @see {@link SerialSessionState} */
+export interface IdleSessionState {
+    readonly status: typeof SerialSessionStatus.Idle;
+}
+/** @see {@link SerialSessionState} */
+export interface ConnectingSessionState {
+    readonly status: typeof SerialSessionStatus.Connecting;
+}
+/** Connected lifecycle variant with narrowed {@link SerialPortInfo} access via `portInfo`. */
+export interface ConnectedSessionState {
+    readonly status: typeof SerialSessionStatus.Connected;
+    readonly portInfo: SerialPortInfo;
+}
+/** @see {@link SerialSessionState} */
+export interface DisconnectingSessionState {
+    readonly status: typeof SerialSessionStatus.Disconnecting;
+}
+/** @see {@link SerialSessionState} */
+export interface UnsupportedSessionState {
+    readonly status: typeof SerialSessionStatus.Unsupported;
+}
+/** @see {@link SerialSessionState} */
+export interface ErrorSessionState {
+    readonly status: typeof SerialSessionStatus.Error;
+    readonly error: SerialError;
+}
+/** @see {@link SerialSessionState} */
+export interface DisposedSessionState {
+    readonly status: typeof SerialSessionStatus.Disposed;
+}
+/**
+ * Discriminated union emitted by {@link SerialSession.state$} — the
+ * canonical lifecycle source.
+ *
+ * Each variant carries the lifecycle `status` plus optional detail fields
+ * (`portInfo` when connected, `error` when in a fatal error state).
+ *
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/406 | Issue #406}
+ */
+export type SerialSessionState = IdleSessionState | ConnectingSessionState | ConnectedSessionState | DisconnectingSessionState | UnsupportedSessionState | ErrorSessionState | DisposedSessionState;
 //# sourceMappingURL=serial-session-state.d.ts.map

package/dist/session/serial-session-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serial-session-state.d.ts","sourceRoot":"","sources":["../../src/session/serial-session-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;CAQrB,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"serial-session-state.d.ts","sourceRoot":"","sources":["../../src/session/serial-session-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAQtB,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,IAAI,CAAC;CAClD;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,UAAU,CAAC;CACxD;AAED,8FAA8F;AAC9F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,SAAS,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED,sCAAsC;AACtC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,aAAa,CAAC;CAC3D;AAED,sCAAsC;AACtC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,WAAW,CAAC;CACzD;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,KAAK,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED,sCAAsC;AACtC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAC;CACtD;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,sBAAsB,GACtB,qBAAqB,GACrB,yBAAyB,GACzB,uBAAuB,GACvB,iBAAiB,GACjB,oBAAoB,CAAC"}

package/dist/session/serial-session.d.ts

@@ -1,12 +1,14 @@
 import type { Observable } from 'rxjs';
 import type { SerialError } from '../errors/serial-error';
+import type { SerialPayload } from '../types';
 import type { SerialSessionState } from './serial-session-state';
 /**
- * v2 public API for interacting with the Web Serial API through a
+ * Public API for interacting with the Web Serial API through a
  * minimal, session-oriented surface.
  *
  * The session is intentionally slim so that apps (Angular, Vue, React, etc.)
- * can drive their UI purely from `state$` + `isConnected$` + `receive$` + `terminalText$` + `lines$` + `errors$` and never
+ * can drive their UI from `state$` (canonical lifecycle state) + `errors$`
+ * (error event channel) + `receive$` + `terminalText$` + `lines$` and never
  * have to rebuild BehaviorSubjects, manage a read loop, or serialize writes
  * themselves.
  *
@@ -15,9 +17,20 @@ import type { SerialSessionState } from './serial-session-state';
  *
  * @example
  * ```typescript
+ * import { createSerialSession, SerialSessionStatus } from '@gurezo/web-serial-rxjs';
+ *
  * const session = createSerialSession({ baudRate: 115200 });
  *
- * session.state$.subscribe((state) => console.log('state:', state));
+ * session.state$.subscribe((state) => {
+ *   switch (state.status) {
+ *     case SerialSessionStatus.Connected:
+ *       console.log('connected:', state.portInfo);
+ *       break;
+ *     case SerialSessionStatus.Error:
+ *       console.error('error:', state.error);
+ *       break;
+ *   }
+ * });
  * session.receive$.subscribe((chunk) => console.log('rx:', chunk));
  * session.errors$.subscribe((error) => console.error('err:', error));
  *
@@ -79,48 +92,69 @@ export interface SerialSession {
     /**
      * Alias for {@link dispose$}.
      *
+     * @deprecated Prefer {@link dispose$}. This alias is retained for backward
+     *   compatibility and is scheduled for removal in the next major version.
+     *
      * @returns An Observable that completes when disposal has finished.
+     *
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/433 | Issue #433}
      */
     destroy$(): Observable<void>;
     /**
-     * Reactive session lifecycle state.
+     * Canonical lifecycle source for the session.
      *
-     * Replays the current state on subscribe. UIs should drive entirely from
-     * this stream instead of reconstructing their own BehaviorSubject.
+     * Reactive session lifecycle state as a discriminated union. Replays the
+     * current state on subscribe. Switch on `state.status` and use the
+     * per-variant fields (`portInfo` when {@link SerialSessionStatus.Connected},
+     * `error` when {@link SerialSessionStatus.Error}) instead of correlating
+     * separate streams.
      */
     readonly state$: Observable<SerialSessionState>;
     /**
-     * `true` when {@link state$} is `'connected'`, `false` for all other states.
+     * `true` when {@link state$} has `status: 'connected'`, `false` otherwise.
      *
      * Derived from `state$` with `distinctUntilChanged` so UIs can bind
      * connect/disabled flags without reimplementing the comparison.
+     *
+     * @deprecated Prefer narrowing {@link state$} with
+     *   {@link SerialSessionStatus.Connected}. Retained for backward compatibility;
+     *   scheduled for removal in the next major version.
+     *
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/435 | Issue #435}
      */
     readonly isConnected$: Observable<boolean>;
     /**
      * The active port’s {@link SerialPort.getInfo} snapshot, or `null` when no
-     * port is open (including {@link SerialSessionState.Idle},
-     * {@link SerialSessionState.Error}, and {@link SerialSessionState.Unsupported}).
+     * port is open (including {@link SerialSessionStatus.Idle},
+     * {@link SerialSessionStatus.Error}, and {@link SerialSessionStatus.Unsupported}).
      *
      * Emits the current value on subscribe. Use with {@link state$} to know when
      * the value is valid for your UI.
+     *
+     * @deprecated Prefer narrowing {@link state$} with
+     *   {@link SerialSessionStatus.Connected} and using `state.portInfo`.
+     *   Retained for backward compatibility; scheduled for removal in the next
+     *   major version.
+     *
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/434 | Issue #434}
      */
     readonly portInfo$: Observable<SerialPortInfo | null>;
     /**
      * Synchronous read of the last {@link portInfo$} value.
      *
+     * @deprecated Prefer narrowing {@link state$} with
+     *   {@link SerialSessionStatus.Connected} and using `state.portInfo`.
+     *   Retained for backward compatibility; scheduled for removal in the next
+     *   major version.
+     *
      * @returns The same as {@link SerialPort.getInfo} for the open port, or
      *   `null` when not connected.
-     */
-    getPortInfo(): SerialPortInfo | null;
-    /**
-     * The underlying `SerialPort` while connected, or `null` otherwise.
      *
-     * Avoid calling `port.close()` or replacing streams yourself; that conflicts
-     * with session lifecycle. Prefer {@link getPortInfo} for identification.
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/434 | Issue #434}
      */
-    getCurrentPort(): SerialPort | null;
+    getPortInfo(): SerialPortInfo | null;
     /**
-     * Primary error channel.
+     * Canonical fatal / non-fatal error channel.
      *
      * All {@link SerialError} instances produced by the session (connect /
      * read / write / close) are multiplexed here. This is the main channel,
@@ -233,6 +267,6 @@ export interface SerialSession {
      *
      * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/203 | Issue #203}
      */
-    send$(data: string | Uint8Array): Observable<void>;
+    send$(data: SerialPayload): Observable<void>;
 }
 //# sourceMappingURL=serial-session.d.ts.map

package/dist/session/serial-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serial-session.d.ts","sourceRoot":"","sources":["../../src/session/serial-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;IAE9B;;;;;;;;OAQG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;;OASG;IACH,WAAW,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAE3C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,WAAW,IAAI,cAAc,GAAG,IAAI,CAAC;IAErC;;;;;OAKG;IACH,cAAc,IAAI,UAAU,GAAG,IAAI,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE3C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;CACpD"}
+{"version":3,"file":"serial-session.d.ts","sourceRoot":"","sources":["../../src/session/serial-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,kBAAkB,IAAI,OAAO,CAAC;IAE9B;;;;;;;;OAQG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;;OASG;IACH,WAAW,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;;OASG;IACH,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAEhD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEtD;;;;;;;;;;;;OAYG;IACH,WAAW,IAAI,cAAc,GAAG,IAAI,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE3C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;CAC9C"}

package/dist/session/session-runtime.d.ts

@@ -0,0 +1,140 @@
+import { Observable } from 'rxjs';
+import type { SerialError } from '../errors/serial-error';
+import type { ReadPump } from './read-pump';
+import { SerialSessionStatus, type SerialSessionState, type SerialSessionStatus as SerialSessionStatusType } from './serial-session-state';
+/**
+ * Discriminated union representing the full internal runtime state of a
+ * {@link SerialSession}, including lifecycle status and any resources that
+ * are valid for that status.
+ *
+ * This is the single source of truth for session lifecycle + resources.
+ * Public consumers observe the mapped {@link SerialSessionState} via
+ * `state$`; this union is internal only.
+ *
+ * @internal
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/397 | Issue #397}
+ */
+export type SessionRuntime = IdleRuntime | ConnectingRuntime | ConnectedRuntime | DisconnectingRuntime | ErrorRuntime | UnsupportedRuntime | DisposedRuntime;
+/** @internal */
+export interface IdleRuntime {
+    readonly status: typeof SerialSessionStatus.Idle;
+}
+/** @internal */
+export interface ConnectingRuntime {
+    readonly status: typeof SerialSessionStatus.Connecting;
+    readonly cancel: () => void;
+}
+/** @internal */
+export interface ConnectedRuntime {
+    readonly status: typeof SerialSessionStatus.Connected;
+    readonly port: SerialPort;
+    readonly pump: ReadPump;
+}
+/** @internal */
+export interface DisconnectingRuntime {
+    readonly status: typeof SerialSessionStatus.Disconnecting;
+    readonly port: SerialPort | null;
+}
+/** @internal */
+export interface ErrorRuntime {
+    readonly status: typeof SerialSessionStatus.Error;
+    readonly error: SerialError;
+}
+/** @internal */
+export interface UnsupportedRuntime {
+    readonly status: typeof SerialSessionStatus.Unsupported;
+}
+/** @internal */
+export interface DisposedRuntime {
+    readonly status: typeof SerialSessionStatus.Disposed;
+}
+/**
+ * Allowed transitions for the internal SerialSession state machine.
+ *
+ * `as const satisfies` keeps literal transition targets while ensuring every
+ * {@link SerialSessionStatus} key is present. Drift from the status union
+ * becomes a compile error.
+ *
+ * @internal
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/398 | Issue #398}
+ */
+export declare const ALLOWED_TRANSITIONS: {
+    readonly idle: readonly ["connecting", "error", "disposed"];
+    readonly connecting: readonly ["connected", "error", "idle", "disposed"];
+    readonly connected: readonly ["disconnecting", "error", "disposed"];
+    readonly disconnecting: readonly ["idle", "error", "disposed"];
+    readonly error: readonly ["idle", "connecting", "disposed"];
+    readonly unsupported: readonly ["disposed"];
+    readonly disposed: readonly [];
+};
+/**
+ * Valid target states when transitioning from {@link T}.
+ *
+ * @internal
+ */
+export type AllowedTransition<T extends SerialSessionStatusType> = (typeof ALLOWED_TRANSITIONS)[T][number];
+/** @internal */
+export declare function runtimeToSessionStatus(runtime: SessionRuntime): SerialSessionStatusType;
+/**
+ * Map internal runtime to the public {@link SerialSessionState} payload.
+ *
+ * @internal
+ * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/406 | Issue #406}
+ */
+export declare function runtimeToPublicState(runtime: SessionRuntime): SerialSessionState;
+/** @internal */
+export declare function isValidTransition(from: SerialSessionStatusType, to: SerialSessionStatusType): boolean;
+/** @internal */
+export declare function createIdleRuntime(): IdleRuntime;
+/** @internal */
+export declare function createConnectingRuntime(cancel: () => void): ConnectingRuntime;
+/** @internal */
+export declare function createConnectedRuntime(port: SerialPort, pump: ReadPump): ConnectedRuntime;
+/** @internal */
+export declare function createDisconnectingRuntime(port: SerialPort | null): DisconnectingRuntime;
+/** @internal */
+export declare function createErrorRuntime(error: SerialError): ErrorRuntime;
+/** @internal */
+export declare function createUnsupportedRuntime(): UnsupportedRuntime;
+/** @internal */
+export declare function createDisposedRuntime(): DisposedRuntime;
+/** @internal */
+export declare function createInitialRuntime(supported: boolean): SessionRuntime;
+/**
+ * Extract the active port from runtime when one is held.
+ *
+ * @internal
+ */
+export declare function getRuntimePort(runtime: SessionRuntime): SerialPort | null;
+/**
+ * Extract the active pump from runtime when one is held.
+ *
+ * @internal
+ */
+export declare function getRuntimePump(runtime: SessionRuntime): ReadPump | null;
+/**
+ * Controller that owns the {@link SessionRuntime} discriminated union and
+ * exposes the public `state$` stream derived from the runtime.
+ *
+ * @internal
+ */
+export interface SessionRuntimeController {
+    get runtime(): SessionRuntime;
+    get status(): SerialSessionStatusType;
+    get state$(): Observable<SerialSessionState>;
+    transition(next: SessionRuntime): boolean;
+    complete(): void;
+}
+/**
+ * Create a controller for the internal session runtime.
+ *
+ * @internal
+ */
+export declare function createSessionRuntimeController(initial: SessionRuntime): SessionRuntimeController;
+/**
+ * Exhaustiveness helper for switch statements over {@link SessionRuntime}.
+ *
+ * @internal
+ */
+export declare function assertNeverRuntime(value: never): never;
+//# sourceMappingURL=session-runtime.d.ts.map

package/dist/session/session-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-runtime.d.ts","sourceRoot":"","sources":["../../src/session/session-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,UAAU,EAAE,MAAM,MAAM,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACL,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,IAAI,uBAAuB,EACpD,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,iBAAiB,GACjB,gBAAgB,GAChB,oBAAoB,GACpB,YAAY,GACZ,kBAAkB,GAClB,eAAe,CAAC;AAEpB,gBAAgB;AAChB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,IAAI,CAAC;CAClD;AAED,gBAAgB;AAChB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,UAAU,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,gBAAgB;AAChB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,SAAS,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,gBAAgB;AAChB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,aAAa,CAAC;IAC1D,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED,gBAAgB;AAChB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,KAAK,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED,gBAAgB;AAChB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,WAAW,CAAC;CACzD;AAED,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAC;CACtD;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAU/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,uBAAuB,IAC7D,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C,gBAAgB;AAChB,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,cAAc,GACtB,uBAAuB,CAEzB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,kBAAkB,CAmBhF;AAED,gBAAgB;AAChB,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,uBAAuB,EAC7B,EAAE,EAAE,uBAAuB,GAC1B,OAAO,CAOT;AAED,gBAAgB;AAChB,wBAAgB,iBAAiB,IAAI,WAAW,CAE/C;AAED,gBAAgB;AAChB,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,iBAAiB,CAE7E;AAED,gBAAgB;AAChB,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,QAAQ,GACb,gBAAgB,CAElB;AAED,gBAAgB;AAChB,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,UAAU,GAAG,IAAI,GACtB,oBAAoB,CAEtB;AAED,gBAAgB;AAChB,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAEnE;AAED,gBAAgB;AAChB,wBAAgB,wBAAwB,IAAI,kBAAkB,CAE7D;AAED,gBAAgB;AAChB,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED,gBAAgB;AAChB,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,GAAG,cAAc,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,IAAI,CASzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,QAAQ,GAAG,IAAI,CAKvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,OAAO,IAAI,cAAc,CAAC;IAC9B,IAAI,MAAM,IAAI,uBAAuB,CAAC;IACtC,IAAI,MAAM,IAAI,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAC7C,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC;IAC1C,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,cAAc,GACtB,wBAAwB,CA2C1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAEtD"}

package/dist/terminal/create-terminal-buffer.d.ts

@@ -1,4 +1,5 @@
 import { type Observable } from 'rxjs';
+import { type MaxChars, type MaxLines } from '../internal/branded-numbers';
 /** @internal Folded state between {@link createTerminalBuffer} emissions. */
 export interface TerminalBufferState {
     completed: string;
@@ -7,7 +8,9 @@ export interface TerminalBufferState {
 /**
  * Applies one raw decoder chunk to terminal display state.
  * Handles `\r\n` and lone `\n` as line endings, and lone `\r` as
- * carriage return (clear current line for redraw). Does not interpret ANSI escapes.
+ * carriage return (clear current line for redraw). When
+ * {@link TerminalBufferOptions.stripAnsi} is enabled (default), ANSI escape
+ * sequences are removed before line folding.
  *
  * @internal Exported for unit tests.
  */
@@ -16,8 +19,8 @@ export declare function applyTerminalChunk(state: TerminalBufferState, chunk: st
 export declare function terminalDisplayText(state: TerminalBufferState): string;
 /** Resolved limits for {@link trimTerminalState}. `0` means unlimited. */
 export interface TerminalBufferLimits {
-    maxLines: number;
-    maxChars: number;
+    maxLines: MaxLines;
+    maxChars: MaxChars;
 }
 /** @internal Count newline-terminated rows in `completed`. */
 export declare function countCompletedLines(completed: string): number;
@@ -57,6 +60,15 @@ export interface TerminalBufferOptions {
      * @default 1048576
      */
     maxChars?: number;
+    /**
+     * When `true`, strips ANSI escape sequences from incoming chunks before
+     * folding carriage-return redraws. Use `false` to preserve raw escape
+     * codes in {@link TerminalBuffer.text$}.
+     *
+     * @default true
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/428 | Issue #428}
+     */
+    stripAnsi?: boolean;
 }
 /** Default limits applied when options are omitted. */
 export declare const DEFAULT_TERMINAL_BUFFER_OPTIONS: Required<TerminalBufferOptions>;

package/dist/terminal/create-terminal-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-terminal-buffer.d.ts","sourceRoot":"","sources":["../../src/terminal/create-terminal-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAA0B,MAAM,MAAM,CAAC;AAG/D,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAgBrB;AAED,gBAAgB;AAChB,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAEtE;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,oBAAoB,GAC3B,mBAAmB,CAuBrB;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uDAAuD;AACvD,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,qBAAqB,CAIzE,CAAC;AAgBJ;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAahB"}
+{"version":3,"file":"create-terminal-buffer.d.ts","sourceRoot":"","sources":["../../src/terminal/create-terminal-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAA0B,MAAM,MAAM,CAAC;AAC/D,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,6BAA6B,CAAC;AAIrC,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAgBrB;AAED,gBAAgB;AAChB,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAEtE;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,oBAAoB,GAC3B,mBAAmB,CAuBrB;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,uDAAuD;AACvD,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,qBAAqB,CAKzE,CAAC;AAkBJ;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAkBhB"}