pixel-data-js 0.23.1 → 0.24.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-data-js",
   "type": "module",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "packageManager": "pnpm@10.30.0",
   "description": "JS Pixel and ImageData operations",
   "author": {
@@ -50,6 +50,7 @@
     "build": "tsup",
     "test": "vitest --coverage --project unit",
     "test:build": "pnpm build && vitest run --project dist",
+    "check-circ": "tsx _scripts/check-circular.ts",
     "test:mutation": "stryker run",
     "docs": "npx typedoc",
     "typecheck": "tsc --noEmit",
@@ -88,7 +89,7 @@
     "typedoc-plugin-mdn-links": "^5.1.1",
     "typedoc-rhineai-theme": "^1.2.0",
     "typescript": "^5.9.3",
-    "unplugin-inline": "^1.8.0",
+    "unplugin-inline": "^1.9.0",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "3.2.4"
   },

package/src/Canvas/CanvasFrameRenderer.ts

@@ -0,0 +1,57 @@
+import type { PixelCanvas } from './PixelCanvas'
+import { makeReusableCanvas } from './ReusableCanvas'
+
+export type DrawPixelLayer = (ctx: CanvasRenderingContext2D) => void
+export type DrawScreenLayer = (ctx: CanvasRenderingContext2D, scale: number) => void
+export type CanvasFrameRenderer = ReturnType<typeof makeCanvasFrameRenderer>
+
+const defaults = {
+  makeReusableCanvas,
+}
+
+type Deps = Partial<typeof defaults>
+
+/**
+ * @param deps - @hidden
+ */
+export function makeCanvasFrameRenderer(deps: Deps = defaults) {
+  const {
+    makeReusableCanvas = defaults.makeReusableCanvas,
+  } = deps
+
+  const bufferCanvas = makeReusableCanvas()
+
+  return function renderCanvasFrame(
+    pixelCanvas: PixelCanvas,
+    scale: number,
+    getImageData: () => ImageData | undefined | null,
+    drawPixelLayer?: DrawPixelLayer,
+    drawScreenLayer?: DrawScreenLayer,
+  ) {
+    const { canvas, ctx } = pixelCanvas
+
+    // 1. Clear pixel buffer (unscaled)
+    const { ctx: pxCtx, canvas: pxCanvas } = bufferCanvas(canvas.width, canvas.height)
+
+    // 2. Draw pixel data into pixel buffer
+    const img = getImageData()
+    if (img) {
+      pxCtx.putImageData(img, 0, 0)
+    }
+
+    // draw transient pixel data
+    drawPixelLayer?.(pxCtx)
+
+    // clear target canvas
+    ctx.setTransform(1, 0, 0, 1, 0, 0)
+    ctx.clearRect(0, 0, canvas.width, canvas.height)
+
+    // Draw pixel buffer scaled onto screen
+    ctx.setTransform(scale, 0, 0, scale, 0, 0)
+    ctx.drawImage(pxCanvas, 0, 0)
+
+    // Draw overlays in screen space
+    ctx.setTransform(1, 0, 0, 1, 0, 0)
+    drawScreenLayer?.(ctx, scale)
+  }
+}

package/src/Canvas/ReusableCanvas.ts

@@ -1,25 +1,69 @@
 import { CANVAS_CTX_FAILED } from './_constants'
 
