@textmode/runner-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,122 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM THE USE OF
+THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without
+fear of later claims of infringement build upon, modify, incorporate in
+other works, reuse and redistribute as freely as possible in any form
+whatsoever and for any purposes, including without limitation commercial
+purposes. These owners may contribute to the Commons to promote the ideal
+of a free culture and the further production of creative, cultural and
+scientific works, or to gain reputation or greater distribution for their
+Work in part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or
+she is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under
+its terms, with knowledge of his or her Copyright and Related Rights in
+the Work and the meaning and intended legal effect of CC0 on those
+rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of
+     data in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of
+     the European Parliament and of the Council of 11 March 1996 on the
+     legal protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of
+each member of the public at large and to the detriment of Affirmer's
+heirs and successors, fully intending that such Waiver shall not be
+subject to revocation, rescission, cancellation, termination, or any
+other legal or equitable action to disrupt the quiet enjoyment of the
+Work by the public as contemplated by Affirmer's express Statement of
+Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non
+exclusive, irrevocable and unconditional license to exercise Affirmer's
+Copyright and Related Rights in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "License"). The License shall be deemed effective as of the
+date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated
+claims and causes of action with respect to the Work, in either case
+contrary to Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other
+    persons that may apply to the Work or any use thereof, including
+    without limitation any person's Copyright and Related Rights in the
+    Work. Further, Affirmer disclaims responsibility for obtaining any
+    necessary consents, permissions or other rights required for any use
+    of the Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/README.md

@@ -0,0 +1,121 @@
+# @textmode/runner-protocol
+
+Shared TypeScript message contract for the hosted textmode runner iframe.
+
+This package is the single source of truth for the wire messages exchanged by
+the runner and browser host apps in the textmode.js ecosystem.
+It contains the public message types, capability model, runtime settings,
+export/playback/font payloads, and runtime validators used on both sides of the
+iframe boundary.
+
+## Install
+
+```sh
+npm install @textmode/runner-protocol
+```
+
+## Usage
+
+```ts
+import {
+	createRunnerCapabilities,
+	isParentMessage,
+	isRunnerMessage,
+	type ParentToRunnerMessage,
+	type RunnerToParentMessage,
+} from '@textmode/runner-protocol';
+
+const capabilities = createRunnerCapabilities();
+
+function handleParentMessage(message: unknown): void {
+	if (!isParentMessage(message)) {
+		return;
+	}
+
+	runMessage(message);
+}
+
+function sendRunnerMessage(message: RunnerToParentMessage): void {
+	if (isRunnerMessage(message)) {
+		port.postMessage(message);
+	}
+}
+
+function runMessage(message: ParentToRunnerMessage): void {
+	switch (message.type) {
+		case 'RUN_CODE':
+			runCode(message.code, message.requestId);
+			break;
+		case 'PING':
+			port.postMessage({ type: 'PONG', nonce: message.nonce, timestamp: Date.now() });
+			break;
+	}
+}
+```
+
+## Public API
+
+Import from the package root only:
+
+```ts
+import { isRunnerMessage, type RuntimeSettings } from '@textmode/runner-protocol';
+```
+
+Public subpath imports are intentionally not supported. This keeps the protocol
+package free to reorganize internal modules without breaking consumers.
+
+The main exports are grouped around:
+
+- capabilities: `RunnerCapabilities`, `ExportFormat`,
+  `createRunnerCapabilities`
+- runtime settings: `RuntimeSettings`
+- exports: image, SVG, TXT, GIF, and WebM option/result/progress types
+- playback: `PlaybackAction`, `PlaybackState`
+- messages: `InitMessage`, `ParentToRunnerMessage`, `RunnerToParentMessage`,
+  `Message`
+- guards: `isInitMessage`, `isParentMessage`, `isRunnerMessage`,
+  `isRunnerCapabilities`
+
+## Protocol Model
+
+The runner protocol has one current message shape. Runtime protocol version
+negotiation is intentionally absent: npm package semver describes source
+compatibility, while runner feature availability is described through
+capabilities.
+
+The initial window message is generic for every host app:
+
+```ts
+{ type: 'INIT' }
+```
+
+After a successful handshake, the runner responds with:
+
+```ts
+{ type: 'READY', capabilities: RunnerCapabilities }
+```
+
+Messages sent after that point use the `ParentToRunnerMessage` and
+`RunnerToParentMessage` unions.
+
+## Validation
+
+The exported guards are strict runtime validators for untrusted `postMessage`
+payloads. Use them before dispatching messages across the iframe boundary:
+
+```ts
+if (!isRunnerMessage(event.data)) {
+	return;
+}
+```
+
+The guards reject retired app-identity and protocol-version fields such as
+`client`, `v`, `clients`, and `protocolVersions`.
+
+## API Docs
+
+Generated TypeDoc Markdown lives in [`api/runner-protocol`](./api/runner-protocol/index.md).
+
+## License
+
+CC0-1.0. See [LICENSE](./LICENSE).

