fragment-tools 0.2.12 → 0.2.14

package/src/client/app/lib/canvas-recorder/CanvasRecorder.js

@@ -1,6 +1,47 @@
+/**
+ * @callback CanvasRecorderStartCallback
+ * @returns {void}
+ */
+
+/**
+ * @callback CanvasRecorderTickCallback
+ * @param {TickData} data - Tick data
+ * @returns {void}
+ */
+
+/**
+ * @callback CanvasRecorderCompleteCallback
+ * @param {Blob | Blob[] | null} result
+ * @returns {void}
+ */
+
+/**
+ * @typedef {Object} TickData
+ * @property {number} time - Current time in milliseconds
+ * @property {number} deltaTime - Time since last frame in milliseconds
+ * @property {number} frameCount - Current frame count
+ */
+
+/**
+ * @typedef {Object} CanvasRecorderOptions
+ * @property {number} [duration=Infinity] - Recording duration in seconds
+ * @property {number} [framerate=25] - Frames per second
+ * @property {number} [quality=100] - Recording quality (1-100)
+ * @property {string} format - Output format
+ * @property {CanvasRecorderStartCallback} [onStart] - Callback when recording starts
+ * @property {CanvasRecorderTickCallback} [onTick] - Callback on each frame
+ * @property {CanvasRecorderCompleteCallback} [onComplete] - Callback when recording completes
+ */
+
+/** @type {CanvasRecorderStartCallback} */
 let noop = () => {};
 
 class CanvasRecorder {
+	/**
+	 * Create a canvas recorder
+	 * @param {HTMLCanvasElement} canvas - The canvas to record
+	 * @param {CanvasRecorderOptions} options - Recording options
+	 */
 	constructor(
 		canvas,
 		{
@@ -13,30 +54,62 @@ class CanvasRecorder {
 			onComplete = noop,
 		},
 	) {
+		/** @type {HTMLCanvasElement} */
 		this.canvas = canvas;
+		/** @type {number} */
 		this.framerate = framerate;
+		/** @type {number} */
 		this.duration = duration;
+		/** @type {number} */
 		this.quality = quality;
+		/** @type {string} */
 		this.format = format;
+		/** @type {CanvasRecorderStartCallback} */
 		this.onStart = onStart;
+		/** @type {CanvasRecorderTickCallback} */
 		this.onTick = onTick;
+		/** @type {Function} */
 		this.onComplete = onComplete;
-
+		/** @type {number} */
 		this.time = 0;
+
+		/** @type {number} */
 		this.deltaTime = 1000 / this.framerate;
 
+		/** @type {number} */
 		this.frameDuration = 1000 / this.framerate;
+
+		/** @type {number} */
 		this.frameTotal = isFinite(this.duration)
 			? this.duration * this.framerate
 			: Infinity;
+
+		/** @type {boolean} */
 		this.started = false;
+
+		/** @type {boolean} */
 		this.stopped = false;
 
+		/** @type {number} */
 		this.startTime = 0;
+
+		/** @type {number} */
+		this.frameCount = 0;
+
+		/** @type {Blob | Blob[] | null} */
+		this.result = null;
 	}
 
+	/**
+	 * Load resources before recording (override in subclass)
+	 * @returns {Promise<void>}
+	 */
 	async load() {}
 
+	/**
+	 * Start the recording
+	 * @returns {Promise<void>}
+	 */
 	async start() {
 		this.startTime = performance.now();
 		this.onStart();
@@ -65,11 +138,17 @@ class CanvasRecorder {
 		this._tick();
 	}
 
+	/**
+	 * Internal tick handler
+	 * @private
+	 * @returns {Promise<void>}
+	 */
 	async _tick() {
 		console.log(`CanvasRecorder - render frame ${this.frameCount + 1}`);
 		this.onTick({
 			time: this.time,
 			deltaTime: this.deltaTime,
+			frameCount: this.frameCount,
 		});
 
 		await this.tick({
@@ -98,8 +177,17 @@ class CanvasRecorder {
 		}
 	}
 
-	tick() {}
-
+	/**
+	 * Process a single frame (override in subclass)
+	 * @param {TickData} _data - Frame data
+	 * @returns {Promise<void>}
+	 */
+	async tick(_data) {}
+
+	/**
+	 * End the recording and compile result
+	 * @returns {void}
+	 */
 	end() {
 		console.log(
 			`CanvasRecorder - compiled ${this.frameCount + 1} frames in ${(performance.now() - this.startTime) / 1000}s`,
@@ -107,6 +195,10 @@ class CanvasRecorder {
 		this.onComplete(this.result);
 	}
 
+	/**
+	 * Stop the recording
+	 * @returns {void}
+	 */
 	stop() {
 		this.stopped = true;
 	}

package/src/client/app/lib/canvas-recorder/FrameRecorder.js

@@ -3,24 +3,62 @@ import { map } from '../../utils/math.utils';
 import CanvasRecorder from './CanvasRecorder';
 import { exportCanvas } from './utils';
 
+/**
+ * @typedef {Object} FrameRecorderOptions
+ * @property {string} [imageEncoding='png'] - Image encoding format (png, jpeg, webp)
+ * @property {number} [duration] - Recording duration in seconds
+ * @property {number} [framerate] - Frames per second
+ * @property {number} [quality] - Recording quality (1-100)
+ * @property {string} format - Output format
+ * @property {import('./CanvasRecorder').CanvasRecorderStartCallback} [onStart] - Callback when recording starts
+ * @property {import('./CanvasRecorder').CanvasRecorderTickCallback} [onTick] - Callback on each frame
+ * @property {import('./CanvasRecorder').CanvasRecorderCompleteCallback} [onComplete] - Callback when recording completes
+ */
+
+/**
+ * Recorder that captures individual frames as images
+ * @extends CanvasRecorder
+ */
 class FrameRecorder extends CanvasRecorder {
+	/**
+	 * Create a frame recorder
+	 * @param {HTMLCanvasElement} canvas - The canvas to record
+	 * @param {FrameRecorderOptions} options - Recording options
+	 */
 	constructor(canvas, options) {
 		super(canvas, options);
 
 		const { imageEncoding = 'png' } = options;
 
+		/** @type {string} */
 		this.imageEncoding = imageEncoding;
 
+		/** @type {number} */
 		this.imageQuality = map(this.quality, 1, 100, 0, 1);
+
+		/** @type {string[]} */
+		this.frames = [];
+
+		/** @type {Blob[]} */
+		this.result = [];
 	}
 
-	start() {
+	/**
+	 * Start recording frames
+	 * @returns {Promise<void>}
+	 */
+	async start() {
 		this.frames = [];
 
-		super.start();
+		await super.start();
 	}
 
-	tick() {
+	/**
+	 * Capture a single frame
+	 * @param {import('./CanvasRecorder').TickData} _data - Frame data (unused)
+	 * @returns {Promise<void>}
+	 */
+	async tick(_data) {
 		let { dataURL } = exportCanvas(this.canvas, {
 			encoding: `image/${this.imageEncoding}`,
 			encodingQuality: this.imageQuality,
@@ -29,6 +67,10 @@ class FrameRecorder extends CanvasRecorder {
 		this.frames[this.frameCount] = dataURL;
 	}
 
+	/**
+	 * End recording and convert frames to blobs
+	 * @returns {Promise<void>}
+	 */
 	async end() {
 		this.result = await Promise.all(
 			this.frames.map((dataURL) => createBlobFromDataURL(dataURL)),

package/src/client/app/lib/canvas-recorder/GIFRecorder.js

@@ -2,8 +2,41 @@ import { map } from '../../utils/math.utils';
 import { GIFEncoder, quantize, applyPalette } from 'gifenc';
 import CanvasRecorder from './CanvasRecorder';
 
+/**
+ * @typedef {import('./CanvasRecorder').CanvasRecorderOptions} GIFRecorderOptions
+ */
+
+/**
+ * Recorder that captures frames and encodes them as an animated GIF
+ * @extends CanvasRecorder
+ */
 class GIFRecorder extends CanvasRecorder {
-	start() {
+	/**
+	 * Create a GIF recorder
+	 * @param {HTMLCanvasElement} canvas - The canvas to record
+	 * @param {GIFRecorderOptions} options - Recording options
+	 */
+	constructor(canvas, options) {
+		super(canvas, options);
+
+		/** @type {ReturnType<typeof GIFEncoder> | null} */
+		this.encoder = null;
+
+		/** @type {HTMLCanvasElement} */
+		this.tmpCanvas = document.createElement('canvas');
+
+		/** @type {CanvasRenderingContext2D | null} */
+		this.tmpContext = this.tmpCanvas.getContext('2d');
+
+		/** @type {number} */
+		this.maxColors = 256;
+	}
+
+	/**
+	 * Start GIF recording
+	 * @returns {Promise<void>}
+	 */
+	async start() {
 		this.encoder = GIFEncoder();
 
 		this.tmpCanvas = document.createElement('canvas');
@@ -21,34 +54,60 @@ class GIFRecorder extends CanvasRecorder {
 				: Infinity;
 		}
 
-		super.start();
+		await super.start();
 	}
 
+	/**
+	 * Get RGBA pixel data from a bitmap
+	 * @param {HTMLCanvasElement | ImageBitmap} bitmap - The bitmap to extract pixels from
+	 * @param {number} [width=bitmap.width] - Target width
+	 * @param {number} [height=bitmap.height] - Target height
+	 * @returns {Uint8ClampedArray} RGBA pixel data
+	 */
 	getBitmapRGBA(bitmap, width = bitmap.width, height = bitmap.height) {
 		this.tmpCanvas.width = width;
 		this.tmpCanvas.height = height;
-		this.tmpContext.clearRect(0, 0, width, height);
-		this.tmpContext.drawImage(bitmap, 0, 0, width, height);
-		return this.tmpContext.getImageData(0, 0, width, height).data;
+
+		if (this.tmpContext) {
+			this.tmpContext.clearRect(0, 0, width, height);
+			this.tmpContext.drawImage(bitmap, 0, 0, width, height);
+			return this.tmpContext.getImageData(0, 0, width, height).data;
+		}
+
+		return new Uint8ClampedArray();
 	}
 
-	tick() {
+	/**
+	 * Capture and encode a single frame
+	 * @param {import('./CanvasRecorder').TickData} _data - Frame data (unused)
+	 * @returns {Promise<void>}
+	 */
+	async tick(_data) {
 		const { width, height } = this.canvas;
 
 		const pixels = this.getBitmapRGBA(this.canvas, width, height);
 		const palette = quantize(pixels, this.maxColors);
 		const index = applyPalette(pixels, palette);
 
-		this.encoder.writeFrame(index, width, height, {
-			palette: palette,
-			delay: this.frameDuration,
-		});
+		if (this.encoder) {
+			this.encoder.writeFrame(index, width, height, {
+				palette: palette,
+				delay: this.frameDuration,
+			});
+		}
 	}
 
+	/**
+	 * End recording and create GIF blob
+	 * @returns {void}
+	 */
 	end() {
-		this.encoder.finish();
-
-		this.result = new Blob([this.encoder.bytes()], { type: 'image/gif' });
+		if (this.encoder) {
+			this.encoder.finish();
+			this.result = new Blob([this.encoder.bytes()], {
+				type: 'image/gif',
+			});
+		}
 
 		super.end();
 	}

package/src/client/app/lib/canvas-recorder/MediaBunnyRecorder.js

@@ -4,7 +4,6 @@ import {
 	Mp4OutputFormat,
 	MkvOutputFormat,
 	MovOutputFormat,
-	WebMInputFormat,
 	BufferTarget,
 	CanvasSource,
 	Quality,
@@ -18,6 +17,26 @@ import {
 import { map } from '@fragment/utils/math.utils.js';
 import { VIDEO_FORMATS } from '@fragment/state/exports.svelte.js';
 
+/**
+ * @typedef {'avc' | 'hevc' | 'vp9' | 'av1' | 'vp8'} VideoCodec
+ */
+
+/**
+ * @typedef {Object} MediaBunnyRecorderOptions
+ * @property {VideoCodec} codec - Video codec to use
+ * @property {number} [duration] - Recording duration in seconds
+ * @property {number} [framerate] - Frames per second
+ * @property {number} [quality] - Recording quality (1-100)
+ * @property {string} format - Output format
+ * @property {import('./CanvasRecorder').CanvasRecorderStartCallback} [onStart] - Callback when recording starts
+ * @property {import('./CanvasRecorder').CanvasRecorderTickCallback} [onTick] - Callback on each frame
+ * @property {import('./CanvasRecorder').CanvasRecorderCompleteCallback} [onComplete] - Callback when recording completes
+ */
+
+/**
+ * Recorder that uses MediaBunny to encode video
+ * @extends CanvasRecorder
+ */
 class MediaBunnyRecorder extends CanvasRecorder {
 	/** @type Quality[] */
 	static BITRATES = [
@@ -29,15 +48,14 @@ class MediaBunnyRecorder extends CanvasRecorder {
 	];
 
 	/**
-	 *
-	 * @param {HTMLCanvasElement} canvas
-	 * @param {object} options
-	 * @param {codec} options.string
+	 * Create a MediaBunny recorder
+	 * @param {HTMLCanvasElement} canvas - The canvas to record
+	 * @param {MediaBunnyRecorderOptions} options - Recording options
 	 */
 	constructor(canvas, { codec, ...options }) {
 		super(canvas, options);
 
-		/** @type {string} */
+		/** @type {VideoCodec} */
 		this.codec = codec;
 
 		const outputFormats = new Map();
@@ -72,23 +90,39 @@ class MediaBunnyRecorder extends CanvasRecorder {
 		});
 	}
 
+	/**
+	 * Load and start the output
+	 * @returns {Promise<void>}
+	 */
 	async load() {
 		await this.output.start();
 	}
 
-	async tick({ frameCount, time }) {
+	/**
+	 * Process a single frame
+	 * @param {import('./CanvasRecorder').TickData} tickData - Frame data
+	 * @returns {Promise<void>}
+	 */
+	async tick({ frameCount }) {
 		const timestamp = frameCount / this.framerate;
 
 		this.videoSource.add(timestamp, this.frameDuration / 1000);
 	}
 
+	/**
+	 * End recording and create video blob
+	 * @returns {Promise<void>}
+	 */
 	async end() {
 		await this.output.finalize();
 
 		const { mimeType } = this.output.format;
-		const { buffer } = this.output.target;
+		const target = /** @type {BufferTarget} */ (this.output.target);
+		const buffer = target.buffer;
 
-		this.result = new Blob([buffer], { type: mimeType });
+		if (buffer) {
+			this.result = new Blob([buffer], { type: mimeType });
+		}
 
 		super.end();
 	}

package/src/client/app/lib/canvas-recorder/utils.js

@@ -3,15 +3,24 @@ import { changeDpiDataUrl } from 'changedpi';
 const supportedEncodings = ['image/png', 'image/jpeg', 'image/webp'];
 
 /**
- * Create a Data URL from a canvas
- * @param {HTMLCanvasElement} canvas
- * @param {object} [options]
- * @param {string} [encoding="image/png"]
- * @param {number} [encodingQuality=0.92]
- * @param {number} [pixelsPerInch=72]
- * @returns {object} result
- * @returns {string} result.dataURL
- * @returns {string} result.extension
+ * @typedef {Object} ExportCanvasOptions
+ * @property {string} [encoding='image/png'] - Image MIME type (image/png, image/jpeg, image/webp)
+ * @property {number} [encodingQuality=0.92] - Image quality (0-1)
+ * @property {number} [pixelsPerInch=72] - DPI/PPI for the exported image
+ */
+
+/**
+ * @typedef {Object} ExportCanvasResult
+ * @property {string} extension - File extension (e.g., '.png', '.jpg')
+ * @property {string} dataURL - Data URL of the exported canvas
+ */
+
+/**
+ * Export a canvas to a data URL with specified encoding and DPI
+ * @param {HTMLCanvasElement} canvas - The canvas to export
+ * @param {ExportCanvasOptions} [options={}] - Export options
+ * @returns {ExportCanvasResult}
+ * @throws {Error} If encoding is not supported
  */
 export function exportCanvas(
 	canvas,

package/src/client/app/renderers/2DRenderer.js

@@ -5,32 +5,36 @@
  */
 
 /**
- * @param {object} params
- * @param {number} params.id
- * @param {HTMLCanvasElement} params.canvas
- * @param {HTMLElement} params.container
- * @param {number} params.width
- * @param {number} params.height
- * @param {number} params.pixelRatio
+ * @typedef {object} PreviewParams
+ * @property {number} id
+ * @property {HTMLCanvasElement} canvas
+ * @property {HTMLElement} container
+ * @property {number} width
+ * @property {number} height
+ * @property {number} pixelRatio
+ */
+
+/**
+ * @param {PreviewParams} params
  * @returns {MountParams2DRenderer}
  */
 export let onMountPreview = ({ canvas }) => {
+	const context = canvas.getContext('2d');
+
+	if (!context) {
+		throw new Error(`Cannot get CanvasRenderingContext2D from canvas`);
+	}
+
 	return {
 		canvas,
-		context: canvas.getContext('2d'),
+		context,
 	};
 };
 
 /**
- * @param {MountParams2DRenderer} params
- * @param {number} params.id
- * @param {HTMLCanvasElement} params.canvas
- * @param {HTMLElement} params.container
- * @param {number} params.width
- * @param {number} params.height
- * @param {number} params.pixelRatio
+ * @param {MountParams2DRenderer & PreviewParams} params
  */
-export let onResizePreview = ({ id, canvas, width, height, pixelRatio }) => {
+export let onResizePreview = ({ canvas, width, height, pixelRatio }) => {
 	canvas.width = width * pixelRatio;
 	canvas.height = height * pixelRatio;
 	canvas.style.width = `${width}px`;

package/src/client/app/renderers/FragmentRenderer.js

@@ -1,5 +1,5 @@
 import { fragment } from '../lib/gl';
-import { client } from '@fragment/client';
+import { client } from '../client';
 import { getShaderPath } from '../utils/glsl.utils';
 import { clearError } from '../state/errors.svelte';
 

package/src/client/app/renderers/P5GLRenderer.js

@@ -1,5 +1,5 @@
 import p5 from 'p5';
-import { client } from '@fragment/client';
+import { client } from '../client';
 import { getShaderPath } from '../utils/glsl.utils';
 import { clearError } from '../state/errors.svelte';
 
@@ -29,8 +29,16 @@ let previews = [];
  * @param {number} params.pixelRatio
  * @returns {MountParamsP5GLRenderer}
  */
-export let onMountPreview = ({ id, container, canvas, width, height }) => {
+export let onMountPreview = ({
+	id,
+	container,
+	canvas,
+	width,
+	height,
+	pixelRatio,
+}) => {
 	const p = new p5((sketch) => {
+		sketch.pixelDensity(pixelRatio);
 		sketch.setup = () => {
 			sketch.createCanvas(width, height, 'webgl', canvas);
 		};
@@ -49,7 +57,7 @@ export let onMountPreview = ({ id, container, canvas, width, height }) => {
 };
 
 /**
- * @param {MountParamsP5GLRenderer} params
+ * @param {object} params
  * @param {number} params.id
  * @param {HTMLCanvasElement} params.canvas
  * @param {HTMLDivElement} params.container
@@ -65,7 +73,7 @@ export let onBeforeUpdatePreview = ({ id }) => {
 };
 
 /**
- * @param {MountParamsP5GLRenderer} params
+ * @param {object} params
  * @param {number} params.id
  * @param {HTMLCanvasElement} params.canvas
  * @param {HTMLDivElement} params.container
@@ -86,7 +94,7 @@ export let onAfterUpdatePreview = ({ id }) => {
 };
 
 /**
- * @param {MountParamsP5GLRenderer} params
+ * @param {object} params
  * @param {number} params.id
  * @param {HTMLCanvasElement} params.canvas
  * @param {number} params.width
@@ -103,7 +111,7 @@ export let onResizePreview = ({ id, width, height, pixelRatio }) => {
 };
 
 /**
- * @param {MountParamsP5GLRenderer} params
+ * @param {object} params
  * @param {number} params.id
  * @param {HTMLCanvasElement} params.canvas
  * @param {HTMLElement} params.container

package/src/client/app/renderers/P5Renderer.js

@@ -25,8 +25,16 @@ let previews = [];
  * @param {number} params.pixelRatio
  * @returns {MountParamsP5Renderer}
  */
-export let onMountPreview = ({ id, container, canvas, width, height }) => {
+export let onMountPreview = ({
+	id,
+	container,
+	canvas,
+	width,
+	height,
+	pixelRatio,
+}) => {
 	const p = new p5((sketch) => {
+		sketch.pixelDensity(pixelRatio);
 		sketch.setup = () => {
 			sketch.createCanvas(width, height, canvas);
 		};