moonscratch 0.1.0 → 0.1.2

package/js/test/variable.ts

@@ -1,200 +0,0 @@
-import { Project } from 'hikkaku'
-import {
-  add,
-  and,
-  changeVariableBy,
-  divide,
-  equals,
-  forEach,
-  getVariable,
-  gt,
-  ifElse,
-  ifThen,
-  join,
-  length,
-  multiply,
-  or,
-  repeat,
-  setVariableTo,
-  whenFlagClicked,
-} from 'hikkaku/blocks'
-import { describe, expect, test } from 'vite-plus/test'
-import {
-  createVmFromProject,
-  getStageVariable,
-  getTargetByName,
-  runUntilFinished,
-} from './helpers.ts'
-
-describe('js/test variable handling', () => {
-  test('executes arithmetic assignment and conditionally branches with variable values', () => {
-    const project = new Project()
-    const total = project.stage.createVariable('total', 0)
-    const multiplier = project.stage.createVariable('multiplier', 0)
-    const done = project.stage.createVariable('done', 0)
-
-    project.stage.run(() => {
-      whenFlagClicked(() => {
-        setVariableTo(total, 10)
-        setVariableTo(multiplier, 2)
-        changeVariableBy(total, multiply(multiplier.get(), 3))
-        setVariableTo(multiplier, divide(total.get(), 2))
-        ifThen(gt(multiplier.get(), 2), () => {
-          setVariableTo(total, add(total.get(), 10))
-        })
-        setVariableTo(done, 1)
-      })
-    })
-
-    const vm = createVmFromProject(project)
-    vm.greenFlag()
-    runUntilFinished(vm)
-
-    expect(getStageVariable(vm, total.id)).toBe(26)
-    expect(getStageVariable(vm, multiplier.id)).toBe(8)
-    expect(getStageVariable(vm, done.id)).toBe(1)
-  })
-
-  test('uses repeat and forEach to update variables deterministically', () => {
-    const project = new Project()
-    const running = project.stage.createVariable('running', 0)
-    const index = project.stage.createVariable('index', 0)
-
-    project.stage.run(() => {
-      whenFlagClicked(() => {
-        repeat(2, () => {
-          changeVariableBy(running, 1)
-        })
-        forEach(index, 4, () => {
-          changeVariableBy(running, 1)
-        })
-      })
-    })
-
-    const vm = createVmFromProject(project)
-    vm.greenFlag()
-    runUntilFinished(vm)
-
-    expect(getStageVariable(vm, running.id)).toBe(6)
-    expect(getStageVariable(vm, index.id)).toBe(4)
-  })
-
-  test('checks branch behavior with logical and numeric/string variable states', () => {
-    const project = new Project()
-    const total = project.stage.createVariable('total', 0)
-    const status = project.stage.createVariable('status', '')
-    const statusVerified = project.stage.createVariable('statusVerified', 0)
-
-    project.stage.run(() => {
-      whenFlagClicked(() => {
-        setVariableTo(total, 4)
-        setVariableTo(status, 'ready')
-        ifElse(
-          gt(total.get(), 3),
-          () => {
-            setVariableTo(status, join(status.get(), '!'))
-          },
-          () => {
-            setVariableTo(status, 'low')
-          },
-        )
-
-        ifThen(and(equals(status.get(), 'ready!'), gt(total.get(), 3)), () => {
-          setVariableTo(statusVerified, 1)
-        })
-
-        ifElse(
-          and(gt(total.get(), 5), equals(status.get(), 'ready!')),
-          () => {
-            changeVariableBy(total, 4)
-          },
-          () => {
-            changeVariableBy(total, -1)
-          },
-        )
-      })
-    })
-
-    const vm = createVmFromProject(project)
-    vm.greenFlag()
-    runUntilFinished(vm)
-
-    expect(getStageVariable(vm, total.id)).toBe(8)
-    expect(getStageVariable(vm, status.id)).toBe('ready!')
-    expect(getStageVariable(vm, statusVerified.id)).toBe(1)
-  })
-
-  test('derives a numeric summary from a string variable', () => {
-    const project = new Project()
-    const label = project.stage.createVariable('label', '')
-    const labelLength = project.stage.createVariable('labelLength', 0)
-    const isLong = project.stage.createVariable('isLong', 0)
-    const status = project.stage.createVariable('status', '')
-
-    project.stage.run(() => {
-      whenFlagClicked(() => {
-        setVariableTo(label, join('hello', ', world'))
-        setVariableTo(labelLength, length(label.get()))
-        ifElse(
-          gt(labelLength.get(), 8),
-          () => {
-            setVariableTo(status, 'long')
-          },
-          () => {
-            setVariableTo(status, 'short')
-          },
-        )
-        ifThen(
-          or(equals(status.get(), 'long'), equals(status.get(), 'short')),
-          () => {
-            setVariableTo(isLong, 1)
-          },
-        )
-      })
-    })
-
-    const vm = createVmFromProject(project)
-    vm.greenFlag()
-    runUntilFinished(vm)
-
-    expect(getStageVariable(vm, label.id)).toBe('hello, world')
-    expect(getStageVariable(vm, labelLength.id)).toBe(12)
-    expect(getStageVariable(vm, status.id)).toBe('long')
-    expect(getStageVariable(vm, isLong.id)).toBe(1)
-  })
-
-  test('updates sprite variables and shares values between stage and sprite scripts', () => {
-    const project = new Project()
-    const stageScore = project.stage.createVariable('stageScore', 0)
-    const sprite = project.createSprite('worker')
-    const spriteScore = sprite.createVariable('spriteScore', 0)
-
-    project.stage.run(() => {
-      whenFlagClicked(() => {
-        setVariableTo(stageScore, 2)
-      })
-    })
-
-    sprite.run(() => {
-      whenFlagClicked(() => {
-        setVariableTo(spriteScore, getVariable(stageScore))
-        repeat(2, () => {
-          changeVariableBy(spriteScore, getVariable(stageScore))
-        })
-        ifThen(gt(spriteScore.get(), 5), () => {
-          setVariableTo(
-            stageScore,
-            add(getVariable(stageScore), spriteScore.get()),
-          )
-        })
-      })
-    })
-
-    const vm = createVmFromProject(project)
-    vm.greenFlag()
-    runUntilFinished(vm)
-
-    expect(getStageVariable(vm, stageScore.id)).toBe(8)
-    expect(getTargetByName(vm, 'worker').variables[spriteScore.id]).toBe(6)
-  })
-})

