@textmode/runner-client 0.1.0

package/dist/internal/heartbeat.js

@@ -0,0 +1,44 @@
+export class HeartbeatController {
+    intervalMs;
+    timeoutMs;
+    now;
+    timerApi;
+    onPing;
+    onTimeout;
+    intervalId = null;
+    lastPongAt = 0;
+    constructor(options) {
+        this.intervalMs = options.intervalMs;
+        this.timeoutMs = options.timeoutMs;
+        this.now = options.now ?? Date.now;
+        this.timerApi = options.timerApi ?? createWindowTimerApi();
+        this.onPing = options.onPing;
+        this.onTimeout = options.onTimeout;
+    }
+    start() {
+        this.stop();
+        this.lastPongAt = this.now();
+        this.intervalId = this.timerApi.setInterval(() => {
+            if (this.now() - this.lastPongAt > this.timeoutMs) {
+                this.onTimeout();
+                return;
+            }
+            this.onPing();
+        }, this.intervalMs);
+    }
+    stop() {
+        if (this.intervalId !== null) {
+            this.timerApi.clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    markPong() {
+        this.lastPongAt = this.now();
+    }
+}
+function createWindowTimerApi() {
+    return {
+        setInterval: (handler, intervalMs) => window.setInterval(handler, intervalMs),
+        clearInterval: (intervalId) => window.clearInterval(intervalId),
+    };
+}

package/dist/internal/iframeMount.d.ts

@@ -0,0 +1,4 @@
+import type { IframeMountMode, IframeSandboxToken } from '../options';
+export declare function createRunnerIframe(runnerHref: string, sandboxTokens: readonly IframeSandboxToken[]): HTMLIFrameElement;
+export declare function mountRunnerIframe(container: HTMLElement, iframe: HTMLIFrameElement, mode: IframeMountMode): void;
+export declare function focusElement(element: HTMLElement): void;

package/dist/internal/iframeMount.js

@@ -0,0 +1,29 @@
+export function createRunnerIframe(runnerHref, sandboxTokens) {
+    const iframe = document.createElement('iframe');
+    iframe.id = 'textmode-sandbox-runner';
+    iframe.title = 'textmode.js sandboxed runner';
+    iframe.src = runnerHref;
+    iframe.sandbox.add(...sandboxTokens);
+    iframe.referrerPolicy = 'no-referrer';
+    iframe.style.width = '100%';
+    iframe.style.height = '100%';
+    iframe.style.border = '0';
+    iframe.style.display = 'block';
+    iframe.style.background = 'transparent';
+    return iframe;
+}
+export function mountRunnerIframe(container, iframe, mode) {
+    if (mode === 'append') {
+        container.appendChild(iframe);
+        return;
+    }
+    container.replaceChildren(iframe);
+}
+export function focusElement(element) {
+    try {
+        element.focus({ preventScroll: true });
+    }
+    catch {
+        element.focus();
+    }
+}

package/dist/internal/messageRouter.d.ts

@@ -0,0 +1,16 @@
+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';
+export interface RunnerMessageHandlers {
+    onReady: (message: ReadyMessage) => void;
+    onRunOk: (message: RunOkMessage) => void;
+    onRunError: (message: RunErrorMessage) => void;
+    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

@@ -0,0 +1,45 @@
+import { isRunnerMessage, } from '@textmode/runner-protocol';
+export function routeRunnerMessage(message, handlers) {
+    if (!isRunnerMessage(message)) {
+        return false;
+    }
+    switch (message.type) {
+        case 'READY':
+            handlers.onReady(message);
+            break;
+        case 'RUN_OK':
+            handlers.onRunOk(message);
+            break;
+        case 'RUN_ERROR':
+            handlers.onRunError(message);
+            break;
+        case 'SYNTH_ERROR':
+            handlers.onSynthError(message);
+            break;
+        case 'TOGGLE_UI':
+            handlers.onToggleUI();
+            break;
+        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;
+    }
+    return true;
+}

package/dist/internal/requestRegistry.d.ts

@@ -0,0 +1,25 @@
+import type { ParentToRunnerMessage } from '@textmode/runner-protocol';
+export type RequestKind = 'run' | 'export' | 'font' | 'playback' | 'settings';
+export interface RequestTimerApi {
+    setTimeout: (handler: () => void, timeoutMs: number) => number;
+    clearTimeout: (timeoutId: number) => void;
+}
+interface RegisterRequestOptions {
+    requestId: string;
+    kind: RequestKind;
+    messageType: ParentToRunnerMessage['type'];
+    timeoutMs: number;
+    onTimeout: (error: Error) => void;
+}
+export declare class RequestRegistry {
+    private readonly pending;
+    private readonly timerApi;
+    constructor(timerApi?: RequestTimerApi);
+    get size(): number;
+    register<T>(options: RegisterRequestOptions): Promise<T>;
+    resolve(requestId: string | undefined, value: unknown): boolean;
+    reject(requestId: string, error: Error): boolean;
+    rejectAll(error: Error): void;
+}
+export declare function requestKindForMessage(type: ParentToRunnerMessage['type']): RequestKind;
+export {};

package/dist/internal/requestRegistry.js

@@ -0,0 +1,77 @@
+export class RequestRegistry {
+    pending = new Map();
+    timerApi;
+    constructor(timerApi = createWindowTimerApi()) {
+        this.timerApi = timerApi;
+    }
+    get size() {
+        return this.pending.size;
+    }
+    register(options) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = this.timerApi.setTimeout(() => {
+                this.pending.delete(options.requestId);
+                const error = new Error(`runner request timed out: ${options.messageType}`);
+                reject(error);
+                options.onTimeout(error);
+            }, options.timeoutMs);
+            this.pending.set(options.requestId, {
+                kind: options.kind,
+                resolve: resolve,
+                reject,
+                timeoutId,
+            });
+        });
+    }
+    resolve(requestId, value) {
+        if (!requestId)
+            return false;
+        const pending = this.pending.get(requestId);
+        if (!pending)
+            return false;
+        this.timerApi.clearTimeout(pending.timeoutId);
+        this.pending.delete(requestId);
+        pending.resolve(value);
+        return true;
+    }
+    reject(requestId, error) {
+        const pending = this.pending.get(requestId);
+        if (!pending)
+            return false;
+        this.timerApi.clearTimeout(pending.timeoutId);
+        this.pending.delete(requestId);
+        pending.reject(error);
+        return true;
+    }
+    rejectAll(error) {
+        for (const [requestId, pending] of this.pending) {
+            this.timerApi.clearTimeout(pending.timeoutId);
+            pending.reject(error);
+            this.pending.delete(requestId);
+        }
+    }
+}
+export function requestKindForMessage(type) {
+    switch (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';
+    }
+}
+function createWindowTimerApi() {
+    return {
+        setTimeout: (handler, timeoutMs) => window.setTimeout(handler, timeoutMs),
+        clearTimeout: (timeoutId) => window.clearTimeout(timeoutId),
+    };
+}

