moonscratch 0.1.0 → 0.1.2

package/benchmarks/render.bench.ts

@@ -1,53 +0,0 @@
-import { Project } from 'hikkaku'
-import {
-  changeXBy,
-  changeYBy,
-  clear,
-  gotoXY,
-  penDown,
-  penUp,
-  repeat,
-  setY,
-  whenFlagClicked,
-} from 'hikkaku/blocks'
-import { bench, run } from 'mitata'
-import { createHeadlessVM, createProgramModuleFromProject } from '../js'
-
-const emptyProject = new Project()
-const emptyCompiled = createProgramModuleFromProject({
-  projectJson: emptyProject.toScratch(),
-})
-bench('render empty/moonscratch', () => {
-  const emptyVM = createHeadlessVM({ program: emptyCompiled })
-  emptyVM.renderFrame()
-})
-
-const filledProject = new Project()
-filledProject.createSprite('mysprite').run(() => {
-  whenFlagClicked(() => {
-    clear()
-    gotoXY(-240, -180)
-    repeat(420, () => {
-      changeXBy(1)
-      setY(-180)
-
-      penDown()
-      repeat(360, () => {
-        changeYBy(1)
-      })
-      penUp()
-    })
-  })
-})
-
-const filledCompiled = createProgramModuleFromProject({
-  projectJson: filledProject.toScratch(),
-})
-bench('render filled/moonscratch', () => {
-  const filledVM = createHeadlessVM({ program: filledCompiled })
-  filledVM.renderFrame()
-})
-
-if (import.meta.main) {
-  await run()
-}

package/benchmarks/run.bench.ts

@@ -1,8 +0,0 @@
-import { run } from 'mitata'
-
-import './calc.bench.ts'
-import './draw.bench.ts'
-import './load.bench.ts'
-import './render.bench.ts'
-
-await run()

package/benchmarks/types.d.ts

@@ -1,15 +0,0 @@
-/// <reference types="@turbowarp/types" />
-
-declare module '@scratch/scratch-vm' {
-  import type VM from 'scratch-vm'
-  export { VM }
-  const VMClass: typeof VM
-  export default VMClass
-}
-
-declare module '@scratch/scratch-render' {
-  import type Render from 'scratch-render'
-  export { Render }
-  const RenderClass: typeof Render
-  export default RenderClass
-}

package/docs/scratch-vm-specs/eventloop.md