-export type ReusableCanvas = {
-  readonly canvas: HTMLCanvasElement
-  readonly ctx: CanvasRenderingContext2D
+export type CanvasContext<T> = T extends HTMLCanvasElement
+  ? CanvasRenderingContext2D
+  : OffscreenCanvasRenderingContext2D
+
+export type ReusableCanvas<T extends HTMLCanvasElement | OffscreenCanvas> = {
+  readonly canvas: T
+  readonly ctx: CanvasContext<T>
 }
 
 /**
- * Creates a reusable canvas and context that are not part of the DOM.
+ * Creates a reusable HTMLCanvasElement and context that are not part of the DOM.
  * Ensures it is always set to `context.imageSmoothingEnabled = false`
  * @see makePixelCanvas
  * @throws {Error} If the {@link HTMLCanvasElement} context cannot be initialized.
  */
 export function makeReusableCanvas() {
-  let canvas: HTMLCanvasElement | null = null
-  let ctx: CanvasRenderingContext2D | null = null
+  return makeReusableCanvasMeta<HTMLCanvasElement>((w, h) => {
+    const canvas = document.createElement('canvas')
+
+    canvas.width = w
+    canvas.height = h
+
+    return canvas
+  })
+}
+
+/**
+ * Creates a reusable OffscreenCanvas and context.
+ * Ensures it is always set to `context.imageSmoothingEnabled = false`
+ * @see makePixelCanvas
+ * @throws {Error} If the {@link OffscreenCanvasRenderingContext2D} context cannot be initialized.
+ */
+export function makeReusableOffscreenCanvas() {
+  return makeReusableCanvasMeta<OffscreenCanvas>((w, h) => new OffscreenCanvas(w, h))
+}
+
+function makeReusableCanvasMeta<T extends HTMLCanvasElement | OffscreenCanvas>(
+  factory: (w: number, h: number) => T,
+) {
+  let canvas: T | null = null
+  let ctx: CanvasContext<T> | null = null
 
-  function get(width: number, height: number): ReusableCanvas {
+  const result: ReusableCanvas<T> = {
+    canvas: null as any,
+    ctx: null as any,
+  }
+
+  function get(width: number, height: number): ReusableCanvas<T> {
     if (canvas === null) {
-      canvas = document.createElement('canvas')!
-      ctx = canvas.getContext('2d')!
-      if (!ctx) throw new Error(CANVAS_CTX_FAILED)
+      canvas = factory(width, height)
+      ctx = canvas.getContext('2d') as CanvasContext<T> | null
+
+      if (!ctx) {
+        throw new Error(CANVAS_CTX_FAILED)
+      }
+
+      // Initialize the fresh context state
+      ctx.imageSmoothingEnabled = false
+
+      ;(result as any).canvas = canvas
+      ;(result as any).ctx = ctx
+
+      // Early return to skip resize/clear checks for brand new canvases
+      return result
     }
 
     // Resize if needed (resizing auto-clears)
@@ -28,16 +72,21 @@ export function makeReusableCanvas() {
       canvas.height = height
       ctx!.imageSmoothingEnabled = false
     } else {
+      // Always reset transform before clearing to ensure the whole buffer is wiped
+      ctx!.setTransform(1, 0, 0, 1, 0, 0)
       // Same size → manually clear
       ctx!.clearRect(0, 0, width, height)
     }
 
-    return { canvas, ctx: ctx! }
+    return result
   }
 
   get.reset = () => {
     canvas = null
     ctx = null
+
+    ;(result as any).canvas = null
+    ;(result as any).ctx = null
   }
 
   return get

package/src/History/HistoryAction.ts

@@ -0,0 +1,38 @@
+import { applyPatchTiles, type PixelPatchTiles } from './PixelPatchTiles'
+import type { PixelWriter } from './PixelWriter'
+
+export interface HistoryAction {
+  undo: () => void
+  redo: () => void
+  dispose?: () => void
+}
+
+export type HistoryActionFactory = typeof makeHistoryAction
+
+export function makeHistoryAction(
+  writer: PixelWriter<any>,
+  patch: PixelPatchTiles,
+  after?: () => void,
+  afterUndo?: () => void,
+  afterRedo?: () => void,
+  applyPatchTilesFn = applyPatchTiles,
+): HistoryAction {
+
+  const target = writer.config.target
+  const tileSize = writer.config.tileSize
+  const accumulator = writer.accumulator
+
+  return {
+    undo: () => {
+      applyPatchTilesFn(target, patch.beforeTiles, tileSize)
+      afterUndo?.()
+      after?.()
+    },
+    redo: () => {
+      applyPatchTilesFn(target, patch.afterTiles, tileSize)
+      afterRedo?.()
+      after?.()
+    },
+    dispose: () => accumulator.recyclePatch(patch),
+  }
+}

package/src/History/HistoryManager.ts

@@ -1,13 +1,9 @@
-export interface HistoryAction {
-  undo: () => void
-  redo: () => void
-  dispose?: () => void
-}
+import type { HistoryAction } from './HistoryAction'
 
 export class HistoryManager {
-  public undoStack: HistoryAction[]
-  public redoStack: HistoryAction[]
-  public listeners: Set<() => void>
+  readonly undoStack: HistoryAction[]
+  readonly redoStack: HistoryAction[]
+  readonly listeners: Set<() => void>
 
   constructor(
     public maxSteps = 50,

package/src/History/PixelAccumulator.ts

@@ -1,95 +1,61 @@
-import type { IPixelData } from '../_types'
+import { PixelTile } from '../PixelTile/PixelTile'
+import type { PixelTilePool } from '../PixelTile/PixelTilePool'
 import type { PixelEngineConfig } from './PixelEngineConfig'
-import { type PixelPatchTiles, PixelTile } from './PixelPatchTiles'
+import { applyPatchTiles, type PixelPatchTiles } from './PixelPatchTiles'
+
+export type DidChangeFn = (didChange: boolean) => boolean
 
 export class PixelAccumulator {
   public lookup: (PixelTile | undefined)[]
   public beforeTiles: PixelTile[]
-  public pool: PixelTile[]
 
   constructor(
-    public target: IPixelData,
     readonly config: PixelEngineConfig,
+    readonly tilePool: PixelTilePool,
   ) {
     this.lookup = []
     this.beforeTiles = []
-    this.pool = []
-  }
-
-  getTile(
-    id: number,
-    tx: number,
-    ty: number,
-  ): PixelTile {
-    let tile = this.pool.pop()
-
-    if (tile) {
-      tile.id = id
-      tile.tx = tx
-      tile.ty = ty
-
-      return tile
-    }
-
-    return new PixelTile(
-      id,
-      tx,
-      ty,
-      this.config.tileArea,
-    )
   }
 
   recyclePatch(patch: PixelPatchTiles) {
-    const before = patch.beforeTiles
-
-    for (let i = 0; i < before.length; i++) {
-      let tile = before[i]
-
-      if (tile) {
-        this.pool.push(tile)
-      }
-    }
-
-    const after = patch.afterTiles
-
-    for (let i = 0; i < after.length; i++) {
-      let tile = after[i]
-
-      if (tile) {
-        this.pool.push(tile)
-      }
-    }
+    this.tilePool.releaseTiles(patch.beforeTiles)
+    this.tilePool.releaseTiles(patch.afterTiles)
   }
 
   /**
    * @param x pixel x coordinate
    * @param y pixel y coordinate
    */
-  storeTileBeforeState(x: number, y: number): void {
-    let target = this.target
+  storePixelBeforeState(x: number, y: number): DidChangeFn {
     let shift = this.config.tileShift
-    let columns = (target.width + this.config.tileMask) >> shift
+    let columns = this.config.targetColumns
     let tx = x >> shift
     let ty = y >> shift
     let id = ty * columns + tx
 
     let tile = this.lookup[id]
+    let added = false
 
     if (!tile) {
-      tile = this.getTile(
-        id,
-        tx,
-        ty,
-      )
+      tile = this.tilePool.getTile(id, tx, ty)
 
       this.extractState(tile)
       this.lookup[id] = tile
       this.beforeTiles.push(tile)
+      added = true
+    }
+
+    return (didChange: boolean) => {
+      if (!didChange && added) {
+        this.beforeTiles.pop()
+        this.lookup[id] = undefined
+        this.tilePool.releaseTile(tile!)
+      }
+      return didChange
     }
   }
 
   /**
-   *
    * @param x pixel x coordinate
    * @param y pixel y coordinate
    * @param w pixel width
@@ -100,27 +66,24 @@ export class PixelAccumulator {
     y: number,
     w: number,
     h: number,
-  ) {
-    let target = this.target
+  ): DidChangeFn {
     let shift = this.config.tileShift
-    let columns = (target.width + this.config.tileMask) >> shift
+    let columns = this.config.targetColumns
 
     let startX = x >> shift
     let startY = y >> shift
     let endX = (x + w - 1) >> shift
     let endY = (y + h - 1) >> shift
 
+    let startIndex = this.beforeTiles.length
+
     for (let ty = startY; ty <= endY; ty++) {
       for (let tx = startX; tx <= endX; tx++) {
         let id = ty * columns + tx
         let tile = this.lookup[id]
 
         if (!tile) {
-          tile = this.getTile(
-            id,
-            tx,
-            ty,
-          )
+          tile = this.tilePool.getTile(id, tx, ty)
 
           this.extractState(tile)
           this.lookup[id] = tile
@@ -128,10 +91,28 @@ export class PixelAccumulator {
         }
       }
     }
+
+    return (didChange: boolean) => {
+      if (!didChange) {
+        let length = this.beforeTiles.length
+
+        for (let i = startIndex; i < length; i++) {
+          let t = this.beforeTiles[i]
+
+          if (t) {
+            this.lookup[t.id] = undefined
+            this.tilePool.releaseTile(t)
+          }
+        }
+
+        this.beforeTiles.length = startIndex
+      }
+      return didChange
+    }
   }
 
   extractState(tile: PixelTile) {
-    let target = this.target
+    let target = this.config.target
     let TILE_SIZE = this.config.tileSize
     let dst = tile.data32
     let src = target.data32
@@ -140,29 +121,45 @@ export class PixelAccumulator {
     let targetWidth = target.width
     let targetHeight = target.height
 
-    let copyWidth = Math.max(0, Math.min(TILE_SIZE, targetWidth - startX))
+    // If the tile is completely outside the canvas, zero it out.
+    if (startX >= targetWidth || startX + TILE_SIZE <= 0 || startY >= targetHeight || startY + TILE_SIZE <= 0) {
+      dst.fill(0)
+      return
+    }
+
+    // Calculate offset if tile starts off the left side of the screen
+    let srcOffsetX = Math.max(0, -startX)
+    let copyWidth = Math.max(0, Math.min(TILE_SIZE - srcOffsetX, targetWidth - Math.max(0, startX)))
 
     for (let ly = 0; ly < TILE_SIZE; ly++) {
       let globalY = startY + ly
       let dstIndex = ly * TILE_SIZE
 
+      // Check negative bounds accurately
       if (globalY < 0 || globalY >= targetHeight || copyWidth === 0) {
         dst.fill(0, dstIndex, dstIndex + TILE_SIZE)
         continue
       }
 
-      let srcIndex = globalY * targetWidth + startX
+      let srcIndex = globalY * targetWidth + Math.max(0, startX)
       let rowData = src.subarray(srcIndex, srcIndex + copyWidth)
 
-      dst.set(rowData, dstIndex)
+      // Shift the paste over by the offset
+      dst.set(rowData, dstIndex + srcOffsetX)
+
+      // Pad the left edge with 0s if we hung off the left side
+      if (srcOffsetX > 0) {
+        dst.fill(0, dstIndex, dstIndex + srcOffsetX)
+      }
 
-      if (copyWidth < TILE_SIZE) {
-        dst.fill(0, dstIndex + copyWidth, dstIndex + TILE_SIZE)
+      // Pad the right edge with 0s if we hung off the right side
+      if (srcOffsetX + copyWidth < TILE_SIZE) {
+        dst.fill(0, dstIndex + srcOffsetX + copyWidth, dstIndex + TILE_SIZE)
       }
     }
   }
 
-  extractAfterTiles(): PixelTile[] {
+  extractPatch(): PixelPatchTiles {
     let afterTiles: PixelTile[] = []
     let length = this.beforeTiles.length
 
@@ -170,22 +167,40 @@ export class PixelAccumulator {
       let beforeTile = this.beforeTiles[i]
 
       if (beforeTile) {
-        let afterTile = this.getTile(
-          beforeTile.id,
-          beforeTile.tx,
-          beforeTile.ty,
-        )
+        let afterTile = this.tilePool.getTile(beforeTile.id, beforeTile.tx, beforeTile.ty)
 
         this.extractState(afterTile)
         afterTiles.push(afterTile)
       }
     }
 
-    return afterTiles
+    let beforeTiles = this.beforeTiles
+    this.beforeTiles = []
+    this.lookup.length = 0
+
+    return {
+      beforeTiles,
+      afterTiles,
+    }
   }
 
-  reset() {
-    this.lookup = []
-    this.beforeTiles = []
+  rollback() {
+    let target = this.config.target
+    let tileSize = this.config.tileSize
+    let length = this.beforeTiles.length
+
+    applyPatchTiles(target, this.beforeTiles, tileSize)
+
+    for (let i = 0; i < length; i++) {
+      let tile = this.beforeTiles[i]
+
+      if (tile) {
+        this.lookup[tile.id] = undefined
+        this.tilePool.releaseTile(tile)
+      }
+    }
+
+    this.beforeTiles.length = 0
+    this.lookup.length = 0
   }
 }

package/src/History/PixelEngineConfig.ts

@@ -1,18 +1,30 @@
+import type { IPixelData } from '../_types'
+
 export class PixelEngineConfig {
-  public readonly tileSize: number
-  public readonly tileShift: number
-  public readonly tileMask: number
-  public readonly tileArea: number
+  readonly tileSize: number
+  // pixelX = tileX << tileShift
+  // pixelY = tileY << tileShift
+  readonly tileShift: number
+  readonly tileMask: number
+  readonly tileArea: number
+  readonly target!: IPixelData
+  readonly targetColumns: number = 0
 
-  constructor(tileSize: number = 256) {
+  constructor(tileSize: number, target: IPixelData) {
     // Ensure it's a power of 2 to guarantee bitwise math works
     if ((tileSize & (tileSize - 1)) !== 0) {
       throw new Error('tileSize must be a power of 2')
     }
 
     this.tileSize = tileSize
-    this.tileShift = Math.log2(tileSize)
+    this.tileShift = 31 - Math.clz32(tileSize)
     this.tileMask = tileSize - 1
     this.tileArea = tileSize * tileSize
+    this.setTarget(target)
+  }
+
+  setTarget(target: IPixelData) {
+    ;(this as any).target = target
+    ;(this as any).targetColumns = (target.width + this.tileMask) >> this.tileShift
   }
 }

package/src/History/PixelMutator/mutatorApplyAlphaMask.ts

@@ -17,17 +17,17 @@ export const mutatorApplyAlphaMask = ((writer: PixelWriter<any>, deps: Deps = de
   } = deps
 
   return {
-    applyAlphaMask: (mask: AlphaMask, opts: ApplyMaskToPixelDataOptions = {}) => {
-      let target = writer.target
+    applyAlphaMask(mask: AlphaMask, opts: ApplyMaskToPixelDataOptions = {}): boolean {
+      let target = writer.config.target
       const {
         x = 0,
         y = 0,
-        w = writer.target.width,
-        h = writer.target.height,
+        w = target.width,
+        h = target.height,
       } = opts
 
-      writer.accumulator.storeRegionBeforeState(x, y, w, h)
-      applyAlphaMaskToPixelData(target, mask, opts)
+      const didChange = writer.accumulator.storeRegionBeforeState(x, y, w, h)
+      return didChange(applyAlphaMaskToPixelData(target, mask, opts))
     },
   }
 }) satisfies HistoryMutator<any, Deps>

package/src/History/PixelMutator/mutatorApplyBinaryMask.ts

@@ -17,17 +17,17 @@ export const mutatorApplyBinaryMask = ((writer: PixelWriter<any>, deps: Deps = d
   } = deps
 
   return {
-    applyBinaryMask: (mask: BinaryMask, opts: ApplyMaskToPixelDataOptions = {}) => {
-      let target = writer.target
+    applyBinaryMask(mask: BinaryMask, opts: ApplyMaskToPixelDataOptions = {}): boolean {
+      let target = writer.config.target
       const {
         x = 0,
         y = 0,
-        w = writer.target.width,
-        h = writer.target.height,
+        w = target.width,
+        h = target.height,
       } = opts
 
-      writer.accumulator.storeRegionBeforeState(x, y, w, h)
-      applyBinaryMaskToPixelData(target, mask, opts)
+      const didChange = writer.accumulator.storeRegionBeforeState(x, y, w, h)
+      return didChange(applyBinaryMaskToPixelData(target, mask, opts))
     },
   }
 }) satisfies HistoryMutator<any, Deps>

package/src/History/PixelMutator/mutatorApplyCircleBrushStroke.ts

@@ -1,7 +1,7 @@
 import {
   type AlphaMask,
   type BlendColor32,
-  type CircleBrushAlphaMask,
+  type CircleAlphaMask,
   type Color32,
   type ColorBlendMaskOptions,
   type HistoryMutator,
@@ -72,7 +72,7 @@ export const mutatorApplyCircleBrushStroke = ((writer: PixelWriter<any>, deps: D
       y0: number,
       x1: number,
       y1: number,
-      brush: CircleBrushAlphaMask,
+      brush: CircleAlphaMask,
       alpha = 255,
       blendFn: BlendColor32 = sourceOverPerfect,
     ) {
@@ -102,8 +102,9 @@ export const mutatorApplyCircleBrushStroke = ((writer: PixelWriter<any>, deps: D
       const brushData = brush.data
       const minOffset = brush.minOffset
 
-      const targetWidth = writer.target.width
-      const targetHeight = writer.target.height
+      const target = writer.config.target
+      const targetWidth = target.width
+      const targetHeight = target.height
 
       forEachLinePoint(
         x0,
@@ -171,7 +172,7 @@ export const mutatorApplyCircleBrushStroke = ((writer: PixelWriter<any>, deps: D
       blendColorPixelOptions.h = bh
 
       blendColorPixelDataAlphaMask(
-        writer.target,
+        target,
         color,
         mask as AlphaMask,
         blendColorPixelOptions,