@kubohiroya/turbowarp-runtime-adapter 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.2.0
+
+- Add target enumeration to the runtime host: `targets()` returns a copy of every loaded target and `spriteTargets()` drops the Stage. An absent target list reads as empty; a non-array one is a runtime fault.
+- Add renderer access: `getRenderer()` returns the attached renderer and throws when there is none, while `requestRedraw()` stays a no-op on a runtime that does not provide it.
+- Add monitor access: `getMonitorBlocks()` and `getMonitorState()` validate the `data_showvariable` / `data_hidevariable` block store and monitor record map before handing them back. `getMonitorState` is invoked with the runtime as its receiver.
+- Add `createBlockSurfaceBuilder`, which builds the repetitive parts of an extension `getInfo()` block list from an injected `Scratch.BlockType` / `Scratch.ArgumentType` pair. It owns record shape, palette visibility, reporter monitor defaults, and duplicate-opcode detection; opcodes, block text, and menu items stay with the caller.
+- Add `coerceScalarBlockValue` for the string/number/boolean coercion a writable scalar block surface needs, with the same injectable `errorCodePrefix` the broadcast port uses.
+- No behavior change to any 0.1.0 export.
+
+## 0.1.0
+
+- Initial public package shape for app-neutral TurboWarp runtime host adapters.
+- Add broadcast action port support with exact Stage broadcast lookup, owned-thread waiting, abort, and dispose behavior.
+- Add compatibility-oriented error code prefixing for consumers that need stable app-specific error codes.

package/LICENSE

@@ -0,0 +1,6 @@
+Mozilla Public License Version 2.0
+==================================
+
+This repository uses the Mozilla Public License Version 2.0.
+
+See https://www.mozilla.org/MPL/2.0/ for the full license text.

package/README.ja.md

