@textmode/runner-client 0.1.0

package/dist/IframeTextmodeRuntime.js

@@ -0,0 +1,539 @@
+import { isRunnerCapabilities, } from '@textmode/runner-protocol';
+import { RunnerRequestError } from './errors';
+import { DEFAULT_IFRAME_SANDBOX_TOKENS, } from './options';
+import { HeartbeatController } from './internal/heartbeat';
+import { createRunnerIframe, focusElement, mountRunnerIframe } from './internal/iframeMount';
+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;
+};
+/**
+ * Browser iframe runtime for communicating with the hosted textmode runner.
+ *
+ * @category Runtime
+ */
+export class IframeTextmodeRuntime {
+    runnerHref;
+    runnerOrigin;
+    sandboxTokens;
+    handshakeTimeoutMs;
+    requestTimeoutMs;
+    options;
+    mountMode;
+    pending = new RequestRegistry();
+    heartbeat;
+    iframe = null;
+    channel = null;
+    port = null;
+    container = null;
+    settings = null;
+    capabilities = null;
+    ready = false;
+    currentStatus = 'idle';
+    readyResolver = null;
+    readyRejecter = null;
+    readyTimeoutId = null;
+    lastRequestedCode = null;
+    constructor(options) {
+        this.options = options;
+        this.mountMode = options.mountMode ?? 'replace';
+        const runnerLocation = new URL(options.runnerUrl, window.location.href);
+        this.runnerHref = runnerLocation.href;
+        this.runnerOrigin = runnerLocation.origin;
+        this.sandboxTokens = [...(options.sandboxTokens ?? DEFAULT_IFRAME_SANDBOX_TOKENS)];
+        this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 12000;
+        this.heartbeat = new HeartbeatController({
+            intervalMs: options.heartbeatIntervalMs ?? 2000,
+            timeoutMs: options.heartbeatTimeoutMs ?? 10000,
+            onPing: () => {
+                this.postMessage({
+                    type: 'PING',
+                    nonce: this.createRequestId('ping'),
+                });
+            },
+            onTimeout: () => {
+                this.handleUnavailable('runner heartbeat timed out');
+            },
+        });
+    }
+    /**
+     * Whether the runner iframe is ready to accept requests.
+     *
+     * @category Runtime
+     */
+    get isReady() {
+        return this.ready && this.currentStatus === 'ready';
+    }
+    /**
+     * Current runner iframe element, when mounted.
+     *
+     * @category Runtime
+     */
+    get frame() {
+        return this.iframe;
+    }
+    /**
+     * Current runner lifecycle status.
+     *
+     * @category Runtime
+     */
+    get status() {
+        return this.currentStatus;
+    }
+    /**
+     * Alias for {@link IframeTextmodeRuntime.status}.
+     *
+     * @category Runtime
+     */
+    get runnerStatus() {
+        return this.currentStatus;
+    }
+    /**
+     * Capabilities advertised by the connected runner.
+     *
+     * @category Runtime
+     */
+    get advertisedCapabilities() {
+        return this.capabilities;
+    }
+    /**
+     * 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) {
+        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.disposeFrame();
+        this.ready = false;
+        this.setStatus('connecting');
+        const iframe = createRunnerIframe(this.runnerHref, this.sandboxTokens);
+        this.iframe = iframe;
+        mountRunnerIframe(container, iframe, this.mountMode);
+        const readyPromise = new Promise((resolve, reject) => {
+            this.readyResolver = resolve;
+            this.readyRejecter = reject;
+            this.readyTimeoutId = window.setTimeout(() => {
+                const error = new Error('runner handshake timed out');
+                this.handleUnavailable(error.message);
+                reject(error);
+            }, this.handshakeTimeoutMs);
+        });
+        iframe.addEventListener('load', () => {
+            this.connectPort();
+        }, { once: true });
+        return readyPromise;
+    }
+    /**
+     * Disposes the iframe connection and rejects pending requests.
+     *
+     * @category Runtime
+     */
+    dispose() {
+        if (this.port) {
+            try {
+                this.postMessage({ type: 'DISPOSE' });
+            }
+            catch {
+                // The connection may already be gone during page teardown.
+            }
+        }
+        this.pending.rejectAll(new Error('runner disposed'));
+        this.heartbeat.stop();
+        this.disposeFrame();
+        this.ready = false;
+        this.setStatus('idle');
+        this.readyResolver = null;
+        this.readyRejecter = null;
+    }
+    /**
+     * Recreates the iframe and reruns the last requested code when available.
+     *
+     * @returns `true` when reconnection succeeds.
+     * @category Runtime
+     */
+    async reconnect() {
+        if (!this.container) {
+            return false;
+        }
+        const code = this.lastRequestedCode;
+        this.setStatus('recovering');
+        const initialized = await this.init(this.container, this.settings ?? undefined);
+        if (initialized && code) {
+            void this.runCode(code);
+        }
+        return initialized;
+    }
+    /**
+     * Focuses the iframe from a host user gesture.
+     *
+     * Some browsers use this to unlock normal iframe animation cadence.
+     *
+     * @category Runtime
+     */
+    activateFromUserGesture() {
+        if (!this.iframe)
+            return;
+        this.iframe.tabIndex = -1;
+        focusElement(this.iframe);
+        try {
+            this.iframe.contentWindow?.focus();
+        }
+        catch {
+            // 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.
+     *
+     * @category Runtime
+     */
+    async runCode(code, options = {}) {
+        this.lastRequestedCode = code;
+        const requestId = this.createRequestId('run');
+        const message = options.softReset
+            ? { type: 'SOFT_RESET', requestId, code }
+            : { type: 'RUN_CODE', requestId, code };
+        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');
+            return;
+        }
+        this.channel = new MessageChannel();
+        this.port = this.channel.port1;
+        this.port.onmessage = (event) => {
+            this.handlePortMessage(event.data);
+        };
+        this.port.start();
+        const initMessage = {
+            type: 'INIT',
+        };
+        this.iframe.contentWindow.postMessage(initMessage, this.runnerOrigin, [this.channel.port2]);
+    }
+    handlePortMessage(message) {
+        routeRunnerMessage(message, {
+            onReady: (readyMessage) => this.handleReady(readyMessage),
+            onRunOk: (runOkMessage) => {
+                this.pending.resolve(runOkMessage.requestId, runOkMessage);
+                this.options.onRunOk?.(runOkMessage);
+            },
+            onRunError: (runErrorMessage) => this.handleRunError(runErrorMessage),
+            onSynthError: (synthErrorMessage) => {
+                this.options.onSynthError?.(synthErrorMessage.message);
+            },
+            onToggleUI: () => {
+                this.options.onToggleUI?.();
+            },
+            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();
+            },
+        });
+    }
+    handleReady(message) {
+        const protocolError = this.validateReadyMessage(message);
+        if (protocolError) {
+            this.handleUnavailable(protocolError);
+            return;
+        }
+        this.capabilities = message.capabilities;
+        if (this.readyTimeoutId !== null) {
+            window.clearTimeout(this.readyTimeoutId);
+            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();
+        }
+    }
+    markReady() {
+        this.ready = true;
+        this.setStatus('ready');
+        this.options.onReady?.(this.capabilities);
+        this.heartbeat.start();
+        this.readyResolver?.(true);
+        this.readyResolver = null;
+        this.readyRejecter = null;
+    }
+    handleRunError(message) {
+        const error = new RunnerRequestError(message);
+        if (message.requestId) {
+            this.pending.reject(message.requestId, error);
+            return;
+        }
+        this.options.onRunError?.({
+            message: message.message,
+            stack: message.stack,
+            line: message.line,
+            column: message.column,
+        });
+    }
+    request(message, timeoutMs = this.requestTimeoutMs, transfer) {
+        if (!this.port || (!this.ready && message.type !== 'CONFIGURE_RUNTIME')) {
+            return Promise.reject(new Error('runner is not ready'));
+        }
+        const requestId = 'requestId' in message ? message.requestId : undefined;
+        if (!requestId) {
+            this.postMessage(message, transfer);
+            return Promise.resolve(undefined);
+        }
+        const promise = this.pending.register({
+            requestId,
+            kind: requestKindForMessage(message.type),
+            messageType: message.type,
+            timeoutMs,
+            onTimeout: (error) => {
+                this.handleUnavailable(error.message);
+            },
+        });
+        this.postMessage(message, transfer);
+        return promise;
+    }
+    postMessage(message, transfer) {
+        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);
+        }
+    }
+    handleUnavailable(reason) {
+        const error = new Error(reason);
+        this.heartbeat.stop();
+        this.ready = false;
+        this.pending.rejectAll(error);
+        this.readyRejecter?.(error);
+        this.readyResolver = null;
+        this.readyRejecter = null;
+        this.disposeFrame();
+        const status = reason.includes('heartbeat') ? 'hung' : 'unavailable';
+        this.setStatus(status, reason);
+        this.options.onUnavailable?.(reason, status);
+    }
+    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';
+        }
+        return null;
+    }
+    assertSandboxOriginPolicy() {
+        assertSandboxOriginPolicy({
+            sandboxTokens: this.sandboxTokens,
+            runnerOrigin: this.runnerOrigin,
+            parentOrigin: window.location.origin,
+        });
+    }
+    setStatus(status, reason = null) {
+        if (this.currentStatus === status && !reason) {
+            return;
+        }
+        this.currentStatus = status;
+        this.options.onStatusChange?.(status, reason);
+    }
+    disposeFrame() {
+        if (this.readyTimeoutId !== null) {
+            window.clearTimeout(this.readyTimeoutId);
+            this.readyTimeoutId = null;
+        }
+        this.port?.close();
+        this.channel?.port1.close();
+        this.channel?.port2.close();
+        this.port = null;
+        this.channel = null;
+        if (this.iframe) {
+            this.iframe.remove();
+            this.iframe = null;
+        }
+    }
+    createRequestId(prefix) {
+        return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+import type { RunErrorMessage } from '@textmode/runner-protocol';
+/**
+ * Error shape surfaced by runner execution callbacks and rejected run requests.
+ *
+ * @category Errors
+ */
+export interface RunnerExecutionError {
+    /** Human-readable error message. */
+    message: string;
+    /** Optional stack trace reported by the runner. */
+    stack?: string;
+    /** Optional 1-based source line. */
+    line?: number;
+    /** Optional 1-based source column. */
+    column?: number;
+}
+/**
+ * Error used when a request-scoped runner execution fails.
+ *
+ * @category Errors
+ */
+export declare class RunnerRequestError extends Error implements RunnerExecutionError {
+    /** Optional 1-based source line. */
+    readonly line?: number;
+    /** Optional 1-based source column. */
+    readonly column?: number;
+    /** Request identifier that produced the error. */
+    readonly requestId?: string;
+    constructor(message: RunErrorMessage);
+}

package/dist/errors.js

@@ -0,0 +1,21 @@
+/**
+ * Error used when a request-scoped runner execution fails.
+ *
+ * @category Errors
+ */
+export class RunnerRequestError extends Error {
+    /** Optional 1-based source line. */
+    line;
+    /** Optional 1-based source column. */
+    column;
+    /** Request identifier that produced the error. */
+    requestId;
+    constructor(message) {
+        super(message.message);
+        this.name = 'RunnerRequestError';
+        this.stack = message.stack;
+        this.line = message.line;
+        this.column = message.column;
+        this.requestId = message.requestId;
+    }
+}

package/dist/font.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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

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

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * 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.
+ *
+ * @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

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * 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.
+ *
+ * @module @textmode/runner-client
+ */
+export { IframeTextmodeRuntime } from './IframeTextmodeRuntime';
+export { RunnerRequestError } from './errors';
+export { DEFAULT_IFRAME_SANDBOX_TOKENS, } from './options';

package/dist/internal/heartbeat.d.ts

@@ -0,0 +1,26 @@
+export interface HeartbeatTimerApi {
+    setInterval: (handler: () => void, intervalMs: number) => number;
+    clearInterval: (intervalId: number) => void;
+}
+export interface HeartbeatControllerOptions {
+    intervalMs: number;
+    timeoutMs: number;
+    now?: () => number;
+    timerApi?: HeartbeatTimerApi;
+    onPing: () => void;
+    onTimeout: () => void;
+}
+export declare class HeartbeatController {
+    private readonly intervalMs;
+    private readonly timeoutMs;
+    private readonly now;
+    private readonly timerApi;
+    private readonly onPing;
+    private readonly onTimeout;
+    private intervalId;
+    private lastPongAt;
+    constructor(options: HeartbeatControllerOptions);
+    start(): void;
+    stop(): void;
+    markPong(): void;
+}