fragment-tools 0.2.11 → 0.2.13

package/src/client/app/client.js

@@ -1,9 +1,53 @@
+/**
+ * @typedef {Object} MessagePayload
+ * @property {string} event - The event name
+ * @property {any} [data] - Optional event data
+ */
+
+/**
+ * @typedef {Object} ShaderWarning
+ * @property {string} type - Warning type
+ * @property {string} importer - File that imported the shader
+ * @property {string} message - Warning message
+ * @property {Object} location - Location of the warning
+ * @property {string} location.lineText - The line of code with the warning
+ */
+
+/**
+ * @typedef {Object} ShaderUpdate
+ * @property {ShaderWarning[]} [warnings] - Array of shader warnings
+ */
+
+/**
+ * @typedef {Object} SketchUpdate
+ * @property {string} filepath
+ */
+
+/**
+ * @callback EventCallback
+ * @param {any} data - Event data
+ * @returns {void}
+ */
+
+/**
+ * @callback UnsubscribeFunction
+ * @returns {void}
+ */
+
 const socketProtocol = location.protocol === 'https:' ? 'wss' : 'ws';
 const socketHost = `${location.hostname}:${__FRAGMENT_PORT__}`;
 
-let socket,
-	listeners = {};
+/** @type {WebSocket | undefined} */
+let socket;
+/** @type {Record<string, EventCallback[]>} */
+let listeners = {};
+let opened = false;
 
+/**
+ * Handle incoming WebSocket message
+ * @param {MessagePayload} payload - The message payload
+ * @returns {void}
+ */
 function handleMessage(payload) {
 	const { event, data = {} } = payload;
 	const callbacks = listeners[event];
@@ -13,6 +57,12 @@ function handleMessage(payload) {
 	}
 }
 
