fragment-tools 0.2.11 → 0.2.13

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/modules/Params.svelte

@@ -151,6 +151,7 @@
 						{disabled}
 						bind:params={sketchProps[key].params}
 						bind:triggers={prop.triggers}
+						trackChanges
 						onclick={(event) => {
 							sketch.version++;
 							// value(event, sketch.params);

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/P5GLRenderer.js

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

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

@@ -4,35 +4,53 @@ import { getShaderPath } from '../utils/glsl.utils';
 import { clearError } from '../state/errors.svelte';
 
 /**
- * @typedef {object} MountParamsThreeRenderer
+ * @typedef {object} MountParamsTHREERenderer
  * @property {HTMLCanvasElement} canvas
- * @property {THREE.Scene} scene
- * @property {THREE.WebGLRenderer} renderer
+ * @property {Scene} scene
+ * @property {WebGLRenderer} renderer
  */
 
 /**
- * @typedef {object} PreviewThreeRenderer
+ * @typedef {object} PreviewTHREERenderer
  * @property {number} id
- * @property {THREE.Scene} scene
- * @property {THREE.renderer} renderer
- * @property {rendered} boolean
+ * @property {Scene} scene
+ * @property {WebGLRenderer} renderer
+ * @property {boolean} rendered
  */
 
-/** @type {PreviewThreeRenderer[]} */
+/**
+ * @typedef {object} PreviewParams
+ * @property {number} id
+ * @property {HTMLCanvasElement} canvas
+ * @property {HTMLDivElement} container
+ * @property {number} width
+ * @property {number} height
+ * @property {number} pixelRatio
+ */
+
+/**
+ * @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
+ */
+
+/** @type {PreviewTHREERenderer[]} */
 let previews = [];
 
 /**
- * @param {object} params
- * @param {number} params.id
- * @param {HTMLCanvasElement} params.canvas
- * @param {HTMLDivElement} params.container
- * @param {number} params.width
- * @param {number} params.height
- * @param {number} params.pixelRatio
- * @returns {MountParamsThreeRenderer}
+ * @param {PreviewParams} params
+ * @returns {MountParamsTHREERenderer}
  */
-export let onMountPreview = ({ id, canvas }) => {
-	let renderer = new WebGLRenderer({ antialias: true, canvas });
+export let onMountPreview = ({ id }) => {
+	let renderer = new WebGLRenderer({ antialias: true });
 
 	const render = renderer.render;
 
@@ -59,10 +77,7 @@ export let onMountPreview = ({ id, canvas }) => {
 };
 
 /**
- * @param {MountParamsThreeRenderer} params
- * @param {number} params.id
- * @param {HTMLCanvasElement} params.canvas
- * @param {HTMLDivElement} params.container
+ * @param {PreviewParams} params
  */
 export let onBeforeUpdatePreview = ({ id }) => {
 	const preview = previews.find((p) => p.id === id);
@@ -73,10 +88,7 @@ export let onBeforeUpdatePreview = ({ id }) => {
 };
 
 /**
- * @param {MountParamsThreeRenderer} params
- * @param {number} params.id
- * @param {HTMLCanvasElement} params.canvas
- * @param {HTMLDivElement} params.container
+ * @param {PreviewParams} params
  */
 export let onAfterUpdatePreview = ({ id }) => {
 	const preview = previews.find((p) => p.id === id);
@@ -94,14 +106,9 @@ export let onAfterUpdatePreview = ({ id }) => {
 };
 
 /**
- * @param {MountParamsThreeRenderer} params
- * @param {number} params.id
- * @param {HTMLCanvasElement} params.canvas
- * @param {number} params.width
- * @param {number} params.height
- * @param {number} params.pixelRatio
+ * @param {PreviewParams} params
  */
-export let onResizePreview = ({ id, width, height, pixelRatio }) => {
+export let onResizePreview = ({ id, width, height, pixelRatio, canvas }) => {
 	const preview = previews.find((p) => p.id === id);
 
 	if (preview) {
@@ -112,10 +119,7 @@ export let onResizePreview = ({ id, width, height, pixelRatio }) => {
 };
 
 /**
- * @param {MountParamsThreeRenderer} params
- * @param {number} params.id
- * @param {HTMLCanvasElement} params.canvas
- * @param {HTMLElement} params.container
+ * @param {PreviewParams} params
  */
 export let onDestroyPreview = ({ id }) => {
 	const previewIndex = previews.findIndex((p) => p.id === id);
@@ -125,13 +129,22 @@ export let onDestroyPreview = ({ id }) => {
 		const { renderer } = preview;
 		clearError(renderer.getContext().__uuid);
 		renderer.dispose();
+		renderer.forceContextLoss();
 		previews.splice(previewIndex, 1);
 	}
 };
 
 /* HOT SHADER RELOADING */
+/** @type {ShaderUpdate[]} */
 let _shaderUpdates = [];
 
+function clearShaderUpdates() {
+	_shaderUpdates = [];
+}
+
+/**
+ * @param {Scene} scene
+ */
 function handleHotShaderUpdate(scene) {
 	if (_shaderUpdates.length > 0) {
 		const verifyMaterial = (material) => {
@@ -172,20 +185,22 @@ function handleHotShaderUpdate(scene) {
 	}
 }
 
-function clearShaderUpdates() {
-	_shaderUpdates = [];
-}
-
 if (import.meta.hot) {
-	import.meta.hot.on('sketch-update', (data) => {
+	import.meta.hot.on('sketch-update', () => {
 		clearShaderUpdates();
 	});
 }
 
-client.on('shader-update', (shaderUpdates) => {
-	previews.forEach((preview) => {
-		clearError(preview.renderer.getContext().__uuid);
-	});
+client.on(
+	'shader-update',
+	/**
+	 * @param {ShaderUpdate[]} shaderUpdates
+	 */
+	(shaderUpdates) => {
+		previews.forEach((preview) => {
+			clearError(preview.renderer.getContext().__uuid);
+		});
 
-	_shaderUpdates = shaderUpdates;
-});
+		_shaderUpdates = shaderUpdates;
+	},
+);

package/src/client/app/state/Sketch.svelte.js

@@ -5,6 +5,7 @@ import {
 	deepClone,
 	deepEqual,
 	hydrate,
+	isDataURL,
 	isFunction,
 	isObject,
 	persist,
@@ -12,11 +13,58 @@ import {
 
 const noop = () => {};
 
+/**
+ * @typedef InstanceProp
+ * @property {any} value
+ * @property {Record<string, any>} params
+ * @property {any[]} triggers
+ * @property {string|undefined} group
+ * @property {string|undefined} type
+ * @property {string|undefined} folder
+ * @property {string|null|undefined} displayName
+ * @property {boolean|(() => boolean)} hidden
+ * @property {boolean|(() => boolean)} disabled
+ */
+
+/**
+ * @typedef SketchProp
+ * @property {any} value
+ * @property {any} __initialValue
+ * @property {any} __currentValue
+ * @property {Record<string, any>} params
+ * @property {any[]} triggers
+ * @property {string|undefined} group
+ * @property {string|undefined} type
+ * @property {string|undefined} folder
+ * @property {string|null|undefined} displayName
+ * @property {boolean} hidden
+ * @property {(() => boolean)} __hidden
+ * @property {boolean} disabled
+ * @property {(() => boolean)} __disabled
+ */
+
+/**
+ * @typedef SketchPropFolder
+ * @property {string} id
+ * @property {string} displayName
+ * @property {string} displayName
+ * @property {string} rootId
+ * @property {(SketchPropFolder | { type: 'field', key: string })[]} children
+ * @property {SketchPropFolder|undefined} parent
+ * @property {'fieldgroup'} type
+ * @property {number} depth
+ * @property {boolean} collapsed
+ * @property {boolean} hidden
+ * @property {boolean} __initialCollapsed
+ */
+
 class Sketch {
+	/** @type {Record<string, SketchProp} */
 	props = $state({});
 	canvas = $state(null);
 	backgroundColor = $state('inherit');
 	propsGroups = $state([]);
+	/** @type {SketchPropFolder[]} */
 	propsFolders = $state([]);
 	version = $state(0);
 
@@ -38,9 +86,13 @@ class Sketch {
 
 		this.recording = null;
 		this.params = {};
+		/** @type {(() => {})[]} */
 		this.beforeCapture = [];
+		/** @type {(() => {})[]} */
 		this.beforeRecord = [];
+		/** @type {(() => {})[]} */
 		this.afterCapture = [];
+		/** @type {(() => {})[]} */
 		this.afterRecord = [];
 
 		this.reconcile(previous);
@@ -58,8 +110,10 @@ class Sketch {
 
 	reconcile(previous) {
 		const instanceProps = this.instance.props ?? {};
+		/** @type {Record<string, SketchProp>} */
 		const newProps = {};
 		const newPropsGroups = [];
+		/** @type {SketchPropFolder[]} */
 		const newPropsFolders = [];
 
 		Object.keys(instanceProps).forEach((key) => {
@@ -117,7 +171,15 @@ class Sketch {
 			}
 		};
 
+		/**
+		 *
+		 * @param {SketchPropFolder[]} prevFolders
+		 */
 		const restorePropsFoldersState = (prevFolders) => {
+			/**
+			 *
+			 * @param {SketchPropFolder} prevFolder
+			 */
 			const restoreFolder = (prevFolder) => {
 				const newFolder = newPropsFolders.find((f) => {
 					return prevFolder.id === f.id;
@@ -163,6 +225,15 @@ class Sketch {
 		this.propsFolders = newPropsFolders;
 	}
 
+	/**
+	 *
+	 * @param {Record<string, any>} target
+	 * @param {string} key
+	 * @param {InstanceProp} instanceProp
+	 * @param {*} propsFoldersCollection
+	 * @param {*} propsGroupsCollection
+	 * @returns
+	 */
 	createProp(
 		target,
 		key,
@@ -208,7 +279,11 @@ class Sketch {
 		}
 
 		if (folder) {
-			this.createPropFolder(folder, propsFoldersCollection, key);
+			// this prevent references from breaking when using Proxies
+			const propsFoldersCollectionCopy = [...propsFoldersCollection];
+			this.createPropFolder(folder, propsFoldersCollectionCopy, key);
+			propsFoldersCollection.length = 0;
+			propsFoldersCollection.push(...propsFoldersCollectionCopy);
 		}
 
 		let prop = {
@@ -232,6 +307,11 @@ class Sketch {
 		return prop;
 	}
 
+	/**
+	 *
+	 * @param {string} key
+	 * @param {any} newValue
+	 */
 	updateProp(key, newValue) {
 		const prop = this.props[key];
 		const instanceProp = this.instance.props[key];
@@ -243,7 +323,13 @@ class Sketch {
 
 		if (instanceProp) {
 			if (!deepEqual(instanceProp.value, newValue)) {
-				if (isObject(instanceProp.value) && isObject(newValue)) {
+				if (
+					Array.isArray(instanceProp.value) &&
+					Array.isArray(newValue)
+				) {
+					instanceProp.value.length = 0;
+					instanceProp.value.push(...newValue);
+				} else if (isObject(instanceProp.value) && isObject(newValue)) {
 					deepAssign(instanceProp.value, newValue);
 				} else {
 					instanceProp.value = newValue;
@@ -266,6 +352,13 @@ class Sketch {
 		this.version++;
 	}
 
+	/**
+	 *
+	 * @param {string} folder
+	 * @param {SketchPropFolder[]} collection
+	 * @param {string} key
+	 * @returns {SketchPropFolder | undefined}
+	 */
 	createPropFolder(folder, collection, key) {
 		if (!folder) return undefined;
 
@@ -316,7 +409,7 @@ class Sketch {
 					collection.push(fieldgroup);
 				}
 
-				if (isCurrent) {
+				if (fieldgroup && isCurrent) {
 					fieldgroup.children.push({
 						type: 'field',
 						key,
@@ -330,6 +423,11 @@ class Sketch {
 		return propFolder;
 	}
 
+	/**
+	 *
+	 * @param {SketchPropFolder} folder
+	 * @param {boolean} collapsed
+	 */
 	updateFolder(folder, collapsed) {
 		this.propsFolders.forEach((f, index) => {
 			if (f.id === folder.id) {
@@ -405,17 +503,20 @@ class Sketch {
 						);
 						fieldgroup.children.splice(childIndex, 1);
 
+						/**
+						 *
+						 * @param {SketchPropFolder} fieldgroup
+						 */
 						const removeFolderIfNeeded = (fieldgroup) => {
 							if (fieldgroup.children.length === 0) {
 								const currentFolderIndex =
 									this.propsFolders.findIndex(
-										(c) => c === fieldgroup,
+										(c) => c.id === fieldgroup.id,
 									);
 								this.propsFolders.splice(currentFolderIndex, 1);
 
-								const { parent } = fieldgroup;
-
-								if (parent) {
+								if (fieldgroup && fieldgroup.parent) {
+									const { parent } = fieldgroup;
 									const childIndex =
 										parent.children.findIndex(
 											(c) => c.id === fieldgroup.id,
@@ -430,11 +531,14 @@ class Sketch {
 					}
 
 					if (instanceProp.folder) {
+						// this prevent references from breaking when using Proxies
+						const propsFoldersCopy = [...this.propsFolders];
 						this.createPropFolder(
 							instanceProp.folder,
-							this.propsFolders,
+							propsFoldersCopy,
 							key,
 						);
+						this.propsFolders = propsFoldersCopy;
 						prop.folder = instanceProp.folder;
 					} else {
 						prop.folder = undefined;
@@ -481,7 +585,7 @@ class Sketch {
 		fieldgroups.forEach((fieldgroup) => {
 			const hasAllFieldsHidden = fieldgroup.children
 				.filter((child) => child.type === 'field')
-				.every((child) => this.props[child.key].__hidden());
+				.every((child) => this.props[child.key]?.__hidden());
 			const hasAllFieldgroupsHidden = fieldgroup.children
 				.filter((child) => child.type === 'fieldgroup')
 				.every((child) => child.hidden);
@@ -498,25 +602,61 @@ class Sketch {
 		});
 	}
 
+	/**
+	 * @param {() => void} fn
+	 */
 	onBeforeCapture(fn) {
 		this.beforeCapture.push(fn);
 	}
 
+	/**
+	 *
+	 * @param {() => void} fn
+	 */
 	onBeforeRecord(fn) {
 		this.beforeRecord.push(fn);
 	}
 
+	/**
+	 * @param {() => void} fn
+	 */
 	onAfterCapture(fn) {
 		this.afterCapture.push(fn);
 	}
 
+	/**
+	 * @param {() => void} fn
+	 */
 	onAfterRecord(fn) {
 		this.afterRecord.push(fn);
 	}
 
 	toJSON() {
+		/**
+		 * @typedef SketchPropJSON
+		 * @property {any} value
+		 * @property {Record<string, any>} params
+		 * @property {any[]} triggers
+		 * @property {any} __initialValue
+		 * @property {any} __currentValue
+		 */
+		/** @type {Record<string, SketchPropJSON>} */
+		const props = {};
+
+		for (const key in this.props) {
+			const prop = this.props[key];
+
+			props[key] = {
+				value: isDataURL(prop.value) ? prop.__initialValue : prop.value,
+				params: prop.params,
+				triggers: prop.triggers,
+				__initialValue: prop.__initialValue,
+				__currentValue: prop.__currentValue,
+			};
+		}
+
 		return {
-			props: this.props,
+			props,
 			propsFolders: this.propsFolders.map(
 				({
 					id,

package/src/client/app/state/errors.svelte.js

@@ -1,17 +1,36 @@
 import { SvelteMap } from 'svelte/reactivity';
 
+/**
+ * Map storing errors by context
+ * @type {SvelteMap<string, Error>}
+ */
 export let errors = new SvelteMap();
 
+/**
+ * Display an error for a specific context
+ * @param {Error | any} error - The error to display
+ * @param {string} context - The context identifier for the error
+ * @returns {void}
+ */
 export function displayError(error, context) {
 	errors.set(context, error);
 }
 
+/**
+ * Clear the error for a specific context
+ * @param {string} context - The context identifier
+ * @returns {void}
+ */
 export function clearError(context) {
 	if (errors.has(context)) {
 		errors.delete(context);
 	}
 }
 
+/**
+ * Clear all errors
+ * @returns {void}
+ */
 export function clearErrors() {
 	errors.clear();
 }