moonscratch 0.1.0-alpha.0

package/js/vm/scratch-assets.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test, vi } from 'vite-plus/test'
+
+import { resolveMissingScratchAssets } from './scratch-assets.ts'
+
+const RGBA_ASSET = {
+  width: 1,
+  height: 1,
+  rgbaBase64: 'AP8A/w==',
+}
+
+const STAGE_PROJECT_WITH_COSTUMES = {
+  targets: [
+    {
+      isStage: true,
+      name: 'Stage',
+      variables: {},
+      lists: {},
+      blocks: {},
+      costumes: [
+        {
+          name: 'backdrop1',
+          assetId: 'bg_green',
+          md5ext: 'bg_green.png',
+        },
+      ],
+    },
+  ],
+}
+
+describe('moonscratch/js/vm/scratch-assets.ts', () => {
+  test('downloads missing assets from Scratch CDN and maps by assetId + md5ext', async () => {
+    const fetchAsset = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+    }))
+    const decodeImageBytes = vi.fn(async () => RGBA_ASSET)
+
+    const assets = await resolveMissingScratchAssets({
+      projectJson: STAGE_PROJECT_WITH_COSTUMES,
+      fetchAsset,
+      decodeImageBytes,
+    })
+
+    expect(fetchAsset).toHaveBeenCalledWith(
+      'https://cdn.scratch.mit.edu/internalapi/asset/bg_green.png/get/',
+    )
+    expect(decodeImageBytes).toHaveBeenCalledTimes(1)
+    expect(assets.bg_green).toEqual(RGBA_ASSET)
+    expect(assets['bg_green.png']).toEqual(RGBA_ASSET)
+  })
+
+  test('does not download when existing asset is keyed by md5ext', async () => {
+    const fetchAsset = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+    }))
+
+    const assets = await resolveMissingScratchAssets({
+      projectJson: STAGE_PROJECT_WITH_COSTUMES,
+      assets: {
+        'bg_green.png': RGBA_ASSET,
+      },
+      fetchAsset,
+    })
+
+    expect(fetchAsset).not.toHaveBeenCalled()
+    expect(assets.bg_green).toEqual(RGBA_ASSET)
+    expect(assets['bg_green.png']).toEqual(RGBA_ASSET)
+  })
+
+  test('deduplicates repeated md5ext downloads', async () => {
+    const fetchAsset = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+    }))
+    const decodeImageBytes = vi.fn(async () => RGBA_ASSET)
+
+    const assets = await resolveMissingScratchAssets({
+      projectJson: {
+        targets: [
+          {
+            isStage: true,
+            name: 'Stage',
+            variables: {},
+            lists: {},
+            blocks: {},
+            costumes: [
+              {
+                name: 'backdrop1',
+                assetId: 'bg_green',
+                md5ext: 'bg_green.png',
+              },
+              {
+                name: 'backdrop2',
+                assetId: 'bg_green_2',
+                md5ext: 'bg_green.png',
+              },
+            ],
+          },
+        ],
+      },
+      fetchAsset,
+      decodeImageBytes,
+    })
+
+    expect(fetchAsset).toHaveBeenCalledTimes(1)
+    expect(decodeImageBytes).toHaveBeenCalledTimes(1)
+    expect(assets.bg_green).toEqual(RGBA_ASSET)
+    expect(assets.bg_green_2).toEqual(RGBA_ASSET)
+    expect(assets['bg_green.png']).toEqual(RGBA_ASSET)
+  })
+
+  test('throws when asset download fails', async () => {
+    const fetchAsset = vi.fn(async () => ({
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+      arrayBuffer: async () => new ArrayBuffer(0),
+    }))
+
+    await expect(
+      resolveMissingScratchAssets({
+        projectJson: STAGE_PROJECT_WITH_COSTUMES,
+        fetchAsset,
+      }),
+    ).rejects.toThrow(
+      'failed to download Scratch asset bg_green.png: 404 Not Found',
+    )
+  })
+})

package/js/vm/scratch-assets.ts

