@kubohiroya/turbowarp-runtime-adapter 0.2.0

package/dist/index.js

@@ -0,0 +1,500 @@
+const broadcastHatOpcode = 'event_whenbroadcastreceived';
+const broadcastMessageType = 'broadcast_msg';
+const afterExecuteEvent = 'AFTER_EXECUTE';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function prefixedCode(prefix, suffix) {
+    if (!/^[A-Z][A-Z0-9]*$/u.test(prefix)) {
+        throw new TypeError('errorCodePrefix must be an uppercase diagnostic prefix.');
+    }
+    return `${prefix}-${suffix}`;
+}
+function hostError(code, message, cause) {
+    const error = new Error(message);
+    Object.defineProperty(error, 'code', { value: code });
+    if (cause !== undefined)
+        Object.defineProperty(error, 'cause', { value: cause });
+    return error;
+}
+function cancelledError(prefix, message) {
+    const error = hostError(prefixedCode(prefix, 'BROADCAST-CANCELLED'), message);
+    error.name = 'AbortError';
+    return error;
+}
+function removeRuntimeListener(runtime, event, listener) {
+    if (typeof runtime.off === 'function') {
+        runtime.off(event, listener);
+        return;
+    }
+    if (typeof runtime.removeListener === 'function') {
+        runtime.removeListener(event, listener);
+        return;
+    }
+    throw hostError('TWRH-RUNTIME-001', 'TurboWarp runtime must provide off or removeListener to dispose listeners.');
+}
+function validateRuntime(value) {
+    if (!isRecord(value)) {
+        throw hostError('TWRH-RUNTIME-001', 'TurboWarp runtime must be an object.');
+    }
+    if (typeof value['on'] !== 'function') {
+        throw hostError('TWRH-RUNTIME-001', 'TurboWarp runtime must provide on.');
+    }
+    if (typeof value['startHats'] !== 'function') {
+        throw hostError('TWRH-RUNTIME-001', 'TurboWarp runtime must provide startHats.');
+    }
+    return value;
+}
+function validateAbortSignal(value, prefix = 'TWRH') {
+    if (!isRecord(value) ||
+        typeof value['aborted'] !== 'boolean' ||
+        typeof value['addEventListener'] !== 'function' ||
+        typeof value['removeEventListener'] !== 'function') {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-CONTEXT-001'), 'broadcastMessageAndWait context must provide an AbortSignal.');
+    }
+    return value;
+}
+function requireMethod(runtime, method) {
+    const operation = runtime[method];
+    if (typeof operation !== 'function') {
+        throw hostError('TWRH-RUNTIME-001', `TurboWarp runtime must provide ${String(method)}.`);
+    }
+    return operation;
+}
+export function createTurboWarpRuntimeHost(options = {}) {
+    if (options.requireUnsandboxed === true && options.Scratch?.extensions?.unsandboxed !== true) {
+        throw hostError('TWRH-SCRATCH-001', 'TurboWarp runtime host requires unsandboxed Scratch.');
+    }
+    const runtime = validateRuntime(options.runtime ?? options.Scratch?.vm?.runtime);
+    return Object.freeze({
+        runtime,
+        onRuntimeEvent(event, listener) {
+            runtime.on(event, listener);
+            return () => removeRuntimeListener(runtime, event, listener);
+        },
+        startHats(opcode, matchFields) {
+            const threads = runtime.startHats(opcode, matchFields);
+            if (threads === undefined)
+                return [];
+            if (!Array.isArray(threads)) {
+                throw hostError('TWRH-RUNTIME-001', 'TurboWarp startHats must return an array or undefined.');
+            }
+            return threads;
+        },
+        stopThread(thread) {
+            requireMethod(runtime, '_stopThread').call(runtime, thread);
+        },
+        getStageTarget() {
+            return requireMethod(runtime, 'getTargetForStage').call(runtime);
+        },
+        currentThreads() {
+            if (runtime.threads === undefined)
+                return [];
+            if (!Array.isArray(runtime.threads)) {
+                throw hostError('TWRH-RUNTIME-001', 'TurboWarp runtime threads must be an array.');
+            }
+            return [...runtime.threads];
+        },
+        targets() {
+            return resolveTargets(runtime);
+        },
+        spriteTargets() {
+            return resolveTargets(runtime).filter((target) => !(isRecord(target) && target['isStage'] === true));
+        },
+        getRenderer() {
+            const renderer = runtime.renderer;
+            if (!isRecord(renderer)) {
+                throw hostError('TWRH-RENDERER-001', 'TurboWarp runtime has no attached renderer.');
+            }
+            return renderer;
+        },
+        requestRedraw() {
+            // A runtime without a renderer redraws on its own tick, so this stays a no-op rather than
+            // forcing every caller to feature-test before asking for a frame.
+            if (typeof runtime.requestRedraw === 'function')
+                runtime.requestRedraw();
+        },
+        getMonitorBlocks() {
+            return resolveMonitorBlocks(runtime);
+        },
+        getMonitorState() {
+            return resolveMonitorState(runtime);
+        }
+    });
+}
+function resolveTargets(runtime) {
+    if (runtime.targets === undefined)
+        return [];
+    if (!Array.isArray(runtime.targets)) {
+        throw hostError('TWRH-RUNTIME-001', 'TurboWarp runtime targets must be an array.');
+    }
+    return [...runtime.targets];
+}
+function resolveMonitorBlocks(runtime) {
+    const monitorBlocks = runtime.monitorBlocks;
+    if (!isRecord(monitorBlocks) ||
+        typeof monitorBlocks['getBlock'] !== 'function' ||
+        typeof monitorBlocks['getScripts'] !== 'function' ||
+        typeof monitorBlocks['changeBlock'] !== 'function') {
+        throw hostError('TWRH-MONITOR-001', 'TurboWarp monitor blocks are unavailable.');
+    }
+    return monitorBlocks;
+}
+function resolveMonitorState(runtime) {
+    const getMonitorState = runtime.getMonitorState;
+    if (typeof getMonitorState !== 'function') {
+        throw hostError('TWRH-MONITOR-001', 'TurboWarp runtime must provide getMonitorState.');
+    }
+    const monitorState = getMonitorState.call(runtime);
+    if (!isRecord(monitorState) ||
+        typeof monitorState['has'] !== 'function' ||
+        typeof monitorState['get'] !== 'function' ||
+        typeof monitorState['valueSeq'] !== 'function') {
+        throw hostError('TWRH-MONITOR-001', 'TurboWarp monitor state is unavailable.');
+    }
+    return monitorState;
+}
+function validateBroadcastRuntime(runtime, prefix) {
+    try {
+        requireMethod(runtime, 'getTargetForStage');
+        requireMethod(runtime, '_stopThread');
+    }
+    catch {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp runtime is missing required broadcast methods.');
+    }
+    if (!Array.isArray(runtime.threads)) {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp runtime threads must be an array.');
+    }
+    if (typeof runtime.off !== 'function' && typeof runtime.removeListener !== 'function') {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp runtime must provide off or removeListener.');
+    }
+    return runtime;
+}
+function resolveExactBroadcast(runtime, message, prefix) {
+    let stage;
+    try {
+        stage = requireMethod(runtime, 'getTargetForStage').call(runtime);
+    }
+    catch (cause) {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp Stage broadcasts could not be read.', cause);
+    }
+    if (!isRecord(stage) || !isRecord(stage['variables'])) {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp Stage broadcasts are unavailable.');
+    }
+    const declared = Object.values(stage['variables']).find((variable) => isRecord(variable) &&
+        variable['type'] === broadcastMessageType &&
+        variable['name'] === message);
+    return declared ? message : null;
+}
+function validateBroadcastPayload(payload, prefix) {
+    if (!isRecord(payload) ||
+        Object.keys(payload).length !== 1 ||
+        typeof payload['message'] !== 'string' ||
+        payload['message'].length === 0) {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-PAYLOAD-001'), 'broadcastMessageAndWait payload must contain one non-empty message string.');
+    }
+    return payload['message'];
+}
+export function createTurboWarpBroadcastPort(options) {
+    if (!isRecord(options)) {
+        throw hostError('TWRH-BROADCAST-RUNTIME-001', 'TurboWarp broadcast port options must be an object.');
+    }
+    const prefix = options.errorCodePrefix ?? 'TWRH';
+    let baseRuntime;
+    try {
+        baseRuntime = validateRuntime(options.runtime);
+    }
+    catch (cause) {
+        throw hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp broadcast port requires a valid runtime object.', cause);
+    }
+    const runtime = validateBroadcastRuntime(baseRuntime, prefix);
+    const activeInvocations = new Set();
+    let disposed = false;
+    function threadIsActive(thread) {
+        return runtime.threads?.includes(thread) === true;
+    }
+    function stopOwnedThreads(threads, reason) {
+        const errors = [];
+        for (const thread of threads) {
+            if (!threadIsActive(thread))
+                continue;
+            try {
+                requireMethod(runtime, '_stopThread').call(runtime, thread);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0) {
+            throw hostError(prefixedCode(prefix, 'BROADCAST-CLEANUP-001'), `TurboWarp broadcast receiver cleanup failed: ${reason}`, errors.length === 1 ? errors[0] : new AggregateError(errors));
+        }
+    }
+    return Object.freeze({
+        broadcastMessageAndWait(payload, context) {
+            if (disposed) {
+                return Promise.reject(hostError(prefixedCode(prefix, 'BROADCAST-DISPOSED'), 'TurboWarp broadcast port is disposed.'));
+            }
+            const message = validateBroadcastPayload(payload, prefix);
+            const signal = validateAbortSignal(context?.signal, prefix);
+            if (signal.aborted) {
+                return Promise.reject(cancelledError(prefix, 'broadcastMessageAndWait was cancelled.'));
+            }
+            const broadcastName = resolveExactBroadcast(runtime, message, prefix);
+            if (broadcastName === null)
+                return Promise.resolve();
+            let started;
+            try {
+                started = runtime.startHats(broadcastHatOpcode, { BROADCAST_OPTION: broadcastName });
+            }
+            catch (cause) {
+                throw hostError(prefixedCode(prefix, 'BROADCAST-START-001'), 'TurboWarp broadcast receiver threads could not be started.', cause);
+            }
+            const threads = started ?? [];
+            if (!Array.isArray(threads)) {
+                throw hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp startHats must return an array or undefined.');
+            }
+            if (threads.length === 0)
+                return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                let runtimeListenerAttached = false;
+                let abortListenerAttached = false;
+                const invocation = {
+                    cancel(messageText) {
+                        settleCancelled(messageText);
+                    }
+                };
+                const cleanup = (reason) => {
+                    const errors = [];
+                    if (runtimeListenerAttached) {
+                        runtimeListenerAttached = false;
+                        try {
+                            removeRuntimeListener(runtime, afterExecuteEvent, handleAfterExecute);
+                        }
+                        catch (error) {
+                            errors.push(error);
+                        }
+                    }
+                    if (abortListenerAttached) {
+                        abortListenerAttached = false;
+                        signal.removeEventListener('abort', handleAbort);
+                    }
+                    activeInvocations.delete(invocation);
+                    try {
+                        stopOwnedThreads(threads, reason);
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                    if (errors.length > 0) {
+                        throw hostError(prefixedCode(prefix, 'BROADCAST-CLEANUP-001'), `TurboWarp broadcast cleanup failed: ${reason}`, errors.length === 1 ? errors[0] : new AggregateError(errors));
+                    }
+                };
+                const settle = (operation, reason) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    try {
+                        cleanup(reason);
+                        operation();
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                };
+                const settleCancelled = (messageText) => {
+                    settle(() => reject(cancelledError(prefix, messageText)), 'cancelled');
+                };
+                const handleAbort = () => {
+                    settleCancelled('broadcastMessageAndWait was cancelled.');
+                };
+                const handleAfterExecute = () => {
+                    if (threads.every((thread) => !threadIsActive(thread))) {
+                        settle(resolve, 'completed');
+                    }
+                };
+                activeInvocations.add(invocation);
+                try {
+                    runtime.on(afterExecuteEvent, handleAfterExecute);
+                    runtimeListenerAttached = true;
+                    signal.addEventListener('abort', handleAbort, { once: true });
+                    abortListenerAttached = true;
+                }
+                catch (cause) {
+                    settled = true;
+                    const errors = [
+                        hostError(prefixedCode(prefix, 'BROADCAST-RUNTIME-001'), 'TurboWarp broadcast receiver completion could not be observed.', cause)
+                    ];
+                    try {
+                        cleanup('observer setup failure');
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                    reject(errors.length === 1
+                        ? errors[0]
+                        : hostError(prefixedCode(prefix, 'BROADCAST-CLEANUP-001'), 'TurboWarp broadcast observer setup cleanup failed.', new AggregateError(errors)));
+                    return;
+                }
+                if (signal.aborted)
+                    handleAbort();
+                else
+                    handleAfterExecute();
+            });
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const invocation of [...activeInvocations]) {
+                invocation.cancel('TurboWarp broadcast port was disposed.');
+            }
+        }
+    });
+}
+function requireBlockType(vocabulary, name) {
+    const value = vocabulary.BlockType[name];
+    if (typeof value !== 'string') {
+        throw hostError('TWRH-BLOCK-001', `Scratch.BlockType.${name} is required.`);
+    }
+    return value;
+}
+function requireArgumentType(vocabulary, name) {
+    const value = vocabulary.ArgumentType[name];
+    if (typeof value !== 'string') {
+        throw hostError('TWRH-BLOCK-001', `Scratch.ArgumentType.${name} is required.`);
+    }
+    return value;
+}
+function validateBlockSpec(spec) {
+    if (!isRecord(spec) || typeof spec.opcode !== 'string' || spec.opcode.length === 0) {
+        throw hostError('TWRH-BLOCK-002', 'A block spec must provide a non-empty opcode.');
+    }
+    if (typeof spec.text !== 'string' || spec.text.length === 0) {
+        throw hostError('TWRH-BLOCK-002', `Block ${spec.opcode} must provide non-empty text.`);
+    }
+    return spec;
+}
+/**
+ * Build the repetitive parts of an extension's `getInfo()` block list.
+ *
+ * The builder owns record shape and palette visibility only. Opcodes, block text, menu items, and
+ * every other app-specific decision stay with the caller, so nothing about a concrete app leaks
+ * into this package.
+ */
+export function createBlockSurfaceBuilder(vocabulary, options = {}) {
+    if (!isRecord(vocabulary) ||
+        !isRecord(vocabulary.ArgumentType) ||
+        !isRecord(vocabulary.BlockType)) {
+        throw hostError('TWRH-BLOCK-001', 'Block surface requires Scratch ArgumentType and BlockType records.');
+    }
+    if (options.visible !== undefined && typeof options.visible !== 'boolean') {
+        throw hostError('TWRH-BLOCK-001', 'Block surface visible must be boolean.');
+    }
+    const defaultVisible = options.visible ?? true;
+    function build(spec, blockTypeName, monitorable) {
+        validateBlockSpec(spec);
+        const visible = spec.visible ?? defaultVisible;
+        const record = {
+            opcode: spec.opcode,
+            blockType: requireBlockType(vocabulary, blockTypeName),
+            text: spec.text,
+            hideFromPalette: !visible
+        };
+        if (spec.arguments !== undefined)
+            record.arguments = Object.freeze({ ...spec.arguments });
+        if (monitorable && (spec.monitor ?? false) === false)
+            record.disableMonitor = true;
+        return Object.freeze(record);
+    }
+    return Object.freeze({
+        reporter(spec) {
+            return build(spec, 'REPORTER', true);
+        },
+        boolean(spec) {
+            return build(spec, 'BOOLEAN', false);
+        },
+        command(spec) {
+            return build(spec, 'COMMAND', false);
+        },
+        hat(spec) {
+            return build(spec, 'HAT', false);
+        },
+        reporters(entries, reporterOptions = {}) {
+            if (!Array.isArray(entries)) {
+                throw hostError('TWRH-BLOCK-002', 'Block reporters must be an array of entries.');
+            }
+            return Object.freeze(entries.map(([opcode, text]) => build({
+                opcode,
+                text,
+                ...(reporterOptions.visible === undefined ? {} : { visible: reporterOptions.visible }),
+                ...(reporterOptions.monitor === undefined ? {} : { monitor: reporterOptions.monitor })
+            }, 'REPORTER', true)));
+        },
+        stringArgument(defaultValue = '') {
+            return Object.freeze({ type: requireArgumentType(vocabulary, 'STRING'), defaultValue });
+        },
+        numberArgument(defaultValue = 0) {
+            return Object.freeze({ type: requireArgumentType(vocabulary, 'NUMBER'), defaultValue });
+        },
+        menuArgument(menu) {
+            if (typeof menu !== 'string' || menu.length === 0) {
+                throw hostError('TWRH-BLOCK-002', 'A menu argument must name a non-empty menu.');
+            }
+            return Object.freeze({ type: requireArgumentType(vocabulary, 'STRING'), menu });
+        },
+        menu(items, menuOptions = {}) {
+            if (!Array.isArray(items) || items.length === 0) {
+                throw hostError('TWRH-BLOCK-002', 'A block menu must list at least one item.');
+            }
+            return Object.freeze({
+                acceptReporters: menuOptions.acceptReporters ?? false,
+                items: Object.freeze([...items])
+            });
+        },
+        surface(blocks, menus = {}) {
+            if (!Array.isArray(blocks)) {
+                throw hostError('TWRH-BLOCK-002', 'A block surface must provide an array of blocks.');
+            }
+            const opcodes = new Set();
+            for (const block of blocks) {
+                if (opcodes.has(block.opcode)) {
+                    throw hostError('TWRH-BLOCK-002', `Duplicate block opcode: ${block.opcode}`);
+                }
+                opcodes.add(block.opcode);
+            }
+            return Object.freeze({
+                blocks: Object.freeze([...blocks]),
+                menus: Object.freeze({ ...menus })
+            });
+        }
+    });
+}
+/**
+ * Coerce one Scratch block argument to a scalar of the named type.
+ *
+ * Scratch hands every argument over as a string, so a writable scalar surface has to decide what
+ * counts as a number or a boolean. That decision is the same in every app, while the diagnostic
+ * codes are not, so the prefix is injectable the way {@link createTurboWarpBroadcastPort} does it.
+ */
+export function coerceScalarBlockValue(value, type, options = {}) {
+    const prefix = options.errorCodePrefix ?? 'TWRH';
+    if (type === 'string')
+        return Object.freeze({ ok: true, value: String(value ?? '') });
+    if (type === 'number') {
+        const number = typeof value === 'number' ? value : Number(value);
+        return Number.isFinite(number)
+            ? Object.freeze({ ok: true, value: number })
+            : Object.freeze({ ok: false, code: prefixedCode(prefix, 'VARIABLE-WRITE-VALUE') });
+    }
+    if (type === 'boolean') {
+        if (typeof value === 'boolean')
+            return Object.freeze({ ok: true, value });
+        if (value === 'true')
+            return Object.freeze({ ok: true, value: true });
+        if (value === 'false')
+            return Object.freeze({ ok: true, value: false });
+        return Object.freeze({ ok: false, code: prefixedCode(prefix, 'VARIABLE-WRITE-VALUE') });
+    }
+    return Object.freeze({ ok: false, code: prefixedCode(prefix, 'VARIABLE-WRITE-TYPE') });
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@kubohiroya/turbowarp-runtime-adapter",
+  "version": "0.2.0",
+  "description": "App-neutral adapters for interacting with the TurboWarp runtime.",
+  "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
+  "license": "MPL-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "homepage": "https://github.com/kubohiroya/turbowarp-runtime-adapter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kubohiroya/turbowarp-runtime-adapter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kubohiroya/turbowarp-runtime-adapter/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "README.ja.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "pnpm@11.11.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc --project tsconfig.build.json",
+    "pack:check": "pnpm pack --dry-run",
+    "release:check": "npm publish --dry-run --access public",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run pack:check"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "keywords": [
+    "turbowarp",
+    "scratch",
+    "runtime",
+    "adapter"
+  ]
+}