@floegence/floeterm-terminal-web 0.5.18 → 0.5.20

package/README.md

@@ -51,6 +51,17 @@ const core = new TerminalCore(
 await core.initialize();
 ```
 
+Hosts can preload the dynamic Ghostty module, WASM, and renderer resources before a terminal surface is visible without creating a `TerminalCore`:
+
+```ts
+import { preloadTerminalResources } from '@floegence/floeterm-terminal-web';
+
+await preloadTerminalResources({ signal });
+await core.initialize({ priority: 'interactive', signal });
+```
+
+Resource loading is single-flight and retryable after a real import or WASM initialization failure. Caller cancellation only stops that caller from waiting; it does not interrupt shared resource initialization. Core initialization is globally bounded, gives queued interactive work priority over background work, and shares the actual ready promise across duplicate calls.
+
 ## Notes
 
 - You must provide a `TerminalTransport` and `TerminalEventSource` for the managed controller.
@@ -96,6 +107,26 @@ If a page reports `historyReset` or changes `historyGeneration` while catch-up i
 
 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.
 
+Running sessions can prepare bounded history before a visible terminal exists. Preparation does not create a Core, attach a session, resize a PTY, or subscribe to live output:
+
+```ts
+const preparedHistory = await preparePagedTerminalHistory({
+  fetchPage: request => transport.historyPage(sessionId, request),
+  maxBytes: 4 * 1024 * 1024,
+  signal,
+});
+
+const attachGeneration = output.beginAttach(0);
+const attach = await transport.attachWithHistoryBoundary(sessionId, cols, rows);
+await output.completeAttach(attachGeneration, attach.historyBoundarySequence, {
+  preparedHistory,
+});
+```
+
+Prepared history is renderer-neutral and pins `historyGeneration`, `firstRetainedSequence`, and `snapshotEndSequence`. The visible attach validates those boundaries, replays the seed once, and fetches only the missing delta. A generation reset, retention advance, stale fence, or malformed seed discards it and falls back to the normal full recovery path.
+
+`preparePagedTerminalHistory` requires those three metadata fields on every prepared page and passes the remaining retained-byte budget as `request.maxBytes` so transports can bound each page as well. The helper always enforces its retained seed budget after a page returns; adapters should honor the request hint to keep peak response memory bounded too.
+
 ## Restorable In-Memory Snapshots
 
 Adaptive host worksets can release inactive renderers without closing their PTY sessions:
@@ -131,6 +162,8 @@ const core = new TerminalCore(container, {
 });
 ```
 
+When a host can capture an atomic attach boundary, call `beginAttach(startSequence)` before subscribing and starting the server attach, then pass its generation token together with the returned server boundary to `completeAttach(attachGeneration, snapshotEndSequence)`. Live output arriving during the attach round trip remains retained, while a stale attach acknowledgement cannot complete a newer generation. The convenience `attach(startSequence, snapshotEndSequence)` performs both steps when no such window exists. Route only sequences after the boundary to `pushLive`: initial history is fixed at the boundary, while catch-up history is bounded before the first retained live sequence. If defensive overlap still reaches the coordinator, the raw live copy wins over history for the same sequence so terminal query/response behavior is not replaced by replay semantics.
+
 Passive mirrors of a remote PTY can render with the session owner's current dimensions:
 
 ```ts

package/dist/core/PagedTerminalOutputCoordinator.d.ts

@@ -5,6 +5,7 @@ export interface PagedTerminalHistoryRequest {
     endSequence?: number;
     historyGeneration?: number;
     cursor?: string | number;
+    maxBytes?: number;
     signal: AbortSignal;
 }
 export interface PagedTerminalHistoryPage {
@@ -21,6 +22,27 @@ export interface PagedTerminalHistoryPage {
     coveredBytes?: number;
     totalBytes?: number;
 }
+export interface PreparePagedTerminalHistoryOptions {
+    fetchPage(request: PagedTerminalHistoryRequest): Promise<PagedTerminalHistoryPage>;
+    startSequence?: number;
+    maxBytes?: number;
+    signal?: AbortSignal;
+    yieldControl?: () => void | Promise<void>;
+}
+export interface PreparedPagedTerminalHistory {
+    readonly chunks: readonly Readonly<TerminalOutputPipelineChunk>[];
+    readonly requestedStartSequence: number;
+    readonly firstRetainedSequence: number;
+    readonly coveredThroughSequence: number;
+    readonly snapshotEndSequence: number;
+    readonly historyGeneration: number;
+    readonly byteLength: number;
+    readonly pageCount: number;
+    readonly complete: boolean;
+}
+export interface PagedTerminalCompleteAttachOptions {
+    preparedHistory?: PreparedPagedTerminalHistory;
+}
 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 {
@@ -82,6 +104,12 @@ export interface PagedTerminalOutputCoordinatorHandle {
     getSnapshot(): PagedTerminalOutputSnapshot;
     dispose(): void;
 }
-export declare const createPagedTerminalOutputCoordinator: (options: PagedTerminalOutputCoordinatorOptions) => PagedTerminalOutputCoordinatorHandle;
+export interface AtomicPagedTerminalOutputCoordinatorHandle extends PagedTerminalOutputCoordinatorHandle {
+    beginAttach(startSequence?: number): number;
+    completeAttach(attachGeneration: number, snapshotEndSequence?: number, options?: PagedTerminalCompleteAttachOptions): Promise<void>;
+    attach(startSequence?: number, snapshotEndSequence?: number, options?: PagedTerminalCompleteAttachOptions): Promise<void>;
+}
+export declare const preparePagedTerminalHistory: (options: PreparePagedTerminalHistoryOptions) => Promise<PreparedPagedTerminalHistory>;
+export declare const createPagedTerminalOutputCoordinator: (options: PagedTerminalOutputCoordinatorOptions) => AtomicPagedTerminalOutputCoordinatorHandle;
 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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"}