@@ -0,0 +1,202 @@
+import { fromImageBytes } from '../assets/create.ts'
+import { parseJson } from './json.ts'
+import type {
+  DecodeImageBytes,
+  FetchAsset,
+  JsonValue,
+  ProjectJson,
+  ResolveMissingScratchAssetsOptions,
+} from './types.ts'
+import { isObjectRecord } from './value-guards.ts'
+
+const DEFAULT_SCRATCH_CDN_BASE_URL =
+  'https://cdn.scratch.mit.edu/internalapi/asset'
+
+type AssetObject = {
+  width: number
+  height: number
+  rgbaBase64: string
+}
+
+type CostumeRef = {
+  assetId: string
+  md5ext: string
+}
+
+const hasOwn = (record: Record<string, JsonValue>, key: string): boolean =>
+  Object.hasOwn(record, key)
+
+const normalizeAssets = (
+  assets: ResolveMissingScratchAssetsOptions['assets'],
+): Record<string, JsonValue> => {
+  if (assets === undefined) {
+    return {}
+  }
+
+  if (typeof assets === 'string') {
+    const parsed = parseJson<unknown>(assets, 'assets')
+    if (!isObjectRecord(parsed)) {
+      throw new Error('assets must be a JSON object')
+    }
+    return { ...(parsed as Record<string, JsonValue>) }
+  }
+
+  return { ...assets }
+}
+
+const normalizeProject = (
+  projectJson: string | ProjectJson,
+): Record<string, unknown> => {
+  const parsed =
+    typeof projectJson === 'string'
+      ? parseJson<unknown>(projectJson, 'projectJson')
+      : projectJson
+  if (!isObjectRecord(parsed)) {
+    throw new Error('projectJson must be a JSON object')
+  }
+  return parsed
+}
+
+const collectCostumeRefs = (project: Record<string, unknown>): CostumeRef[] => {
+  const refs: CostumeRef[] = []
+  const targets = project.targets
+  if (!Array.isArray(targets)) {
+    return refs
+  }
+
+  for (const target of targets) {
+    if (!isObjectRecord(target)) {
+      continue
+    }
+    const costumes = target.costumes
+    if (!Array.isArray(costumes)) {
+      continue
+    }
+
+    for (const costume of costumes) {
+      if (!isObjectRecord(costume)) {
+        continue
+      }
+      const rawMd5ext = costume.md5ext
+      const md5ext = typeof rawMd5ext === 'string' ? rawMd5ext.trim() : ''
+      if (md5ext.length === 0) {
+        continue
+      }
+      const rawAssetId = costume.assetId
+      const assetId = typeof rawAssetId === 'string' ? rawAssetId.trim() : ''
+      refs.push({ assetId, md5ext })
+    }
+  }
+
+  return refs
+}
+
+const normalizeCdnBaseUrl = (input: string | undefined): string => {
+  const base = (input ?? DEFAULT_SCRATCH_CDN_BASE_URL).trim()
+  if (base.length === 0) {
+    throw new Error('scratchCdnBaseUrl must not be empty')
+  }
+  return base.endsWith('/') ? base.slice(0, -1) : base
+}
+
+const defaultFetchAsset = (): FetchAsset => {
+  const fetchAsset = (globalThis as { fetch?: unknown }).fetch
+  if (typeof fetchAsset !== 'function') {
+    throw new Error('global fetch is not available; pass fetchAsset option')
+  }
+  return fetchAsset as FetchAsset
+}
+
+const validateDecodedAsset = (
+  md5ext: string,
+  decoded: AssetObject,
+): AssetObject => {
+  if (!Number.isFinite(decoded.width) || decoded.width <= 0) {
+    throw new Error(`decodeImageBytes returned invalid width for ${md5ext}`)
+  }
+  if (!Number.isFinite(decoded.height) || decoded.height <= 0) {
+    throw new Error(`decodeImageBytes returned invalid height for ${md5ext}`)
+  }
+  if (
+    typeof decoded.rgbaBase64 !== 'string' ||
+    decoded.rgbaBase64.length === 0
+  ) {
+    throw new Error(
+      `decodeImageBytes returned invalid rgbaBase64 for ${md5ext}`,
+    )
+  }
+  return decoded
+}
+
+const toJsonAsset = (asset: AssetObject): Record<string, JsonValue> => ({
+  width: asset.width,
+  height: asset.height,
+  rgbaBase64: asset.rgbaBase64,
+})
+
+const buildAssetUrl = (baseUrl: string, md5ext: string): string =>
+  `${baseUrl}/${encodeURIComponent(md5ext)}/get/`
+
+export const resolveMissingScratchAssets = async ({
+  projectJson,
+  assets,
+  scratchCdnBaseUrl,
+  fetchAsset,
+  decodeImageBytes,
+}: ResolveMissingScratchAssetsOptions): Promise<Record<string, JsonValue>> => {
+  const resolvedAssets = normalizeAssets(assets)
+  const refs = collectCostumeRefs(normalizeProject(projectJson))
+  if (refs.length === 0) {
+    return resolvedAssets
+  }
+
+  const baseUrl = normalizeCdnBaseUrl(scratchCdnBaseUrl)
+  const fetchFn = fetchAsset ?? defaultFetchAsset()
+  const decodeFn: DecodeImageBytes = decodeImageBytes ?? fromImageBytes
+  const cache = new Map<string, Record<string, JsonValue>>()
+
+  for (const { assetId, md5ext } of refs) {
+    if (assetId.length > 0 && hasOwn(resolvedAssets, assetId)) {
+      const asset = resolvedAssets[assetId]
+      if (asset === undefined) {
+        continue
+      }
+      if (!hasOwn(resolvedAssets, md5ext)) {
+        resolvedAssets[md5ext] = asset
+      }
+      continue
+    }
+    if (hasOwn(resolvedAssets, md5ext)) {
+      const asset = resolvedAssets[md5ext]
+      if (asset === undefined) {
+        continue
+      }
+      if (assetId.length > 0 && !hasOwn(resolvedAssets, assetId)) {
+        resolvedAssets[assetId] = asset
+      }
+      continue
+    }
+
+    let loaded = cache.get(md5ext)
+    if (!loaded) {
+      const url = buildAssetUrl(baseUrl, md5ext)
+      const response = await fetchFn(url)
+      if (!response.ok) {
+        throw new Error(
+          `failed to download Scratch asset ${md5ext}: ${response.status} ${response.statusText}`,
+        )
+      }
+      const bytes = await response.arrayBuffer()
+      const decoded = validateDecodedAsset(md5ext, await decodeFn(bytes))
+      loaded = toJsonAsset(decoded)
+      cache.set(md5ext, loaded)
+    }
+
+    resolvedAssets[md5ext] = loaded
+    if (assetId.length > 0) {
+      resolvedAssets[assetId] = loaded
+    }
+  }
+
+  return resolvedAssets
+}