package/js/test/warp.test.ts

@@ -1,59 +0,0 @@
-import { Project } from 'hikkaku'
-import {
-  callProcedure,
-  defineProcedure,
-  procedureLabel,
-  repeat,
-  say,
-  whenFlagClicked,
-} from 'hikkaku/blocks'
-import { describe, expect, it } from 'vite-plus/test'
-import { createHeadlessVM, createProgramModuleFromProject } from '../vm'
-
-describe('warp-exit', () => {
-  it('should emit warp-exit before finished', () => {
-    const project = new Project()
-    project.stage.run(() => {
-      const fn = defineProcedure(
-        [procedureLabel('myfn')],
-        () => {
-          // produce more blocks
-          for (let i = 0; i < 1000; i++) {
-            repeat(100, () => {
-              say('Hello')
-            })
-          }
-        },
-        true,
-      )
-      whenFlagClicked(() => {
-        repeat(3, () => {
-          callProcedure(fn, [])
-        })
-      })
-    })
-    const program = createProgramModuleFromProject({
-      projectJson: project.toScratch(),
-      assets: {},
-    })
-    const vm = createHeadlessVM({
-      program,
-      options: {
-        stepTimeoutTicks: 10000,
-        turbo: true,
-      },
-    })
-    vm.greenFlag()
-
-    const reasons: string[] = []
-    for (let i = 0; i < 16; i++) {
-      const frame = vm.stepFrame()
-      reasons.push(frame.stopReason)
-      if (frame.stopReason === 'finished') {
-        break
-      }
-    }
-    expect(reasons).toContain('warp-exit')
-    expect(reasons[reasons.length - 1]).toBe('finished')
-  })
-})

package/js/vm/AGENTS.md

@@ -1,6 +0,0 @@
-# js/vm
-
-- Manages VM bindings and execution support logic.
-- Maintains runtime/program WASM ABI bridging (`factory.ts`, `program-wasm.ts`); keep ABI checks and payload decoding explicit.
-- Since type guards, normalization, and JSON conversion are prone to spec drift, tests are required.
-- Use shared test data in `../test/test-projects.ts` to reduce duplication.

package/js/vm/README.md

