@tldraw/utils 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b73a0d46b63f

package/src/lib/media/gif.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import { isGIF, isGifAnimated } from './gif'
+
+describe('isGIF', () => {
+	it('should return true for valid GIF header', () => {
+		const buffer = new ArrayBuffer(10)
+		const view = new Uint8Array(buffer)
+
+		// Set GIF header "GIF"
+		view[0] = 71 // G
+		view[1] = 73 // I
+		view[2] = 70 // F
+
+		expect(isGIF(buffer)).toBe(true)
+	})
+
+	it('should return false for non-GIF header', () => {
+		const buffer = new ArrayBuffer(10)
+		const view = new Uint8Array(buffer)
+
+		// Set PNG header instead
+		view[0] = 137 // PNG signature
+		view[1] = 80 // P
+		view[2] = 78 // N
+
+		expect(isGIF(buffer)).toBe(false)
+	})
+
+	it('should return false for empty buffer', () => {
+		const buffer = new ArrayBuffer(0)
+		expect(isGIF(buffer)).toBe(false)
+	})
+})
+
+describe('isGifAnimated', () => {
+	it('should return false for non-GIF data', () => {
+		const buffer = new ArrayBuffer(20)
+		const view = new Uint8Array(buffer)
+
+		// Set non-GIF header
+		view[0] = 80 // P
+		view[1] = 78 // N
+		view[2] = 71 // G
+
+		expect(isGifAnimated(buffer)).toBe(false)
+	})
+
+	it('should return false for empty buffer', () => {
+		const buffer = new ArrayBuffer(0)
+		expect(isGifAnimated(buffer)).toBe(false)
+	})
+})

package/src/lib/media/gif.ts

