@textmode/runner-client 0.1.0 → 0.2.1

package/README.md

@@ -4,9 +4,8 @@ Browser iframe runtime client for the hosted textmode runner.
 
 This package gives any browser host app a typed runtime API for mounting the
 runner iframe, performing the current generic protocol handshake, routing
-request/response messages, monitoring heartbeat status, loading fonts,
-controlling playback, running code, exporting output, reconnecting, and
-disposing the transport.
+request/response messages, monitoring heartbeat status, running code,
+soft-resetting sketches, reconnecting, and disposing the transport.
 
 It does not execute textmode.js sketches directly. It controls a runner app at
 the `runnerUrl` you provide.
@@ -40,17 +39,9 @@ const runtime = new IframeTextmodeRuntime({
 	onStatusChange(status: RunnerRuntimeStatus, reason) {
 		console.info('runner status changed', status, reason);
 	},
-	onExportProgress(requestId, format, progress) {
-		console.info('export progress', requestId, format, progress);
-	},
 });
 
-await runtime.init(container, {
-	width: 640,
-	height: 640,
-	fontSize: 16,
-	frameRate: 60,
-});
+await runtime.init(container);
 
 try {
 	await runtime.runCode(`
@@ -64,12 +55,7 @@ try {
 	}
 }
 
-const image = await runtime.export('image', {
-	format: 'png',
-	scale: 2,
-});
-
-console.info(image.filename, image.mimeType, image.blob);
+await runtime.runCode('t.frameCount = 0;', { softReset: true });
 runtime.dispose();
 ```
 
@@ -91,7 +77,6 @@ The main exports are:
 - `RunnerRuntimeStatus`
 - `RunnerExecutionError`
 - `RunnerRequestError`
-- `FontLoadResult`
 - `IframeTextmodeRuntimeOptions`
 - `IframeMountMode`
 - `IframeSandboxToken`
@@ -102,9 +87,9 @@ The main exports are:
 Typical host apps follow this lifecycle:
 
 1. Create an `IframeTextmodeRuntime` with a trusted `runnerUrl`.
-2. Call `init(container, settings)` from a browser context.
-3. Use `runCode`, `configure`, `setSettings`, `export`, `loadFont`, and
-   `playback` as needed.
+2. Call `init(container)` from a browser context.
+3. Use `runCode` for normal execution and `runCode(code, { softReset: true })`
+   when the host should reset sketch time before rerunning code.
 4. Call `reconnect` after a recoverable runner failure.
 5. Call `dispose` when the host view is unmounted.
 
@@ -118,8 +103,9 @@ The default iframe sandbox tokens are:
 ['allow-scripts', 'allow-same-origin']
 ```
 
-`allow-downloads` is not included by default. Export downloads should be
-initiated by the host app after it receives an export result from the runner.
+`allow-downloads` is not included by default. Sketches can use the installed
+`textmode.export.js` helpers inside the sandboxed runtime, but the host client
+does not expose a parent-controlled export channel.
 
 The runtime refuses to start a runner that combines `allow-scripts` and
 `allow-same-origin` on the same origin as the parent page.

package/dist/IframeTextmodeRuntime.d.ts

@@ -1,5 +1,4 @@
-import { type ExportMessage, type ExportResultMessage, type GifExportOptions, type ImageExportOptions, type PlaybackAction, type PlaybackState, type RunnerCapabilities, type RuntimeSettings, type SvgExportOptions, type TxtExportOptions, type WebmExportOptions } from '@textmode/runner-protocol';
-import type { FontLoadResult } from './font';
+import { type RunnerCapabilities } from '@textmode/runner-protocol';
 import { type IframeTextmodeRuntimeOptions } from './options';
 import type { RunnerRuntimeStatus } from './status';
 /**
@@ -17,11 +16,11 @@ export declare class IframeTextmodeRuntime {
     private readonly mountMode;
     private readonly pending;
     private readonly heartbeat;
+    private readonly visibility;
     private iframe;
     private channel;
     private port;
     private container;
-    private settings;
     private capabilities;
     private ready;
     private currentStatus;
@@ -64,11 +63,10 @@ export declare class IframeTextmodeRuntime {
      * Mounts the runner iframe and performs the current protocol handshake.
      *
      * @param container - DOM element that should contain the runner iframe.
-     * @param settings - Optional fixed runtime settings to configure after ready.
      * @returns `true` when the runner is ready.
      * @category Runtime
      */
-    init(container: HTMLElement, settings?: RuntimeSettings): Promise<boolean>;
+    init(container: HTMLElement): Promise<boolean>;
     /**
      * Disposes the iframe connection and rejects pending requests.
      *
@@ -90,18 +88,6 @@ export declare class IframeTextmodeRuntime {
      * @category Runtime
      */
     activateFromUserGesture(): void;
-    /**
-     * Configures complete fixed runtime settings.
-     *
-     * @category Runtime
-     */
-    configure(settings: RuntimeSettings): Promise<PlaybackState | null>;
-    /**
-     * Applies a partial runtime settings update.
-     *
-     * @category Runtime
-     */
-    setSettings(settings: Partial<RuntimeSettings>): Promise<PlaybackState | null>;
     /**
      * Executes code in the runner.
      *
@@ -110,57 +96,6 @@ export declare class IframeTextmodeRuntime {
     runCode(code: string, options?: {
         softReset?: boolean;
     }): Promise<boolean>;
-    /**
-     * Exports the current runner output in any supported format.
-     *
-     * @category Exports
-     */
-    export(format: ExportMessage['format'], options?: ImageExportOptions | SvgExportOptions | TxtExportOptions | GifExportOptions | WebmExportOptions, timeoutMs?: number): Promise<ExportResultMessage>;
-    /**
-     * Exports the current runner output as a raster image.
-     *
-     * @category Exports
-     */
-    exportImage(options: ImageExportOptions): Promise<ExportResultMessage>;
-    /**
-     * Exports the current runner output as SVG.
-     *
-     * @category Exports
-     */
-    exportSvg(options: SvgExportOptions): Promise<ExportResultMessage>;
-    /**
-     * Exports the current runner output as plain text.
-     *
-     * @category Exports
-     */
-    exportTxt(options: TxtExportOptions): Promise<ExportResultMessage>;
-    /**
-     * Records an animated GIF export.
-     *
-     * @category Exports
-     */
-    exportGif(options: GifExportOptions): Promise<ExportResultMessage>;
-    /**
-     * Records a WebM export.
-     *
-     * @category Exports
-     */
-    exportWebm(options: WebmExportOptions): Promise<ExportResultMessage>;
-    /**
-     * Loads a font file into the runner.
-     *
-     * @category Fonts
-     */
-    loadFont(file: File): Promise<FontLoadResult>;
-    /**
-     * Sends a playback command and resolves with the resulting playback state.
-     *
-     * @category Playback
-     */
-    playback(action: PlaybackAction, options?: {
-        frame?: number;
-        maxFrames?: number;
-    }): Promise<PlaybackState>;
     private connectPort;
     private handlePortMessage;
     private handleReady;
@@ -169,9 +104,11 @@ export declare class IframeTextmodeRuntime {
     private request;
     private postMessage;
     private handleUnavailable;
+    private forceDisposeFrameForReconnect;
     private validateReadyMessage;
     private assertSandboxOriginPolicy;
     private setStatus;
     private disposeFrame;
+    private rejectPendingHandshake;
     private createRequestId;
 }

package/dist/IframeTextmodeRuntime.js

@@ -6,15 +6,7 @@ import { createRunnerIframe, focusElement, mountRunnerIframe } from './internal/
 import { routeRunnerMessage } from './internal/messageRouter';
 import { RequestRegistry, requestKindForMessage } from './internal/requestRegistry';
 import { assertSandboxOriginPolicy } from './internal/sandboxPolicy';
-const getRuntimeErrorMessage = (error, fallback) => {
-    if (error instanceof Error && error.message) {
-        return error.message;
-    }
-    if (typeof error === 'string' && error.trim()) {
-        return error;
-    }
-    return fallback;
-};
+import { createDocumentVisibilityApi } from './internal/visibility';
 /**
  * Browser iframe runtime for communicating with the hosted textmode runner.
  *
@@ -28,13 +20,13 @@ export class IframeTextmodeRuntime {
     requestTimeoutMs;
     options;
     mountMode;
-    pending = new RequestRegistry();
+    pending;
     heartbeat;
+    visibility;
     iframe = null;
     channel = null;
     port = null;
     container = null;
-    settings = null;
     capabilities = null;
     ready = false;
     currentStatus = 'idle';
@@ -51,9 +43,12 @@ export class IframeTextmodeRuntime {
         this.sandboxTokens = [...(options.sandboxTokens ?? DEFAULT_IFRAME_SANDBOX_TOKENS)];
         this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 12000;
+        this.visibility = createDocumentVisibilityApi();
+        this.pending = new RequestRegistry(undefined, this.visibility);
         this.heartbeat = new HeartbeatController({
             intervalMs: options.heartbeatIntervalMs ?? 2000,
             timeoutMs: options.heartbeatTimeoutMs ?? 10000,
+            visibilityApi: this.visibility,
             onPing: () => {
                 this.postMessage({
                     type: 'PING',
@@ -109,20 +104,16 @@ export class IframeTextmodeRuntime {
      * Mounts the runner iframe and performs the current protocol handshake.
      *
      * @param container - DOM element that should contain the runner iframe.
-     * @param settings - Optional fixed runtime settings to configure after ready.
      * @returns `true` when the runner is ready.
      * @category Runtime
      */
-    async init(container, settings) {
+    async init(container) {
         this.container = container;
-        this.settings = settings ? { ...settings } : null;
         this.assertSandboxOriginPolicy();
         if (this.isReady && this.iframe?.isConnected) {
-            if (settings) {
-                await this.configure(settings);
-            }
             return true;
         }
+        this.rejectPendingHandshake('runner initialization superseded');
         this.disposeFrame();
         this.ready = false;
         this.setStatus('connecting');
@@ -139,6 +130,8 @@ export class IframeTextmodeRuntime {
             }, this.handshakeTimeoutMs);
         });
         iframe.addEventListener('load', () => {
+            if (this.iframe !== iframe)
+                return;
             this.connectPort();
         }, { once: true });
         return readyPromise;
@@ -159,6 +152,7 @@ export class IframeTextmodeRuntime {
         }
         this.pending.rejectAll(new Error('runner disposed'));
         this.heartbeat.stop();
+        this.rejectPendingHandshake('runner disposed');
         this.disposeFrame();
         this.ready = false;
         this.setStatus('idle');
@@ -177,7 +171,8 @@ export class IframeTextmodeRuntime {
         }
         const code = this.lastRequestedCode;
         this.setStatus('recovering');
-        const initialized = await this.init(this.container, this.settings ?? undefined);
+        this.forceDisposeFrameForReconnect();
+        const initialized = await this.init(this.container);
         if (initialized && code) {
             void this.runCode(code);
         }
@@ -202,42 +197,6 @@ export class IframeTextmodeRuntime {
             // Element focus still helps browsers that gate iframe animation cadence.
         }
     }
-    /**
-     * Configures complete fixed runtime settings.
-     *
-     * @category Runtime
-     */
-    async configure(settings) {
-        this.settings = { ...settings };
-        const wasReady = this.ready;
-        this.setStatus('configuring');
-        return this.request({
-            type: 'CONFIGURE_RUNTIME',
-            requestId: this.createRequestId('settings'),
-            settings,
-        }).then((message) => {
-            if (wasReady) {
-                this.setStatus('ready');
-            }
-            return message.state;
-        });
-    }
-    /**
-     * Applies a partial runtime settings update.
-     *
-     * @category Runtime
-     */
-    async setSettings(settings) {
-        this.settings = {
-            ...(this.settings ?? settings),
-            ...settings,
-        };
-        return this.request({
-            type: 'SET_SETTINGS',
-            requestId: this.createRequestId('settings'),
-            settings,
-        }).then((message) => message.state);
-    }
     /**
      * Executes code in the runner.
      *
@@ -252,95 +211,6 @@ export class IframeTextmodeRuntime {
         await this.request(message);
         return true;
     }
-    /**
-     * Exports the current runner output in any supported format.
-     *
-     * @category Exports
-     */
-    async export(format, options, timeoutMs) {
-        const message = {
-            type: 'EXPORT',
-            requestId: this.createRequestId('export'),
-            format,
-            options,
-        };
-        return this.request(message, timeoutMs);
-    }
-    /**
-     * Exports the current runner output as a raster image.
-     *
-     * @category Exports
-     */
-    async exportImage(options) {
-        return this.export('image', options);
-    }
-    /**
-     * Exports the current runner output as SVG.
-     *
-     * @category Exports
-     */
-    async exportSvg(options) {
-        return this.export('svg', options);
-    }
-    /**
-     * Exports the current runner output as plain text.
-     *
-     * @category Exports
-     */
-    async exportTxt(options) {
-        return this.export('txt', options);
-    }
-    /**
-     * Records an animated GIF export.
-     *
-     * @category Exports
-     */
-    async exportGif(options) {
-        return this.export('gif', options, Math.max(this.requestTimeoutMs, 120000));
-    }
-    /**
-     * Records a WebM export.
-     *
-     * @category Exports
-     */
-    async exportWebm(options) {
-        return this.export('webm', options, Math.max(this.requestTimeoutMs, 120000));
-    }
-    /**
-     * Loads a font file into the runner.
-     *
-     * @category Fonts
-     */
-    async loadFont(file) {
-        const requestId = this.createRequestId('font');
-        const buffer = await file.arrayBuffer();
-        const message = {
-            type: 'LOAD_FONT',
-            requestId,
-            fileName: file.name,
-            mimeType: file.type || undefined,
-            buffer,
-        };
-        return this.request(message, undefined, [buffer]).then((result) => ({
-            familyName: result.familyName,
-            characters: result.characters,
-        }));
-    }
-    /**
-     * Sends a playback command and resolves with the resulting playback state.
-     *
-     * @category Playback
-     */
-    async playback(action, options = {}) {
-        const message = {
-            type: 'PLAYBACK',
-            requestId: this.createRequestId('playback'),
-            action,
-            frame: options.frame,
-            maxFrames: options.maxFrames,
-        };
-        return this.request(message).then((result) => result.state);
-    }
     connectPort() {
         if (!this.iframe?.contentWindow) {
             this.handleUnavailable('runner frame is unavailable');
@@ -361,8 +231,10 @@ export class IframeTextmodeRuntime {
         routeRunnerMessage(message, {
             onReady: (readyMessage) => this.handleReady(readyMessage),
             onRunOk: (runOkMessage) => {
-                this.pending.resolve(runOkMessage.requestId, runOkMessage);
-                this.options.onRunOk?.(runOkMessage);
+                const resolved = this.pending.resolve(runOkMessage.requestId, runOkMessage);
+                if (!runOkMessage.requestId || resolved) {
+                    this.options.onRunOk?.(runOkMessage);
+                }
             },
             onRunError: (runErrorMessage) => this.handleRunError(runErrorMessage),
             onSynthError: (synthErrorMessage) => {
@@ -374,24 +246,6 @@ export class IframeTextmodeRuntime {
             onUserInteraction: () => {
                 this.options.onUserInteraction?.();
             },
-            onExportProgress: (exportProgressMessage) => {
-                this.options.onExportProgress?.(exportProgressMessage.requestId, exportProgressMessage.format, exportProgressMessage.progress);
-            },
-            onExportResult: (exportResultMessage) => {
-                this.pending.resolve(exportResultMessage.requestId, exportResultMessage);
-            },
-            onFontLoaded: (fontLoadedMessage) => {
-                this.pending.resolve(fontLoadedMessage.requestId, fontLoadedMessage);
-            },
-            onFontError: (fontErrorMessage) => {
-                this.pending.reject(fontErrorMessage.requestId, new Error(fontErrorMessage.message));
-            },
-            onPlaybackState: (playbackStateMessage) => {
-                this.options.onPlaybackState?.(playbackStateMessage.state);
-                if (playbackStateMessage.requestId) {
-                    this.pending.resolve(playbackStateMessage.requestId, playbackStateMessage);
-                }
-            },
             onPong: () => {
                 this.heartbeat.markPong();
             },
@@ -409,23 +263,7 @@ export class IframeTextmodeRuntime {
             this.readyTimeoutId = null;
         }
         this.options.onConnected?.();
-        const settings = this.settings;
-        if (settings) {
-            void this.configure(settings)
-                .then(() => {
-                this.markReady();
-            })
-                .catch((error) => {
-                this.ready = false;
-                this.setStatus('unavailable', getRuntimeErrorMessage(error, 'runner configuration failed'));
-                this.readyRejecter?.(error);
-                this.readyResolver = null;
-                this.readyRejecter = null;
-            });
-        }
-        else {
-            this.markReady();
-        }
+        this.markReady();
     }
     markReady() {
         this.ready = true;
@@ -449,37 +287,36 @@ export class IframeTextmodeRuntime {
             column: message.column,
         });
     }
-    request(message, timeoutMs = this.requestTimeoutMs, transfer) {
-        if (!this.port || (!this.ready && message.type !== 'CONFIGURE_RUNTIME')) {
+    request(message, timeoutMs = this.requestTimeoutMs) {
+        if (!this.port || !this.ready) {
             return Promise.reject(new Error('runner is not ready'));
         }
         const requestId = 'requestId' in message ? message.requestId : undefined;
         if (!requestId) {
-            this.postMessage(message, transfer);
+            this.postMessage(message);
             return Promise.resolve(undefined);
         }
+        const kind = requestKindForMessage(message.type);
         const promise = this.pending.register({
             requestId,
-            kind: requestKindForMessage(message.type),
+            kind,
             messageType: message.type,
             timeoutMs,
             onTimeout: (error) => {
+                if (kind === 'run') {
+                    return;
+                }
                 this.handleUnavailable(error.message);
             },
         });
-        this.postMessage(message, transfer);
+        this.postMessage(message);
         return promise;
     }
-    postMessage(message, transfer) {
+    postMessage(message) {
         if (!this.port) {
             throw new Error('runner port is not connected');
         }
-        if (transfer && transfer.length > 0) {
-            this.port.postMessage(message, transfer);
-        }
-        else {
-            this.port.postMessage(message);
-        }
+        this.port.postMessage(message);
     }
     handleUnavailable(reason) {
         const error = new Error(reason);
@@ -490,17 +327,32 @@ export class IframeTextmodeRuntime {
         this.readyResolver = null;
         this.readyRejecter = null;
         this.disposeFrame();
-        const status = reason.includes('heartbeat') ? 'hung' : 'unavailable';
+        const status = reason === 'runner heartbeat timed out' ? 'hung' : 'unavailable';
         this.setStatus(status, reason);
         this.options.onUnavailable?.(reason, status);
     }
+    forceDisposeFrameForReconnect() {
+        if (this.port) {
+            try {
+                this.postMessage({ type: 'DISPOSE' });
+            }
+            catch {
+                // The existing connection may already be unavailable.
+            }
+        }
+        this.heartbeat.stop();
+        this.pending.rejectAll(new Error('runner reconnecting'));
+        this.rejectPendingHandshake('runner reconnecting');
+        this.ready = false;
+        this.disposeFrame();
+    }
     validateReadyMessage(message) {
         const capabilities = message.capabilities;
         if (!isRunnerCapabilities(capabilities)) {
             return 'runner did not advertise a valid current capability set';
         }
-        if (!capabilities.runtimeConfig) {
-            return 'runner does not support runtime configuration';
+        if (!capabilities.heartbeat) {
+            return 'runner does not support heartbeat monitoring';
         }
         return null;
     }
@@ -533,6 +385,18 @@ export class IframeTextmodeRuntime {
             this.iframe = null;
         }
     }
+    rejectPendingHandshake(reason) {
+        if (!this.readyRejecter && !this.readyResolver) {
+            return;
+        }
+        if (this.readyTimeoutId !== null) {
+            window.clearTimeout(this.readyTimeoutId);
+            this.readyTimeoutId = null;
+        }
+        this.readyRejecter?.(new Error(reason));
+        this.readyResolver = null;
+        this.readyRejecter = null;
+    }
     createRequestId(prefix) {
         return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
     }

package/dist/index.d.ts

@@ -4,14 +4,12 @@
  * Browser iframe runtime client for the hosted textmode runner.
  *
  * `@textmode/runner-client` manages the runner iframe lifecycle, current
- * protocol handshake, request/response routing, heartbeat monitoring, export
- * helpers, font loading, playback control, reconnect, and disposal for host
- * apps.
+ * protocol handshake, request/response routing, heartbeat monitoring, reconnect,
+ * and disposal for host apps.
  *
  * @module @textmode/runner-client
  */
 export { IframeTextmodeRuntime } from './IframeTextmodeRuntime';
 export { RunnerRequestError, type RunnerExecutionError } from './errors';
-export { type FontLoadResult } from './font';
 export { DEFAULT_IFRAME_SANDBOX_TOKENS, type IframeMountMode, type IframeSandboxToken, type IframeTextmodeRuntimeOptions, } from './options';
 export { type RunnerRuntimeStatus } from './status';

package/dist/index.js

@@ -4,9 +4,8 @@
  * Browser iframe runtime client for the hosted textmode runner.
  *
  * `@textmode/runner-client` manages the runner iframe lifecycle, current
- * protocol handshake, request/response routing, heartbeat monitoring, export
- * helpers, font loading, playback control, reconnect, and disposal for host
- * apps.
+ * protocol handshake, request/response routing, heartbeat monitoring, reconnect,
+ * and disposal for host apps.
  *
  * @module @textmode/runner-client
  */

package/dist/internal/heartbeat.d.ts

@@ -1,3 +1,4 @@
+import { type PageVisibilityApi } from './visibility';
 export interface HeartbeatTimerApi {
     setInterval: (handler: () => void, intervalMs: number) => number;
     clearInterval: (intervalId: number) => void;
@@ -7,6 +8,7 @@ export interface HeartbeatControllerOptions {
     timeoutMs: number;
     now?: () => number;
     timerApi?: HeartbeatTimerApi;
+    visibilityApi?: PageVisibilityApi;
     onPing: () => void;
     onTimeout: () => void;
 }
@@ -15,12 +17,18 @@ export declare class HeartbeatController {
     private readonly timeoutMs;
     private readonly now;
     private readonly timerApi;
+    private readonly visibilityApi;
     private readonly onPing;
     private readonly onTimeout;
     private intervalId;
+    private cleanupVisibility;
+    private isActive;
     private lastPongAt;
     constructor(options: HeartbeatControllerOptions);
     start(): void;
     stop(): void;
     markPong(): void;
+    private readonly handleVisibilityChange;
+    private startInterval;
+    private stopInterval;
 }

package/dist/internal/heartbeat.js

@@ -1,24 +1,61 @@
+import { createDocumentVisibilityApi, isPageVisible } from './visibility';
 export class HeartbeatController {
     intervalMs;
     timeoutMs;
     now;
     timerApi;
+    visibilityApi;
     onPing;
     onTimeout;
     intervalId = null;
+    cleanupVisibility = null;
+    isActive = false;
     lastPongAt = 0;
     constructor(options) {
         this.intervalMs = options.intervalMs;
         this.timeoutMs = options.timeoutMs;
         this.now = options.now ?? Date.now;
         this.timerApi = options.timerApi ?? createWindowTimerApi();
+        this.visibilityApi = options.visibilityApi ?? createDocumentVisibilityApi();
         this.onPing = options.onPing;
         this.onTimeout = options.onTimeout;
     }
     start() {
         this.stop();
+        this.isActive = true;
         this.lastPongAt = this.now();
+        this.cleanupVisibility = this.visibilityApi.addChangeListener(this.handleVisibilityChange);
+        if (isPageVisible(this.visibilityApi)) {
+            this.startInterval();
+        }
+    }
+    stop() {
+        this.isActive = false;
+        this.stopInterval();
+        this.cleanupVisibility?.();
+        this.cleanupVisibility = null;
+    }
+    markPong() {
+        this.lastPongAt = this.now();
+    }
+    handleVisibilityChange = () => {
+        if (!this.isActive)
+            return;
+        if (!isPageVisible(this.visibilityApi)) {
+            this.stopInterval();
+            return;
+        }
+        this.lastPongAt = this.now();
+        this.startInterval();
+    };
+    startInterval() {
+        if (this.intervalId !== null)
+            return;
         this.intervalId = this.timerApi.setInterval(() => {
+            if (!isPageVisible(this.visibilityApi)) {
+                this.stopInterval();
+                return;
+            }
             if (this.now() - this.lastPongAt > this.timeoutMs) {
                 this.onTimeout();
                 return;
@@ -26,15 +63,12 @@ export class HeartbeatController {
             this.onPing();
         }, this.intervalMs);
     }
-    stop() {
+    stopInterval() {
         if (this.intervalId !== null) {
             this.timerApi.clearInterval(this.intervalId);
             this.intervalId = null;
         }
     }
-    markPong() {
-        this.lastPongAt = this.now();
-    }
 }
 function createWindowTimerApi() {
     return {

package/dist/internal/messageRouter.d.ts

@@ -1,4 +1,4 @@
-import { type ExportProgressMessage, type ExportResultMessage, type FontErrorMessage, type FontLoadedMessage, type PlaybackStateMessage, type PongMessage, type ReadyMessage, type RunErrorMessage, type RunOkMessage, type SynthErrorMessage } from '@textmode/runner-protocol';
+import { type PongMessage, type ReadyMessage, type RunErrorMessage, type RunOkMessage, type SynthErrorMessage } from '@textmode/runner-protocol';
 export interface RunnerMessageHandlers {
     onReady: (message: ReadyMessage) => void;
     onRunOk: (message: RunOkMessage) => void;
@@ -6,11 +6,6 @@ export interface RunnerMessageHandlers {
     onSynthError: (message: SynthErrorMessage) => void;
     onToggleUI: () => void;
     onUserInteraction: () => void;
-    onExportProgress: (message: ExportProgressMessage) => void;
-    onExportResult: (message: ExportResultMessage) => void;
-    onFontLoaded: (message: FontLoadedMessage) => void;
-    onFontError: (message: FontErrorMessage) => void;
-    onPlaybackState: (message: PlaybackStateMessage) => void;
     onPong: (message: PongMessage) => void;
 }
 export declare function routeRunnerMessage(message: unknown, handlers: RunnerMessageHandlers): boolean;

package/dist/internal/messageRouter.js

@@ -22,21 +22,6 @@ export function routeRunnerMessage(message, handlers) {
         case 'USER_INTERACTION':
             handlers.onUserInteraction();
             break;
-        case 'EXPORT_PROGRESS':
-            handlers.onExportProgress(message);
-            break;
-        case 'EXPORT_RESULT':
-            handlers.onExportResult(message);
-            break;
-        case 'FONT_LOADED':
-            handlers.onFontLoaded(message);
-            break;
-        case 'FONT_ERROR':
-            handlers.onFontError(message);
-            break;
-        case 'PLAYBACK_STATE':
-            handlers.onPlaybackState(message);
-            break;
         case 'PONG':
             handlers.onPong(message);
             break;

package/dist/internal/requestRegistry.d.ts

@@ -1,8 +1,10 @@
 import type { ParentToRunnerMessage } from '@textmode/runner-protocol';
-export type RequestKind = 'run' | 'export' | 'font' | 'playback' | 'settings';
+import { type PageVisibilityApi } from './visibility';
+export type RequestKind = 'run' | 'lifecycle';
 export interface RequestTimerApi {
     setTimeout: (handler: () => void, timeoutMs: number) => number;
     clearTimeout: (timeoutId: number) => void;
+    now: () => number;
 }
 interface RegisterRequestOptions {
     requestId: string;
@@ -14,7 +16,8 @@ interface RegisterRequestOptions {
 export declare class RequestRegistry {
     private readonly pending;
     private readonly timerApi;
-    constructor(timerApi?: RequestTimerApi);
+    private readonly visibilityApi;
+    constructor(timerApi?: RequestTimerApi, visibilityApi?: PageVisibilityApi);
     get size(): number;
     register<T>(options: RegisterRequestOptions): Promise<T>;
     resolve(requestId: string | undefined, value: unknown): boolean;

package/dist/internal/requestRegistry.js

@@ -1,25 +1,75 @@
+import { createDocumentVisibilityApi, isPageVisible } from './visibility';
 export class RequestRegistry {
     pending = new Map();
     timerApi;
-    constructor(timerApi = createWindowTimerApi()) {
+    visibilityApi;
+    constructor(timerApi = createWindowTimerApi(), visibilityApi = createDocumentVisibilityApi()) {
         this.timerApi = timerApi;
+        this.visibilityApi = visibilityApi;
     }
     get size() {
         return this.pending.size;
     }
     register(options) {
         return new Promise((resolve, reject) => {
-            const timeoutId = this.timerApi.setTimeout(() => {
+            let remainingMs = options.timeoutMs;
+            let timeoutId = null;
+            let startedAt = this.timerApi.now();
+            const timerApi = this.timerApi;
+            let cleanupVisibility = () => { };
+            function pauseTimer() {
+                if (timeoutId === null)
+                    return;
+                const elapsedMs = Math.max(0, timerApi.now() - startedAt);
+                remainingMs = Math.max(0, remainingMs - elapsedMs);
+                timerApi.clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            const cleanup = () => {
+                if (timeoutId !== null) {
+                    timerApi.clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                cleanupVisibility();
+            };
+            const rejectTimedOut = () => {
+                cleanup();
                 this.pending.delete(options.requestId);
                 const error = new Error(`runner request timed out: ${options.messageType}`);
                 reject(error);
                 options.onTimeout(error);
-            }, options.timeoutMs);
+            };
+            const scheduleTimer = () => {
+                startedAt = timerApi.now();
+                timeoutId = timerApi.setTimeout(() => {
+                    timeoutId = null;
+                    if (!isPageVisible(this.visibilityApi)) {
+                        remainingMs = 0;
+                        return;
+                    }
+                    rejectTimedOut();
+                }, Math.max(0, remainingMs));
+            };
+            function resumeTimer() {
+                if (timeoutId !== null)
+                    return;
+                scheduleTimer();
+            }
+            cleanupVisibility = this.visibilityApi.addChangeListener(() => {
+                if (isPageVisible(this.visibilityApi)) {
+                    resumeTimer();
+                    return;
+                }
+                pauseTimer();
+            });
+            if (isPageVisible(this.visibilityApi)) {
+                scheduleTimer();
+            }
             this.pending.set(options.requestId, {
                 kind: options.kind,
                 resolve: resolve,
                 reject,
-                timeoutId,
+                cleanup,
             });
         });
     }
@@ -29,7 +79,7 @@ export class RequestRegistry {
         const pending = this.pending.get(requestId);
         if (!pending)
             return false;
-        this.timerApi.clearTimeout(pending.timeoutId);
+        pending.cleanup();
         this.pending.delete(requestId);
         pending.resolve(value);
         return true;
@@ -38,14 +88,14 @@ export class RequestRegistry {
         const pending = this.pending.get(requestId);
         if (!pending)
             return false;
-        this.timerApi.clearTimeout(pending.timeoutId);
+        pending.cleanup();
         this.pending.delete(requestId);
         pending.reject(error);
         return true;
     }
     rejectAll(error) {
         for (const [requestId, pending] of this.pending) {
-            this.timerApi.clearTimeout(pending.timeoutId);
+            pending.cleanup();
             pending.reject(error);
             this.pending.delete(requestId);
         }
@@ -56,22 +106,15 @@ export function requestKindForMessage(type) {
         case 'RUN_CODE':
         case 'SOFT_RESET':
             return 'run';
-        case 'EXPORT':
-            return 'export';
-        case 'LOAD_FONT':
-            return 'font';
-        case 'PLAYBACK':
-            return 'playback';
-        case 'CONFIGURE_RUNTIME':
-        case 'SET_SETTINGS':
         case 'PING':
         case 'DISPOSE':
-            return 'settings';
+            return 'lifecycle';
     }
 }
 function createWindowTimerApi() {
     return {
         setTimeout: (handler, timeoutMs) => window.setTimeout(handler, timeoutMs),
         clearTimeout: (timeoutId) => window.clearTimeout(timeoutId),
+        now: () => Date.now(),
     };
 }

package/dist/internal/visibility.d.ts

@@ -0,0 +1,6 @@
+export interface PageVisibilityApi {
+    getState: () => string;
+    addChangeListener: (listener: () => void) => () => void;
+}
+export declare function isPageVisible(visibility: PageVisibilityApi): boolean;
+export declare function createDocumentVisibilityApi(): PageVisibilityApi;

package/dist/internal/visibility.js

@@ -0,0 +1,65 @@
+export function isPageVisible(visibility) {
+    return visibility.getState() === 'visible';
+}
+export function createDocumentVisibilityApi() {
+    const listeners = new Set();
+    let forcedHidden = false;
+    const notify = () => {
+        for (const listener of listeners) {
+            listener();
+        }
+    };
+    const getState = () => {
+        if (forcedHidden)
+            return 'hidden';
+        const documentState = getDocument()?.visibilityState;
+        return typeof documentState === 'string' ? documentState : 'visible';
+    };
+    const addChangeListener = (listener) => {
+        listeners.add(listener);
+        if (listeners.size === 1) {
+            attachGlobalListeners();
+        }
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0) {
+                detachGlobalListeners();
+            }
+        };
+    };
+    const handleVisibilityChange = () => {
+        notify();
+    };
+    const handlePageHide = () => {
+        forcedHidden = true;
+        notify();
+    };
+    const handlePageShow = () => {
+        forcedHidden = false;
+        notify();
+    };
+    const attachGlobalListeners = () => {
+        getDocument()?.addEventListener?.('visibilitychange', handleVisibilityChange);
+        getDocument()?.addEventListener?.('freeze', handlePageHide);
+        getDocument()?.addEventListener?.('resume', handlePageShow);
+        getWindow()?.addEventListener?.('pagehide', handlePageHide);
+        getWindow()?.addEventListener?.('pageshow', handlePageShow);
+    };
+    const detachGlobalListeners = () => {
+        getDocument()?.removeEventListener?.('visibilitychange', handleVisibilityChange);
+        getDocument()?.removeEventListener?.('freeze', handlePageHide);
+        getDocument()?.removeEventListener?.('resume', handlePageShow);
+        getWindow()?.removeEventListener?.('pagehide', handlePageHide);
+        getWindow()?.removeEventListener?.('pageshow', handlePageShow);
+    };
+    return {
+        getState,
+        addChangeListener,
+    };
+}
+function getDocument() {
+    return typeof document === 'undefined' ? null : document;
+}
+function getWindow() {
+    return typeof window === 'undefined' ? null : window;
+}

package/dist/options.d.ts

@@ -1,4 +1,4 @@
-import type { ExportProgress, PlaybackState, RunnerCapabilities, RunOkMessage } from '@textmode/runner-protocol';
+import type { RunnerCapabilities, RunOkMessage } from '@textmode/runner-protocol';
 import type { RunnerExecutionError } from './errors';
 import type { RunnerRuntimeStatus } from './status';
 /**
@@ -42,7 +42,7 @@ export interface IframeTextmodeRuntimeOptions {
     heartbeatIntervalMs?: number;
     /** Maximum time without a heartbeat pong before the runner is marked hung. */
     heartbeatTimeoutMs?: number;
-    /** Called after the runner is ready and optional runtime configuration succeeds. */
+    /** Called after the runner is ready. */
     onReady?: (capabilities: RunnerCapabilities) => void;
     /** Called when code execution succeeds. */
     onRunOk?: (message: RunOkMessage) => void;
@@ -54,10 +54,6 @@ export interface IframeTextmodeRuntimeOptions {
     onToggleUI?: () => void;
     /** Called when the runner reports user interaction. */
     onUserInteraction?: () => void;
-    /** Called as multi-frame exports report progress. */
-    onExportProgress?: (requestId: string, format: 'gif' | 'webm', progress: ExportProgress) => void;
-    /** Called whenever the runner reports playback state. */
-    onPlaybackState?: (state: PlaybackState) => void;
     /** Called when the runner becomes unavailable or hung. */
     onUnavailable?: (reason: string, status: RunnerRuntimeStatus) => void;
     /** Called after the MessagePort connection is established. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@textmode/runner-client",
-    "version": "0.1.0",
+    "version": "0.2.1",
     "description": "Browser iframe runtime client for the hosted textmode runner.",
     "license": "AGPL-3.0-or-later",
     "type": "module",
@@ -30,6 +30,6 @@
         "prepare": "npm run build"
     },
     "dependencies": {
-        "@textmode/runner-protocol": "^0.1.0"
+        "@textmode/runner-protocol": "^0.2.0"
     }
 }

package/dist/font.d.ts

@@ -1,11 +0,0 @@
-/**
- * Metadata returned after the runner successfully loads a font file.
- *
- * @category Fonts
- */
-export interface FontLoadResult {
-    /** Font family name detected by the runner. */
-    familyName: string | null;
-    /** Characters available in the loaded font. */
-    characters: string[];
-}

package/dist/font.js

@@ -1 +0,0 @@
-export {};