moonscratch 0.1.0-alpha.0

package/js/assets/build-asset.ts

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,142 @@
+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==',
+    })
+  })
+})

package/js/assets/create.ts

@@ -0,0 +1,122 @@
+import { buildAsset } from './build-asset.ts'
+import type {
+  CanvasLike,
+  ImageDataLike,
+  RgbaAsset,
+  RgbaMatrix,
+} from './types.ts'
+import { toByte, toPositiveInt } from './validation.ts'
+
+export const fromRgbaBytes = (
+  width: number,
+  height: number,
+  rgba: ArrayLike<number>,
+): RgbaAsset => buildAsset(width, height, rgba)
+
+export const fromImageData = (imageData: ImageDataLike): RgbaAsset =>
+  buildAsset(imageData.width, imageData.height, imageData.data)
+
+export const fromCanvas = (canvas: CanvasLike): RgbaAsset => {
+  const width = toPositiveInt(canvas.width, 'canvas.width')
+  const height = toPositiveInt(canvas.height, 'canvas.height')
+  const context = canvas.getContext('2d')
+
+  if (!context) {
+    throw new Error('canvas.getContext("2d") returned null')
+  }
+
+  return fromImageData(context.getImageData(0, 0, width, height))
+}
+
+export const fromRgbaMatrix = (pixels: RgbaMatrix): RgbaAsset => {
+  const height = pixels.length
+  if (height <= 0) {
+    throw new Error('pixels must have at least one row')
+  }
+
+  const firstRow = pixels[0]
+  const width = firstRow?.length ?? 0
+  if (width <= 0) {
+    throw new Error('pixels must have at least one column')
+  }
+
+  const flat = new Uint8Array(width * height * 4)
+
+  for (let y = 0; y < height; y += 1) {
+    const row = pixels[y]
+    if (!row || row.length !== width) {
+      throw new Error(`pixels[${y}] must contain exactly ${width} columns`)
+    }
+
+    for (let x = 0; x < width; x += 1) {
+      const pixel = row[x]
+      if (!pixel || pixel.length < 4) {
+        throw new Error(`pixels[${y}][${x}] must contain 4 channels (RGBA)`)
+      }
+
+      const base = (y * width + x) * 4
+      flat[base] = toByte(pixel[0], `pixels[${y}][${x}][0]`)
+      flat[base + 1] = toByte(pixel[1], `pixels[${y}][${x}][1]`)
+      flat[base + 2] = toByte(pixel[2], `pixels[${y}][${x}][2]`)
+      flat[base + 3] = toByte(pixel[3], `pixels[${y}][${x}][3]`)
+    }
+  }
+
+  return buildAsset(width, height, flat)
+}
+
+type SharpNamespace = {
+  default?: (input?: unknown) => SharpPipeline
+}
+
+type SharpPipeline = {
+  ensureAlpha(): SharpPipeline
+  raw(): SharpPipeline
+  toBuffer(options: { resolveWithObject: true }): Promise<{
+    data: Uint8Array
+    info: {
+      width: number
+      height: number
+    }
+  }>
+}
+
+const loadSharp = async (): Promise<(input?: unknown) => SharpPipeline> => {
+  try {
+    const sharp = (await import('sharp')) as SharpNamespace
+    return (
+      sharp.default ??
+      ((sharp as unknown as { sharp?: (input?: unknown) => SharpPipeline })
+        .sharp as ((input?: unknown) => SharpPipeline) | undefined) ??
+      (() => {
+        throw new Error('invalid sharp module shape')
+      })
+    )
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new Error(`sharp is required to load image assets: ${reason}`)
+  }
+}
+
+const fromSharpPipeline = async (
+  pipeline: SharpPipeline,
+): Promise<RgbaAsset> => {
+  const { data, info } = await pipeline
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true })
+  return fromRgbaBytes(info.width, info.height, data)
+}
+
+export const fromImageBytes = async (
+  bytes: ArrayBuffer | Uint8Array,
+): Promise<RgbaAsset> => {
+  const sharp = await loadSharp()
+  const normalized = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+  return fromSharpPipeline(sharp(normalized))
+}
+
+export const fromImageFile = async (path: string): Promise<RgbaAsset> => {
+  const sharp = await loadSharp()
+  return fromSharpPipeline(sharp(path))
+}