@@ -16,8 +16,18 @@ function getDataBlocksLength(buffer: Uint8Array, offset: number): number {
 }
 
 /**
- * Checks if buffer contains GIF image
+ * Checks if buffer contains GIF image by examining the file header.
  *
+ * @param buffer - The ArrayBuffer containing the image data to check
+ * @returns True if the buffer contains a GIF image, false otherwise
+ * @example
+ * ```ts
+ * // Check a file from user input
+ * const file = event.target.files[0]
+ * const buffer = await file.arrayBuffer()
+ * const isGif = isGIF(buffer)
+ * console.log(isGif ? 'GIF image' : 'Not a GIF')
+ * ```
  * @public
  */
 export function isGIF(buffer: ArrayBuffer): boolean {
@@ -27,8 +37,21 @@ export function isGIF(buffer: ArrayBuffer): boolean {
 }
 
 /**
- * Checks if buffer contains animated GIF image
+ * Checks if buffer contains animated GIF image by parsing the GIF structure and counting image descriptors.
+ * A GIF is considered animated if it contains more than one image descriptor block.
  *
+ * @param buffer - The ArrayBuffer containing the GIF image data
+ * @returns True if the GIF is animated (contains multiple frames), false otherwise
+ * @example
+ * ```ts
+ * // Check if a GIF file is animated
+ * const file = event.target.files[0]
+ * if (file.type === 'image/gif') {
+ *   const buffer = await file.arrayBuffer()
+ *   const animated = isGifAnimated(buffer)
+ *   console.log(animated ? 'Animated GIF' : 'Static GIF')
+ * }
+ * ```
  * @public
  */
 export function isGifAnimated(buffer: ArrayBuffer): boolean {

package/src/lib/media/media.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { MediaHelpers } from './media'
+
+describe('MediaHelpers', () => {
+	// Note: Most MediaHelpers methods are DOM-dependent and already tested through
+	// integration tests in packages that use them. The complex mocking required
+	// for these tests doesn't add value and makes tests brittle.
+
+	describe('type checking methods', () => {
+		it('should correctly identify animated image types', () => {
+			expect(MediaHelpers.isAnimatedImageType('image/gif')).toBe(true)
+			expect(MediaHelpers.isAnimatedImageType('image/apng')).toBe(true)
+			expect(MediaHelpers.isAnimatedImageType('image/avif')).toBe(true)
+			expect(MediaHelpers.isAnimatedImageType('image/webp')).toBe(false) // webp can be static
+		})
+
+		it('should correctly identify static image types', () => {
+			expect(MediaHelpers.isStaticImageType('image/jpeg')).toBe(true)
+			expect(MediaHelpers.isStaticImageType('image/png')).toBe(true)
+			expect(MediaHelpers.isStaticImageType('image/webp')).toBe(true)
+			expect(MediaHelpers.isStaticImageType('image/gif')).toBe(false)
+		})
+
+		it('should correctly identify vector image types', () => {
+			expect(MediaHelpers.isVectorImageType('image/svg+xml')).toBe(true)
+			expect(MediaHelpers.isVectorImageType('image/jpeg')).toBe(false)
+			expect(MediaHelpers.isVectorImageType('image/gif')).toBe(false)
+		})
+
+		it('should correctly identify all image types', () => {
+			expect(MediaHelpers.isImageType('image/jpeg')).toBe(true)
+			expect(MediaHelpers.isImageType('image/png')).toBe(true)
+			expect(MediaHelpers.isImageType('image/gif')).toBe(true)
+			expect(MediaHelpers.isImageType('image/svg+xml')).toBe(true)
+			expect(MediaHelpers.isImageType('video/mp4')).toBe(false)
+			expect(MediaHelpers.isImageType('text/plain')).toBe(false)
+		})
+
+		it('should handle null and undefined gracefully', () => {
+			expect(MediaHelpers.isAnimatedImageType(null)).toBe(false)
+			expect(MediaHelpers.isStaticImageType(null)).toBe(false)
+			expect(MediaHelpers.isVectorImageType(null)).toBe(false)
+		})
+	})
+
+	// Note: The following methods are not tested here as they require extensive DOM mocking
+	// that would test the mocking framework more than the actual business logic:
+	// - loadVideo: Complex DOM video element mocking
+	// - getVideoFrameAsDataUrl: Canvas and video interaction mocking
+	// - getImageAndDimensions: Image element and DOM manipulation mocking
+	// - getVideoSize: Depends on loadVideo
+	// - getImageSize: Complex PNG parsing logic with extensive mocking
+	// - isAnimated: Delegates to format-specific functions already tested elsewhere
+	// - usingObjectURL: Simple wrapper around URL APIs with cleanup
+
+	// These methods are better tested through integration tests in the consuming packages
+	// (like @tldraw/tldraw) where they're used in realistic scenarios.
+})

package/src/lib/media/media.ts

@@ -6,38 +6,121 @@ import { isGifAnimated } from './gif'
 import { PngHelpers } from './png'
 import { isWebpAnimated } from './webp'
 
-/** @public */
+/**
+ * Array of supported vector image MIME types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_VECTOR_IMAGE_TYPES } from '@tldraw/utils'
+ *
+ * const isSvg = DEFAULT_SUPPORTED_VECTOR_IMAGE_TYPES.includes('image/svg+xml')
+ * console.log(isSvg) // true
+ * ```
+ * @public
+ */
 export const DEFAULT_SUPPORTED_VECTOR_IMAGE_TYPES = Object.freeze(['image/svg+xml' as const])
-/** @public */
+/**
+ * Array of supported static (non-animated) image MIME types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_STATIC_IMAGE_TYPES } from '@tldraw/utils'
+ *
+ * const isStatic = DEFAULT_SUPPORTED_STATIC_IMAGE_TYPES.includes('image/jpeg')
+ * console.log(isStatic) // true
+ * ```
+ * @public
+ */
 export const DEFAULT_SUPPORTED_STATIC_IMAGE_TYPES = Object.freeze([
 	'image/jpeg' as const,
 	'image/png' as const,
 	'image/webp' as const,
 ])
-/** @public */
+/**
+ * Array of supported animated image MIME types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_ANIMATED_IMAGE_TYPES } from '@tldraw/utils'
+ *
+ * const isAnimated = DEFAULT_SUPPORTED_ANIMATED_IMAGE_TYPES.includes('image/gif')
+ * console.log(isAnimated) // true
+ * ```
+ * @public
+ */
 export const DEFAULT_SUPPORTED_ANIMATED_IMAGE_TYPES = Object.freeze([
 	'image/gif' as const,
 	'image/apng' as const,
 	'image/avif' as const,
 ])
-/** @public */
+/**
+ * Array of all supported image MIME types, combining static, vector, and animated types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_IMAGE_TYPES } from '@tldraw/utils'
+ *
+ * const isSupported = DEFAULT_SUPPORTED_IMAGE_TYPES.includes('image/png')
+ * console.log(isSupported) // true
+ * ```
+ * @public
+ */
 export const DEFAULT_SUPPORTED_IMAGE_TYPES = Object.freeze([
 	...DEFAULT_SUPPORTED_STATIC_IMAGE_TYPES,
 	...DEFAULT_SUPPORTED_VECTOR_IMAGE_TYPES,
 	...DEFAULT_SUPPORTED_ANIMATED_IMAGE_TYPES,
 ])
-/** @public */
+/**
+ * Array of supported video MIME types.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORT_VIDEO_TYPES } from '@tldraw/utils'
+ *
+ * const isVideo = DEFAULT_SUPPORT_VIDEO_TYPES.includes('video/mp4')
+ * console.log(isVideo) // true
+ * ```
+ * @public
+ */
 export const DEFAULT_SUPPORT_VIDEO_TYPES = Object.freeze([
 	'video/mp4' as const,
 	'video/webm' as const,
 	'video/quicktime' as const,
 ])
-/** @public */
+/**
+ * Array of all supported media MIME types, combining images and videos.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_MEDIA_TYPES } from '@tldraw/utils'
+ *
+ * const isMediaFile = DEFAULT_SUPPORTED_MEDIA_TYPES.includes('video/mp4')
+ * console.log(isMediaFile) // true
+ * ```
+ * @public
+ */
 export const DEFAULT_SUPPORTED_MEDIA_TYPES = Object.freeze([
 	...DEFAULT_SUPPORTED_IMAGE_TYPES,
 	...DEFAULT_SUPPORT_VIDEO_TYPES,
 ])
-/** @public */
+/**
+ * Comma-separated string of all supported media MIME types, useful for HTML file input accept attributes.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_SUPPORTED_MEDIA_TYPE_LIST } from '@tldraw/utils'
+ *
+ * // Use in HTML file input for media uploads
+ * const input = document.createElement('input')
+ * input.type = 'file'
+ * input.accept = DEFAULT_SUPPORTED_MEDIA_TYPE_LIST
+ * input.addEventListener('change', (e) => {
+ *   const files = (e.target as HTMLInputElement).files
+ *   if (files) console.log(`Selected ${files.length} file(s)`)
+ * })
+ * ```
+ * @public
+ */
 export const DEFAULT_SUPPORTED_MEDIA_TYPE_LIST = DEFAULT_SUPPORTED_MEDIA_TYPES.join(',')
 
 /**
@@ -47,7 +130,15 @@ export const DEFAULT_SUPPORTED_MEDIA_TYPE_LIST = DEFAULT_SUPPORTED_MEDIA_TYPES.j
  */
 export class MediaHelpers {
 	/**
-	 * Load a video from a url.
+	 * Load a video element from a URL with cross-origin support.
+	 *
+	 * @param src - The URL of the video to load
+	 * @returns Promise that resolves to the loaded HTMLVideoElement
+	 * @example
+	 * ```ts
+	 * const video = await MediaHelpers.loadVideo('https://example.com/video.mp4')
+	 * console.log(`Video dimensions: ${video.videoWidth}x${video.videoHeight}`)
+	 * ```
 	 * @public
 	 */
 	static loadVideo(src: string): Promise<HTMLVideoElement> {
@@ -63,6 +154,22 @@ export class MediaHelpers {
 		})
 	}
 
+	/**
+	 * Extract a frame from a video element as a data URL.
+	 *
+	 * @param video - The HTMLVideoElement to extract frame from
+	 * @param time - The time in seconds to extract the frame from (default: 0)
+	 * @returns Promise that resolves to a data URL of the video frame
+	 * @example
+	 * ```ts
+	 * const video = await MediaHelpers.loadVideo('https://example.com/video.mp4')
+	 * const frameDataUrl = await MediaHelpers.getVideoFrameAsDataUrl(video, 5.0)
+	 * // Use frameDataUrl as image thumbnail
+	 * const img = document.createElement('img')
+	 * img.src = frameDataUrl
+	 * ```
+	 * @public
+	 */
 	static async getVideoFrameAsDataUrl(video: HTMLVideoElement, time = 0): Promise<string> {
 		const promise = promiseWithResolve<string>()
 		let didSetTime = false
@@ -118,7 +225,17 @@ export class MediaHelpers {
 	}
 
 	/**
-	 * Load an image from a url.
+	 * Load an image from a URL and get its dimensions along with the image element.
+	 *
+	 * @param src - The URL of the image to load
+	 * @returns Promise that resolves to an object with width, height, and the image element
+	 * @example
+	 * ```ts
+	 * const { w, h, image } = await MediaHelpers.getImageAndDimensions('https://example.com/image.png')
+	 * console.log(`Image size: ${w}x${h}`)
+	 * // Image is ready to use
+	 * document.body.appendChild(image)
+	 * ```
 	 * @public
 	 */
 	static getImageAndDimensions(
@@ -162,7 +279,14 @@ export class MediaHelpers {
 	/**
 	 * Get the size of a video blob
 	 *
-	 * @param blob - A SharedBlob containing the video
+	 * @param blob - A Blob containing the video
+	 * @returns Promise that resolves to an object with width and height properties
+	 * @example
+	 * ```ts
+	 * const file = new File([...], 'video.mp4', { type: 'video/mp4' })
+	 * const { w, h } = await MediaHelpers.getVideoSize(file)
+	 * console.log(`Video dimensions: ${w}x${h}`)
+	 * ```
 	 * @public
 	 */
 	static async getVideoSize(blob: Blob): Promise<{ w: number; h: number }> {
@@ -175,7 +299,14 @@ export class MediaHelpers {
 	/**
 	 * Get the size of an image blob
 	 *
-	 * @param blob - A Blob containing the image.
+	 * @param blob - A Blob containing the image
+	 * @returns Promise that resolves to an object with width and height properties
+	 * @example
+	 * ```ts
+	 * const file = new File([...], 'image.png', { type: 'image/png' })
+	 * const { w, h } = await MediaHelpers.getImageSize(file)
+	 * console.log(`Image dimensions: ${w}x${h}`)
+	 * ```
 	 * @public
 	 */
 	static async getImageSize(blob: Blob): Promise<{ w: number; h: number }> {
@@ -210,6 +341,19 @@ export class MediaHelpers {
 		return { w, h }
 	}
 
+	/**
+	 * Check if a media file blob contains animation data.
+	 *
+	 * @param file - The Blob to check for animation
+	 * @returns Promise that resolves to true if the file is animated, false otherwise
+	 * @example
+	 * ```ts
+	 * const file = new File([...], 'animation.gif', { type: 'image/gif' })
+	 * const animated = await MediaHelpers.isAnimated(file)
+	 * console.log(animated ? 'Animated' : 'Static')
+	 * ```
+	 * @public
+	 */
 	static async isAnimated(file: Blob): Promise<boolean> {
 		if (file.type === 'image/gif') {
 			return isGifAnimated(await file.arrayBuffer())
@@ -230,22 +374,87 @@ export class MediaHelpers {
 		return false
 	}
 
+	/**
+	 * Check if a MIME type represents an animated image format.
+	 *
+	 * @param mimeType - The MIME type to check
+	 * @returns True if the MIME type is an animated image format, false otherwise
+	 * @example
+	 * ```ts
+	 * const isAnimated = MediaHelpers.isAnimatedImageType('image/gif')
+	 * console.log(isAnimated) // true
+	 * ```
+	 * @public
+	 */
 	static isAnimatedImageType(mimeType: string | null): boolean {
 		return DEFAULT_SUPPORTED_ANIMATED_IMAGE_TYPES.includes((mimeType as any) || '')
 	}
 
+	/**
+	 * Check if a MIME type represents a static (non-animated) image format.
+	 *
+	 * @param mimeType - The MIME type to check
+	 * @returns True if the MIME type is a static image format, false otherwise
+	 * @example
+	 * ```ts
+	 * const isStatic = MediaHelpers.isStaticImageType('image/jpeg')
+	 * console.log(isStatic) // true
+	 * ```
+	 * @public
+	 */
 	static isStaticImageType(mimeType: string | null): boolean {
 		return DEFAULT_SUPPORTED_STATIC_IMAGE_TYPES.includes((mimeType as any) || '')
 	}
 
+	/**
+	 * Check if a MIME type represents a vector image format.
+	 *
+	 * @param mimeType - The MIME type to check
+	 * @returns True if the MIME type is a vector image format, false otherwise
+	 * @example
+	 * ```ts
+	 * const isVector = MediaHelpers.isVectorImageType('image/svg+xml')
+	 * console.log(isVector) // true
+	 * ```
+	 * @public
+	 */
 	static isVectorImageType(mimeType: string | null): boolean {
 		return DEFAULT_SUPPORTED_VECTOR_IMAGE_TYPES.includes((mimeType as any) || '')
 	}
 
+	/**
+	 * Check if a MIME type represents any supported image format (static, animated, or vector).
+	 *
+	 * @param mimeType - The MIME type to check
+	 * @returns True if the MIME type is a supported image format, false otherwise
+	 * @example
+	 * ```ts
+	 * const isImage = MediaHelpers.isImageType('image/png')
+	 * console.log(isImage) // true
+	 * ```
+	 * @public
+	 */
 	static isImageType(mimeType: string): boolean {
 		return DEFAULT_SUPPORTED_IMAGE_TYPES.includes((mimeType as any) || '')
 	}
 
+	/**
+	 * Utility function to create an object URL from a blob, execute a function with it, and automatically clean it up.
+	 *
+	 * @param blob - The Blob to create an object URL for
+	 * @param fn - Function to execute with the object URL
+	 * @returns Promise that resolves to the result of the function
+	 * @example
+	 * ```ts
+	 * const result = await MediaHelpers.usingObjectURL(imageBlob, async (url) => {
+	 *   const { w, h } = await MediaHelpers.getImageAndDimensions(url)
+	 *   return { width: w, height: h }
+	 * })
+	 * // Object URL is automatically revoked after function completes
+	 * console.log(`Image dimensions: ${result.width}x${result.height}`)
+	 * ```
+	 * @public
+	 */
 	static async usingObjectURL<T>(blob: Blob, fn: (url: string) => Promise<T>): Promise<T> {
 		const url = URL.createObjectURL(blob)
 		try {

package/src/lib/media/png.ts

@@ -62,8 +62,51 @@ const crc: CRCCalculator<Uint8Array> = (current, previous) => {
 const LEN_SIZE = 4
 const CRC_SIZE = 4
 
-/** @public */
+/**
+ * Utility class for reading and manipulating PNG image files.
+ * Provides methods for parsing PNG chunks, validating PNG format, and modifying PNG metadata.
+ *
+ * @example
+ * ```ts
+ * // Validate PNG file from blob
+ * const blob = new Blob([pngData], { type: 'image/png' })
+ * const view = new DataView(await blob.arrayBuffer())
+ * const isPng = PngHelpers.isPng(view, 0)
+ *
+ * // Parse PNG metadata for image processing
+ * const chunks = PngHelpers.readChunks(view)
+ * const physChunk = PngHelpers.findChunk(view, 'pHYs')
+ *
+ * // Create high-DPI PNG for export
+ * const highDpiBlob = PngHelpers.setPhysChunk(view, 2, { type: 'image/png' })
+ * ```
+ *
+ * @public
+ */
 export class PngHelpers {
+	/**
+	 * Checks if binary data at the specified offset contains a valid PNG file signature.
+	 * Validates the 8-byte PNG signature: 89 50 4E 47 0D 0A 1A 0A.
+	 *
+	 * @param view - DataView containing the binary data to check
+	 * @param offset - Byte offset where the PNG signature should start
+	 * @returns True if the data contains a valid PNG signature, false otherwise
+	 *
+	 * @example
+	 * ```ts
+	 * // Validate PNG from file upload
+	 * const file = event.target.files[0]
+	 * const buffer = await file.arrayBuffer()
+	 * const view = new DataView(buffer)
+	 *
+	 * if (PngHelpers.isPng(view, 0)) {
+	 *   console.log('Valid PNG file detected')
+	 *   // Process PNG file...
+	 * } else {
+	 *   console.error('Not a valid PNG file')
+	 * }
+	 * ```
+	 */
 	static isPng(view: DataView, offset: number) {
 		if (
 			view.getUint8(offset + 0) === 0x89 &&
@@ -80,6 +123,25 @@ export class PngHelpers {
 		return false
 	}
 
+	/**
+	 * Reads the 4-character chunk type identifier from a PNG chunk header.
+	 *
+	 * @param view - DataView containing the PNG data
+	 * @param offset - Byte offset of the chunk type field (after length field)
+	 * @returns 4-character string representing the chunk type (e.g., 'IHDR', 'IDAT', 'IEND')
+	 *
+	 * @example
+	 * ```ts
+	 * // Read chunk type from PNG header (after 8-byte signature)
+	 * const chunkType = PngHelpers.getChunkType(dataView, 8)
+	 * console.log(chunkType) // 'IHDR' (Image Header)
+	 *
+	 * // Read chunk type at a specific position during parsing
+	 * let offset = 8 // Skip PNG signature
+	 * const chunkLength = dataView.getUint32(offset)
+	 * const type = PngHelpers.getChunkType(dataView, offset + 4)
+	 * ```
+	 */
 	static getChunkType(view: DataView, offset: number) {
 		return [
 			String.fromCharCode(view.getUint8(offset)),
@@ -89,6 +151,32 @@ export class PngHelpers {
 		].join('')
 	}
 
+	/**
+	 * Parses all chunks in a PNG file and returns their metadata.
+	 * Skips duplicate IDAT chunks but includes all other chunk types.
+	 *
+	 * @param view - DataView containing the complete PNG file data
+	 * @param offset - Starting byte offset (defaults to 0)
+	 * @returns Record mapping chunk types to their metadata (start position, data offset, and size)
+	 * @throws Error if the data is not a valid PNG file
+	 *
+	 * @example
+	 * ```ts
+	 * // Parse PNG structure for metadata extraction
+	 * const view = new DataView(await blob.arrayBuffer())
+	 * const chunks = PngHelpers.readChunks(view)
+	 *
+	 * // Check for specific chunks
+	 * const ihdrChunk = chunks['IHDR']
+	 * const physChunk = chunks['pHYs']
+	 *
+	 * if (physChunk) {
+	 *   console.log(`Found pixel density info at byte ${physChunk.start}`)
+	 * } else {
+	 *   console.log('No pixel density information found')
+	 * }
+	 * ```
+	 */
 	static readChunks(view: DataView, offset = 0) {
 		const chunks: Record<string, { dataOffset: number; size: number; start: number }> = {}
 		if (!PngHelpers.isPng(view, offset)) {
@@ -122,6 +210,29 @@ export class PngHelpers {
 		return chunks
 	}
 
+	/**
+	 * Parses the pHYs (physical pixel dimensions) chunk data.
+	 * Reads pixels per unit for X and Y axes, and the unit specifier.
+	 *
+	 * @param view - DataView containing the PNG data
+	 * @param offset - Byte offset of the pHYs chunk data
+	 * @returns Object with ppux (pixels per unit X), ppuy (pixels per unit Y), and unit specifier
+	 *
+	 * @example
+	 * ```ts
+	 * // Extract pixel density information for DPI calculation
+	 * const physChunk = PngHelpers.findChunk(dataView, 'pHYs')
+	 * if (physChunk) {
+	 *   const physData = PngHelpers.parsePhys(dataView, physChunk.dataOffset)
+	 *
+	 *   if (physData.unit === 1) { // meters
+	 *     const dpiX = Math.round(physData.ppux * 0.0254)
+	 *     const dpiY = Math.round(physData.ppuy * 0.0254)
+	 *     console.log(`DPI: ${dpiX} x ${dpiY}`)
+	 *   }
+	 * }
+	 * ```
+	 */
 	static parsePhys(view: DataView, offset: number) {
 		return {
 			ppux: view.getUint32(offset),
@@ -130,11 +241,61 @@ export class PngHelpers {
 		}
 	}
 
+	/**
+	 * Finds a specific chunk type in the PNG file and returns its metadata.
+	 *
+	 * @param view - DataView containing the PNG file data
+	 * @param type - 4-character chunk type to search for (e.g., 'pHYs', 'IDAT')
+	 * @returns Chunk metadata object if found, undefined otherwise
+	 *
+	 * @example
+	 * ```ts
+	 * // Look for pixel density information in PNG
+	 * const physChunk = PngHelpers.findChunk(dataView, 'pHYs')
+	 * if (physChunk) {
+	 *   const physData = PngHelpers.parsePhys(dataView, physChunk.dataOffset)
+	 *   console.log(`Found pHYs chunk with ${physData.ppux} x ${physData.ppuy} pixels per unit`)
+	 * }
+	 *
+	 * // Check for text metadata
+	 * const textChunk = PngHelpers.findChunk(dataView, 'tEXt')
+	 * if (textChunk) {
+	 *   console.log(`Found text metadata at byte ${textChunk.start}`)
+	 * }
+	 * ```
+	 */
 	static findChunk(view: DataView, type: string) {
 		const chunks = PngHelpers.readChunks(view)
 		return chunks[type]
 	}
 
+	/**
+	 * Adds or replaces a pHYs chunk in a PNG file to set pixel density for high-DPI displays.
+	 * The method determines insertion point by prioritizing IDAT chunk position over existing pHYs,
+	 * creates a properly formatted pHYs chunk with CRC validation, and returns a new Blob.
+	 *
+	 * @param view - DataView containing the original PNG file data
+	 * @param dpr - Device pixel ratio multiplier (defaults to 1)
+	 * @param options - Optional Blob constructor options for MIME type and other properties
+	 * @returns New Blob containing the PNG with updated pixel density information
+	 *
+	 * @example
+	 * ```ts
+	 * // Export PNG with proper pixel density for high-DPI displays
+	 * const canvas = document.createElement('canvas')
+	 * const ctx = canvas.getContext('2d')
+	 * // ... draw content to canvas ...
+	 *
+	 * canvas.toBlob(async (blob) => {
+	 *   if (blob) {
+	 *     const view = new DataView(await blob.arrayBuffer())
+	 *     // Create 2x DPI version for Retina displays
+	 *     const highDpiBlob = PngHelpers.setPhysChunk(view, 2, { type: 'image/png' })
+	 *     // Download or use the blob...
+	 *   }
+	 * }, 'image/png')
+	 * ```
+	 */
 	static setPhysChunk(view: DataView, dpr = 1, options?: BlobPropertyBag) {
 		let offset = 46
 		let size = 0