package/js/vm/types.ts

@@ -0,0 +1,358 @@
+import type { ScratchProject } from 'sb3-types'
+
+type MaybePromise<T> = T | Promise<T>
+
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue =
+  | JsonPrimitive
+  | { [key: string]: JsonValue }
+  | JsonValue[]
+export type ProjectJson = JsonValue | ScratchProject
+
+export interface VMOptions {
+  turbo: boolean
+  compatibility30tps: boolean
+  maxClones: number
+  deterministic: boolean
+  seed: number
+  penWidth: number
+  penHeight: number
+  stepTimeoutTicks: number
+}
+
+export interface VMOptionsInput extends Partial<VMOptions> {
+  compatibility_30tps?: boolean
+  max_clones?: number
+  pen_width?: number
+  pen_height?: number
+  step_timeout_ticks?: number
+  stepTimeoutTicks?: number
+}
+
+export type FrameStopReason = 'finished' | 'timeout' | 'rerender' | 'warp-exit'
+
+export interface FrameReport {
+  activeThreads: number
+  ticks: number
+  ops: number
+  emittedEffects: number
+  stopReason: FrameStopReason
+  shouldRender: boolean
+  isInWarp: boolean
+}
+
+export type RunEndedBy = 'idle' | 'frame_limit'
+
+export interface RunReport {
+  frames: number
+  ticks: number
+  ops: number
+  activeThreads: number
+  endedBy: RunEndedBy
+}
+
+export interface RunUntilIdleOptions {
+  maxFrames?: number
+}
+
+export type VMInputEvent =
+  | {
+      type: 'answer'
+      answer: string
+    }
+  | {
+      type: 'mouse'
+      x: number
+      y: number
+      isDown?: boolean
+    }
+  | {
+      type: 'keys_down'
+      keys: string[]
+    }
+  | {
+      type: 'touching'
+      touching: Record<string, string[]>
+    }
+  | {
+      type: 'mouse_targets'
+      stage?: boolean
+      target?: string
+      targets?: string[]
+    }
+  | {
+      type: 'backdrop'
+      backdrop: string | string[]
+    }
+
+export type {
+  RenderFrame,
+  RenderFrameLike,
+  RenderImageData,
+  RenderWithSharpOptions,
+  RenderWithWebGLOptions,
+  WebGLRenderResult,
+} from '../render/types.ts'
+
+export interface VMSnapshotTarget {
+  id: string
+  name: string
+  isStage: boolean
+  x: number
+  y: number
+  direction: number
+  size: number
+  volume: number
+  musicInstrument: number
+  textToSpeechVoice: string
+  visible: boolean
+  currentCostume: number
+  variables: Record<string, JsonValue>
+  lists: Record<string, JsonValue[]>
+}
+
+export interface VMSnapshot {
+  runId: number
+  nowMs: number
+  running: boolean
+  answer: string
+  musicTempo: number
+  textToSpeechLanguage: string
+  activeThreads: number
+  targets: VMSnapshotTarget[]
+}
+
+export interface PlaySoundEffect {
+  type: 'play_sound'
+  target: string
+  sound: string
+}
+
+export interface MusicPlayNoteEffect {
+  type: 'music_play_note'
+  target: string
+  note: number
+  beats: number
+  instrument: number
+  tempo: number
+}
+
+export interface MusicPlayDrumEffect {
+  type: 'music_play_drum'
+  target: string
+  drum: number
+  beats: number
+  tempo: number
+}
+
+export interface TextToSpeechEffect {
+  type: 'text_to_speech'
+  target: string
+  words: string
+  voice: string
+  language: string
+  waitKey: string
+}
+
+export interface TranslateRequestEffect {
+  type: 'translate_request'
+  words: string
+  language: string
+}
+
+export interface StopAllSoundsEffect {
+  type: 'stop_all_sounds'
+}
+
+export interface SayEffect {
+  type: 'say'
+  target: string
+  message: string
+}
+
+export interface ThinkEffect {
+  type: 'think'
+  target: string
+  message: string
+}
+
+export interface AskEffect {
+  type: 'ask'
+  question: string
+}
+
+export interface BroadcastEffect {
+  type: 'broadcast'
+  message: string
+}
+
+export interface LogEffect {
+  type: 'log'
+  level: string
+  message: string
+}
+
+export interface UnknownEffect {
+  type: string
+  [key: string]: JsonValue
+}
+
+type KnownEffect =
+  | PlaySoundEffect
+  | MusicPlayNoteEffect
+  | MusicPlayDrumEffect
+  | TextToSpeechEffect
+  | TranslateRequestEffect
+  | StopAllSoundsEffect
+  | SayEffect
+  | ThinkEffect
+  | AskEffect
+  | BroadcastEffect
+  | LogEffect
+
+export type VMEffect = KnownEffect | UnknownEffect
+
+export type TranslateCache = Record<string, Record<string, string>>
+
+export interface EffectHandlers {
+  translate?: (
+    effect: TranslateRequestEffect,
+  ) => MaybePromise<string | null | undefined>
+  textToSpeech?: (effect: TextToSpeechEffect) => MaybePromise<void>
+  musicNote?: (effect: MusicPlayNoteEffect) => MaybePromise<void>
+  musicDrum?: (effect: MusicPlayDrumEffect) => MaybePromise<void>
+  effect?: (effect: VMEffect) => MaybePromise<void>
+}
+
+export interface CompileProjectToWatOptions {
+  projectJson: string | ProjectJson
+  assets?: string | Record<string, JsonValue>
+}
+
+export interface ProgramManifest {
+  abiVersion: number
+  opcodeSetVersion: number
+  projectByteLength: number
+  assetsByteLength: number
+  buildFingerprint: string
+}
+
+export interface CompileProjectToWatResult {
+  wat: string
+  abiVersion: number
+  manifest: ProgramManifest
+}
+
+export type ProgramWasmBytes = Uint8Array | ArrayBuffer
+
+export type WatToWasm = (wat: string) => ProgramWasmBytes
+
+export interface CompileProjectToWasmOptions
+  extends CompileProjectToWatOptions {
+  watToWasm?: WatToWasm
+}
+
+export interface CompileProjectToWasmResult extends CompileProjectToWatResult {
+  wasmBytes: Uint8Array
+}
+
+export interface RuntimeHandle {
+  raw: unknown
+  abiVersion: number
+}
+
+export interface ProgramPayload {
+  projectJson: string
+  assetsJson: string
+  commandsJson?: string
+}
+
+export interface ProgramWasmExecHost {
+  getVarNumber: (targetIndex: number, variableId: string) => number
+  setVarNumber: (targetIndex: number, variableId: string, value: number) => void
+  setVarJson: (
+    targetIndex: number,
+    variableId: string,
+    valueJson: string,
+  ) => void
+  execHostOpcode: (targetIndex: number, pc: number) => number
+  execHostTail: (targetIndex: number, startPc: number) => number
+  execDrawOpcode: (
+    targetIndex: number,
+    opcode: string,
+    arg0: number,
+    arg1: number,
+    extra: number,
+  ) => number
+}
+
+export type ProgramWasmExecRunner = () => number
+
+export interface ProgramModule {
+  raw: WebAssembly.Instance
+  abiVersion: number
+  manifest: ProgramManifest
+  readPayload: () => ProgramPayload
+  hasWasmExec: () => boolean
+  createWasmExecRunner: (
+    host: ProgramWasmExecHost,
+  ) => ProgramWasmExecRunner | null
+}
+
+export interface CreateProgramModuleOptions {
+  wasmBytes: ProgramWasmBytes
+  manifest?: ProgramManifest
+}
+
+export interface CreateProgramModuleFromProjectOptions
+  extends CompileProjectToWasmOptions {}
+
+export interface PrecompileProgramForRuntimeOptions {
+  program: ProgramModule
+  runtime?: RuntimeHandle
+}
+
+export interface CreateHeadlessVMOptions {
+  program: ProgramModule
+  runtime?: RuntimeHandle
+  options?: string | VMOptionsInput
+  initialNowMs?: number
+  viewerLanguage?: string
+  translateCache?: TranslateCache
+}
+
+export interface CreateHeadlessVMFromProjectOptions
+  extends Omit<CreateHeadlessVMOptions, 'program'>,
+    CreateProgramModuleFromProjectOptions {}
+
+export interface ScratchAssetResponse {
+  ok: boolean
+  status: number
+  statusText: string
+  arrayBuffer(): Promise<ArrayBuffer>
+}
+
+export type FetchAsset = (url: string) => Promise<ScratchAssetResponse>
+
+export type DecodeImageBytes = (bytes: ArrayBuffer | Uint8Array) => Promise<{
+  width: number
+  height: number
+  rgbaBase64: string
+}>
+
+export interface ResolveMissingScratchAssetsOptions {
+  projectJson: string | ProjectJson
+  assets?: string | Record<string, JsonValue>
+  scratchCdnBaseUrl?: string
+  fetchAsset?: FetchAsset
+  decodeImageBytes?: DecodeImageBytes
+}
+
+export interface CreateHeadlessVMWithScratchAssetsOptions
+  extends Omit<CreateHeadlessVMFromProjectOptions, 'assets'> {
+  projectJson: string | ProjectJson
+  assets?: string | Record<string, JsonValue>
+  scratchCdnBaseUrl?: string
+  fetchAsset?: FetchAsset
+  decodeImageBytes?: DecodeImageBytes
+}

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

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'vite-plus/test'
+
+import {
+  hasNumberField,
+  hasStringField,
+  isObjectRecord,
+} from './value-guards.ts'
+
+describe('moonscratch/js/vm/value-guards.ts', () => {
+  test('isObjectRecord identifies plain objects', () => {
+    expect(isObjectRecord({ foo: 'bar' })).toBe(true)
+    expect(isObjectRecord(null)).toBe(false)
+    expect(isObjectRecord([])).toBe(false)
+  })
+
+  test('hasStringField validates string fields', () => {
+    expect(hasStringField({ name: 'Sprite1' }, 'name')).toBe(true)
+    expect(hasStringField({ name: 1 }, 'name')).toBe(false)
+  })
+
+  test('hasNumberField validates number fields', () => {
+    expect(hasNumberField({ beats: 1.5 }, 'beats')).toBe(true)
+    expect(hasNumberField({ beats: '1.5' }, 'beats')).toBe(false)
+  })
+})