+/**
+ * Subscribe to an event
+ * @param {string} event - The event name to listen for
+ * @param {EventCallback} cb - The callback function
+ * @returns {UnsubscribeFunction} Function to unsubscribe
+ */
 function on(event, cb) {
 	if (!listeners[event]) {
 		listeners[event] = [];
@@ -25,6 +75,12 @@ function on(event, cb) {
 	};
 }
 
+/**
+ * Unsubscribe from an event
+ * @param {string} event - The event name
+ * @param {EventCallback} cb - The callback function to remove
+ * @returns {void}
+ */
 function off(event, cb) {
 	const callbacks = listeners[event];
 
@@ -35,9 +91,14 @@ function off(event, cb) {
 	}
 }
 
-let opened = false;
+/**
+ * Emit an event to the server
+ * @param {string} event - The event name
+ * @param {any} data - The data to send
+ * @returns {void}
+ */
 function emit(event, data) {
-	if (opened) {
+	if (socket && opened) {
 		socket.send(
 			JSON.stringify({
 				event,
@@ -52,7 +113,7 @@ if (import.meta.hot) {
 
 	socket = new WebSocket(`${socketProtocol}://${socketHost}`);
 
-	socket.addEventListener('message', async (message) => {
+	socket.addEventListener('message', (message) => {
 		const { data } = message;
 
 		handleMessage(JSON.parse(data));
@@ -63,22 +124,33 @@ if (import.meta.hot) {
 		opened = true;
 	});
 
-	import.meta.hot.on('sketch-update', (data) => {
-		console.log(`[fragment] hmr update /${data.filepath}`);
-	});
+	import.meta.hot.on(
+		'sketch-update',
+		/** @param {SketchUpdate} sketchUpdate */
+		(sketchUpdate) => {
+			console.log(`[fragment] hmr update /${sketchUpdate.filepath}`);
+		},
+	);
 }
 
+/**
+ * Client API for WebSocket communication
+ * @type {{ on: typeof on, off: typeof off, emit: typeof emit }}
+ */
 export const client = { on, off, emit };
 
 client.on('shader-update', (shaderUpdates) => {
-	shaderUpdates.forEach(({ warnings = [] } = {}) => {
-		if (warnings.length > 0) {
-			warnings.forEach((warning) => {
-				const { location } = warning;
-				console.warn(
-					`[fragment-plugin-hsr] ${warning.type} ${warning.importer}\n\n  ${location.lineText}\n\n${warning.message}`,
-				);
-			});
-		}
-	});
+	shaderUpdates.forEach(
+		/** @param {ShaderUpdate} shaderUpdate */
+		({ warnings = [] } = {}) => {
+			if (warnings.length > 0) {
+				warnings.forEach((warning) => {
+					const { location } = warning;
+					console.warn(
+						`[fragment-plugin-hsr] ${warning.type} ${warning.importer}\n\n  ${location.lineText}\n\n${warning.message}`,
+					);
+				});
+			}
+		},
+	);
 });

package/src/client/app/components/IconFlip.svelte

@@ -0,0 +1,46 @@
+<script>
+	let { angle = 0 } = $props();
+</script>
+
+<svg
+	width="16"
+	height="16"
+	fill="none"
+	viewBox="0 0 24 24"
+	style="--angle: {angle}"
+>
+	<path
+		stroke="currentColor"
+		stroke-linecap="round"
+		stroke-linejoin="round"
+		stroke-width="1.5"
+		d="M18 8H6"
+	></path>
+	<path
+		stroke="currentColor"
+		stroke-linecap="round"
+		stroke-linejoin="round"
+		stroke-width="1.5"
+		d="M10 5L6 8L10 11"
+	></path>
+	<path
+		stroke="currentColor"
+		stroke-linecap="round"
+		stroke-linejoin="round"
+		stroke-width="1.5"
+		d="M6 16H18"
+	></path>
+	<path
+		stroke="currentColor"
+		stroke-linecap="round"
+		stroke-linejoin="round"
+		stroke-width="1.5"
+		d="M14 13L18 16L14 19"
+	></path>
+</svg>
+
+<style>
+	svg {
+		transform: rotate(var(--angle));
+	}
+</style>

package/src/client/app/hooks.js

@@ -2,18 +2,42 @@ import { rendering } from './state/rendering.svelte';
 import { sketchesManager } from './state/sketches.svelte';
 import { getContext } from './triggers/shared';
 
+/**
+ * Register a callback to be called before capturing
+ * @param {Function} listener - The callback function to execute before capture
+ * @param {string} [context] - The sketch context (defaults to current context)
+ * @returns {void}
+ */
 export const onBeforeCapture = (listener, context = getContext()) => {
 	sketchesManager.sketches[context]?.onBeforeCapture(listener);
 };
 
+/**
+ * Register a callback to be called after capturing
+ * @param {Function} listener - The callback function to execute after capture
+ * @param {string} [context] - The sketch context (defaults to current context)
+ * @returns {void}
+ */
 export const onAfterCapture = (listener, context = getContext()) => {
 	sketchesManager.sketches[context]?.onAfterCapture(listener);
 };
 
+/**
+ * Register a callback to be called before recording
+ * @param {Function} listener - The callback function to execute before recording
+ * @param {string} [context] - The sketch context (defaults to current context)
+ * @returns {void}
+ */
 export const onBeforeRecord = (listener, context = getContext()) => {
 	sketchesManager.sketches[context]?.onBeforeRecord(listener);
 };
 
+/**
+ * Register a callback to be called after recording
+ * @param {Function} listener - The callback function to execute after recording
+ * @param {string} [context] - The sketch context (defaults to current context)
+ * @returns {void}
+ */
 export const onAfterRecord = (listener, context = getContext()) => {
 	sketchesManager.sketches[context]?.onAfterRecord(listener);
 };
@@ -23,7 +47,7 @@ export const onAfterRecord = (listener, context = getContext()) => {
  * @param {object} options
  * @param {string} [options.filename]
  * @param {function} [options.pattern]
- * @param {exportDir} [options.pattern]
+ * @param {string} [options.exportDir]
  */
 export async function screenshot({ filename, pattern, exportDir } = {}) {
 	const context = getContext();

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();
 	}