package/dist/capabilities.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Export families supported by the current runner.
+ *
+ * @category Capabilities
+ */
+export declare const EXPORT_FORMATS: readonly ["image", "svg", "txt", "gif", "webm"];
+/**
+ * Export format advertised by runner capabilities and export messages.
+ *
+ * @category Capabilities
+ */
+export type ExportFormat = (typeof EXPORT_FORMATS)[number];
+/**
+ * Feature flags advertised by a ready runner iframe.
+ *
+ * Capabilities describe feature availability only. They are not a runtime
+ * protocol version negotiation mechanism.
+ *
+ * @category Capabilities
+ */
+export interface RunnerCapabilities {
+    /** Whether fixed runtime settings can be configured before execution. */
+    runtimeConfig: boolean;
+    /** Export formats available through the runner. */
+    exports: ExportFormat[];
+    /** Whether host apps can load fonts into the runner. */
+    fonts: boolean;
+    /** Whether playback controls and state reporting are available. */
+    playback: boolean;
+    /** Whether the runner responds to heartbeat pings. */
+    heartbeat: boolean;
+}
+/**
+ * Creates the capability set for the current hosted runner implementation.
+ *
+ * @returns The current runner capability set.
+ * @category Capabilities
+ */
+export declare function createRunnerCapabilities(): RunnerCapabilities;

package/dist/capabilities.js

@@ -0,0 +1,21 @@
+/**
+ * Export families supported by the current runner.
+ *
+ * @category Capabilities
+ */
+export const EXPORT_FORMATS = ['image', 'svg', 'txt', 'gif', 'webm'];
+/**
+ * Creates the capability set for the current hosted runner implementation.
+ *
+ * @returns The current runner capability set.
+ * @category Capabilities
+ */
+export function createRunnerCapabilities() {
+    return {
+        runtimeConfig: true,
+        exports: [...EXPORT_FORMATS],
+        fonts: true,
+        playback: true,
+        heartbeat: true,
+    };
+}

package/dist/exports.d.ts