@@ -1,183 +0,0 @@
-# VM Usage
-
-This folder provides a headless runtime API for running Scratch projects in TypeScript.
-
-Exports are available from `moonscratch` (the package entrypoint) and from
-`packages/moonscratch/js/vm` during local development.
-
-## Install and import
-
-```ts
-import {
-  createHeadlessVM,
-  createHeadlessVMFromProject,
-  createHeadlessVMWithScratchAssets,
-  precompileProgramForRuntime,
-  createProgramModuleFromProject,
-  HeadlessVM,
-} from 'moonscratch';
-```
-
-`createVM`, `createVMFromProject`, and `createVMWithScratchAssets` are aliases.
-
-## Basic usage
-
-```ts
-import { createHeadlessVM } from 'moonscratch';
-
-// Any Scratch 3.0 project JSON object or string.
-const projectJson = {
-  meta: { semver: '3.0.0', vm: '0.2.0', agent: 'example' },
-  targets: [
-    {
-      isStage: true,
-      name: 'Stage',
-      currentCostume: 0,
-      variables: {},
-      lists: {},
-      broadcasts: {},
-      costumes: [],
-      sounds: [],
-      blocks: {},
-    },
-  ],
-};
-
-const program = createProgramModuleFromProject({ projectJson });
-const vm = createHeadlessVM({
-  program,
-  options: {
-    turbo: true,
-    deterministic: true,
-    seed: 123,
-    compatibility_30tps: false,
-  },
-  viewerLanguage: 'en',
-});
-
-vm.start();     // initialize runtime state (optional in many cases)
-vm.greenFlag(); // press green flag
-vm.setTime(Date.now()); // update runtime clock explicitly
-const frame = vm.stepFrame(); // run until rerender/finished/timeout event
-console.log(frame.activeThreads);
-
-// Reuse the compiled program module for many VM instances.
-const vm2 = createHeadlessVM({ program });
-
-// Convenience helper: compile + instantiate + create VM in one call.
-const vm3 = createHeadlessVMFromProject({ projectJson });
-
-// Optional: precompile runtime artifact once, then create VMs.
-precompileProgramForRuntime({ program });
-const vm4 = createHeadlessVM({ program });
-```
-
-- `stepFrame()` advances until one of three events happens.
-  - `stopReason: 'rerender' | 'finished' | 'timeout'`.
-- `setTime(nowMs)` updates the runtime clock used by timer/wait behavior.
-
-## Input state
-
-`HeadlessVM` exposes helpers to update I/O state:
-
-```ts
-vm.setAnswer('Scratch');
-vm.setMouseState({ x: 120, y: 80, isDown: true });
-vm.setKeysDown(['space', 'arrowup']);
-vm.setTouching({ Sprite1: ['_mouse_'] });
-vm.setMouseTargets({ stage: true, targets: ['Sprite1'] });
-vm.setBackdrop('bg2');
-vm.postIO('username', 'alice'); // value as JsonValue
-vm.postIORawJson('loudness', '12');
-vm.broadcast('GO');
-```
-
-## Effects
-
-### Pull effects manually
-
-```ts
-const effects = vm.takeEffects();
-for (const effect of effects) {
-  if (effect.type === 'log') {
-    console.log(effect.level, effect.message);
-  }
-}
-```
-
-### Handle effects with handlers
-
-```ts
-await vm.handleEffects({
-  async translate({ words }) {
-    return words === 'hello' ? 'こんにちは' : null;
-  },
-  async textToSpeech(effect) {
-    await speak(effect.words, effect.voice);
-    vm.ackTextToSpeech(effect.waitKey);
-  },
-  musicNote(effect) {
-    playNote(effect.instrument, effect.note, effect.beats);
-  },
-  async musicDrum(effect) {
-    playDrum(effect.drum, effect.beats);
-  },
-  effect(effect) {
-    console.log('effect:', effect);
-  },
-});
-```
-
-`handleEffects` consumes the current effect queue and dispatches to provided handlers.
-
-## Snapshot and rendering
-
-```ts
-import { createHeadlessVM, renderWithSVG, renderWithSharp, renderWithWebGL } from 'moonscratch';
-
-const snapshot = vm.snapshot();
-const json = vm.snapshotJson();
-const frame = vm.renderFrame();
-const svg = renderWithSVG(frame);
-const png = await renderWithSharp(frame);
-const webgl = renderWithWebGL(frame);
-
-// Types:
-// snapshot: VMSnapshot
-// frame: RenderFrame
-// svg: SVG string
-// png: Buffer
-// webgl: { canvas, toImageData(), toImageElement() }
-```
-
-## Assets
-
-Use `createHeadlessVMWithScratchAssets` to load missing Scratch costume assets
-automatically from CDN.
-
-```ts
-const vm = await createHeadlessVMWithScratchAssets({
-  projectJson,
-  scratchCdnBaseUrl: 'https://cdn.scratch.mit.edu/internalapi/asset',
-  fetchAsset: (url) => fetch(url),
-  decodeImageBytes: async (bytes) => {
-    const image = await decodeToImage(bytes);
-    return {
-      width: image.width,
-      height: image.height,
-      rgbaBase64: image.rgbaBase64,
-    };
-  },
-});
-```
-
-If you already have assets in memory, pass them via `assets` (`Record<string, JsonValue>`).
-For missing ids, the API attempts to fetch and cache by `assetId` / `md5ext`.
-
-## Utility methods
-
-- `vm.raw`: underlying WASM runtime handle.
-- `vm.stopAll()`: stop all running sounds/threads.
-- `vm.setTime(nowMs)`: update VM clock (`sensing_timer`, waits, etc.).
-- `vm.setTranslateResult(words, language, translated)`: seed translate cache.
-- `vm.setTranslateCache(cache)` / `vm.clearTranslateCache()`.