@@ -1,103 +0,0 @@
-# Scratch VM Event Loop Spec
-
-This document records how `scratch-vm` controls frame stepping, thread ticks, and time,
-and how `moonscratch` mirrors that behavior.
-
-## Terminology
-
-- `frame`
-  - One call to `Runtime._step()`.
-  - In browser mode, called by `setInterval` from `Runtime.start()`.
-- `tick`
-  - One inner pass of `Sequencer.stepThreads()` while-loop.
-  - A tick attempts to run each runnable thread once.
-- `ms`
-  - Millisecond time base used by timer/wait behavior.
-- `redrawRequested`
-  - Runtime flag set by visible operations, used to decide if the current frame
-    should continue ticking.
-- `yield`
-  - Pause current thread until the next scheduler turn.
-- `yieldTick`
-  - Pause current thread until the next sequencer tick.
-
-## Observed Scratch VM Behavior
-
-## Frame loop
-
-- `Runtime.start()` sets `currentStepTime` then schedules `_step()`:
-  - `THREAD_STEP_INTERVAL = 1000 / 60`
-  - `THREAD_STEP_INTERVAL_COMPATIBILITY = 1000 / 30`
-- Compatibility mode changes the interval; turbo mode does not.
-
-## What happens in one frame (`Runtime._step`)
-
-1. Clean killed threads.
-2. Start edge-activated hats.
-3. Reset `redrawRequested = false`.
-4. Call `sequencer.stepThreads()`.
-5. Update glows/monitor state.
-6. Draw renderer frame once.
-
-## Tick loop (`Sequencer.stepThreads`)
-
-- `WORK_TIME = 0.75 * runtime.currentStepTime`.
-- Continue ticking while:
-  1. there are threads,
-  2. at least one active thread exists,
-  3. elapsed work time is below `WORK_TIME`,
-  4. `runtime.turboMode || !runtime.redrawRequested`.
-- Each tick:
-  - Iterate through thread list.
-  - Skip done threads.
-  - Run runnable threads (`stepThread`).
-  - Clean up done threads.
-
-## `yieldTick` semantics
-
-- `util.yieldTick()` sets `thread.status = STATUS_YIELD_TICK`.
-- At the first tick of the next `stepThreads` call, this status is cleared and thread resumes.
-- This is "next tick", not "after 1 ms".
-
-## Relationship: 1 tick, 1 frame, 1 ms
-
-- `1 frame` is a scheduler/render boundary (`_step`).
-- `1 frame` contains `N` ticks, where `N` is dynamic.
-- `1 ms` is timer/wait time axis and does not map 1:1 to ticks.
-- Therefore:
-  - frame count controls pacing,
-  - tick count controls execution throughput,
-  - ms controls timer predicates.
-
-## Turbo Mode (important)
-
-- Turbo mode does not change frame interval directly.
-- Turbo mode changes the tick continuation condition:
-  - without turbo: redraw request can stop additional ticks in the same frame,
-  - with turbo: redraw request does not stop same-frame ticking.
-- Practical effect: same FPS, more work per frame.
-
-## Moonscratch Design Rules
-
-## Time model
-
-- Runtime clock is virtual: `nowMs`.
-- Time is updated only via explicit `setTime(nowMs)`.
-- `stepFrame` does not advance clock time.
-
-## Frame API policy
-
-- Canonical API:
-  - `setTime(nowMs)`
-  - `stepFrame(frameCount = 1)`
-  - `runFrames(...)`
-  - `runUntilIdle(...)`
-- Recommended viewer loop:
-  1. call `setTime(...)` once per RAF/tick,
-  2. run one or more `stepFrame(...)` calls within a work budget,
-  3. render once after stepping.
-
-## Compatibility note
-
-- `scratch-vm` uses one draw per `Runtime._step()` and uses `redrawRequested` to decide whether to continue stepping in the same frame.
-- `moonscratch` should preserve this shape: avoid exposing intermediate script progress by rendering between partial step chunks.

package/docs/scratch-vm-specs/moonscratch-time-separation.md

@@ -1,50 +0,0 @@
-# Moonscratch Time Separation Notes
-
-This document summarizes the investigation around `examples/3d-cube` rendering behavior
-and the design choice to separate VM time updates from stepping.
-
-## Problem observed
-
-- In `scratch-gui` / `scratch-vm`, the cube appears to render as a single visual update
-  (or in a gap users do not perceive).
-- In the old `moonscratch` viewer loop, users could see pen drawing progress line-by-line.
-- This was not primarily a raw performance issue. It was caused by scheduling boundaries
-  becoming visible.
-
-## Key findings
-
-- Both runtimes are incremental internally.
-- The visible difference came from how stepping and rendering were orchestrated:
-  - `scratch-vm`:
-    - one `Runtime._step()` per interval,
-    - `Sequencer.stepThreads()` runs until work budget / redraw constraints,
-    - renderer draws once at end of `_step`.
-  - old `moonscratch` viewer:
-    - stepped in small chunks tied to RAF pacing,
-    - intermediate VM progress was rendered more directly.
-
-## Design change
-
-- `stepFrame` now executes scheduler work only.
-- `setTime(nowMs)` is the only API that moves VM clock time.
-- This makes time ownership explicit and lets callers control:
-  - when timer/wait predicates advance,
-  - how much execution is done before rendering.
-
-## Viewer policy
-
-Recommended loop:
-
-1. `setTime(now)` once per display tick.
-2. Run `stepFrame(1)` repeatedly within a bounded work window.
-3. Render exactly once after stepping.
-
-This preserves responsiveness while reducing visible intermediate pen progress.
-
-## Compatibility and migration notes
-
-- Breaking API changes:
-  - removed: `stepFrame(frameCount, frameMs)`
-  - added/renamed: `setTime(nowMs)` (formerly `setNowMs`)
-  - removed from `FrameReport`: `nowMs` and frame-duration-derived fields
-- Time-dependent scripts (`wait`, `timer`) require caller-driven `setTime` updates.