package/js/assets/index.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'vite-plus/test'
+
+import * as create from './create.ts'
+import * as index from './index.ts'
+
+describe('moonscratch/js/assets/index.ts', () => {
+  test('re-exports create helpers', () => {
+    expect(index.fromRgbaBytes).toBe(create.fromRgbaBytes)
+    expect(index.fromImageData).toBe(create.fromImageData)
+    expect(index.fromCanvas).toBe(create.fromCanvas)
+    expect(index.fromRgbaMatrix).toBe(create.fromRgbaMatrix)
+    expect(index.fromImageBytes).toBe(create.fromImageBytes)
+    expect(index.fromImageFile).toBe(create.fromImageFile)
+  })
+})

package/js/assets/index.ts

@@ -0,0 +1,2 @@
+export * from './create.ts'
+export * from './types.ts'

package/js/assets/types.ts

@@ -0,0 +1,26 @@
+export interface RgbaAsset {
+  width: number
+  height: number
+  rgbaBase64: string
+}
+
+export type RgbaTuple = readonly [number, number, number, number]
+export type RgbaMatrix = ReadonlyArray<
+  ReadonlyArray<RgbaTuple | ReadonlyArray<number>>
+>
+
+export interface ImageDataLike {
+  width: number
+  height: number
+  data: ArrayLike<number>
+}
+
+export interface Canvas2DContextLike {
+  getImageData(sx: number, sy: number, sw: number, sh: number): ImageDataLike
+}
+
+export interface CanvasLike {
+  width: number
+  height: number
+  getContext(contextId: string, options?: unknown): Canvas2DContextLike | null
+}

package/js/assets/validation.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'vite-plus/test'
+
+import { toByte, toPositiveInt } from './validation.ts'
+
+describe('moonscratch/js/assets/validation.ts', () => {
+  test('toPositiveInt accepts finite positive integers', () => {
+    expect(toPositiveInt(1, 'width')).toBe(1)
+  })
+
+  test('toPositiveInt rejects invalid values', () => {
+    expect(() => toPositiveInt(Number.NaN, 'width')).toThrow(
+      'width must be a finite number',
+    )
+    expect(() => toPositiveInt(1.5, 'height')).toThrow(
+      'height must be an integer',
+    )
+    expect(() => toPositiveInt(0, 'height')).toThrow(
+      'height must be greater than 0',
+    )
+  })
+
+  test('toByte accepts byte values', () => {
+    expect(toByte(255, 'rgba[0]')).toBe(255)
+  })
+
+  test('toByte rejects out-of-range values', () => {
+    expect(() => toByte(-1, 'rgba[0]')).toThrow(
+      'rgba[0] must be between 0 and 255',
+    )
+    expect(() => toByte(256, 'rgba[1]')).toThrow(
+      'rgba[1] must be between 0 and 255',
+    )
+  })
+})

package/js/assets/validation.ts

@@ -0,0 +1,25 @@
+export const toPositiveInt = (value: unknown, name: string): number => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`${name} must be a finite number`)
+  }
+  if (!Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer`)
+  }
+  if (value <= 0) {
+    throw new Error(`${name} must be greater than 0`)
+  }
+  return value
+}
+
+export const toByte = (value: unknown, name: string): number => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`${name} must be a finite number`)
+  }
+  if (!Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer`)
+  }
+  if (value < 0 || value > 255) {
+    throw new Error(`${name} must be between 0 and 255`)
+  }
+  return value
+}

package/js/assets.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from 'vite-plus/test'
+import * as assetsIndex from './assets/index.ts'
+import * as assets from './assets.ts'
+
+describe('moonscratch/js/assets.ts', () => {
+  test('re-exports public asset APIs', () => {
+    expect(assets.fromRgbaBytes).toBe(assetsIndex.fromRgbaBytes)
+    expect(assets.fromImageData).toBe(assetsIndex.fromImageData)
+    expect(assets.fromCanvas).toBe(assetsIndex.fromCanvas)
+    expect(assets.fromRgbaMatrix).toBe(assetsIndex.fromRgbaMatrix)
+    expect(assets.fromImageBytes).toBe(assetsIndex.fromImageBytes)
+    expect(assets.fromImageFile).toBe(assetsIndex.fromImageFile)
+  })
+})

package/js/assets.ts

@@ -0,0 +1 @@
+export * from './assets/index.ts'

