@textmode/runner-client

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.

It does not execute textmode.js sketches directly. It controls a runner app at the runnerUrl you provide.

Install

npm install @textmode/runner-client

@textmode/runner-protocol is installed as a dependency and is also available for consumers that need the protocol types directly.

Usage

import {
	IframeTextmodeRuntime,
	RunnerRequestError,
	type RunnerRuntimeStatus,
} from '@textmode/runner-client';

const container = document.querySelector<HTMLElement>('#runner');

if (!container) {
	throw new Error('missing runner container');
}

const runtime = new IframeTextmodeRuntime({
	runnerUrl: 'https://runner.textmode.art/',
	onStatusChange(status: RunnerRuntimeStatus, reason) {
		console.info('runner status changed', status, reason);
	},
});

await runtime.init(container);

try {
	await runtime.runCode(`
		t.draw(() => {
			t.print('textmode', 0, 0);
		});
	`);
} catch (error) {
	if (error instanceof RunnerRequestError) {
		console.error(error.message, error.line, error.column);
	}
}

await runtime.runCode('t.frameCount = 0;', { softReset: true });
runtime.dispose();

Public API

Import from the package root only:

import { IframeTextmodeRuntime } from '@textmode/runner-client';

Public subpath imports are intentionally not supported. Internal modules such as request routing, heartbeat control, iframe mounting, and sandbox policy may change without a semver-major release.

The main exports are:

• IframeTextmodeRuntime
• RunnerRuntimeStatus
• RunnerExecutionError
• RunnerRequestError
• IframeTextmodeRuntimeOptions
• IframeMountMode
• IframeSandboxToken
• DEFAULT_IFRAME_SANDBOX_TOKENS

Runtime Lifecycle

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.

The runtime exposes status, isReady, and frame getters for host UI state.

Sandbox Policy

The default iframe sandbox tokens are:

['allow-scripts', 'allow-same-origin']

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.

API Docs

Generated TypeDoc Markdown lives in api/runner-client.

License

AGPL-3.0-or-later. See LICENSE.