feat(moonscratch): improve compatibility (#102)

* feat(moonscratch): switch to frame-based stepping API

- add internal event loop spec under packages/moonscratch/docs
- replace step(dtMs) with stepFrame/runFrames/runForTime/runUntilIdle
- add initialNowMs and vm_set_now_ms support
- update MoonBit API to vm_step_frame
- refresh tests, docs, and AGENTS requirements

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

* feat: add support for WARP

* feat: add renderer

* fix

* fix

* fix

* fix(moonscratch): use Scratch compare semantics for lt/gt

- compare numeric operands as numbers before string fallback
- add regression test for negative numeric comparisons

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

* fix(moonscratch): respect pen transparency on stroke rasterization

- avoid repeated alpha overdraw when drawing pen lines
- add regression test for semi-transparent overlay stroke

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

* chore(moonscratch): always build js target before test/build scripts

- ensure _build/js bindings are up to date for viewer/runtime behavior

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

* fix(moonscratch): align pen rasterization with scratch line blending

* fix

* fix

* breaking

* perf: 読み込みの高速化

* fix

* fix

* perf: add precompile

* perf: better AOT

* perf: AOT

* fix

---------

Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

Author: nakasyou

AGENTS.md

@@ -48,3 +48,6 @@
   * `bun fmt`: apply formatting
   * `bun typecheck`: run type checking
   * `bun ref:build`: update the docs
+* when changes include `packages/moonscratch`, you also have to run:
+  * `moon check` (in `packages/moonscratch`)
+  * `bun run test` (in `packages/moonscratch`)

a.svg

@@ -15,12 +15,12 @@ You can browse and install extra skills here:
 - In the toplevel directory, there is a `moon.mod.json` file listing module
   metadata.
 
-* src/ にあるテストはユニットテストのみで、マクロなテストは test/ に書く
+* Tests under `src/` are unit tests only; macro-style tests should be written in `test/`.
 
 ## AGENTS.md Maintenance
 
-- AGENTS.md はルートだけでなく、責務が分かれる主要ディレクトリにも配置する。
-- エージェントはプロジェクト構成や運用ルールの変更を検知したら、関連する AGENTS.md を必要に応じて自律的に更新し、現状と乖離させない。
+- Place `AGENTS.md` files not only at the root but also in major directories where responsibilities diverge.
+- Agents should autonomously update related `AGENTS.md` files when project structure or operating rules change, keeping instructions synchronized with the current state.
 
 ## Coding convention
 
@@ -77,3 +77,8 @@ You can browse and install extra skills here:
 - `bun run test` to run tests. `vite-plus/test` API is same as `vitest`.
 - `bun run build` to build the project.
 - `bun typecheck` to typecheck the code using `tsgo`.
+- If you add or modify tests, run `bun run test` before reporting completion.
+- Required before finishing any change in `packages/moonscratch`:
+  - `bun typecheck`
+  - `moon check`
+  - `bun run test`

bun.lock

@@ -31,7 +31,7 @@ JS からは Wasm ラッパ API で利用可能にする。
   - new/start/green_flag/step/post_io/broadcast/stop_all/snapshot/dispose
 - JS API
   - createHeadlessVM({projectJson, assets, options, host})
-  - start(), greenFlag(), step(dtMs), postIO(), onEffect(), getSnapshot()
+  - start(), greenFlag(), setTime(nowMs), stepFrame(frameCount?), postIO(), onEffect(), getSnapshot()
 
 ### Implementation
 

packages/moonscratch/AGENTS.md

@@ -25,7 +25,8 @@ test {
     Err(_) => fail("failed to create vm")
   }
   @moonscratch.vm_start(vm)
-  let report = @moonscratch.vm_step(vm, 16)
+  @moonscratch.vm_set_time(vm, 33)
+  let report = @moonscratch.vm_step_frame(vm, 1)
   let snapshot_json = @moonscratch.vm_snapshot_json(vm)
   inspect(report.active_threads >= 0, content="true")
   inspect(snapshot_json.contains("targets"), content="true")
@@ -56,7 +57,8 @@ import {
 
 const vm = createHeadlessVM({ projectJson, assets, options })
 vm.greenFlag()
-vm.step(16)
+vm.setTime(Date.now())
+vm.stepFrame()
 const effects = vm.takeEffects()
 const snapshot = vm.snapshot()
 

packages/moonscratch/PLAN.md

@@ -0,0 +1,84 @@
+# nakasyou/moonscratch
+
+Headless Scratch runtime in MoonBit.
+
+## What is implemented
+
+- Loads Scratch 3 `project.json` (+ optional assets metadata map)
+- Can fill missing costume assets from `cdn.scratch.mit.edu` (async API)
+- Runs scripts from hats (`event_whenflagclicked`, `event_whenbroadcastreceived`)
+- Supports core opcodes for:
+  - `event`, `control`, `data`, `operator`
+  - subset of `motion`, `looks`, `sound`, `sensing`
+- Emits side effects as JSON event queue (`vm_take_effects_json`)
+
+## MoonBit API
+
+```mbt check
+///|
+test {
+  let precompiled_result = try? @moonscratch.vm_compile_from_json(
+    "{\"targets\":[{\"isStage\":true,\"name\":\"Stage\",\"variables\":{},\"lists\":{},\"blocks\":{}}]}",
+  )
+  let precompiled = match precompiled_result {
+    Ok(value) => value
+    Err(_) => fail("failed to precompile project")
+  }
+  let vm_result = try? @moonscratch.vm_new_from_compiled(precompiled)
+  let vm = match vm_result {
+    Ok(value) => value
+    Err(_) => fail("failed to create vm")
+  }
+  @moonscratch.vm_start(vm)
+  @moonscratch.vm_set_time(vm, 33)
+  let report = @moonscratch.vm_step_frame(vm)
+  let snapshot_json = @moonscratch.vm_snapshot_json(vm)
+  inspect(report.active_threads >= 0, content="true")
+  inspect(snapshot_json.contains("targets"), content="true")
+}
+```
+
+## JavaScript setup
+
+Build JS artifacts:
+
+```bash
+moon build --target js
+```
+
+Use the JS wrapper:
+
+```bash
+node js/example.mjs
+```
+
+Wrapper file: `js/headless-vm.mjs`
+
+```js
+import {
+  createHeadlessVM,
+  createPrecompiledProject,
+  createHeadlessVMWithScratchAssets,
+} from './js/headless-vm.mjs'
+
+const precompiled = createPrecompiledProject({ projectJson, assets })
+const vm = createHeadlessVM({ precompiled, options })
+vm.greenFlag()
+vm.setTime(Date.now())
+vm.stepFrame()
+const effects = vm.takeEffects()
+const snapshot = vm.snapshot()
+
+const vmWithScratchAssets = await createHeadlessVMWithScratchAssets({
+  projectJson,
+  assets,
+  options,
+})
+```
+
+## Verification
+
+```bash
+moon check
+moon test
+```

packages/moonscratch/README.mbt.md

@@ -0,0 +1,149 @@
+import { Project } from 'hikkaku'
+import {
+  add,
+  addToList,
+  and,
+  changeVariableBy,
+  divide,
+  equals,
+  gt,
+  ifThen,
+  lt,
+  mathop,
+  mod,
+  multiply,
+  or,
+  repeat,
+  repeatUntil,
+  setVariableTo,
+  subtract,
+  whenFlagClicked,
+} from 'hikkaku/blocks'
+import { bench, describe } from 'vite-plus/test'
+import { createHeadlessVM, createPrecompiledProject } from '../js/vm/factory.ts'
+
+await import('scratch-storage')
+
+const benchOptions = {
+  time: 3000,
+  warmupTime: 1000,
+}
+
+const runUntilFinished = (vm: {
+  greenFlag(): void
+  stepFrame(): { stopReason: string }
+}) => {
+  vm.greenFlag()
+  while (true) {
+    const result = vm.stepFrame()
+    if (result.stopReason === 'finished') {
+      break
+    }
+  }
+}
+
+describe('calc', () => {
+  const project = new Project()
+  const acc = project.stage.createVariable('acc', 0)
+  const angle = project.stage.createVariable('angle', 0)
+
+  project.stage.run(() => {
+    whenFlagClicked(() => {
+      setVariableTo(acc, 0)
+      setVariableTo(angle, 0)
+      repeat(50000, () => {
+        setVariableTo(
+          acc,
+          add(
+            acc.get(),
+            multiply(mathop('sin', angle.get()), mathop('cos', angle.get())),
+          ),
+        )
+        changeVariableBy(angle, subtract(divide(angle.get(), 2), -1))
+      })
+    })
+  })
+
+  const projectJson = project.toScratch()
+  const precompiled = createPrecompiledProject({ projectJson })
+  const vm = createHeadlessVM({
+    precompiled,
+    initialNowMs: 0,
+    options: {
+      stepTimeoutTicks: 1000000,
+      turbo: true,
+    },
+  })
+
+  bench(
+    'moonscratch',
+    () => {
+      runUntilFinished(vm)
+    },
+    benchOptions,
+  )
+})
+
+describe('calc primes', () => {
+  const project = new Project()
+  const primes = project.stage.createList('primes', [])
+  const candidate = project.stage.createVariable('candidate', 2)
+  const divisor = project.stage.createVariable('divisor', 0)
+  const isPrime = project.stage.createVariable('is prime', 0)
+  const primeCount = project.stage.createVariable('prime count', 0)
+
+  project.stage.run(() => {
+    whenFlagClicked(() => {
+      setVariableTo(primeCount, 0)
+      setVariableTo(candidate, 2)
+      setVariableTo(divisor, 2)
+      setVariableTo(isPrime, 0)
+      repeatUntil(equals(primeCount.get(), 100), () => {
+        setVariableTo(isPrime, 1)
+        setVariableTo(divisor, 2)
+        repeatUntil(
+          or(
+            gt(divisor.get(), mathop('sqrt', candidate.get())),
+            equals(isPrime.get(), 0),
+          ),
+          () => {
+            ifThen(
+              and(
+                equals(mod(candidate.get(), divisor.get()), 0),
+                lt(divisor.get(), candidate.get()),
+              ),
+              () => {
+                setVariableTo(isPrime, 0)
+              },
+            )
+            changeVariableBy(divisor, 1)
+          },
+        )
+        ifThen(equals(isPrime.get(), 1), () => {
+          addToList(primes, candidate.get())
+          changeVariableBy(primeCount, 1)
+        })
+        changeVariableBy(candidate, 1)
+      })
+    })
+  })
+
+  const projectJson = project.toScratch()
+  const precompiled = createPrecompiledProject({ projectJson })
+  const vm = createHeadlessVM({
+    precompiled,
+    initialNowMs: 0,
+    options: {
+      stepTimeoutTicks: 1000000,
+      turbo: true,
+    },
+  })
+
+  bench(
+    'moonscratch',
+    () => {
+      runUntilFinished(vm)
+    },
+    benchOptions,
+  )
+})