package/dist/internal/sandboxPolicy.d.ts

@@ -0,0 +1,7 @@
+import type { IframeSandboxToken } from '../options';
+export interface SandboxOriginPolicyOptions {
+    sandboxTokens: readonly IframeSandboxToken[];
+    runnerOrigin: string;
+    parentOrigin: string;
+}
+export declare function assertSandboxOriginPolicy(options: SandboxOriginPolicyOptions): void;

package/dist/internal/sandboxPolicy.js

@@ -0,0 +1,6 @@
+export function assertSandboxOriginPolicy(options) {
+    const canRunSameOriginScripts = options.sandboxTokens.includes('allow-scripts') && options.sandboxTokens.includes('allow-same-origin');
+    if (canRunSameOriginScripts && options.runnerOrigin === options.parentOrigin) {
+        throw new Error('Refusing to start sandbox runner with allow-scripts and allow-same-origin on the parent origin');
+    }
+}

package/dist/options.d.ts

@@ -0,0 +1,67 @@
+import type { ExportProgress, PlaybackState, RunnerCapabilities, RunOkMessage } from '@textmode/runner-protocol';
+import type { RunnerExecutionError } from './errors';
+import type { RunnerRuntimeStatus } from './status';
+/**
+ * Iframe sandbox token supported by the runner client.
+ *
+ * @category Options
+ */
+export type IframeSandboxToken = 'allow-downloads' | 'allow-same-origin' | 'allow-scripts';
+/**
+ * How the runner iframe should be mounted into its container.
+ *
+ * @category Options
+ */
+export type IframeMountMode = 'append' | 'replace';
+/**
+ * Default sandbox tokens used by the runner iframe.
+ *
+ * The default deliberately excludes `allow-downloads`; downloads should be
+ * initiated by the host app after receiving export results.
+ *
+ * @category Options
+ */
+export declare const DEFAULT_IFRAME_SANDBOX_TOKENS: readonly IframeSandboxToken[];
+/**
+ * Options for {@link IframeTextmodeRuntime}.
+ *
+ * @category Options
+ */
+export interface IframeTextmodeRuntimeOptions {
+    /** Absolute or parent-relative URL for the hosted runner app. */
+    runnerUrl: string;
+    /** Iframe mount behavior. Defaults to `replace`. */
+    mountMode?: IframeMountMode;
+    /** Sandbox tokens applied to the runner iframe. */
+    sandboxTokens?: IframeSandboxToken[];
+    /** Timeout for the initial iframe MessagePort handshake. */
+    handshakeTimeoutMs?: number;
+    /** Default timeout for request/response runner messages. */
+    requestTimeoutMs?: number;
+    /** Interval between heartbeat pings. */
+    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. */
+    onReady?: (capabilities: RunnerCapabilities) => void;
+    /** Called when code execution succeeds. */
+    onRunOk?: (message: RunOkMessage) => void;
+    /** Called for non-request-scoped runner execution errors. */
+    onRunError?: (error: RunnerExecutionError) => void;
+    /** Called when the runner reports a synth parameter error. */
+    onSynthError?: (message: string) => void;
+    /** Called when the runner requests host UI visibility changes. */
+    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. */
+    onConnected?: () => void;
+    /** Called whenever runtime lifecycle status changes. */
+    onStatusChange?: (status: RunnerRuntimeStatus, reason?: string | null) => void;
+}

