moonscratch 0.1.0 → 0.1.2

package/js/vm/headless-vm.test.ts

@@ -1,131 +0,0 @@
-import { describe, expect, test, vi } from 'vite-plus/test'
-import { renderWithSVG } from '../render/index.ts'
-import {
-  EXAMPLE_PROJECT,
-  getStageVariables,
-  INPUT_EVENT_PROJECT,
-  stepMany,
-  TEXT_TO_SPEECH_TRANSLATE_PROJECT,
-} from '../test/test-projects.ts'
-import { createHeadlessVM, createProgramModuleFromProject } from './factory.ts'
-import type { CreateHeadlessVMOptions, ProjectJson } from './types.ts'
-
-describe('moonscratch/js/vm/headless-vm.ts', () => {
-  const createVm = (
-    projectJson: ProjectJson,
-    overrides: Omit<CreateHeadlessVMOptions, 'program'> = {},
-  ) => {
-    const program = createProgramModuleFromProject({ projectJson })
-    return createHeadlessVM({
-      program,
-      ...overrides,
-    })
-  }
-
-  test('runs project and normalizes frame values', () => {
-    const vm = createVm(EXAMPLE_PROJECT, {
-      initialNowMs: 0,
-    })
-    vm.greenFlag()
-    expect(getStageVariables(vm).var_score).toBe(42)
-    vm.setTime(17)
-
-    const first = vm.stepFrame()
-    const second = vm.stepFrame()
-
-    expect(first).toEqual({
-      activeThreads: 0,
-      ticks: 0,
-      ops: 0,
-      emittedEffects: 0,
-      stopReason: 'finished',
-      shouldRender: true,
-      isInWarp: false,
-    })
-    expect(second.stopReason).toBe('finished')
-    expect(getStageVariables(vm).var_score).toBe(42)
-  })
-
-  test('renders current scene with renderFrame and renderWithSVG', () => {
-    const vm = createVm(EXAMPLE_PROJECT)
-    const frame = vm.renderFrame()
-    const svg = renderWithSVG(frame)
-
-    expect(frame.width).toBeGreaterThan(0)
-    expect(frame.height).toBeGreaterThan(0)
-    expect(frame.pixels.length).toBe(frame.width * frame.height * 4)
-    expect(svg).toContain('<svg')
-    expect(svg).toContain('shape-rendering="crispEdges"')
-    expect(svg).toContain('fill="rgb(255,255,255)"')
-    expect(svg).toContain('</svg>')
-  })
-
-  test('detects click and key hats from input state', () => {
-    const vm = createVm(INPUT_EVENT_PROJECT, {
-      initialNowMs: 0,
-    })
-    vm.greenFlag()
-    vm.setMouseState({
-      x: 0,
-      y: 0,
-      isDown: true,
-    })
-    vm.setMouseTargets({
-      stage: true,
-      targets: ['Sprite1'],
-    })
-    vm.setKeysDown(['space'])
-    stepMany(vm, 12)
-
-    expect(getStageVariables(vm).var_stage_click).toBe(1)
-    expect(getStageVariables(vm).var_sprite_click).toBe(1)
-    expect(getStageVariables(vm).var_key).toBe(1)
-  })
-
-  test('handleEffects dispatches handlers and caches translated text for next run', async () => {
-    const vm = createVm(TEXT_TO_SPEECH_TRANSLATE_PROJECT, {
-      viewerLanguage: 'ja',
-    })
-    const translate = vi.fn(async () => 'こんにちは')
-    const textToSpeech = vi.fn(async () => undefined)
-    const effect = vi.fn(async () => undefined)
-
-    vm.greenFlag()
-    stepMany(vm, 6)
-
-    const handled = await vm.handleEffects({ translate, textToSpeech, effect })
-    expect(handled.map((item) => item.type)).toEqual([
-      'translate_request',
-      'text_to_speech',
-    ])
-    expect(translate).toHaveBeenCalledTimes(1)
-    expect(textToSpeech).toHaveBeenCalledTimes(1)
-    expect(effect).toHaveBeenCalledTimes(2)
-
-    stepMany(vm, 10)
-    expect(getStageVariables(vm).var_done).toBe(1)
-    expect(getStageVariables(vm).var_trans).toBe('hello')
-
-    vm.greenFlag()
-    stepMany(vm, 6)
-
-    const secondRunEffects = vm.takeEffects()
-    expect(
-      secondRunEffects.some((item) => item.type === 'translate_request'),
-    ).toBe(false)
-    const secondRunTts = secondRunEffects.find(
-      (item): item is { type: 'text_to_speech'; waitKey: string } =>
-        item.type === 'text_to_speech' &&
-        typeof (item as { waitKey?: unknown }).waitKey === 'string',
-    )
-    expect(secondRunTts).toBeDefined()
-    if (!secondRunTts) {
-      throw new Error('text_to_speech effect was not found in second run')
-    }
-    vm.ackTextToSpeech(secondRunTts.waitKey)
-    stepMany(vm, 10)
-
-    expect(getStageVariables(vm).var_done).toBe(1)
-    expect(getStageVariables(vm).var_trans).toBe('こんにちは')
-  })
-})