@@ -0,0 +1,120 @@
+import type { ExportFormat } from './capabilities';
+/**
+ * Raster image export file format.
+ *
+ * @category Exports
+ */
+export type ImageExportFormat = 'png' | 'jpg' | 'webp';
+/**
+ * Options for raster image exports.
+ *
+ * @category Exports
+ */
+export interface ImageExportOptions {
+    /** Output image format. */
+    format?: ImageExportFormat;
+    /** Export scale multiplier. */
+    scale?: number;
+    /** Encoder quality for lossy image formats. */
+    quality?: number;
+}
+/**
+ * Options for SVG exports.
+ *
+ * @category Exports
+ */
+export interface SvgExportOptions {
+    /** Whether to include background rectangles in the SVG output. */
+    includeBackgroundRectangles?: boolean;
+    /** SVG drawing mode for text geometry. */
+    drawMode?: 'fill' | 'stroke';
+    /** Stroke width used when `drawMode` is `stroke`. */
+    strokeWidth?: number;
+}
+/**
+ * Options for plain text exports.
+ *
+ * @category Exports
+ */
+export interface TxtExportOptions {
+    /** Whether trailing spaces should be preserved. */
+    preserveTrailingSpaces?: boolean;
+    /** Line ending style for generated text. */
+    lineEnding?: 'lf' | 'crlf';
+}
+/**
+ * Options for animated GIF exports.
+ *
+ * @category Exports
+ */
+export interface GifExportOptions {
+    /** Suggested filename without requiring the runner to initiate a download. */
+    filename?: string;
+    /** Number of frames to record. */
+    frameCount?: number;
+    /** Capture frame rate. */
+    frameRate?: number;
+    /** Export scale multiplier. */
+    scale?: number;
+    /** GIF repeat count. */
+    repeat?: number;
+}
+/**
+ * Options for WebM exports.
+ *
+ * @category Exports
+ */
+export interface WebmExportOptions {
+    /** Suggested filename without requiring the runner to initiate a download. */
+    filename?: string;
+    /** Number of frames to record. */
+    frameCount?: number;
+    /** Capture frame rate. */
+    frameRate?: number;
+    /** Encoder quality hint. */
+    quality?: number;
+    /** Whether the export should preserve transparency when supported. */
+    transparent?: boolean;
+}
+/**
+ * Typed export request payload grouped by export format.
+ *
+ * @category Exports
+ */
+export type ExportRequest = {
+    format: 'image';
+    options?: ImageExportOptions;
+} | {
+    format: 'svg';
+    options?: SvgExportOptions;
+} | {
+    format: 'txt';
+    options?: TxtExportOptions;
+} | {
+    format: 'gif';
+    options?: GifExportOptions;
+} | {
+    format: 'webm';
+    options?: WebmExportOptions;
+};
+/**
+ * Progress payload emitted while recording multi-frame exports.
+ *
+ * @category Exports
+ */
+export interface ExportProgress {
+    /** Export lifecycle state reported by the runner. */
+    state: string;
+    /** Zero-based frame currently being recorded, when applicable. */
+    frameIndex?: number;
+    /** Total frame count for the export, when known. */
+    totalFrames?: number;
+    /** Optional human-readable progress detail. */
+    message?: string;
+}
+/**
+ * Export format used by the protocol.
+ *
+ * @category Exports
+ */
+export type ProtocolExportFormat = ExportFormat;

package/dist/exports.js

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

package/dist/guards.d.ts

@@ -0,0 +1,26 @@
+import type { RunnerCapabilities } from './capabilities';
+import type { InitMessage, ParentToRunnerMessage, RunnerToParentMessage } from './messages';
+/**
+ * Checks whether a value is a valid current runner-to-host message.
+ *
+ * @category Guards
+ */
+export declare function isRunnerMessage(msg: unknown): msg is RunnerToParentMessage;
+/**
+ * Checks whether a value is a valid current host-to-runner MessagePort message.
+ *
+ * @category Guards
+ */
+export declare function isParentMessage(msg: unknown): msg is ParentToRunnerMessage;
+/**
+ * Checks whether a value is a valid current runner iframe initialization message.
+ *
+ * @category Guards
+ */
+export declare function isInitMessage(msg: unknown): msg is InitMessage;
+/**
+ * Checks whether a value is a valid current runner capability set.
+ *
+ * @category Guards
+ */
+export declare function isRunnerCapabilities(value: unknown): value is RunnerCapabilities;

package/dist/guards.internal.d.ts

@@ -0,0 +1,17 @@
+import { type ExportFormat } from './capabilities';
+import type { ExportProgress } from './exports';
+import type { PlaybackAction, PlaybackState } from './playback';
+import type { RuntimeSettings } from './runtime';
+export declare function isMessageRecord(value: unknown): value is Record<string, unknown> & {
+    type?: unknown;
+};
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function isOptionalString(value: unknown): value is string | undefined;
+export declare function isOptionalFiniteNumber(value: unknown): value is number | undefined;
+export declare function isOptionalBlob(value: unknown): value is Blob | undefined;
+export declare function isRuntimeSettings(value: unknown): value is RuntimeSettings;
+export declare function isPartialRuntimeSettings(value: unknown): value is Partial<RuntimeSettings>;
+export declare function isExportFormat(value: unknown): value is ExportFormat;
+export declare function isPlaybackAction(value: unknown): value is PlaybackAction;
+export declare function isPlaybackState(value: unknown): value is PlaybackState;
+export declare function isExportProgress(value: unknown): value is ExportProgress;