package/js/index.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'vite-plus/test'
+
+import * as assetsIndex from './assets/index.ts'
+import * as index from './index.ts'
+import * as renderIndex from './render/index.ts'
+import * as vmIndex from './vm/index.ts'
+
+describe('moonscratch/js/index.ts', () => {
+  test('re-exports vm and assets APIs', () => {
+    expect(index.createHeadlessVM).toBe(vmIndex.createHeadlessVM)
+    expect(index.createVM).toBe(vmIndex.createVM)
+    expect(index.moonscratch).toBe(vmIndex.moonscratch)
+
+    expect(index.fromRgbaBytes).toBe(assetsIndex.fromRgbaBytes)
+    expect(index.fromImageData).toBe(assetsIndex.fromImageData)
+    expect(index.fromCanvas).toBe(assetsIndex.fromCanvas)
+    expect(index.fromRgbaMatrix).toBe(assetsIndex.fromRgbaMatrix)
+    expect(index.fromImageBytes).toBe(assetsIndex.fromImageBytes)
+    expect(index.fromImageFile).toBe(assetsIndex.fromImageFile)
+
+    expect(index.renderWithSVG).toBe(renderIndex.renderWithSVG)
+    expect(index.renderWithSharp).toBe(renderIndex.renderWithSharp)
+    expect(index.renderWithWebGL).toBe(renderIndex.renderWithWebGL)
+    expect(index.normalizeRenderFrame).toBe(renderIndex.normalizeRenderFrame)
+  })
+})

package/js/index.ts

@@ -0,0 +1,3 @@
+export * from './assets/index.ts'
+export * from './render/index.ts'
+export * from './vm/index.ts'

package/js/render/index.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test, vi } from 'vite-plus/test'
+
+import { renderWithSharp, renderWithSVG, renderWithWebGL } from './index.ts'
+
+const sharpCalls: unknown[] = []
+
+vi.mock('sharp', () => ({
+  default: vi.fn((input?: unknown, options?: unknown) => {
+    sharpCalls.push([input, options])
+    return {
+      raw() {
+        return this
+      },
+      png() {
+        return this
+      },
+      jpeg() {
+        return this
+      },
+      webp() {
+        return this
+      },
+      async toBuffer() {
+        return Buffer.from([1, 2, 3, 4])
+      },
+    }
+  }),
+}))
+
+describe('moonscratch/js/render', () => {
+  const frame = {
+    width: 2,
+    height: 2,
+    pixels: new Uint8Array([
+      255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255,
+    ]),
+  }
+
+  test('renderWithSVG builds a compact svg payload', () => {
+    const svg = renderWithSVG(frame)
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('shape-rendering="crispEdges"')
+    expect(svg).toContain('fill="rgb(255,0,0)"')
+    expect(svg).toContain('</svg>')
+  })
+
+  test('renderWithSharp calls sharp and returns buffer', async () => {
+    const buffer = await renderWithSharp(frame)
+    expect(sharpCalls).toEqual([
+      [frame.pixels, { raw: { width: 2, height: 2, channels: 4 } }],
+    ])
+    expect(buffer).toEqual(Buffer.from([1, 2, 3, 4]))
+  })
+
+  test('renderWithWebGL throws when canvas is not available', () => {
+    expect(() =>
+      renderWithWebGL({
+        ...frame,
+        width: 1,
+        height: 1,
+        pixels: new Uint8Array([0, 0, 0, 255]),
+      }),
+    ).toThrow('renderWithWebGL')
+  })
+})

package/js/render/index.ts

@@ -0,0 +1,13 @@
+export { renderWithSharp } from './sharp.ts'
+export { renderWithSVG } from './svg.ts'
+export type {
+  RenderFrame,
+  RenderFrameLike,
+  RenderImageData,
+  RenderWithSharpOptions,
+  RenderWithWebGLOptions,
+  RenderWithWebGLResult,
+  WebGLRenderResult,
+} from './types.ts'
+export { normalizeRenderFrame, normalizeRenderFrameTrusted } from './utils.ts'
+export { renderWithWebGL } from './webgl.ts'

package/js/render/sharp.ts