package/dist/options.js

@@ -0,0 +1,15 @@
+/**
+ * Default sandbox tokens used by the runner iframe.
+ *
+ * The default deliberately excludes `allow-downloads`; downloads should be
+ * initiated by the host app after receiving export results.
+ *
+ * @category Options
+ */
+export const DEFAULT_IFRAME_SANDBOX_TOKENS = [
+    'allow-scripts',
+    // The runner is served from a separate origin in dev and production. Keeping
+    // same-origin inside that isolated origin preserves runner asset behavior
+    // without giving it parent DOM access.
+    'allow-same-origin',
+];

package/dist/status.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Lifecycle state for an iframe runner connection.
+ *
+ * @category Runtime
+ */
+export type RunnerRuntimeStatus = 'idle' | 'connecting' | 'configuring' | 'ready' | 'recovering' | 'unavailable' | 'hung';

package/dist/status.js

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

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@textmode/runner-client",
+    "version": "0.1.0",
+    "description": "Browser iframe runtime client for the hosted textmode runner.",
+    "license": "AGPL-3.0-or-later",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist/**/*.d.ts",
+        "dist/**/*.js"
+    ],
+    "scripts": {
+        "build": "tsc -b",
+        "check-types": "tsc -p tsconfig.json --noEmit",
+        "lint": "eslint .",
+        "test": "vitest run --passWithNoTests",
+        "build:docs": "typedoc --options typedoc.json",
+        "dev:docs": "typedoc --options typedoc.json --watch",
+        "prepare": "npm run build"
+    },
+    "dependencies": {
+        "@textmode/runner-protocol": "^0.1.0"
+    }
+}