package/js/vm/headless-vm.ts

@@ -1,342 +0,0 @@
-import { moonscratch } from './bindings.ts'
-import { DEFAULT_MAX_FRAMES } from './constants.ts'
-import {
-  isMusicPlayDrumEffect,
-  isMusicPlayNoteEffect,
-  isTextToSpeechEffect,
-  isTranslateRequestEffect,
-} from './effect-guards.ts'
-import { parseJson } from './json.ts'
-import {
-  cloneTranslateCache,
-  normalizeLanguage,
-  normalizeMaxFrames,
-  normalizeNowMs,
-  toFrameReport,
-} from './normalize.ts'
-import type {
-  EffectHandlers,
-  FrameReport,
-  JsonValue,
-  RenderFrame,
-  RunReport,
-  RunUntilIdleOptions,
-  TranslateCache,
-  VMEffect,
-  VMInputEvent,
-  VMSnapshot,
-} from './types.ts'
-
-type BoundWasmVmHandle = unknown
-type BoundMoonscratch = {
-  vm_set_time?: (vmHandle: BoundWasmVmHandle, nowMs: number) => void
-  vm_render_frame?: (vmHandle: BoundWasmVmHandle) => unknown
-}
-
-interface HeadlessVMHooks {
-  afterGreenFlag?: () => void
-  beforeStepFrame?: () => void
-}
-
-export class HeadlessVM {
-  private readonly vmHandle: unknown
-  private readonly hooks: HeadlessVMHooks
-  private translateCache: TranslateCache = {}
-
-  constructor(vmHandle: unknown, hooks: HeadlessVMHooks = {}) {
-    this.vmHandle = vmHandle
-    this.hooks = hooks
-  }
-
-  get raw(): unknown {
-    return this.vmHandle
-  }
-
-  start(): void {
-    moonscratch.vm_start(this.vmHandle)
-  }
-
-  greenFlag(): void {
-    moonscratch.vm_green_flag(this.vmHandle)
-    this.hooks.afterGreenFlag?.()
-  }
-
-  stepFrame(): FrameReport {
-    this.hooks.beforeStepFrame?.()
-    const raw = moonscratch.vm_step_frame(this.vmHandle)
-    return toFrameReport(raw)
-  }
-
-  runFrames(frameCount: number): RunReport {
-    const normalizedFrameCount = normalizeMaxFrames(frameCount)
-    let frames = 0
-    let ticks = 0
-    let ops = 0
-    let activeThreads = this.snapshot().activeThreads
-    while (activeThreads > 0 && frames < normalizedFrameCount) {
-      const frame = this.stepFrame()
-      frames += 1
-      ticks += frame.ticks
-      ops += frame.ops
-      activeThreads = frame.activeThreads
-    }
-    return {
-      frames,
-      ticks,
-      ops,
-      activeThreads,
-      endedBy: 'frame_limit',
-    }
-  }
-
-  runUntilIdle(options: RunUntilIdleOptions = {}): RunReport {
-    const normalizedMaxFrames = normalizeMaxFrames(
-      options.maxFrames ?? DEFAULT_MAX_FRAMES,
-    )
-    let frames = 0
-    let ticks = 0
-    let ops = 0
-    let activeThreads = this.snapshot().activeThreads
-    while (activeThreads > 0 && frames < normalizedMaxFrames) {
-      const frame = this.stepFrame()
-      frames += 1
-      ticks += frame.ticks
-      ops += frame.ops
-      activeThreads = frame.activeThreads
-    }
-    return {
-      frames,
-      ticks,
-      ops,
-      activeThreads,
-      endedBy: activeThreads === 0 ? 'idle' : 'frame_limit',
-    }
-  }
-
-  postIO(device: string, payload: JsonValue): void {
-    moonscratch.vm_post_io_json(this.vmHandle, device, JSON.stringify(payload))
-  }
-
-  postIORawJson(device: string, payloadJson: string): void {
-    moonscratch.vm_post_io_json(this.vmHandle, device, payloadJson)
-  }
-
-  setAnswer(answer: string): void {
-    this.dispatchInputEvent({
-      type: 'answer',
-      answer,
-    })
-  }
-
-  setMouseState(input: { x: number; y: number; isDown?: boolean }): void {
-    this.dispatchInputEvent({
-      type: 'mouse',
-      x: input.x,
-      y: input.y,
-      isDown: input.isDown ?? false,
-    })
-  }
-
-  setKeysDown(keys: string[]): void {
-    this.dispatchInputEvent({
-      type: 'keys_down',
-      keys,
-    })
-  }
-
-  setTouching(touching: Record<string, string[]>): void {
-    this.dispatchInputEvent({
-      type: 'touching',
-      touching,
-    })
-  }
-
-  setMouseTargets(input: {
-    stage?: boolean
-    target?: string
-    targets?: string[]
-  }): void {
-    this.dispatchInputEvent({
-      type: 'mouse_targets',
-      stage: input.stage,
-      target: input.target,
-      targets: input.targets,
-    })
-  }
-
-  setBackdrop(backdrop: string | string[]): void {
-    this.dispatchInputEvent({
-      type: 'backdrop',
-      backdrop,
-    })
-  }
-
-  dispatchInputEvents(events: VMInputEvent[]): void {
-    for (const event of events) {
-      this.dispatchInputEvent(event)
-    }
-  }
-
-  dispatchInputEvent(event: VMInputEvent): void {
-    switch (event.type) {
-      case 'answer':
-        this.postIO('answer', event.answer)
-        return
-      case 'mouse':
-        this.postIO('mouse', {
-          x: event.x,
-          y: event.y,
-          isDown: event.isDown ?? false,
-        })
-        return
-      case 'keys_down':
-        this.postIO('keys_down', event.keys)
-        return
-      case 'touching':
-        this.postIO('touching', event.touching)
-        return
-      case 'mouse_targets':
-        this.postIO('mouse_targets', {
-          stage: event.stage ?? false,
-          target: event.target ?? '',
-          targets: event.targets ?? [],
-        })
-        return
-      case 'backdrop':
-        if (Array.isArray(event.backdrop)) {
-          this.postIO('backdrop', {
-            backdrops: event.backdrop,
-          })
-          return
-        }
-        this.postIO('backdrop', {
-          backdrop: event.backdrop,
-        })
-        return
-      default: {
-        const unreachable: never = event
-        throw new Error(`Unknown input event: ${String(unreachable)}`)
-      }
-    }
-  }
-
-  broadcast(message: string): void {
-    moonscratch.vm_broadcast(this.vmHandle, message)
-  }
-
-  stopAll(): void {
-    moonscratch.vm_stop_all(this.vmHandle)
-  }
-
-  setTime(nowMs: number): void {
-    const binding = moonscratch as unknown as BoundMoonscratch
-    if (typeof binding.vm_set_time === 'function') {
-      binding.vm_set_time(this.vmHandle, normalizeNowMs(nowMs))
-      return
-    }
-    throw new Error(
-      'vm_set_time is unavailable in this build. Please rebuild moonscratch JS bindings.',
-    )
-  }
-
-  takeEffects(): VMEffect[] {
-    const effects = parseJson<unknown>(
-      moonscratch.vm_take_effects_json(this.vmHandle),
-      'vm_take_effects_json',
-    )
-    if (!Array.isArray(effects)) {
-      throw new Error('vm_take_effects_json: expected JSON array')
-    }
-    return effects as VMEffect[]
-  }
-
-  snapshot(): VMSnapshot {
-    const snapshot = parseJson<unknown>(
-      moonscratch.vm_snapshot_json(this.vmHandle),
-      'vm_snapshot_json',
-    )
-    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
-      throw new Error('vm_snapshot_json: expected JSON object')
-    }
-    return snapshot as VMSnapshot
-  }
-
-  snapshotJson(): string {
-    return moonscratch.vm_snapshot_json(this.vmHandle)
-  }
-
-  renderFrame(): RenderFrame {
-    const binding = moonscratch as unknown as BoundMoonscratch
-    if (typeof binding.vm_render_frame !== 'function') {
-      throw new Error(
-        'vm_render_frame is unavailable in this build. Please rebuild moonscratch JS bindings.',
-      )
-    }
-    return binding.vm_render_frame(this.vmHandle) as RenderFrame
-  }
-
-  setViewerLanguage(language: string): void {
-    this.postIO('viewer_language', normalizeLanguage(language))
-  }
-
-  setTranslateResult(
-    words: string,
-    language: string,
-    translated: string,
-  ): string {
-    const normalizedLanguage = normalizeLanguage(language)
-    if (!this.translateCache[normalizedLanguage]) {
-      this.translateCache[normalizedLanguage] = {}
-    }
-    this.translateCache[normalizedLanguage][String(words)] = String(translated)
-    this.syncTranslateCache()
-    return translated
-  }
-
-  setTranslateCache(cache: TranslateCache): void {
-    this.translateCache = cloneTranslateCache(cache)
-    this.syncTranslateCache()
-  }
-
-  clearTranslateCache(): void {
-    this.translateCache = {}
-    this.syncTranslateCache()
-  }
-
-  ackTextToSpeech(waitKey: string | null | undefined): void {
-    if (typeof waitKey !== 'string' || waitKey.length === 0) {
-      return
-    }
-    this.postIO(waitKey, true)
-  }
-
-  async handleEffects(handlers: EffectHandlers = {}): Promise<VMEffect[]> {
-    const effects = this.takeEffects()
-    for (const effect of effects) {
-      if (isTranslateRequestEffect(effect) && handlers.translate) {
-        const translated = await handlers.translate(effect)
-        if (typeof translated === 'string') {
-          this.setTranslateResult(effect.words, effect.language, translated)
-        }
-      } else if (isTextToSpeechEffect(effect)) {
-        if (handlers.textToSpeech) {
-          await handlers.textToSpeech(effect)
-        }
-        this.ackTextToSpeech(effect.waitKey)
-      } else if (isMusicPlayNoteEffect(effect) && handlers.musicNote) {
-        await handlers.musicNote(effect)
-      } else if (isMusicPlayDrumEffect(effect) && handlers.musicDrum) {
-        await handlers.musicDrum(effect)
-      }
-
-      if (handlers.effect) {
-        await handlers.effect(effect)
-      }
-    }
-    return effects
-  }
-
-  private syncTranslateCache(): void {
-    this.postIO('translate_cache', this.translateCache)
-  }
-}

