@textmode/runner-client 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# @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, loading fonts,
+controlling playback, running code, exporting output, reconnecting, and
+disposing the transport.
+
+It does not execute textmode.js sketches directly. It controls a runner app at
+the `runnerUrl` you provide.
+
+## Install
+
+```sh
+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
+
+```ts
+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);
+	},
+	onExportProgress(requestId, format, progress) {
+		console.info('export progress', requestId, format, progress);
+	},
+});
+
+await runtime.init(container, {
+	width: 640,
+	height: 640,
+	fontSize: 16,
+	frameRate: 60,
+});
+
+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);
+	}
+}
+
+const image = await runtime.export('image', {
+	format: 'png',
+	scale: 2,
+});
+
+console.info(image.filename, image.mimeType, image.blob);
+runtime.dispose();
+```
+
+## Public API
+
+Import from the package root only:
+
+```ts
+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`
+- `FontLoadResult`
+- `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, settings)` from a browser context.
+3. Use `runCode`, `configure`, `setSettings`, `export`, `loadFont`, and
+   `playback` as needed.
+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:
+
+```ts
+['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.
+
+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`](./api/runner-client/index.md).
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](./LICENSE).

package/dist/IframeTextmodeRuntime.d.ts

@@ -0,0 +1,177 @@
+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 IframeTextmodeRuntimeOptions } from './options';
+import type { RunnerRuntimeStatus } from './status';
+/**
+ * Browser iframe runtime for communicating with the hosted textmode runner.
+ *
+ * @category Runtime
+ */
+export declare class IframeTextmodeRuntime {
+    private readonly runnerHref;
+    private readonly runnerOrigin;
+    private readonly sandboxTokens;
+    private readonly handshakeTimeoutMs;
+    private readonly requestTimeoutMs;
+    private readonly options;
+    private readonly mountMode;
+    private readonly pending;
+    private readonly heartbeat;
+    private iframe;
+    private channel;
+    private port;
+    private container;
+    private settings;
+    private capabilities;
+    private ready;
+    private currentStatus;
+    private readyResolver;
+    private readyRejecter;
+    private readyTimeoutId;
+    private lastRequestedCode;
+    constructor(options: IframeTextmodeRuntimeOptions);
+    /**
+     * Whether the runner iframe is ready to accept requests.
+     *
+     * @category Runtime
+     */
+    get isReady(): boolean;
+    /**
+     * Current runner iframe element, when mounted.
+     *
+     * @category Runtime
+     */
+    get frame(): HTMLIFrameElement | null;
+    /**
+     * Current runner lifecycle status.
+     *
+     * @category Runtime
+     */
+    get status(): RunnerRuntimeStatus;
+    /**
+     * Alias for {@link IframeTextmodeRuntime.status}.
+     *
+     * @category Runtime
+     */
+    get runnerStatus(): RunnerRuntimeStatus;
+    /**
+     * Capabilities advertised by the connected runner.
+     *
+     * @category Runtime
+     */
+    get advertisedCapabilities(): RunnerCapabilities | null;
+    /**
+     * 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>;
+    /**
+     * Disposes the iframe connection and rejects pending requests.
+     *
+     * @category Runtime
+     */
+    dispose(): void;
+    /**
+     * Recreates the iframe and reruns the last requested code when available.
+     *
+     * @returns `true` when reconnection succeeds.
+     * @category Runtime
+     */
+    reconnect(): Promise<boolean>;
+    /**
+     * Focuses the iframe from a host user gesture.
+     *
+     * Some browsers use this to unlock normal iframe animation cadence.
+     *
+     * @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.
+     *
+     * @category Runtime
+     */
+    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;
+    private markReady;
+    private handleRunError;
+    private request;
+    private postMessage;
+    private handleUnavailable;
+    private validateReadyMessage;
+    private assertSandboxOriginPolicy;
+    private setStatus;
+    private disposeFrame;
+    private createRequestId;
+}