package/dist/guards.internal.js

@@ -0,0 +1,64 @@
+import { EXPORT_FORMATS } from './capabilities';
+export function isMessageRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+export function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+export function isOptionalFiniteNumber(value) {
+    return value === undefined || isFiniteNumber(value);
+}
+export function isOptionalBlob(value) {
+    return value === undefined || (typeof Blob !== 'undefined' && value instanceof Blob);
+}
+export function isRuntimeSettings(value) {
+    if (!isMessageRecord(value))
+        return false;
+    return (isPositiveFiniteNumber(value.width) &&
+        isPositiveFiniteNumber(value.height) &&
+        isPositiveFiniteNumber(value.fontSize) &&
+        isPositiveFiniteNumber(value.frameRate));
+}
+export function isPartialRuntimeSettings(value) {
+    if (!isMessageRecord(value))
+        return false;
+    return ((value.width === undefined || isPositiveFiniteNumber(value.width)) &&
+        (value.height === undefined || isPositiveFiniteNumber(value.height)) &&
+        (value.fontSize === undefined || isPositiveFiniteNumber(value.fontSize)) &&
+        (value.frameRate === undefined || isPositiveFiniteNumber(value.frameRate)));
+}
+export function isExportFormat(value) {
+    return EXPORT_FORMATS.includes(value);
+}
+export function isPlaybackAction(value) {
+    return (value === 'play' ||
+        value === 'pause' ||
+        value === 'stop' ||
+        value === 'seek' ||
+        value === 'next' ||
+        value === 'previous' ||
+        value === 'setMaxFrames' ||
+        value === 'state');
+}
+export function isPlaybackState(value) {
+    if (!isMessageRecord(value))
+        return false;
+    return (typeof value.isPlaying === 'boolean' &&
+        isFiniteNumber(value.frame) &&
+        isFiniteNumber(value.maxFrames) &&
+        (value.fps === undefined || isFiniteNumber(value.fps)));
+}
+export function isExportProgress(value) {
+    if (!isMessageRecord(value))
+        return false;
+    return (typeof value.state === 'string' &&
+        isOptionalFiniteNumber(value.frameIndex) &&
+        isOptionalFiniteNumber(value.totalFrames) &&
+        isOptionalString(value.message));
+}
+function isPositiveFiniteNumber(value) {
+    return isFiniteNumber(value) && value > 0;
+}

package/dist/guards.js

