@textmode/runner-client 0.2.0 → 0.5.0

package/README.md

@@ -5,7 +5,7 @@ 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, running code,
-soft-resetting sketches, reconnecting, and disposing the transport.
+reconnecting, and disposing the transport.
 
 It does not execute textmode.js sketches directly. It controls a runner app at
 the `runnerUrl` you provide.
@@ -36,6 +36,12 @@ if (!container) {
 
 const runtime = new IframeTextmodeRuntime({
 	runnerUrl: 'https://runner.textmode.art/',
+	onUserActivationRequired() {
+		container.dataset.userActivation = 'required';
+	},
+	onUserInteraction() {
+		delete container.dataset.userActivation;
+	},
 	onStatusChange(status: RunnerRuntimeStatus, reason) {
 		console.info('runner status changed', status, reason);
 	},
@@ -55,7 +61,6 @@ try {
 	}
 }
 
-await runtime.runCode('t.frameCount = 0;', { softReset: true });
 runtime.dispose();
 ```
 
@@ -88,10 +93,17 @@ Typical host apps follow this lifecycle:
 
 1. Create an `IframeTextmodeRuntime` with a trusted `runnerUrl`.
 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.
+3. Use `runCode` to replace the current sketch execution while preserving its timeline.
+4. Use `resetRuntime` to rebuild textmode while preserving the current iframe document and its browser interaction state.
+5. Call `reconnect` only when the iframe document or transport must be replaced.
+6. Call `dispose` when the host view is unmounted.
+
+`resetRuntime` falls back to reconnecting when an older runner does not advertise the optional `runtimeReset` capability.
+
+Cross-origin WebKit runners may request one trusted child-frame interaction
+through `onUserActivationRequired`. A host can temporarily expose or elevate
+the existing iframe until `onUserInteraction` fires. Programmatic focus or a
+synthetic parent-page click is not an equivalent substitute.
 
 The runtime exposes `status`, `isReady`, and `frame` getters for host UI state.
 

package/dist/IframeTextmodeRuntime.d.ts

@@ -1,5 +1,5 @@
-import { type RunnerCapabilities } from '@textmode/runner-protocol';
-import { type IframeTextmodeRuntimeOptions } from './options';
+import { type AudioDataMessage, type RunnerCapabilities } from '@textmode/runner-protocol';
+import { type IframeTextmodeRuntimeOptions, type RunnerProbeOptions, type RunnerReconnectOptions } from './options';
 import type { RunnerRuntimeStatus } from './status';
 /**
  * Browser iframe runtime for communicating with the hosted textmode runner.
@@ -74,12 +74,13 @@ export declare class IframeTextmodeRuntime {
      */
     dispose(): void;
     /**
-     * Recreates the iframe and reruns the last requested code when available.
+     * Recreates the iframe and optionally reruns the last requested code.
      *
+     * @param options - Reconnect behavior. The last code is rerun by default.
      * @returns `true` when reconnection succeeds.
      * @category Runtime
      */
-    reconnect(): Promise<boolean>;
+    reconnect(options?: RunnerReconnectOptions): Promise<boolean>;
     /**
      * Focuses the iframe from a host user gesture.
      *
@@ -93,9 +94,32 @@ export declare class IframeTextmodeRuntime {
      *
      * @category Runtime
      */
-    runCode(code: string, options?: {
-        softReset?: boolean;
-    }): Promise<boolean>;
+    runCode(code: string): Promise<boolean>;
+    /**
+     * Executes code as a transactional candidate.
+     *
+     * Failed and timed-out probes do not replace the code used by reconnect.
+     *
+     * @category Runtime
+     */
+    probeCode(code: string, options?: RunnerProbeOptions): Promise<boolean>;
+    /**
+     * Rebuilds the textmode runtime while preserving the current iframe document.
+     *
+     * Older runners fall back to a full reconnect followed by one code execution.
+     *
+     * @category Runtime
+     */
+    resetRuntime(code: string): Promise<boolean>;
+    /**
+     * Sends a fire-and-forget audio analysis frame to the runner.
+     *
+     * Audio frames are intentionally not request-tracked: hosts may send them at
+     * animation-frame cadence, and stale frames can be safely dropped.
+     *
+     * @category Runtime
+     */
+    sendAudioData(data: Omit<AudioDataMessage, 'type'>): boolean;
     private connectPort;
     private handlePortMessage;
     private handleReady;
@@ -109,5 +133,6 @@ export declare class IframeTextmodeRuntime {
     private assertSandboxOriginPolicy;
     private setStatus;
     private disposeFrame;
+    private rejectPendingHandshake;
     private createRequestId;
 }

package/dist/IframeTextmodeRuntime.js

@@ -109,10 +109,18 @@ export class IframeTextmodeRuntime {
      */
     async init(container) {
         this.container = container;
-        this.assertSandboxOriginPolicy();
+        try {
+            this.assertSandboxOriginPolicy();
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            this.handleUnavailable(reason);
+            throw error;
+        }
         if (this.isReady && this.iframe?.isConnected) {
             return true;
         }
+        this.rejectPendingHandshake('runner initialization superseded');
         this.disposeFrame();
         this.ready = false;
         this.setStatus('connecting');
@@ -129,6 +137,8 @@ export class IframeTextmodeRuntime {
             }, this.handshakeTimeoutMs);
         });
         iframe.addEventListener('load', () => {
+            if (this.iframe !== iframe)
+                return;
             this.connectPort();
         }, { once: true });
         return readyPromise;
@@ -149,6 +159,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');
@@ -156,16 +167,17 @@ export class IframeTextmodeRuntime {
         this.readyRejecter = null;
     }
     /**
-     * Recreates the iframe and reruns the last requested code when available.
+     * Recreates the iframe and optionally reruns the last requested code.
      *
+     * @param options - Reconnect behavior. The last code is rerun by default.
      * @returns `true` when reconnection succeeds.
      * @category Runtime
      */
-    async reconnect() {
+    async reconnect(options = {}) {
         if (!this.container) {
             return false;
         }
-        const code = this.lastRequestedCode;
+        const code = options.rerun === false ? null : this.lastRequestedCode;
         this.setStatus('recovering');
         this.forceDisposeFrameForReconnect();
         const initialized = await this.init(this.container);
@@ -198,13 +210,62 @@ export class IframeTextmodeRuntime {
      *
      * @category Runtime
      */
-    async runCode(code, options = {}) {
-        this.lastRequestedCode = code;
+    async runCode(code) {
         const requestId = this.createRequestId('run');
-        const message = options.softReset
-            ? { type: 'SOFT_RESET', requestId, code }
-            : { type: 'RUN_CODE', requestId, code };
+        const message = { type: 'RUN_CODE', requestId, code };
         await this.request(message);
+        this.lastRequestedCode = code;
+        return true;
+    }
+    /**
+     * Executes code as a transactional candidate.
+     *
+     * Failed and timed-out probes do not replace the code used by reconnect.
+     *
+     * @category Runtime
+     */
+    async probeCode(code, options = {}) {
+        const requestId = this.createRequestId('probe');
+        const message = { type: 'RUN_CODE', requestId, code };
+        await this.request(message, options.timeoutMs ?? this.requestTimeoutMs);
+        this.lastRequestedCode = code;
+        return true;
+    }
+    /**
+     * Rebuilds the textmode runtime while preserving the current iframe document.
+     *
+     * Older runners fall back to a full reconnect followed by one code execution.
+     *
+     * @category Runtime
+     */
+    async resetRuntime(code) {
+        if (this.capabilities?.runtimeReset !== true) {
+            const reconnected = await this.reconnect({ rerun: false });
+            return reconnected ? this.runCode(code) : false;
+        }
+        const requestId = this.createRequestId('reset');
+        await this.request({ type: 'RESET_RUNTIME', requestId, code });
+        this.lastRequestedCode = code;
+        return true;
+    }
+    /**
+     * Sends a fire-and-forget audio analysis frame to the runner.
+     *
+     * Audio frames are intentionally not request-tracked: hosts may send them at
+     * animation-frame cadence, and stale frames can be safely dropped.
+     *
+     * @category Runtime
+     */
+    sendAudioData(data) {
+        if (!this.port || !this.ready) {
+            return false;
+        }
+        this.postMessage({
+            type: 'AUDIO_DATA',
+            fft: data.fft,
+            waveform: data.waveform,
+            timestamp: data.timestamp,
+        });
         return true;
     }
     connectPort() {
@@ -236,9 +297,15 @@ export class IframeTextmodeRuntime {
             onSynthError: (synthErrorMessage) => {
                 this.options.onSynthError?.(synthErrorMessage.message);
             },
+            onHardReset: () => {
+                this.options.onHardReset?.();
+            },
             onToggleUI: () => {
                 this.options.onToggleUI?.();
             },
+            onUserActivationRequired: () => {
+                this.options.onUserActivationRequired?.();
+            },
             onUserInteraction: () => {
                 this.options.onUserInteraction?.();
             },
@@ -295,7 +362,6 @@ export class IframeTextmodeRuntime {
         const kind = requestKindForMessage(message.type);
         const promise = this.pending.register({
             requestId,
-            kind,
             messageType: message.type,
             timeoutMs,
             onTimeout: (error) => {
@@ -338,6 +404,7 @@ export class IframeTextmodeRuntime {
         }
         this.heartbeat.stop();
         this.pending.rejectAll(new Error('runner reconnecting'));
+        this.rejectPendingHandshake('runner reconnecting');
         this.ready = false;
         this.disposeFrame();
     }
@@ -380,6 +447,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

@@ -11,5 +11,5 @@
  */
 export { IframeTextmodeRuntime } from './IframeTextmodeRuntime';
 export { RunnerRequestError, type RunnerExecutionError } from './errors';
-export { DEFAULT_IFRAME_SANDBOX_TOKENS, type IframeMountMode, type IframeSandboxToken, type IframeTextmodeRuntimeOptions, } from './options';
+export { DEFAULT_IFRAME_SANDBOX_TOKENS, type IframeMountMode, type IframeSandboxToken, type IframeTextmodeRuntimeOptions, type RunnerProbeOptions, type RunnerReconnectOptions, } from './options';
 export { type RunnerRuntimeStatus } from './status';

package/dist/internal/messageRouter.d.ts

@@ -4,7 +4,9 @@ export interface RunnerMessageHandlers {
     onRunOk: (message: RunOkMessage) => void;
     onRunError: (message: RunErrorMessage) => void;
     onSynthError: (message: SynthErrorMessage) => void;
+    onHardReset: () => void;
     onToggleUI: () => void;
+    onUserActivationRequired: () => void;
     onUserInteraction: () => void;
     onPong: (message: PongMessage) => void;
 }

package/dist/internal/messageRouter.js

@@ -16,9 +16,15 @@ export function routeRunnerMessage(message, handlers) {
         case 'SYNTH_ERROR':
             handlers.onSynthError(message);
             break;
+        case 'HARD_RESET':
+            handlers.onHardReset();
+            break;
         case 'TOGGLE_UI':
             handlers.onToggleUI();
             break;
+        case 'USER_ACTIVATION_REQUIRED':
+            handlers.onUserActivationRequired();
+            break;
         case 'USER_INTERACTION':
             handlers.onUserInteraction();
             break;

package/dist/internal/requestRegistry.d.ts

@@ -8,7 +8,6 @@ export interface RequestTimerApi {
 }
 interface RegisterRequestOptions {
     requestId: string;
-    kind: RequestKind;
     messageType: ParentToRunnerMessage['type'];
     timeoutMs: number;
     onTimeout: (error: Error) => void;
@@ -18,7 +17,6 @@ export declare class RequestRegistry {
     private readonly timerApi;
     private readonly visibilityApi;
     constructor(timerApi?: RequestTimerApi, visibilityApi?: PageVisibilityApi);
-    get size(): number;
     register<T>(options: RegisterRequestOptions): Promise<T>;
     resolve(requestId: string | undefined, value: unknown): boolean;
     reject(requestId: string, error: Error): boolean;

package/dist/internal/requestRegistry.js

@@ -7,9 +7,6 @@ export class RequestRegistry {
         this.timerApi = timerApi;
         this.visibilityApi = visibilityApi;
     }
-    get size() {
-        return this.pending.size;
-    }
     register(options) {
         return new Promise((resolve, reject) => {
             let remainingMs = options.timeoutMs;
@@ -66,7 +63,6 @@ export class RequestRegistry {
                 scheduleTimer();
             }
             this.pending.set(options.requestId, {
-                kind: options.kind,
                 resolve: resolve,
                 reject,
                 cleanup,
@@ -104,10 +100,12 @@ export class RequestRegistry {
 export function requestKindForMessage(type) {
     switch (type) {
         case 'RUN_CODE':
-        case 'SOFT_RESET':
             return 'run';
+        case 'RESET_RUNTIME':
+            return 'lifecycle';
         case 'PING':
         case 'DISPOSE':
+        case 'AUDIO_DATA':
             return 'lifecycle';
     }
 }

package/dist/options.d.ts

@@ -13,6 +13,22 @@ export type IframeSandboxToken = 'allow-downloads' | 'allow-same-origin' | 'allo
  * @category Options
  */
 export type IframeMountMode = 'append' | 'replace';
+/**
+ * Controls how a runner reconnect restores previously requested code.
+ *
+ * @category Options
+ */
+export interface RunnerReconnectOptions {
+    /** Rerun the last requested code after reconnecting. Defaults to `true`. */
+    rerun?: boolean;
+}
+/**
+ * Controls a transactional code probe.
+ */
+export interface RunnerProbeOptions {
+    /** Request timeout for the probe. Defaults to the runtime request timeout. */
+    timeoutMs?: number;
+}
 /**
  * Default sandbox tokens used by the runner iframe.
  *
@@ -50,8 +66,12 @@ export interface IframeTextmodeRuntimeOptions {
     onRunError?: (error: RunnerExecutionError) => void;
     /** Called when the runner reports a synth parameter error. */
     onSynthError?: (message: string) => void;
+    /** Called when the runner requests a fresh host runtime. */
+    onHardReset?: () => void;
     /** Called when the runner requests host UI visibility changes. */
     onToggleUI?: () => void;
+    /** Called when the runner needs a trusted interaction inside its iframe document. */
+    onUserActivationRequired?: () => void;
     /** Called when the runner reports user interaction. */
     onUserInteraction?: () => void;
     /** Called when the runner becomes unavailable or hung. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@textmode/runner-client",
-    "version": "0.2.0",
+    "version": "0.5.0",
     "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.2.0"
+        "@textmode/runner-protocol": "^0.5.0"
     }
 }