package/js/vm/bindings.test.ts

@@ -1,13 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-
-import { moonscratch } from './bindings.ts'
-
-describe('moonscratch/js/vm/bindings.ts', () => {
-  test('exports generated vm bindings', () => {
-    expect(typeof moonscratch.vm_compile_from_json).toBe('function')
-    expect(typeof moonscratch.vm_new_from_compiled).toBe('function')
-    expect(typeof moonscratch.vm_step_frame).toBe('function')
-    expect(typeof moonscratch.vm_set_time).toBe('function')
-    expect(typeof moonscratch.vm_render_frame).toBe('function')
-  })
-})

package/js/vm/bindings.ts

@@ -1,5 +0,0 @@
-// biome-ignore lint/suspicious/noTsIgnore: we can't use ts-expect-error because states are dynamic
-// @ts-ignore
-import * as moonscratch from '../../_build/js/debug/build/moonscratch.js'
-
-export { moonscratch }

package/js/vm/compare-operators.test.ts

@@ -1,145 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-import { getStageVariables } from '../test/test-projects.ts'
-import { createHeadlessVM, createProgramModuleFromProject } from './factory.ts'
-import type { ProjectJson } from './types.ts'
-
-const COMPARE_OPERATOR_PROJECT: ProjectJson = {
-  targets: [
-    {
-      isStage: true,
-      name: 'Stage',
-      variables: {
-        var_lt_bad: ['lt_bad', 0],
-        var_lt_good: ['lt_good', 0],
-        var_gt_good: ['gt_good', 0],
-      },
-      lists: {},
-      blocks: {},
-    },
-    {
-      isStage: false,
-      name: 'Sprite1',
-      variables: {},
-      lists: {},
-      blocks: {
-        hat: {
-          opcode: 'event_whenflagclicked',
-          next: 'if_lt_bad',
-          parent: null,
-          inputs: {},
-          fields: {},
-          topLevel: true,
-        },
-        if_lt_bad: {
-          opcode: 'control_if',
-          next: 'if_lt_good',
-          parent: 'hat',
-          inputs: {
-            CONDITION: [2, 'lt_bad'],
-            SUBSTACK: [2, 'set_lt_bad'],
-          },
-          fields: {},
-          topLevel: false,
-        },
-        lt_bad: {
-          opcode: 'operator_lt',
-          next: null,
-          parent: 'if_lt_bad',
-          inputs: {
-            OPERAND1: [1, [4, -24]],
-            OPERAND2: [1, [4, -85]],
-          },
-          fields: {},
-          topLevel: false,
-        },
-        set_lt_bad: {
-          opcode: 'data_setvariableto',
-          next: null,
-          parent: 'if_lt_bad',
-          inputs: { VALUE: [1, [4, 1]] },
-          fields: { VARIABLE: ['lt_bad', 'var_lt_bad'] },
-          topLevel: false,
-        },
-        if_lt_good: {
-          opcode: 'control_if',
-          next: 'if_gt_good',
-          parent: 'if_lt_bad',
-          inputs: {
-            CONDITION: [2, 'lt_good'],
-            SUBSTACK: [2, 'set_lt_good'],
-          },
-          fields: {},
-          topLevel: false,
-        },
-        lt_good: {
-          opcode: 'operator_lt',
-          next: null,
-          parent: 'if_lt_good',
-          inputs: {
-            OPERAND1: [1, [4, -85]],
-            OPERAND2: [1, [4, -24]],
-          },
-          fields: {},
-          topLevel: false,
-        },
-        set_lt_good: {
-          opcode: 'data_setvariableto',
-          next: null,
-          parent: 'if_lt_good',
-          inputs: { VALUE: [1, [4, 1]] },
-          fields: { VARIABLE: ['lt_good', 'var_lt_good'] },
-          topLevel: false,
-        },
-        if_gt_good: {
-          opcode: 'control_if',
-          next: null,
-          parent: 'if_lt_good',
-          inputs: {
-            CONDITION: [2, 'gt_good'],
-            SUBSTACK: [2, 'set_gt_good'],
-          },
-          fields: {},
-          topLevel: false,
-        },
-        gt_good: {
-          opcode: 'operator_gt',
-          next: null,
-          parent: 'if_gt_good',
-          inputs: {
-            OPERAND1: [1, [4, -24]],
-            OPERAND2: [1, [4, -85]],
-          },
-          fields: {},
-          topLevel: false,
-        },
-        set_gt_good: {
-          opcode: 'data_setvariableto',
-          next: null,
-          parent: 'if_gt_good',
-          inputs: { VALUE: [1, [4, 1]] },
-          fields: { VARIABLE: ['gt_good', 'var_gt_good'] },
-          topLevel: false,
-        },
-      },
-    },
-  ],
-}
-
-describe('moonscratch/js/vm compare operators', () => {
-  test('compares negative numeric operands as numbers', () => {
-    const program = createProgramModuleFromProject({
-      projectJson: COMPARE_OPERATOR_PROJECT,
-    })
-    const vm = createHeadlessVM({
-      program,
-      initialNowMs: 0,
-    })
-    vm.greenFlag()
-    vm.setTime(16)
-    vm.stepFrame()
-
-    expect(getStageVariables(vm).var_lt_bad).toBe(0)
-    expect(getStageVariables(vm).var_lt_good).toBe(1)
-    expect(getStageVariables(vm).var_gt_good).toBe(1)
-  })
-})