@@ -0,0 +1,87 @@
+import type { RenderFrame, RenderWithSharpOptions } from './types.ts'
+import { normalizeRenderFrame } from './utils.ts'
+
+type SharpNamespace = {
+  default?: SharpFactory
+  sharp?: SharpFactory
+}
+
+type SharpFactory = (input?: unknown, options?: unknown) => SharpPipeline
+
+type SharpPipeline = {
+  raw?(): SharpPipeline
+  png?(): SharpPipeline
+  jpeg?(): SharpPipeline
+  webp?(): SharpPipeline
+  toBuffer(): Promise<unknown>
+}
+
+const loadSharp = async (): Promise<
+  (input?: unknown, options?: unknown) => SharpPipeline
+> => {
+  try {
+    const sharp = (await import('sharp')) as unknown as SharpNamespace
+    if (sharp.default) {
+      return sharp.default
+    }
+    const direct = sharp.sharp
+    if (typeof direct === 'function') {
+      return direct
+    }
+    throw new Error('invalid sharp module shape')
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new Error(
+      `sharp is required to render PNG/WebP/JPEG output: ${reason}`,
+    )
+  }
+}
+
+export const renderWithSharp = async (
+  input: RenderFrame,
+  options: RenderWithSharpOptions = {},
+): Promise<Buffer> => {
+  const frame = normalizeRenderFrame(input)
+  if (frame.width <= 0 || frame.height <= 0) {
+    return Buffer.from([])
+  }
+
+  const sharp = await loadSharp()
+  const pipeline = sharp(frame.pixels, {
+    raw: { width: frame.width, height: frame.height, channels: 4 },
+  })
+  const format = options.format ?? 'png'
+  let current = pipeline
+  switch (format) {
+    case 'png':
+      if (typeof current.png === 'function') {
+        current = current.png()
+      }
+      break
+    case 'jpeg':
+    case 'jpg':
+      if (typeof current.jpeg === 'function') {
+        current = current.jpeg()
+      }
+      break
+    case 'webp':
+      if (typeof current.webp === 'function') {
+        current = current.webp()
+      }
+      break
+    default:
+      throw new Error(`unsupported sharp output format: ${String(format)}`)
+  }
+
+  if (typeof current.toBuffer !== 'function') {
+    throw new Error('sharp pipeline does not expose toBuffer')
+  }
+  const rawBuffer = await current.toBuffer()
+  if (rawBuffer instanceof Buffer) {
+    return rawBuffer
+  }
+  if (rawBuffer instanceof Uint8Array) {
+    return Buffer.from(rawBuffer)
+  }
+  throw new Error('sharp returned unsupported buffer type')
+}

package/js/render/svg.ts

@@ -0,0 +1,68 @@
+import type { RenderFrame } from './types.ts'
+import { normalizeRenderFrame } from './utils.ts'
+
+const appendRect = (
+  parts: string[],
+  x: number,
+  y: number,
+  width: number,
+  rgba: [number, number, number, number],
+): void => {
+  const [r, g, b, a] = rgba
+  if (width <= 0 || a <= 0) {
+    return
+  }
+  const opacity = a < 255 ? ` fill-opacity="${a / 255}"` : ''
+  parts.push(
+    `<rect x="${x}" y="${y}" width="${width}" height="1" fill="rgb(${r},${g},${b})"${opacity}/>`,
+  )
+}
+
+const isPixelEqual = (
+  pixels: Uint8Array,
+  base: number,
+  otherBase: number,
+): boolean =>
+  pixels[base] === pixels[otherBase] &&
+  pixels[base + 1] === pixels[otherBase + 1] &&
+  pixels[base + 2] === pixels[otherBase + 2] &&
+  pixels[base + 3] === pixels[otherBase + 3]
+
+const pixelByte = (value: number | undefined): number => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return 0
+  }
+  return value
+}
+
+export const renderWithSVG = (frame: RenderFrame): string => {
+  const normalized = normalizeRenderFrame(frame)
+  const { width, height, pixels } = normalized
+  const parts = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" shape-rendering="crispEdges">`,
+  ]
+
+  for (let y = 0; y < height; y += 1) {
+    let x = 0
+    while (x < width) {
+      const base = (y * width + x) * 4
+      const r = pixelByte(pixels[base])
+      const g = pixelByte(pixels[base + 1])
+      const b = pixelByte(pixels[base + 2])
+      const a = pixelByte(pixels[base + 3])
+      let runWidth = 1
+      while (x + runWidth < width) {
+        const nextBase = (y * width + x + runWidth) * 4
+        if (!isPixelEqual(pixels, base, nextBase)) {
+          break
+        }
+        runWidth += 1
+      }
+      appendRect(parts, x, y, runWidth, [r, g, b, a])
+      x += runWidth
+    }
+  }
+
+  parts.push('</svg>')
+  return parts.join('')
+}