pixel-data-js 0.30.0 → 0.32.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-data-js",
   "type": "module",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "packageManager": "pnpm@10.33.0",
   "description": "JS Pixel and ImageData operations",
   "author": {

package/src/Control/BatchedQueue.ts

@@ -0,0 +1,76 @@
+export type BatchedQueueFn = (fn: () => void) => void
+
+export type BatchedQueue = ReturnType<typeof makeBatchedQueue>
+
+/**
+ * Creates a high-performance, zero-allocation batching queue.
+ * This utility collects items marked as "dirty" and flushes them in a single batch.
+ * * **⚠️ CRITICAL: Synchronous Processing Required**
+ * Because the internal sets are reused, the `Set` passed to the `processor` is instantly
+ * cleared the moment the processor function returns. If you need to process the items
+ * asynchronously, you **must** manually clone the set inside your processor.
+ * @template T - The type of items being batched.
+ * @param processor - The callback executed when the batch flushes. Receives a `Set` of all batched items.
+ * @param queue - The scheduling function used to defer the flush. Defaults to `queueMicrotask`.
+ * @returns An object containing methods to mark items as dirty.
+ * @example
+ * * @example
+ * ```ts
+ * import { nextTick } from 'vue'
+ * let bq = makeBatchedQueue<string>(
+ *   (items) => drawSomething(items),
+ *   nextTick,
+ * )
+ * ```
+ */
+export function makeBatchedQueue<T>(
+  processor: (items: Set<T>) => void,
+  queue: BatchedQueueFn,
+) {
+  let activeSet = new Set<T>()
+  let processingSet = new Set<T>()
+  let scheduled = false
+
+  const flush = () => {
+    // swap sets
+    const current = activeSet
+    activeSet = processingSet
+    processingSet = current
+
+    scheduled = false
+
+    try {
+      processor(processingSet)
+    } finally {
+      processingSet.clear()
+    }
+  }
+
+  function markDirty(item: T) {
+    activeSet.add(item)
+
+    if (!scheduled) {
+      scheduled = true
+      queue(flush)
+    }
+  }
+
+  function markMultipleDirty(items: T[]) {
+    let len = items.length
+    if (len === 0) return
+
+    for (let i = 0; i < len; i++) {
+      activeSet.add(items[i])
+    }
+
+    if (!scheduled) {
+      scheduled = true
+      queue(flush)
+    }
+  }
+
+  return {
+    markDirty,
+    markMultipleDirty,
+  }
+}

package/src/Control/RenderQueue.ts

@@ -0,0 +1,49 @@
+/**
+ * Creates a debounced render queue using `requestAnimationFrame`.
+ * This utility ensures that a callback is executed exactly once right before
+ * the next visual frame, regardless of how many times the trigger is called
+ * synchronously. It safely prevents layout thrashing and redundant computations.
+ * @param cb - The function to execute on the next animation frame.
+ * @returns A trigger function that schedules the callback. It includes a `.cancel()` method to abort the pending frame.
+ * * @example
+ * ```ts
+ * let renderQueue = makeRenderQueue(() => {
+ * console.log('DOM updated!')
+ * })
+ * * // Calling this multiple times synchronously...
+ * renderQueue()
+ * renderQueue()
+ * renderQueue()
+ * * // ...will only result in one 'DOM updated!' log on the next frame.
+ * ```
+ * * @example
+ * ```ts
+ * // Canceling a scheduled render (e.g., when a component unmounts)
+ * let trigger = makeRenderQueue(updateLayout)
+ * trigger()
+ * trigger.cancel() // The callback will not execute
+ * ```
+ */
+export function makeRenderQueue(cb: () => void) {
+  let needsRender = false
+  let frameId = 0
+
+  const trigger = () => {
+    if (needsRender) return
+    needsRender = true
+
+    frameId = requestAnimationFrame(() => {
+      needsRender = false
+      cb()
+    })
+  }
+
+  trigger.cancel = () => {
+    if (needsRender) {
+      cancelAnimationFrame(frameId)
+      needsRender = false
+    }
+  }
+
+  return trigger
+}

package/src/History/PixelWriter.ts

@@ -8,6 +8,7 @@ import { type HistoryActionFactory, makeHistoryAction } from './HistoryAction'
 import { HistoryManager } from './HistoryManager'
 import { PixelAccumulator } from './PixelAccumulator'
 import { PixelEngineConfig } from './PixelEngineConfig'
+import type { PixelPatchTiles } from './PixelPatchTiles'
 
 export interface PixelWriterOptions {
   maxHistorySteps?: number
@@ -72,15 +73,13 @@ export class PixelWriter<M> {
    *   throw immediately to prevent silent data loss from a nested extractPatch.
    *
    * @param transaction Callback to be executed inside the transaction.
-   * @param after    Called after both undo and redo — use for generic change notifications.
-   * @param afterUndo Called after undo only — use for dimension or state changes specific to undo.
+   * @param afterUndo Called after undo only.
    * @param afterRedo Called after redo only.
    */
   withHistory(
     transaction: (mutator: M) => void,
-    after?: () => void,
-    afterUndo?: () => void,
-    afterRedo?: () => void,
+    afterUndo?: (patch: PixelPatchTiles) => void,
+    afterRedo?: (patch: PixelPatchTiles) => void,
   ): void {
     if (this._inProgress) {
       throw new Error('withHistory is not re-entrant — commit or rollback the current operation first')
@@ -100,7 +99,7 @@ export class PixelWriter<M> {
     if (this.accumulator.beforeTiles.length === 0) return
 
     const patch = this.accumulator.extractPatch()
-    const action = this.historyActionFactory(this.config, this.accumulator, patch, after, afterUndo, afterRedo)
+    const action = this.historyActionFactory(this.config, this.accumulator, patch, afterUndo, afterRedo)
 
     this.historyManager.commit(action)
   }
@@ -110,7 +109,6 @@ export class PixelWriter<M> {
     newHeight: number,
     offsetX = 0,
     offsetY = 0,
-    after?: (target: ImageData) => void,
     afterUndo?: (target: ImageData) => void,
     afterRedo?: (target: ImageData) => void,
     resizeImageDataFn = resizeImageData,
@@ -134,12 +132,10 @@ export class PixelWriter<M> {
       undo: () => {
         setPixelData(target, beforeImageData)
         afterUndo?.(beforeImageData)
-        after?.(beforeImageData)
       },
       redo: () => {
         setPixelData(target, afterImageData)
         afterRedo?.(afterImageData)
-        after?.(afterImageData)
       },
     })
   }

package/src/ImageData/extractImageData.ts

@@ -0,0 +1,55 @@
+import type { Rect } from '../Rect/_rect-types'
+import type { ImageDataLike } from './_ImageData-types'
+import { extractImageDataBuffer } from './extractImageDataBuffer'
+
+/**
+ * Extracts a specific rectangular region of pixels from a larger {@link ImageDataLike}
+ * source into a new {@link Uint8ClampedArray}.
+ *
+ * This is a "read-only" operation that returns a copy of the pixel data.
+ *
+ * @param imageData - The source image data to read from.
+ * @param rect - A rect defining the region to extract.
+ * @returns A buffer containing the RGBA pixel data of the region.
+ */
+export function extractImageData(
+  imageData: ImageDataLike,
+  rect: Rect,
+): ImageData | null
+/**
+ * @param imageData - The source image data to read from.
+ * @param x - The starting horizontal coordinate.
+ * @param y - The starting vertical coordinate.
+ * @param w - The width of the region to extract.
+ * @param h - The height of the region to extract.
+ * @returns A buffer containing the RGBA pixel data of the region.
+ */
+export function extractImageData(
+  imageData: ImageDataLike,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): ImageData | null
+export function extractImageData(
+  imageData: ImageDataLike,
+  _x: Rect | number,
+  _y?: number,
+  _w?: number,
+  _h?: number,
+): ImageData | null {
+  const { x, y, w, h } = typeof _x === 'object'
+    ? _x
+    : { x: _x, y: _y!, w: _w!, h: _h! }
+
+  if (w <= 0) return null
+  if (h <= 0) return null
+
+  const result = new ImageData(w, h)
+
+  const buffer = extractImageDataBuffer(imageData, x, y, w, h)
+  result.data.set(buffer)
+
+  return result
+
+}

package/src/ImageData/extractImageDataBuffer.ts

@@ -1,9 +1,6 @@
 import type { Rect } from '../Rect/_rect-types'
-import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
 import type { ImageDataLike } from './_ImageData-types'
 
-const SCRATCH_BLIT = makeClippedBlit()
-
 /**
  * Extracts a specific rectangular region of pixels from a larger {@link ImageDataLike}
  * source into a new {@link Uint8ClampedArray}.
@@ -43,37 +40,69 @@ export function extractImageDataBuffer(
   const { x, y, w, h } = typeof _x === 'object'
     ? _x
     : { x: _x, y: _y!, w: _w!, h: _h! }
+  if (w <= 0) return new Uint8ClampedArray(0)
+  if (h <= 0) return new Uint8ClampedArray(0)
+
+  const srcW = imageData.width
+  const srcH = imageData.height
+  const src = imageData.data
+
+  const outLen = w * h * 4
+  const out = new Uint8ClampedArray(outLen)
+
+  let srcX = x
+  let srcY = y
+  let dstX = 0
+  let dstY = 0
+  let copyW = w
+  let copyH = h
+
+  if (srcX < 0) {
+    dstX = -srcX
+    copyW += srcX
+    srcX = 0
+  }
+
+  if (srcY < 0) {
+    dstY = -srcY
+    copyH += srcY
+    srcY = 0
+  }
+
+  copyW = Math.min(copyW, srcW - srcX)
+  copyH = Math.min(copyH, srcH - srcY)
+
+  if (copyW <= 0) return out
+  if (copyH <= 0) return out
 
-  const { width: srcW, height: srcH, data: src } = imageData
-  // Safety check for invalid dimensions
-  if (w <= 0 || h <= 0) return new Uint8ClampedArray(0)
-  const out = new Uint8ClampedArray(w * h * 4)
+  // 2. Perform high-speed block copy
+  // Attempt to use a 32-bit view if the buffer is memory-aligned.
+  // This reduces loop iterations and arithmetic by 4x.
+  const isAligned = src.byteOffset % 4 === 0
 
-  const clip = resolveBlitClipping(
-    0,
-    0,
-    x,
-    y,
-    w,
-    h,
-    w,
-    h,
-    srcW,
-    srcH,
-    SCRATCH_BLIT,
-  )
+  if (isAligned) {
+    const srcLen32 = src.byteLength / 4
+    const src32 = new Uint32Array(src.buffer, src.byteOffset, srcLen32)
+    const out32 = new Uint32Array(out.buffer)
 
-  if (!clip.inBounds) return out
+    for (let row = 0; row < copyH; row++) {
+      const srcStart = (srcY + row) * srcW + srcX
+      const dstStart = (dstY + row) * w + dstX
+      const chunk = src32.subarray(srcStart, srcStart + copyW)
 
-  const { x: dstX, y: dstY, sx: srcX, sy: srcY, w: copyW, h: copyH } = clip
-  const rowLen = copyW * 4
+      out32.set(chunk, dstStart)
+    }
+  } else {
+    // Fallback for unaligned data
+    const rowLen = copyW * 4
 
-  for (let row = 0; row < copyH; row++) {
-    const srcStart = ((srcY + row) * srcW + srcX) * 4
-    const dstStart = ((dstY + row) * w + dstX) * 4
+    for (let row = 0; row < copyH; row++) {
+      const srcStart = ((srcY + row) * srcW + srcX) * 4
+      const dstStart = ((dstY + row) * w + dstX) * 4
+      const chunk = src.subarray(srcStart, srcStart + rowLen)
 
-    // Perform the high-speed bulk copy
-    out.set(src.subarray(srcStart, srcStart + rowLen), dstStart)
+      out.set(chunk, dstStart)
+    }
   }
 
   return out

package/src/ImageData/writeImageData.ts

@@ -1,8 +1,3 @@
-import { MaskType } from '../Mask/_mask-types'
-import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
-
-const SCRATCH_BLIT = makeClippedBlit()
-
 /**
  * Writes image data from a source to a target with support for clipping and alpha masking.
  *
@@ -10,88 +5,72 @@ const SCRATCH_BLIT = makeClippedBlit()
  * @param source - The source ImageData to read from.
  * @param x - The x-coordinate in the target where drawing starts.
  * @param y - The y-coordinate in the target where drawing starts.
- * @param sx - The x-coordinate in the source to start copying from.
- * @param sy - The y-coordinate in the source to start copying from.
- * @param sw - The width of the rectangle to copy.
- * @param sh - The height of the rectangle to copy.
- * @param mask - An optional Uint8Array mask (0-255). 0 is transparent, 255 is opaque.
- * @param maskType - type of mask
  */
 export function writeImageData(
   target: ImageData,
   source: ImageData,
   x: number,
   y: number,
-  sx: number = 0,
-  sy: number = 0,
-  sw: number = source.width,
-  sh: number = source.height,
-  mask: Uint8Array | null = null,
-  maskType: MaskType = MaskType.BINARY,
 ): void {
   const dstW = target.width
   const dstH = target.height
-  const dstData = target.data
+  const dst = target.data
+
   const srcW = source.width
-  const srcData = source.data
+  const srcH = source.height
+  const src = source.data
 
-  const clip = resolveBlitClipping(
-    x, y, sx, sy, sw, sh,
-    dstW, dstH, srcW, source.height,
-    SCRATCH_BLIT,
-  )
+  let dstX = x
+  let dstY = y
+  let srcX = 0
+  let srcY = 0
+  let copyW = srcW
+  let copyH = srcH
 
-  if (!clip.inBounds) return
+  if (dstX < 0) {
+    srcX = -dstX
+    copyW += dstX
+    dstX = 0
+  }
 
-  const {
-    x: dstX,
-    y: dstY,
-    sx: srcX,
-    sy: srcY,
-    w: copyW,
-    h: copyH,
-  } = clip
+  if (dstY < 0) {
+    srcY = -dstY
+    copyH += dstY
+    dstY = 0
+  }
+
+  copyW = Math.min(copyW, dstW - dstX)
+  copyH = Math.min(copyH, dstH - dstY)
 
-  const useMask = !!mask
+  if (copyW <= 0) return
+  if (copyH <= 0) return
 
-  for (let row = 0; row < copyH; row++) {
-    const currentDstY = dstY + row
-    const currentSrcY = srcY + row
+  const isDstAligned = dst.byteOffset % 4 === 0
+  const isSrcAligned = src.byteOffset % 4 === 0
 
-    const dstStart = (currentDstY * dstW + dstX) * 4
-    const srcStart = (currentSrcY * srcW + srcX) * 4
+  if (isDstAligned && isSrcAligned) {
+    const dstLen32 = dst.byteLength / 4
+    const dst32 = new Uint32Array(dst.buffer, dst.byteOffset, dstLen32)
 
-    if (useMask && mask) {
-      for (let ix = 0; ix < copyW; ix++) {
-        const mi = currentSrcY * srcW + (srcX + ix)
-        const alpha = mask[mi]
+    const srcLen32 = src.byteLength / 4
+    const src32 = new Uint32Array(src.buffer, src.byteOffset, srcLen32)
 
-        if (alpha === 0) {
-          continue
-        }
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = (dstY + row) * dstW + dstX
+      const srcStart = (srcY + row) * srcW + srcX
+      const chunk = src32.subarray(srcStart, srcStart + copyW)
 
-        const di = dstStart + (ix * 4)
-        const si = srcStart + (ix * 4)
+      dst32.set(chunk, dstStart)
+    }
+  } else {
+    const rowLen = copyW * 4
 
-        if (maskType === MaskType.BINARY || alpha === 255) {
-          dstData[di] = srcData[si]
-          dstData[di + 1] = srcData[si + 1]
-          dstData[di + 2] = srcData[si + 2]
-          dstData[di + 3] = srcData[si + 3]
-        } else {
-          const a = alpha / 255
-          const invA = 1 - a
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = ((dstY + row) * dstW + dstX) * 4
+      const srcStart = ((srcY + row) * srcW + srcX) * 4
+      const chunk = src.subarray(srcStart, srcStart + rowLen)
 
-          dstData[di] = srcData[si] * a + dstData[di] * invA
-          dstData[di + 1] = srcData[si + 1] * a + dstData[di + 1] * invA
-          dstData[di + 2] = srcData[si + 2] * a + dstData[di + 2] * invA
-          dstData[di + 3] = srcData[si + 3] * a + dstData[di + 3] * invA
-        }
-      }
-    } else {
-      const byteLen = copyW * 4
-      const sub = srcData.subarray(srcStart, srcStart + byteLen)
-      dstData.set(sub, dstStart)
+      dst.set(chunk, dstStart)
     }
   }
 }

package/src/ImageData/writeImageDataBuffer.ts

@@ -1,7 +1,4 @@
 import type { Rect } from '../Rect/_rect-types'
-import { makeClippedBlit, resolveBlitClipping } from '../Rect/resolveClipping'
-
-const SCRATCH_BLIT = makeClippedBlit()
 
 /**
  * Copies a pixel buffer into a specific region of an {@link ImageData} object.
@@ -43,43 +40,84 @@ export function writeImageDataBuffer(
   _w?: number,
   _h?: number,
 ): void {
-  const { x, y, w, h } = typeof _x === 'object'
-    ? _x
-    : { x: _x, y: _y!, w: _w!, h: _h! }
-
-  const { width: dstW, height: dstH, data: dst } = target
-
-  const clip = resolveBlitClipping(
-    x,
-    y,
-    0,
-    0,
-    w,
-    h,
-    dstW,
-    dstH,
-    w,
-    h,
-    SCRATCH_BLIT,
-  )
-
-  if (!clip.inBounds) return
-
-  const {
-    x: dstX,
-    y: dstY,
-    sx: srcX,
-    sy: srcY,
-    w: copyW,
-    h: copyH,
-  } = clip
-
-  const rowLen = copyW * 4
-
-  for (let row = 0; row < copyH; row++) {
-    const dstStart = ((dstY + row) * dstW + dstX) * 4
-    const srcStart = ((srcY + row) * w + srcX) * 4
-
-    dst.set(data.subarray(srcStart, srcStart + rowLen), dstStart)
+  let x: number
+  let y: number
+  let w: number
+  let h: number
+
+  if (typeof _x === 'object') {
+    x = _x.x
+    y = _x.y
+    w = _x.w
+    h = _x.h
+  } else {
+    x = _x
+    y = _y!
+    w = _w!
+    h = _h!
+  }
+
+  if (w <= 0) return
+  if (h <= 0) return
+
+  const dstW = target.width
+  const dstH = target.height
+  const dst = target.data
+
+  // Inline clipping logic for destination boundaries
+  let dstX = x
+  let dstY = y
+  let srcX = 0
+  let srcY = 0
+  let copyW = w
+  let copyH = h
+
+  if (dstX < 0) {
+    srcX = -dstX
+    copyW += dstX
+    dstX = 0
+  }
+
+  if (dstY < 0) {
+    srcY = -dstY
+    copyH += dstY
+    dstY = 0
+  }
+
+  copyW = Math.min(copyW, dstW - dstX)
+  copyH = Math.min(copyH, dstH - dstY)
+
+  if (copyW <= 0) return
+  if (copyH <= 0) return
+
+  // Fast-path: Both arrays must be 4-byte aligned to use Uint32Array safely
+  const isDstAligned = dst.byteOffset % 4 === 0
+  const isSrcAligned = data.byteOffset % 4 === 0
+
+  if (isDstAligned && isSrcAligned) {
+    const dstLen32 = dst.byteLength / 4
+    const dst32 = new Uint32Array(dst.buffer, dst.byteOffset, dstLen32)
+
+    const srcLen32 = data.byteLength / 4
+    const src32 = new Uint32Array(data.buffer, data.byteOffset, srcLen32)
+
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = (dstY + row) * dstW + dstX
+      const srcStart = (srcY + row) * w + srcX
+      const chunk = src32.subarray(srcStart, srcStart + copyW)
+
+      dst32.set(chunk, dstStart)
+    }
+  } else {
+    // Fallback for unaligned data arrays
+    const rowLen = copyW * 4
+
+    for (let row = 0; row < copyH; row++) {
+      const dstStart = ((dstY + row) * dstW + dstX) * 4
+      const srcStart = ((srcY + row) * w + srcX) * 4
+      const chunk = data.subarray(srcStart, srcStart + rowLen)
+
+      dst.set(chunk, dstStart)
+    }
   }
 }