@@ -0,0 +1,116 @@
+import { isExportFormat, isExportProgress, isFiniteNumber, isMessageRecord, isOptionalBlob, isOptionalFiniteNumber, isOptionalString, isPartialRuntimeSettings, isPlaybackAction, isPlaybackState, isRuntimeSettings, } from './guards.internal';
+/**
+ * Checks whether a value is a valid current runner-to-host message.
+ *
+ * @category Guards
+ */
+export function isRunnerMessage(msg) {
+    if (!isMessageRecord(msg))
+        return false;
+    switch (msg.type) {
+        case 'READY':
+            return !('v' in msg) && isRunnerCapabilities(msg.capabilities);
+        case 'TOGGLE_UI':
+        case 'USER_INTERACTION':
+            return true;
+        case 'RUN_OK':
+            return isFiniteNumber(msg.timestamp) && isOptionalString(msg.requestId);
+        case 'RUN_ERROR':
+            return (typeof msg.message === 'string' &&
+                isOptionalString(msg.stack) &&
+                isOptionalFiniteNumber(msg.line) &&
+                isOptionalFiniteNumber(msg.column) &&
+                isOptionalString(msg.requestId));
+        case 'SYNTH_ERROR':
+            return typeof msg.message === 'string' && isOptionalString(msg.uniformName);
+        case 'EXPORT_RESULT':
+            return (typeof msg.requestId === 'string' &&
+                isExportFormat(msg.format) &&
+                isOptionalBlob(msg.blob) &&
+                isOptionalString(msg.text) &&
+                isOptionalString(msg.filename) &&
+                isOptionalString(msg.mimeType));
+        case 'EXPORT_PROGRESS':
+            return (typeof msg.requestId === 'string' &&
+                (msg.format === 'gif' || msg.format === 'webm') &&
+                isExportProgress(msg.progress));
+        case 'FONT_LOADED':
+            return (typeof msg.requestId === 'string' &&
+                (msg.familyName === null || typeof msg.familyName === 'string') &&
+                Array.isArray(msg.characters) &&
+                msg.characters.every((entry) => typeof entry === 'string'));
+        case 'FONT_ERROR':
+            return typeof msg.requestId === 'string' && typeof msg.message === 'string';
+        case 'PLAYBACK_STATE':
+            return isOptionalString(msg.requestId) && isPlaybackState(msg.state);
+        case 'PONG':
+            return isOptionalString(msg.nonce) && isFiniteNumber(msg.timestamp);
+        default:
+            return false;
+    }
+}
+/**
+ * Checks whether a value is a valid current host-to-runner MessagePort message.
+ *
+ * @category Guards
+ */
+export function isParentMessage(msg) {
+    if (!isMessageRecord(msg))
+        return false;
+    switch (msg.type) {
+        case 'RUN_CODE':
+        case 'SOFT_RESET':
+            return typeof msg.code === 'string' && isOptionalString(msg.requestId);
+        case 'DISPOSE':
+            return true;
+        case 'CONFIGURE_RUNTIME':
+            return isRuntimeSettings(msg.settings) && isOptionalString(msg.requestId);
+        case 'SET_SETTINGS':
+            return isPartialRuntimeSettings(msg.settings) && isOptionalString(msg.requestId);
+        case 'EXPORT':
+            return (typeof msg.requestId === 'string' &&
+                isExportFormat(msg.format) &&
+                (msg.options === undefined || isMessageRecord(msg.options)));
+        case 'LOAD_FONT':
+            return (typeof msg.requestId === 'string' &&
+                typeof msg.fileName === 'string' &&
+                isOptionalString(msg.mimeType) &&
+                msg.buffer instanceof ArrayBuffer);
+        case 'PLAYBACK':
+            return (isOptionalString(msg.requestId) &&
+                isPlaybackAction(msg.action) &&
+                isOptionalFiniteNumber(msg.frame) &&
+                isOptionalFiniteNumber(msg.maxFrames));
+        case 'PING':
+            return isOptionalString(msg.nonce);
+        default:
+            return false;
+    }
+}
+/**
+ * Checks whether a value is a valid current runner iframe initialization message.
+ *
+ * @category Guards
+ */
+export function isInitMessage(msg) {
+    return isMessageRecord(msg) && msg.type === 'INIT' && Object.keys(msg).length === 1;
+}
+/**
+ * Checks whether a value is a valid current runner capability set.
+ *
+ * @category Guards
+ */
+export function isRunnerCapabilities(value) {
+    if (!isMessageRecord(value))
+        return false;
+    if ('protocolVersions' in value)
+        return false;
+    if ('clients' in value)
+        return false;
+    return (typeof value.runtimeConfig === 'boolean' &&
+        Array.isArray(value.exports) &&
+        value.exports.every(isExportFormat) &&
+        typeof value.fonts === 'boolean' &&
+        typeof value.playback === 'boolean' &&
+        typeof value.heartbeat === 'boolean');
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @packageDocumentation
+ *
+ * Shared message protocol for the textmode runner iframe.
+ *
+ * `@textmode/runner-protocol` is the single source of truth for the wire
+ * contract used by the hosted runner and browser host apps.
+ * Runtime protocol version negotiation is intentionally absent: package semver
+ * describes source compatibility, while this package describes the one current
+ * message shape. Feature availability is advertised through capabilities.
+ *
+ * @module @textmode/runner-protocol
+ */
+export { EXPORT_FORMATS, createRunnerCapabilities, type ExportFormat, type RunnerCapabilities, } from './capabilities';
+export { type ExportProgress, type ExportRequest, type GifExportOptions, type ImageExportFormat, type ImageExportOptions, type SvgExportOptions, type TxtExportOptions, type WebmExportOptions, } from './exports';
+export { isInitMessage, isParentMessage, isRunnerCapabilities, isRunnerMessage, } from './guards';
+export { type ConfigureRuntimeMessage, type DisposeMessage, type ExportMessage, type ExportProgressMessage, type ExportResultMessage, type FontErrorMessage, type FontLoadedMessage, type InitMessage, type LoadFontMessage, type Message, type ParentToRunnerMessage, type PingMessage, type PlaybackMessage, type PlaybackStateMessage, type PongMessage, type ReadyMessage, type RunCodeMessage, type RunErrorMessage, type RunOkMessage, type RunnerToParentMessage, type SetSettingsMessage, type SoftResetMessage, type SynthErrorMessage, type ToggleUIMessage, type UserInteractionMessage, type WindowToRunnerMessage, } from './messages';
+export { type PlaybackAction, type PlaybackState } from './playback';
+export { type RuntimeSettings } from './runtime';

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * Shared message protocol for the textmode runner iframe.
+ *
+ * `@textmode/runner-protocol` is the single source of truth for the wire
+ * contract used by the hosted runner and browser host apps.
+ * Runtime protocol version negotiation is intentionally absent: package semver
+ * describes source compatibility, while this package describes the one current
+ * message shape. Feature availability is advertised through capabilities.
+ *
+ * @module @textmode/runner-protocol
+ */
+export { EXPORT_FORMATS, createRunnerCapabilities, } from './capabilities';
+export { isInitMessage, isParentMessage, isRunnerCapabilities, isRunnerMessage, } from './guards';

package/dist/messages.d.ts

@@ -0,0 +1,300 @@
+import type { RunnerCapabilities } from './capabilities';
+import type { ExportProgress, ExportRequest } from './exports';
+import type { PlaybackAction, PlaybackState } from './playback';
+import type { RuntimeSettings } from './runtime';
+/**
+ * Initial window message sent by a host app to the runner iframe.
+ *
+ * @category Messages
+ */
+export interface InitMessage {
+    type: 'INIT';
+}
+/**
+ * Runner readiness message sent after a successful iframe handshake.
+ *
+ * @category Messages
+ */
+export interface ReadyMessage {
+    type: 'READY';
+    /** Feature set supported by this runner. */
+    capabilities: RunnerCapabilities;
+}
+/**
+ * Successful code execution result.
+ *
+ * @category Messages
+ */
+export interface RunOkMessage {
+    type: 'RUN_OK';
+    /** Runner-side completion timestamp. */
+    timestamp: number;
+    /** Request identifier when the run was initiated by a request/response host. */
+    requestId?: string;
+}
+/**
+ * Code execution failure result.
+ *
+ * @category Messages
+ */
+export interface RunErrorMessage {
+    type: 'RUN_ERROR';
+    /** Human-readable error message. */
+    message: string;
+    /** Optional stack trace. */
+    stack?: string;
+    /** Optional 1-based source line. */
+    line?: number;
+    /** Optional 1-based source column. */
+    column?: number;
+    /** Request identifier when the failure belongs to a request/response call. */
+    requestId?: string;
+}
+/**
+ * Shader synth parameter error reported by the runner.
+ *
+ * @category Messages
+ */
+export interface SynthErrorMessage {
+    type: 'SYNTH_ERROR';
+    /** Human-readable error message. */
+    message: string;
+    /** Uniform name associated with the error, when available. */
+    uniformName?: string;
+}
+/**
+ * Runner-originated shortcut event requesting host UI visibility changes.
+ *
+ * @category Messages
+ */
+export interface ToggleUIMessage {
+    type: 'TOGGLE_UI';
+}
+/**
+ * Runner-originated user interaction event.
+ *
+ * @category Messages
+ */
+export interface UserInteractionMessage {
+    type: 'USER_INTERACTION';
+}
+/**
+ * Export completion payload.
+ *
+ * @category Messages
+ */
+export interface ExportResultMessage {
+    type: 'EXPORT_RESULT';
+    /** Request identifier for the export call. */
+    requestId: string;
+    /** Completed export format. */
+    format: ExportRequest['format'];
+    /** Binary export result for blob-based formats. */
+    blob?: Blob;
+    /** Text export result for text-based formats. */
+    text?: string;
+    /** Suggested filename, when provided by the runner. */
+    filename?: string;
+    /** MIME type for the export result. */
+    mimeType?: string;
+}
+/**
+ * Progress payload for multi-frame exports.
+ *
+ * @category Messages
+ */
+export interface ExportProgressMessage {
+    type: 'EXPORT_PROGRESS';
+    /** Request identifier for the export call. */
+    requestId: string;
+    /** Streaming export format. */
+    format: 'gif' | 'webm';
+    /** Current progress snapshot. */
+    progress: ExportProgress;
+}
+/**
+ * Successful font load result.
+ *
+ * @category Messages
+ */
+export interface FontLoadedMessage {
+    type: 'FONT_LOADED';
+    /** Request identifier for the font load call. */
+    requestId: string;
+    /** Font family name detected by the runner. */
+    familyName: string | null;
+    /** Characters available in the loaded font. */
+    characters: string[];
+}
+/**
+ * Font load failure result.
+ *
+ * @category Messages
+ */
+export interface FontErrorMessage {
+    type: 'FONT_ERROR';
+    /** Request identifier for the font load call. */
+    requestId: string;
+    /** Human-readable error message. */
+    message: string;
+}
+/**
+ * Playback state response or event.
+ *
+ * @category Messages
+ */
+export interface PlaybackStateMessage {
+    type: 'PLAYBACK_STATE';
+    /** Request identifier when the state belongs to a playback request. */
+    requestId?: string;
+    /** Current playback state. */
+    state: PlaybackState;
+}
+/**
+ * Heartbeat response from the runner.
+ *
+ * @category Messages
+ */
+export interface PongMessage {
+    type: 'PONG';
+    /** Echoed heartbeat nonce. */
+    nonce?: string;
+    /** Runner-side response timestamp. */
+    timestamp: number;
+}
+/**
+ * Messages sent from the runner iframe to a host app.
+ *
+ * @category Messages
+ */
+export type RunnerToParentMessage = ReadyMessage | RunOkMessage | RunErrorMessage | SynthErrorMessage | ToggleUIMessage | UserInteractionMessage | ExportResultMessage | ExportProgressMessage | FontLoadedMessage | FontErrorMessage | PlaybackStateMessage | PongMessage;
+/**
+ * Request to execute code in the runner.
+ *
+ * @category Messages
+ */
+export interface RunCodeMessage {
+    type: 'RUN_CODE';
+    /** Source code to execute. */
+    code: string;
+    /** Optional request identifier for result routing. */
+    requestId?: string;
+}
+/**
+ * Request to reset frame state and execute code.
+ *
+ * @category Messages
+ */
+export interface SoftResetMessage {
+    type: 'SOFT_RESET';
+    /** Source code to execute after soft reset. */
+    code: string;
+    /** Optional request identifier for result routing. */
+    requestId?: string;
+}
+/**
+ * Request to dispose the runner runtime.
+ *
+ * @category Messages
+ */
+export interface DisposeMessage {
+    type: 'DISPOSE';
+}
+/**
+ * Request to initialize or reconfigure fixed runtime settings.
+ *
+ * @category Messages
+ */
+export interface ConfigureRuntimeMessage {
+    type: 'CONFIGURE_RUNTIME';
+    /** Complete runtime settings. */
+    settings: RuntimeSettings;
+    /** Optional request identifier for result routing. */
+    requestId?: string;
+}
+/**
+ * Request to update part of the current runtime settings.
+ *
+ * @category Messages
+ */
+export interface SetSettingsMessage {
+    type: 'SET_SETTINGS';
+    /** Partial runtime settings to apply. */
+    settings: Partial<RuntimeSettings>;
+    /** Optional request identifier for result routing. */
+    requestId?: string;
+}
+/**
+ * Request to export the current runner output.
+ *
+ * @category Messages
+ */
+export interface ExportMessage {
+    type: 'EXPORT';
+    /** Request identifier for result routing. */
+    requestId: string;
+    /** Requested export format. */
+    format: ExportRequest['format'];
+    /** Export options matching the requested format. */
+    options?: ExportRequest['options'];
+}
+/**
+ * Request to load a font file into the runner.
+ *
+ * @category Messages
+ */
+export interface LoadFontMessage {
+    type: 'LOAD_FONT';
+    /** Request identifier for result routing. */
+    requestId: string;
+    /** Original file name. */
+    fileName: string;
+    /** Browser-reported MIME type, when available. */
+    mimeType?: string;
+    /** Font file bytes. */
+    buffer: ArrayBuffer;
+}
+/**
+ * Request to control or inspect playback.
+ *
+ * @category Messages
+ */
+export interface PlaybackMessage {
+    type: 'PLAYBACK';
+    /** Optional request identifier for result routing. */
+    requestId?: string;
+    /** Playback action to perform. */
+    action: PlaybackAction;
+    /** Target frame for seek-like actions. */
+    frame?: number;
+    /** Maximum frame count for playback range updates. */
+    maxFrames?: number;
+}
+/**
+ * Heartbeat request sent by a host app.
+ *
+ * @category Messages
+ */
+export interface PingMessage {
+    type: 'PING';
+    /** Optional nonce echoed by the runner. */
+    nonce?: string;
+}
+/**
+ * Messages sent from a host app to the runner after handshake.
+ *
+ * @category Messages
+ */
+export type ParentToRunnerMessage = RunCodeMessage | SoftResetMessage | DisposeMessage | ConfigureRuntimeMessage | SetSettingsMessage | ExportMessage | LoadFontMessage | PlaybackMessage | PingMessage;
+/**
+ * Messages sent to the runner iframe window before MessagePort attachment.
+ *
+ * @category Messages
+ */
+export type WindowToRunnerMessage = InitMessage;
+/**
+ * Any message in the runner protocol.
+ *
+ * @category Messages
+ */
+export type Message = RunnerToParentMessage | ParentToRunnerMessage | WindowToRunnerMessage;

package/dist/messages.js

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

package/dist/playback.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Playback command accepted by the runner.
+ *
+ * @category Playback
+ */
+export type PlaybackAction = 'play' | 'pause' | 'stop' | 'seek' | 'next' | 'previous' | 'setMaxFrames' | 'state';
+/**
+ * Playback state snapshot emitted by the runner.
+ *
+ * @category Playback
+ */
+export interface PlaybackState {
+    /** Whether playback is actively advancing frames. */
+    isPlaying: boolean;
+    /** Current frame index. */
+    frame: number;
+    /** Maximum frame count used by playback controls. */
+    maxFrames: number;
+    /** Optional measured or configured frames per second. */
+    fps?: number;
+}

package/dist/playback.js

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

package/dist/runtime.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fixed runtime dimensions and timing used by configurable runner hosts.
+ *
+ * @category Runtime
+ */
+export interface RuntimeSettings {
+    /** Canvas width in CSS pixels. */
+    width: number;
+    /** Canvas height in CSS pixels. */
+    height: number;
+    /** Textmode font size in CSS pixels. */
+    fontSize: number;
+    /** Target animation frame rate. */
+    frameRate: number;
+}

package/dist/runtime.js

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

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@textmode/runner-protocol",
+    "version": "0.1.0",
+    "description": "Shared message protocol and validators for the hosted textmode runner iframe.",
+    "license": "CC0-1.0",
+    "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"
+    }
+}