@floegence/floeterm-terminal-web 0.5.13 → 0.5.15

package/README.md

@@ -67,17 +67,32 @@ Hosts with cursor-paged history APIs can use the framework-neutral coordinator i
 
 ```ts
 const output = createPagedTerminalOutputCoordinator({
-  fetchPage: ({ startSequence, cursor, signal }) =>
-    transport.historyPage(sessionId, startSequence, cursor, signal),
-  write: data => core.write(data),
+  fetchPage: ({ startSequence, endSequence, historyGeneration, cursor, signal }) =>
+    transport.historyPage(sessionId, {
+      startSequence,
+      endSequence,
+      historyGeneration,
+      cursor,
+      signal,
+    }),
+  write: data => new Promise(resolve => core.write(data, resolve)),
+  writeHistory: data => new Promise(resolve => core.writeHistory(data, resolve)),
   clear: () => core.clear(),
 });
 
-await output.attach(1);
+void output.attach(1);
+const baseline = await output.waitForBaseline();
+if (!baseline.baselineReady) {
+  throw baseline.failure;
+}
 events.onData(sessionId, chunk => output.pushLive(chunk));
 ```
 
-The coordinator understands sparse sequence coverage, retains live output while history is loading, catches up gaps, retries transient failures, and reports history truncation before rebasing. A live chunk remains renderable when a sparse history page covers its sequence without returning that chunk. Background catch-up does not block terminal input.
+History pages must explicitly include `coveredThroughSequence`, including the valid empty-history value `0`. A missing or malformed value produces a structured contract failure instead of guessing from the last returned chunk. The first page may also provide `snapshotEndSequence`, `firstRetainedSequence`, and `historyGeneration`; pass the snapshot end and generation through each later request.
+
+`baselineReady` becomes true only after the complete fixed history snapshot has been source-sequence merged with retained live output and the final history writer completion has fired. After that fence, catch-up retries preserve baseline readiness and do not need to block input. Structured failures distinguish initial replay from background catch-up and expose stable codes without requiring error-string parsing.
+
+Use `TerminalCore.writeHistory` for history batches. Its auto-response suppression is scoped to that parser write and ends at its completion callback, so later live output and user input use normal terminal behavior.
 
 ## Restorable In-Memory Snapshots
 

package/dist/core/PagedTerminalOutputCoordinator.d.ts

@@ -1,7 +1,9 @@
-import { type TerminalOutputPipelineChunk, type TerminalOutputPipelineScheduler } from './TerminalOutputPipeline';
+import type { TerminalOutputPipelineChunk, TerminalOutputPipelineScheduler } from './TerminalOutputPipeline';
 export type PagedTerminalOutputState = 'idle' | 'initial-replay' | 'live' | 'catching-up' | 'retry-wait' | 'failed' | 'disposed';
 export interface PagedTerminalHistoryRequest {
     startSequence: number;
+    endSequence?: number;
+    historyGeneration?: number;
     cursor?: string | number;
     signal: AbortSignal;
 }
@@ -10,15 +12,32 @@ export interface PagedTerminalHistoryPage {
     hasMore: boolean;
     nextCursor?: string | number;
     firstAvailableSequence?: number;
+    firstRetainedSequence?: number;
     coveredThroughSequence: number;
+    snapshotEndSequence?: number;
+    historyGeneration?: number;
+    historyReset?: boolean;
+    historyTruncated?: boolean;
     coveredBytes?: number;
     totalBytes?: number;
 }
 export type PagedTerminalHistoryTruncationReason = 'history-evicted' | 'retained-live-overflow';
+export type PagedTerminalOutputFailureCode = 'history_fetch_failed' | 'history_coverage_incomplete' | 'history_contract_missing' | 'history_contract_invalid' | 'retained_live_overflow' | 'history_evicted';
+export interface PagedTerminalOutputFailure {
+    code: PagedTerminalOutputFailureCode;
+    phase: 'initial' | 'catch_up';
+    retryable: boolean;
+    attempt: number;
+    coveredSequence: number;
+    firstRetainedSequence?: number;
+    attachGeneration: number;
+    cause?: unknown;
+}
 export interface PagedTerminalOutputPolicy {
     maxRetainedLiveChunks: number;
     maxRetainedLiveBytes: number;
     retryDelaysMs: readonly number[];
+    maxWriteBatchBytes: number;
 }
 export interface PagedTerminalOutputScheduler extends TerminalOutputPipelineScheduler {
     setTimer(callback: () => void, delayMs: number): ReturnType<typeof setTimeout>;
@@ -27,17 +46,23 @@ export interface PagedTerminalOutputScheduler extends TerminalOutputPipelineSche
 export interface PagedTerminalOutputSnapshot {
     state: PagedTerminalOutputState;
     active: boolean;
+    baselineReady: boolean;
     coveredThroughSequence: number;
     retainedLiveChunks: number;
     retainedLiveBytes: number;
     retryAttempt: number;
     retryScheduled: boolean;
+    failure: PagedTerminalOutputFailure | null;
+    /** @deprecated Use failure for stable recovery diagnostics. */
     lastError: unknown;
+    attachGeneration: number;
     disposed: boolean;
 }
+type PagedTerminalOutputWriter = (data: Uint8Array, chunks: readonly TerminalOutputPipelineChunk[]) => unknown | Promise<unknown>;
 export interface PagedTerminalOutputCoordinatorOptions {
     fetchPage(request: PagedTerminalHistoryRequest): Promise<PagedTerminalHistoryPage>;
-    write(data: Uint8Array, chunks: readonly TerminalOutputPipelineChunk[]): void;
+    write: PagedTerminalOutputWriter;
+    writeHistory?: PagedTerminalOutputWriter;
     clear?: () => void;
     transformChunk?: (chunk: TerminalOutputPipelineChunk) => Uint8Array | null;
     isInteractive?: () => boolean;
@@ -48,6 +73,7 @@ export interface PagedTerminalOutputCoordinatorOptions {
 }
 export interface PagedTerminalOutputCoordinatorHandle {
     attach(startSequence?: number): Promise<void>;
+    waitForBaseline(): Promise<PagedTerminalOutputSnapshot>;
     pushLive(chunk: TerminalOutputPipelineChunk): void;
     setActive(active: boolean): void;
     clear(startSequence?: number): void;
@@ -56,4 +82,5 @@ export interface PagedTerminalOutputCoordinatorHandle {
     dispose(): void;
 }
 export declare const createPagedTerminalOutputCoordinator: (options: PagedTerminalOutputCoordinatorOptions) => PagedTerminalOutputCoordinatorHandle;
+export {};
 //# sourceMappingURL=PagedTerminalOutputCoordinator.d.ts.map

package/dist/core/PagedTerminalOutputCoordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PagedTerminalOutputCoordinator.d.ts","sourceRoot":"","sources":["../../src/core/PagedTerminalOutputCoordinator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PagedTerminalOutputCoordinator.d.ts","sourceRoot":"","sources":["../../src/core/PagedTerminalOutputCoordinator.ts"],"names":[],"mappings":"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"}