package/js/vm/index.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-
-import * as factory from './factory.ts'
-import * as headless from './headless-vm.ts'
-import * as index from './index.ts'
-import * as scratchAssets from './scratch-assets.ts'
-
-describe('moonscratch/js/vm/index.ts', () => {
-  test('re-exports vm runtime APIs', () => {
-    expect(index.createHeadlessVM).toBe(factory.createHeadlessVM)
-    expect(index.createHeadlessVMFromProject).toBe(
-      factory.createHeadlessVMFromProject,
-    )
-    expect(index.createHeadlessVMWithScratchAssets).toBe(
-      factory.createHeadlessVMWithScratchAssets,
-    )
-    expect(index.createVM).toBe(factory.createVM)
-    expect(index.createVMFromProject).toBe(factory.createVMFromProject)
-    expect(index.createVMWithScratchAssets).toBe(
-      factory.createVMWithScratchAssets,
-    )
-    expect(index.HeadlessVM).toBe(headless.HeadlessVM)
-    expect(index.resolveMissingScratchAssets).toBe(
-      scratchAssets.resolveMissingScratchAssets,
-    )
-    expect(index.moonscratch).toBe(factory.moonscratch)
-  })
-})

package/js/vm/index.ts

@@ -1,5 +0,0 @@
-export * from './factory.ts'
-export * from './headless-vm.ts'
-export * from './program-wasm.ts'
-export * from './scratch-assets.ts'
-export * from './types.ts'

