fragment-tools 0.2.12 → 0.2.14

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

@@ -1,37 +1,55 @@
 import { WebGLRenderer, Scene } from 'three';
-import { client } from '@fragment/client';
+import { client } from '../client';
 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.WebGLrenderer} 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 }) => {
+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);
@@ -131,8 +135,16 @@ export let onDestroyPreview = ({ id }) => {
 };
 
 /* HOT SHADER RELOADING */
+/** @type {ShaderUpdate[]} */
 let _shaderUpdates = [];
 
+function clearShaderUpdates() {
+	_shaderUpdates = [];
+}
+
+/**
+ * @param {Scene} scene
+ */
 function handleHotShaderUpdate(scene) {
 	if (_shaderUpdates.length > 0) {
 		const verifyMaterial = (material) => {
@@ -173,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;
@@ -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();
 }

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

@@ -1,3 +1,4 @@
+import { saveFiles } from '@fragment/utils/file.utils';
 import { screenshotCanvas, recordCanvas } from '../utils/canvas.utils';
 import { hydrate, persist } from './utils.svelte';
 
@@ -58,6 +59,7 @@ class Exports {
 	imageCount = $state(1);
 	recording = $state(false);
 	capturing = $state(false);
+	committing = $state(false);
 	imageCollapsed = $state(false);
 	videoCollapsed = $state(false);
 
@@ -96,6 +98,8 @@ class Exports {
 			quality = this.imageQuality,
 			pixelsPerInch = this.pixelsPerInch,
 			filename,
+			files = [],
+			commit = false,
 			pattern,
 			exportDir,
 			params = {},
@@ -117,7 +121,7 @@ class Exports {
 		for (let i = 0; i < count; i++) {
 			onBeforeCapture(captureParams);
 
-			await screenshotCanvas(canvas, {
+			const file = screenshotCanvas(canvas, {
 				filename,
 				pattern,
 				exportDir,
@@ -128,10 +132,19 @@ class Exports {
 				pixelsPerInch,
 			});
 
+			files.push(file);
+
 			onAfterCapture(captureParams);
 		}
 
 		onComplete(captureParams);
+
+		try {
+			await saveFiles(files, [], { commit });
+		} catch (error) {
+			console.error(`[fragment] Error while saving screenshot.`);
+			console.log(error);
+		}
 	}
 
 	record(

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

@@ -12,6 +12,11 @@ import { layout } from './layout.svelte.js';
 import { persist, hydrate } from './utils.svelte';
 import presets from '../lib/presets';
 import { client } from '../client.js';
+import { saveFiles } from '@fragment/utils/file.utils.js';
+import {
+	defaultFilenamePattern,
+	getFilenameParams,
+} from '@fragment/utils/canvas.utils.js';
 
 export const SIZES = {
 	FIXED: 'fixed',
@@ -581,6 +586,8 @@ export class Render {
 		filename = this.sketch.key,
 		pattern = this.sketch.filenamePattern,
 		exportDir = this.sketch.exportDir,
+		files = [],
+		commit = false,
 	} = {}) {
 		const { sketch } = this;
 
@@ -591,6 +598,8 @@ export class Render {
 			params: {
 				props: sketch.props,
 			},
+			files,
+			commit,
 			onBeforeCapture: (params) => {
 				sketch.beforeCapture.forEach((fn) => fn(params));
 				this.renderSketch();
@@ -602,6 +611,44 @@ export class Render {
 		});
 	}
 
+	async commit({
+		filename = this.sketch.key,
+		pattern = this.sketch.filenamePattern ?? defaultFilenamePattern,
+		exportDir = this.sketch.exportDir,
+	} = {}) {
+		const { sketch } = this;
+		const { props } = sketch;
+
+		const data = {};
+
+		for (const key in props) {
+			data[key] = { value: props[key].value };
+		}
+
+		let patternParams = getFilenameParams();
+		let name = pattern({
+			filename,
+			params: { props },
+			...patternParams,
+		});
+
+		let files = [
+			{
+				filename: `${name}.props.json`,
+				exportDir,
+				data: JSON.stringify(data),
+			},
+		];
+
+		await this.screenshot({
+			filename,
+			pattern,
+			exportDir,
+			files,
+			commit: true,
+		});
+	}
+
 	get params() {
 		return {
 			...this.mountParams,

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

@@ -6,11 +6,28 @@ import Sketch from './Sketch.svelte.js';
 import { rendering } from './rendering.svelte.js';
 import { removeHotListeners } from '../triggers/index.js';
 
+/**
+ * @typedef {Object} SketchInstance
+ * @property {string} [rendering]
+ * @property {any} [renderer]
+ */
+
+/**
+ * @typedef {Record<string, () => Promise<SketchInstance>>} SketchCollection
+ */
+
 class SketchesManager {
+	/** @type {Record<string, Sketch>} */
 	sketches = $state({});
 	keys = $derived(Object.keys(this.sketches));
 	count = $derived(this.keys.length);
 
+	/**
+	 * Load a single sketch from a collection
+	 * @param {SketchCollection} collection - The collection of sketches
+	 * @param {string} key - The key of the sketch to load
+	 * @returns {Promise<SketchInstance | undefined>}
+	 */
 	async loadSketch(collection, key) {
 		try {
 			let sketch = await collection[key]();
@@ -27,6 +44,11 @@ class SketchesManager {
 		}
 	}
 
+	/**
+	 * Load all sketches from a collection
+	 * @param {SketchCollection} collection - The collection of sketches to load
+	 * @returns {Promise<void>}
+	 */
 	async loadAll(collection) {
 		const keys = [...Object.keys(collection)];
 
@@ -42,16 +64,30 @@ class SketchesManager {
 			keys.map((key) => this.loadSketch(collection, key)),
 		);
 
-		const newSketches = keys.reduce((all, key, index) => {
-			if (loadedSketches[index]) {
-				all[key] = loadedSketches[index];
-			}
+		/** @type {Record<string, SketchInstance>} */
+		const newSketches = keys.reduce(
+			/**
+			 * @param {Record<string, SketchInstance>} all
+			 * @param {string} key
+			 * @param {number} index
+			 */
+			(all, key, index) => {
+				if (loadedSketches[index]) {
+					all[key] = loadedSketches[index];
+				}
 
-			return all;
-		}, {});
+				return all;
+			},
+			{},
+		);
 
+		/** @type {Record<string, Sketch>} */
 		const newInstancedSketches = Object.keys(newSketches).reduce(
-			(all, key, index) => {
+			/**
+			 * @param {Record<string, Sketch>} all
+			 * @param {string} key
+			 */
+			(all, key) => {
 				const prevSketch = this.sketches[key];
 
 				const instanced = new Sketch({