package/js/vm/constants.test.ts

@@ -1,11 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-
-import { DEFAULT_FPS, DEFAULT_FRAME_MS, DEFAULT_LANGUAGE } from './constants.ts'
-
-describe('moonscratch/js/vm/constants.ts', () => {
-  test('exports default constants', () => {
-    expect(DEFAULT_LANGUAGE).toBe('en')
-    expect(DEFAULT_FPS).toBe(30)
-    expect(DEFAULT_FRAME_MS).toBeCloseTo(1000 / 30)
-  })
-})

package/js/vm/constants.ts

@@ -1,4 +0,0 @@
-export const DEFAULT_LANGUAGE = 'en'
-export const DEFAULT_FPS = 30
-export const DEFAULT_FRAME_MS = 1000 / DEFAULT_FPS
-export const DEFAULT_MAX_FRAMES = 10_000

package/js/vm/effect-guards.test.ts

@@ -1,68 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-
-import {
-  isMusicPlayDrumEffect,
-  isMusicPlayNoteEffect,
-  isTextToSpeechEffect,
-  isTranslateRequestEffect,
-} from './effect-guards.ts'
-
-describe('moonscratch/js/vm/effect-guards.ts', () => {
-  test('identifies translate_request effect', () => {
-    expect(
-      isTranslateRequestEffect({
-        type: 'translate_request',
-        words: 'hello',
-        language: 'ja',
-      }),
-    ).toBe(true)
-    expect(
-      isTranslateRequestEffect({ type: 'translate_request', words: 'hello' }),
-    ).toBe(false)
-  })
-
-  test('identifies text_to_speech effect', () => {
-    expect(
-      isTextToSpeechEffect({
-        type: 'text_to_speech',
-        target: 'Sprite1',
-        words: 'hello',
-        voice: 'TENOR',
-        language: 'ja',
-        waitKey: 'text2speech_done_1',
-      }),
-    ).toBe(true)
-    expect(
-      isTextToSpeechEffect({ type: 'text_to_speech', words: 'hello' }),
-    ).toBe(false)
-  })
-
-  test('identifies music effects', () => {
-    expect(
-      isMusicPlayNoteEffect({
-        type: 'music_play_note',
-        target: 'Sprite1',
-        note: 60,
-        beats: 1,
-        instrument: 1,
-        tempo: 120,
-      }),
-    ).toBe(true)
-    expect(
-      isMusicPlayDrumEffect({
-        type: 'music_play_drum',
-        target: 'Sprite1',
-        drum: 1,
-        beats: 0.5,
-        tempo: 120,
-      }),
-    ).toBe(true)
-    expect(
-      isMusicPlayDrumEffect({
-        type: 'music_play_drum',
-        target: 'Sprite1',
-        drum: 1,
-      }),
-    ).toBe(false)
-  })
-})