package/js/vm/internal-types.ts

@@ -1,32 +0,0 @@
-export interface RawVMOptions {
-  turbo?: boolean
-  compatibility_30tps?: boolean
-  max_clones?: number
-  deterministic?: boolean
-  seed?: number
-  pen_width?: number
-  pen_height?: number
-  step_timeout_ticks?: number
-}
-
-export interface RawFrameReport {
-  active_threads: number
-  tick_count: number
-  op_count: number
-  emitted_effects: number
-  stop_reason: string
-  should_render: boolean
-  is_in_warp: boolean
-}
-
-interface MoonOk<T> {
-  $tag: 1
-  _0: T
-}
-
-interface MoonErr<E> {
-  $tag: 0
-  _0: E
-}
-
-export type MoonResult<T, E> = MoonOk<T> | MoonErr<E>

package/js/vm/json.test.ts

@@ -1,40 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-
-import {
-  parseJson,
-  toJsonString,
-  toOptionalJsonString,
-  unwrapResult,
-} from './json.ts'
-
-describe('moonscratch/js/vm/json.ts', () => {
-  test('serializes JSON object inputs', () => {
-    expect(toJsonString({ answer: 42 }, 'projectJson', true)).toBe(
-      '{"answer":42}',
-    )
-  })
-
-  test('rejects empty required JSON strings', () => {
-    expect(() => toJsonString('  ', 'projectJson', true)).toThrow(
-      'projectJson must be a non-empty JSON string or object',
-    )
-  })
-
-  test('keeps optional JSON undefined', () => {
-    expect(toOptionalJsonString(undefined, 'assets')).toBeUndefined()
-  })
-
-  test('unwraps moon results', () => {
-    expect(unwrapResult({ $tag: 1, _0: 123 }, 'context')).toBe(123)
-    expect(() =>
-      unwrapResult({ $tag: 0, _0: { _0: 'boom' } }, 'context'),
-    ).toThrow('context: boom')
-  })
-
-  test('parses json and reports context on parse error', () => {
-    expect(parseJson<{ value: number }>(' {"value": 1}', 'ctx').value).toBe(1)
-    expect(() => parseJson('not-json', 'ctx')).toThrow(
-      'ctx: failed to parse JSON',
-    )
-  })
-})