package/index.html

@@ -1,91 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>MoonScratch Viewer</title>
-  <style>
-    :root {
-      color-scheme: dark;
-      font-family: 'Trebuchet MS', 'Segoe UI', 'Hiragino Kaku Gothic ProN',
-        'Yu Gothic', 'Meiryo', sans-serif;
-    }
-
-    body {
-      margin: 0;
-      min-height: 100vh;
-      background:
-        radial-gradient(circle at 10% 20%, #24344d 0%, transparent 35%),
-        radial-gradient(circle at 90% 20%, #3d2549 0%, transparent 35%),
-        linear-gradient(180deg, #111827, #0d1117);
-      color: #f8fafc;
-      display: flex;
-      justify-content: center;
-      align-items: flex-start;
-      padding: 20px;
-    }
-
-    main {
-      width: min(920px, 100%);
-      background: rgba(15, 23, 42, 0.75);
-      border: 1px solid rgba(148, 163, 184, 0.35);
-      border-radius: 12px;
-      padding: 20px;
-      box-shadow:
-        0 20px 45px rgba(0, 0, 0, 0.35),
-        inset 0 1px 0 rgba(255, 255, 255, 0.05);
-      backdrop-filter: blur(3px);
-    }
-
-    h1 {
-      margin: 0 0 12px;
-      font-size: 1.45rem;
-      letter-spacing: 0.02em;
-    }
-
-    .controls {
-      display: flex;
-      gap: 12px;
-      align-items: center;
-      flex-wrap: wrap;
-      margin-bottom: 16px;
-    }
-
-    label {
-      font-weight: 700;
-      color: #e2e8f0;
-    }
-
-    select {
-      border: 1px solid #334155;
-      background: #0f172a;
-      color: #f8fafc;
-      padding: 8px 10px;
-      border-radius: 8px;
-      min-width: 260px;
-    }
-
-    .status {
-      margin: 8px 0 14px;
-      color: #94a3b8;
-      min-height: 1.4em;
-    }
-
-    canvas {
-      width: 100%;
-      max-width: 100%;
-      aspect-ratio: 4 / 3;
-      background: #0f172a;
-      border: 1px solid rgba(148, 163, 184, 0.45);
-      border-radius: 8px;
-      display: block;
-      image-rendering: pixelated;
-      margin-top: 12px;
-    }
-  </style>
-</head>
-<body>
-  <main id="app"></main>
-  <script src="./viewer/index.ts" type="module"></script>
-</body>
-</html>

package/js/AGENTS.md

@@ -1,5 +0,0 @@
-# js
-
-- Public APIs and modules for Bun/TypeScript.
-- Prioritize running `bun typecheck` and `bun run test` when making changes.
-- Keep boundary types and conversion logic explicit to stay aligned with MoonBit.

package/js/a.ts

@@ -1,52 +0,0 @@
-import {
-  callProcedure,
-  defineProcedure,
-  procedureLabel,
-  repeat,
-  say,
-  whenFlagClicked,
-} from '../../hikkaku/src/blocks'
-import { Project } from '../../hikkaku/src/index'
-import { createHeadlessVM, createProgramModuleFromProject } from '.'
-
-const project = new Project()
-project.stage.run(() => {
-  const a = defineProcedure(
-    [procedureLabel('a')],
-    () => {
-      repeat(100000, () => {
-        say('Hello, World!')
-      })
-    },
-    true,
-  )
-  whenFlagClicked(() => {
-    repeat(10, () => {
-      callProcedure(a, [])
-    })
-  })
-})
-
-const program = createProgramModuleFromProject({
-  projectJson: await Bun.file(
-    new URL('../../../examples/tesseract/dist/project.json', import.meta.url),
-  ).json(), //project.toScratch(),
-})
-
-const vm = createHeadlessVM({
-  program,
-  options: {
-    stepTimeoutTicks: 100,
-  },
-})
-
-vm.greenFlag()
-
-while (true) {
-  const report = vm.stepFrame()
-  console.log('Stopped:', report.stopReason)
-  if (report.stopReason === 'finished' || report.stopReason === 'warp-exit') {
-    console.log(report.stopReason)
-    break
-  }
-}

package/js/assets/AGENTS.md

@@ -1,5 +0,0 @@
-# js/assets
-
-- Manages asset generation, validation, and conversion logic.
-- Add corresponding `*.test.ts` files with new features to fix input variation coverage.
-- For breaking changes, verify compatibility through the public surface in `index.ts`.

package/js/assets/base64.test.ts

@@ -1,14 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-
-import { encodeBase64 } from './base64.ts'
-
-describe('moonscratch/js/assets/base64.ts', () => {
-  test('encodes rgba bytes as base64', () => {
-    const encoded = encodeBase64(new Uint8Array([0, 255, 0, 255]))
-    expect(encoded).toBe('AP8A/w==')
-  })
-
-  test('encodes empty bytes', () => {
-    expect(encodeBase64(new Uint8Array([]))).toBe('')
-  })
-})

package/js/assets/base64.ts

@@ -1,21 +0,0 @@
-interface BufferLike {
-  from(input: Uint8Array): { toString(encoding: string): string }
-}
-
-export const encodeBase64 = (bytes: Uint8Array): string => {
-  const maybeBuffer = (globalThis as { Buffer?: BufferLike }).Buffer
-  if (maybeBuffer) {
-    return maybeBuffer.from(bytes).toString('base64')
-  }
-
-  const maybeBtoa = (globalThis as { btoa?: (binary: string) => string }).btoa
-  if (typeof maybeBtoa === 'function') {
-    let binary = ''
-    for (let i = 0; i < bytes.length; i += 1) {
-      binary += String.fromCharCode(bytes[i] ?? 0)
-    }
-    return maybeBtoa(binary)
-  }
-
-  throw new Error('No base64 encoder found in this runtime')
-}

package/js/assets/build-asset.test.ts

@@ -1,26 +0,0 @@
-import { describe, expect, test } from 'vite-plus/test'
-
-import { buildAsset } from './build-asset.ts'
-
-describe('moonscratch/js/assets/build-asset.ts', () => {
-  test('builds rgba asset from flat bytes', () => {
-    const asset = buildAsset(2, 1, [0, 255, 0, 255, 255, 0, 0, 255])
-    expect(asset).toEqual({
-      width: 2,
-      height: 1,
-      rgbaBase64: 'AP8A//8AAP8=',
-    })
-  })
-
-  test('throws when rgba length is shorter than expected', () => {
-    expect(() => buildAsset(2, 1, [255, 0, 0, 255])).toThrow(
-      'rgba length must be at least 8',
-    )
-  })
-
-  test('throws when rgba contains invalid byte values', () => {
-    expect(() => buildAsset(1, 1, [300, 0, 0, 255])).toThrow(
-      'rgba[0] must be between 0 and 255',
-    )
-  })
-})

package/js/assets/build-asset.ts

@@ -1,28 +0,0 @@
-import { encodeBase64 } from './base64.ts'
-import type { RgbaAsset } from './types.ts'
-import { toByte, toPositiveInt } from './validation.ts'
-
-export const buildAsset = (
-  width: number,
-  height: number,
-  rgba: ArrayLike<number>,
-): RgbaAsset => {
-  const safeWidth = toPositiveInt(width, 'width')
-  const safeHeight = toPositiveInt(height, 'height')
-  const expectedLength = safeWidth * safeHeight * 4
-
-  if (rgba.length < expectedLength) {
-    throw new Error(`rgba length must be at least ${expectedLength}`)
-  }
-
-  const bytes = new Uint8Array(expectedLength)
-  for (let i = 0; i < expectedLength; i += 1) {
-    bytes[i] = toByte(rgba[i], `rgba[${i}]`)
-  }
-
-  return {
-    width: safeWidth,
-    height: safeHeight,
-    rgbaBase64: encodeBase64(bytes),
-  }
-}

package/js/assets/create.test.ts

@@ -1,142 +0,0 @@
-import { describe, expect, test, vi } from 'vite-plus/test'
-
-import {
-  fromCanvas,
-  fromImageBytes,
-  fromImageData,
-  fromImageFile,
-  fromRgbaBytes,
-  fromRgbaMatrix,
-} from './create.ts'
-
-const sharpCalls: unknown[] = []
-
-vi.mock('sharp', () => ({
-  default: vi.fn((input?: unknown) => {
-    sharpCalls.push(input)
-
-    return {
-      ensureAlpha() {
-        return this
-      },
-      raw() {
-        return this
-      },
-      async toBuffer() {
-        return {
-          data: new Uint8Array([0, 255, 0, 255]),
-          info: {
-            width: 1,
-            height: 1,
-          },
-        }
-      },
-    }
-  }),
-}))
-
-describe('moonscratch/js/assets/create.ts', () => {
-  test('builds an asset from image data', () => {
-    const asset = fromImageData({
-      width: 1,
-      height: 1,
-      data: new Uint8Array([0, 255, 0, 255]),
-    })
-
-    expect(asset).toEqual({
-      width: 1,
-      height: 1,
-      rgbaBase64: 'AP8A/w==',
-    })
-  })
-
-  test('builds an asset from flat rgba bytes', () => {
-    const asset = fromRgbaBytes(
-      2,
-      1,
-      new Uint8Array([0, 255, 0, 255, 255, 0, 0, 255]),
-    )
-
-    expect(asset).toEqual({
-      width: 2,
-      height: 1,
-      rgbaBase64: 'AP8A//8AAP8=',
-    })
-  })
-
-  test('builds an asset from H x W x 4 matrix', () => {
-    const asset = fromRgbaMatrix([
-      [
-        [0, 255, 0, 255],
-        [255, 0, 0, 255],
-      ],
-      [
-        [0, 0, 255, 255],
-        [255, 255, 255, 255],
-      ],
-    ])
-
-    expect(asset).toEqual({
-      width: 2,
-      height: 2,
-      rgbaBase64: 'AP8A//8AAP8AAP///////w==',
-    })
-  })
-
-  test('builds an asset from canvas API', () => {
-    const getImageData = vi.fn(() => ({
-      width: 1,
-      height: 1,
-      data: new Uint8Array([255, 0, 0, 255]),
-    }))
-
-    const getContext = vi.fn(() => ({ getImageData }))
-
-    const asset = fromCanvas({
-      width: 1,
-      height: 1,
-      getContext,
-    })
-
-    expect(getContext).toHaveBeenCalledWith('2d')
-    expect(getImageData).toHaveBeenCalledWith(0, 0, 1, 1)
-    expect(asset.rgbaBase64).toBe('/wAA/w==')
-  })
-
-  test('throws when matrix row widths are inconsistent', () => {
-    expect(() =>
-      fromRgbaMatrix([
-        [
-          [0, 0, 0, 255],
-          [255, 255, 255, 255],
-        ],
-        [[0, 0, 0, 255]],
-      ]),
-    ).toThrow('pixels[1] must contain exactly 2 columns')
-  })
-
-  test('loads an image asset from bytes via sharp', async () => {
-    const asset = await fromImageBytes(new Uint8Array([1, 2, 3]))
-
-    expect(sharpCalls).toEqual([new Uint8Array([1, 2, 3])])
-    expect(asset).toEqual({
-      width: 1,
-      height: 1,
-      rgbaBase64: 'AP8A/w==',
-    })
-  })
-
-  test('loads an image asset from file via sharp', async () => {
-    const asset = await fromImageFile('fixtures/example.png')
-
-    expect(sharpCalls).toEqual([
-      new Uint8Array([1, 2, 3]),
-      'fixtures/example.png',
-    ])
-    expect(asset).toEqual({
-      width: 1,
-      height: 1,
-      rgbaBase64: 'AP8A/w==',
-    })
-  })
-})