@@ -0,0 +1,108 @@
+# turbowarp-runtime-adapter
+
+[English](README.md)
+
+`@kubohiroya/turbowarp-runtime-adapter` は、unsandboxed extension や packaged TurboWarp app から TurboWarp runtime を操作するための、アプリ非依存の adapter を提供します。
+
+この package は、アプリ固有の DSL semantics、block metadata、story/navigation、pose、3D scene graph policy を定義しません。それらは `tm-kamishibai` や `tm-3d-app` などの app package 側に残します。
+
+## 役割
+
+- `Scratch.vm.runtime` または明示された runtime object から runtime を解決する。
+- runtime event を disposable listener として購読する。
+- 小さく検証された host adapter 経由で hats を起動する。
+- Stage target、sprite target、renderer、monitor store を読む。
+- Stage に宣言された exact broadcast name 用の汎用 `broadcastMessageAndWait` port を提供する。
+- extension の `getInfo()` block list のうち定型部分を組み立てる。
+- Scratch VM への直接アクセスを狭い interface に閉じ込める。
+
+## runtime surface
+
+`createTurboWarpRuntimeHost` は session ごとに 1 つの adapter を返します。raw runtime を持ち回すのではなく
+この adapter を注入してください。Stage しか必要としない consumer は、runtime 全体の形ではなく
+`getStageTarget()` だけに依存できます。
+
+| member | 参照先 |
+| --- | --- |
+| `runtime` | 検証済み runtime。この package がまだ所有していない操作向け |
+| `onRuntimeEvent(event, listener)` | 購読し、解除関数を返す |
+| `startHats(opcode, matchFields?)` | 常に配列。`undefined` を返さない |
+| `stopThread(thread)` / `currentThreads()` | `_stopThread` / `threads` |
+| `getStageTarget()` | `getTargetForStage()` |
+| `targets()` / `spriteTargets()` | `targets` の複製。`spriteTargets` は Stage を除く |
+| `getRenderer()` / `requestRedraw()` | `renderer`。`requestRedraw` は未提供なら no-op |
+| `getMonitorBlocks()` / `getMonitorState()` | 検証済みの monitor block store と record map |
+
+## block surface
+
+`createBlockSurfaceBuilder` は、extension が既に持っている `Scratch.BlockType` / `Scratch.ArgumentType`
+を受け取って block record を組み立てます。record の形、palette 可視性、reporter の monitor 既定値、
+opcode 重複検出だけを所有します。opcode・block text・menu 項目は caller 側に残るため、アプリ固有の
+語彙はこの package に入りません。
+
+```ts
+import {coerceScalarBlockValue, createBlockSurfaceBuilder} from '@kubohiroya/turbowarp-runtime-adapter';
+
+const build = createBlockSurfaceBuilder({ArgumentType, BlockType}, {visible: stateVisible});
+const surface = build.surface(
+  [
+    build.reporter({opcode: 'sceneId', text: 'current scene id'}),
+    ...build.reporters([
+      ['status', 'story status'],
+      ['version', 'runtime version']
+    ]),
+    build.command({
+      opcode: 'setVariable',
+      text: 'set [NAME] to [VALUE] as [TYPE]',
+      arguments: {
+        NAME: build.stringArgument(),
+        VALUE: build.stringArgument(),
+        TYPE: build.menuArgument('scalarTypes')
+      },
+      visible: writeVisible
+    })
+  ],
+  {scalarTypes: build.menu(['string', 'number', 'boolean'])}
+);
+
+const written = coerceScalarBlockValue(args.VALUE, args.TYPE, {errorCodePrefix: 'K4'});
+```
+
+## 互換性
+
+既存 app が安定した app 固有 diagnostics を公開している場合は、`errorCodePrefix` を渡せます。たとえば `tm-kamishibai` は runtime interaction mechanics をこの package に委譲しつつ、`K4-BROADCAST-*` error を維持できます。
+
+## 使用例
+
+```ts
+import {
+  createTurboWarpBroadcastPort,
+  createTurboWarpRuntimeHost
+} from '@kubohiroya/turbowarp-runtime-adapter';
+
+const host = createTurboWarpRuntimeHost({Scratch});
+const broadcast = createTurboWarpBroadcastPort({
+  runtime: host.runtime,
+  errorCodePrefix: 'K4'
+});
+
+const dispose = host.onRuntimeEvent('PROJECT_STOP_ALL', () => {
+  console.log('stopped');
+});
+
+await broadcast.broadcastMessageAndWait(
+  {message: 'openScene'},
+  {signal: new AbortController().signal}
+);
+
+dispose();
+```
+
+## 開発
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm run check
+pnpm run release:check
+```

package/README.md

@@ -0,0 +1,108 @@
+# turbowarp-runtime-adapter
+
+[日本語](README.ja.md)
+
+`@kubohiroya/turbowarp-runtime-adapter` provides app-neutral adapters for interacting with the TurboWarp runtime from unsandboxed extensions and packaged TurboWarp apps.
+
+This package intentionally does not define app-specific DSL semantics, block metadata, story/navigation behavior, pose handling, or 3D scene graph policy. Those remain in app packages such as `tm-kamishibai` and `tm-3d-app`.
+
+## Scope
+
+- Resolve a runtime from `Scratch.vm.runtime` or an explicit runtime object.
+- Subscribe to runtime events with disposable listeners.
+- Start hats through a small validated host adapter.
+- Read the Stage target, the sprite targets, the renderer, and the monitor stores.
+- Provide a generic `broadcastMessageAndWait` port for exact Stage broadcast names.
+- Build the repetitive parts of an extension `getInfo()` block list.
+- Keep Scratch VM access behind a narrow interface.
+
+## Runtime surface
+
+`createTurboWarpRuntimeHost` returns one adapter per session. Inject it rather than passing a raw
+runtime around: a consumer that only needs the Stage then depends on `getStageTarget()` alone, not
+on the whole runtime shape.
+
+| Member | Reads |
+| --- | --- |
+| `runtime` | the validated runtime, for anything this package does not own yet |
+| `onRuntimeEvent(event, listener)` | subscribes and returns a disposer |
+| `startHats(opcode, matchFields?)` | always an array, never `undefined` |
+| `stopThread(thread)` / `currentThreads()` | `_stopThread` / `threads` |
+| `getStageTarget()` | `getTargetForStage()` |
+| `targets()` / `spriteTargets()` | `targets`, copied; `spriteTargets` drops the Stage |
+| `getRenderer()` / `requestRedraw()` | `renderer`; `requestRedraw` is a no-op when absent |
+| `getMonitorBlocks()` / `getMonitorState()` | the validated monitor block store and record map |
+
+## Block surfaces
+
+`createBlockSurfaceBuilder` takes the `Scratch.BlockType` / `Scratch.ArgumentType` pair an
+extension already has and builds block records from it. It owns record shape, palette visibility,
+reporter monitor defaults, and duplicate-opcode detection. Opcodes, block text, and menu items stay
+with the caller, so no app vocabulary enters this package.
+
+```ts
+import {coerceScalarBlockValue, createBlockSurfaceBuilder} from '@kubohiroya/turbowarp-runtime-adapter';
+
+const build = createBlockSurfaceBuilder({ArgumentType, BlockType}, {visible: stateVisible});
+const surface = build.surface(
+  [
+    build.reporter({opcode: 'sceneId', text: 'current scene id'}),
+    ...build.reporters([
+      ['status', 'story status'],
+      ['version', 'runtime version']
+    ]),
+    build.command({
+      opcode: 'setVariable',
+      text: 'set [NAME] to [VALUE] as [TYPE]',
+      arguments: {
+        NAME: build.stringArgument(),
+        VALUE: build.stringArgument(),
+        TYPE: build.menuArgument('scalarTypes')
+      },
+      visible: writeVisible
+    })
+  ],
+  {scalarTypes: build.menu(['string', 'number', 'boolean'])}
+);
+
+const written = coerceScalarBlockValue(args.VALUE, args.TYPE, {errorCodePrefix: 'K4'});
+```
+
+## Compatibility
+
+Consumers that already expose stable app-specific diagnostics can pass `errorCodePrefix`. For example, `tm-kamishibai` can keep `K4-BROADCAST-*` errors while delegating the runtime interaction mechanics to this package.
+
+## Example
+
+```ts
+import {
+  createTurboWarpBroadcastPort,
+  createTurboWarpRuntimeHost
+} from '@kubohiroya/turbowarp-runtime-adapter';
+
+const host = createTurboWarpRuntimeHost({Scratch});
+const broadcast = createTurboWarpBroadcastPort({
+  runtime: host.runtime,
+  errorCodePrefix: 'K4'
+});
+
+const dispose = host.onRuntimeEvent('PROJECT_STOP_ALL', () => {
+  console.log('stopped');
+});
+
+await broadcast.broadcastMessageAndWait(
+  {message: 'openScene'},
+  {signal: new AbortController().signal}
+);
+
+dispose();
+```
+
+## Development
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm run check
+pnpm run release:check
+```

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+export interface ScratchRuntimeHost {
+    vm?: {
+        runtime?: unknown;
+    };
+    extensions?: {
+        unsandboxed?: boolean;
+    };
+}
+export interface TurboWarpRuntimeLike {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    off?: (event: string, listener: (...args: unknown[]) => void) => void;
+    removeListener?: (event: string, listener: (...args: unknown[]) => void) => void;
+    startHats(opcode: string, matchFields?: Record<string, string>): unknown[] | undefined;
+    getTargetForStage?: () => unknown;
+    _stopThread?: (thread: unknown) => void;
+    threads?: unknown[];
+    targets?: unknown[];
+    renderer?: unknown;
+    requestRedraw?: () => void;
+    monitorBlocks?: unknown;
+    getMonitorState?: () => unknown;
+}
+/**
+ * The Scratch monitor block store, as used by the `data_showvariable` and `data_hidevariable`
+ * primitives. Only the members needed to read and toggle a monitor are declared.
+ */
+export interface TurboWarpMonitorBlocks {
+    getBlock(id: string): unknown;
+    getScripts(): string[];
+    changeBlock(change: {
+        id: string;
+        element: string;
+        value: unknown;
+    }): void;
+}
+/** The immutable monitor record map the runtime keeps alongside {@link TurboWarpMonitorBlocks}. */
+export interface TurboWarpMonitorState {
+    has(id: string): boolean;
+    get(id: string): unknown;
+    valueSeq(): Iterable<unknown>;
+}
+export interface TurboWarpRuntimeHostOptions {
+    Scratch?: ScratchRuntimeHost;
+    runtime?: unknown;
+    requireUnsandboxed?: boolean;
+}
+export interface TurboWarpRuntimeHost {
+    runtime: TurboWarpRuntimeLike;
+    onRuntimeEvent(event: string, listener: (...args: unknown[]) => void): () => void;
+    startHats(opcode: string, matchFields?: Record<string, string>): unknown[];
+    stopThread(thread: unknown): void;
+    getStageTarget(): unknown;
+    currentThreads(): unknown[];
+    /** Every loaded target, Stage included, as a copy the caller may not mutate in place. */
+    targets(): unknown[];
+    /** Every loaded target except the Stage, in runtime order. */
+    spriteTargets(): unknown[];
+    /** The renderer the VM attached. Throws when the runtime has none. */
+    getRenderer(): unknown;
+    /** Ask the renderer for a frame. A runtime without `requestRedraw` is a no-op, not an error. */
+    requestRedraw(): void;
+    getMonitorBlocks(): TurboWarpMonitorBlocks;
+    getMonitorState(): TurboWarpMonitorState;
+}
+export interface BroadcastPortContext {
+    signal: AbortSignal;
+}
+export interface TurboWarpBroadcastPort {
+    broadcastMessageAndWait(payload: {
+        message: string;
+    }, context: BroadcastPortContext): Promise<void>;
+    dispose(): void;
+}
+export interface TurboWarpBroadcastPortOptions {
+    runtime: unknown;
+    errorCodePrefix?: string;
+}
+export declare function createTurboWarpRuntimeHost(options?: TurboWarpRuntimeHostOptions): TurboWarpRuntimeHost;
+export declare function createTurboWarpBroadcastPort(options: TurboWarpBroadcastPortOptions): TurboWarpBroadcastPort;
+/**
+ * The `Scratch.BlockType` / `Scratch.ArgumentType` pair an extension's `getInfo()` builds against.
+ * Passing them in keeps this package free of any ambient `Scratch` global.
+ */
+export interface ScratchBlockVocabulary {
+    ArgumentType: Record<string, string>;
+    BlockType: Record<string, string>;
+}
+export interface BlockArgumentRecord {
+    type: string;
+    defaultValue?: string | number | boolean;
+    menu?: string;
+}
+export interface BlockRecord {
+    opcode: string;
+    blockType: string;
+    text: string;
+    arguments?: Readonly<Record<string, BlockArgumentRecord>>;
+    hideFromPalette?: boolean;
+    disableMonitor?: boolean;
+}
+export interface BlockMenuRecord {
+    acceptReporters: boolean;
+    items: readonly string[];
+}
+export interface BlockSpec {
+    opcode: string;
+    text: string;
+    arguments?: Readonly<Record<string, BlockArgumentRecord>>;
+    /** Defaults to the builder's own visibility. */
+    visible?: boolean;
+    /** Reporters default to `true`; other block types ignore it. */
+    monitor?: boolean;
+}
+export interface BlockSurfaceBuilderOptions {
+    /** Default palette visibility for every block this builder makes. Defaults to `true`. */
+    visible?: boolean;
+}
+export interface BlockSurfaceBuilder {
+    reporter(spec: BlockSpec): BlockRecord;
+    boolean(spec: BlockSpec): BlockRecord;
+    command(spec: BlockSpec): BlockRecord;
+    hat(spec: BlockSpec): BlockRecord;
+    /** Build a run of plain reporters from `[opcode, text]` pairs. */
+    reporters(entries: readonly (readonly [string, string])[], options?: {
+        visible?: boolean;
+        monitor?: boolean;
+    }): readonly BlockRecord[];
+    stringArgument(defaultValue?: string): BlockArgumentRecord;
+    numberArgument(defaultValue?: number): BlockArgumentRecord;
+    menuArgument(menu: string): BlockArgumentRecord;
+    menu(items: readonly string[], options?: {
+        acceptReporters?: boolean;
+    }): BlockMenuRecord;
+    surface(blocks: readonly BlockRecord[], menus?: Readonly<Record<string, BlockMenuRecord>>): Readonly<{
+        blocks: readonly BlockRecord[];
+        menus: Readonly<Record<string, BlockMenuRecord>>;
+    }>;
+}
+/**
+ * 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 declare function createBlockSurfaceBuilder(vocabulary: ScratchBlockVocabulary, options?: BlockSurfaceBuilderOptions): BlockSurfaceBuilder;
+export type ScalarBlockValueType = 'string' | 'number' | 'boolean';
+export type ScalarBlockValueResult = Readonly<{
+    ok: true;
+    value: string | number | boolean;
+}> | Readonly<{
+    ok: false;
+    code: string;
+}>;
+/**
+ * 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 declare function coerceScalarBlockValue(value: unknown, type: string, options?: {
+    errorCodePrefix?: string;
+}): ScalarBlockValueResult;