fragment-tools 0.2.12 → 0.2.13

package/src/client/app/utils/file.utils.js

@@ -1,9 +1,11 @@
 /**
  * @typedef {Object} File
- * @property {string} filepath
- * @property {string} exportDir
+ * @property {string} filename
  * @property {string} data
+ * @property {string} [exportDir]
  * @property {string} [encoding]
+ * @property {Blob} [blob]
+ * @property {number} [size]
  */
 
 /**
@@ -20,7 +22,12 @@ export async function createDataURLFromBlob(blob) {
 		};
 
 		reader.onload = (e) => {
-			resolve(e.target.result);
+			const result = e.target?.result;
+			if (typeof result === 'string') {
+				resolve(result);
+			} else {
+				reject(new Error('Failed to read blob as data URL'));
+			}
 		};
 
 		reader.readAsDataURL(blob);
@@ -30,7 +37,7 @@ export async function createDataURLFromBlob(blob) {
 /**
  * Transform a Data URL into a blob
  * @param {string} dataURL
- * @returns {Blob}
+ * @returns {Promise<Blob>}
  */
 export function createBlobFromDataURL(dataURL) {
 	return new Promise((resolve, reject) => {
@@ -60,15 +67,24 @@ export function createBlobFromDataURL(dataURL) {
 	});
 }
 
+/**
+ * Download data as a file
+ * @param {string | object} data - The data to download
+ * @param {string} filename - The filename for the download
+ * @returns {void}
+ */
 export function download(data, filename) {
 	let extension = getFileExtension(filename);
 
-	if (typeof data === 'object' && ['json', 'txt'].includes(extension)) {
-		data = JSON.stringify(data, undefined, 4);
+	let content;
+	if (typeof data === 'object') {
+		content = JSON.stringify(data, undefined, 4);
+	} else {
+		content = data;
 	}
 
 	let type = getMimeType(extension);
-	let blob = new Blob([data], { type });
+	let blob = new Blob([content], { type });
 
 	downloadBlob(blob, { filename });
 }
@@ -78,6 +94,7 @@ export function download(data, filename) {
  * @param {Blob} blob
  * @param {object} [options]
  * @param {string} [options.filename="untitled"]
+ * @returns {void}
  */
 export function downloadBlob(blob, { filename = 'untitled' } = {}) {
 	let a = document.createElement('a');
@@ -91,7 +108,7 @@ export function downloadBlob(blob, { filename = 'untitled' } = {}) {
 	a.onclick = () => {
 		a.onclick = () => {};
 		setTimeout(() => {
-			window.URL.revokeObjectURL(blob);
+			window.URL.revokeObjectURL(a.href);
 			if (a.parentElement) a.parentElement.removeChild(a);
 			a.removeAttribute('href');
 		});
@@ -106,7 +123,7 @@ export function downloadBlob(blob, { filename = 'untitled' } = {}) {
  * @returns {string} filename
  */
 export function getFilename(path) {
-	return path.split(/[\\/]/).pop();
+	return path.split(/[\\/]/).pop() || path;
 }
 
 /**
@@ -114,34 +131,44 @@ export function getFilename(path) {
  * @param {string} data
  * @returns {number}
  */
-export function estimateFileSize(data) {
+export function estimateFileSize(data, errorMargin = 1) {
 	const base64Length = data.length - (data.indexOf(',') + 1);
-	return (base64Length * (3 / 4) - 2) / 1024 / 1024;
+	return ((base64Length * (3 / 4) - 2) / 1024 / 1024) * errorMargin;
 }
 
+/**
+ * Extract file extension from a path
+ * @param {string} path - The file path
+ * @returns {string} The file extension or undefined if not found
+ */
 export function getFileExtension(path) {
 	const match = path.match(/[^\\/]\.([^.\\/]+)$/);
 
 	if (match && match.length > 1) {
 		return match[1];
 	}
+
+	return '';
 }
 
 /**
- *
- * @param {string} extension
- * @returns {string}
+ * Get MIME type from file extension
+ * @param {string} extension - The file extension
+ * @returns {string} The MIME type or 'application/octet-stream' if not recognized
  */
 export function getMimeType(extension) {
 	if (extension === 'json') return 'application/json';
 	if (extension === 'txt') return 'text';
 	if (extension === 'png') return 'image/png';
 	if (extension === 'jpeg' || extension === 'jpg') return 'image/jpeg';
+
+	return 'application/octet-stream';
 }
 
 /**
- *
- * @param {File|File[]} files
+ * Save file(s) in the browser using download
+ * @param {File | File[]} files - Single file or array of files to save
+ * @returns {Promise<void>}
  */
 export async function saveInBrowser(files) {
 	/**
@@ -152,11 +179,11 @@ export async function saveInBrowser(files) {
 			blob = await createBlobFromDataURL(data);
 		}
 
-		await downloadBlob(blob, { filename });
+		downloadBlob(blob, { filename });
 	}
 
 	if (Array.isArray(files)) {
-		return Promise.all(files.map((file) => saveFile(file)));
+		await Promise.all(files.map((file) => saveFile(file)));
 	} else {
 		await saveFile(files);
 	}
@@ -164,34 +191,45 @@ export async function saveInBrowser(files) {
 
 /**
  * Save files to disk by sending them to Fragment save plugin. Fallback to saveInBrowser if fails
- * @param {File[]} files
- * @returns {Promise<string[]>}
+ * @param {File[]} [files=[]]
+ * @param {string[]} [out=[]]
+ * @returns {Promise<string[] | void>}
  */
-export async function saveFiles(files = [], out = []) {
+export async function saveFiles(files = [], out = [], { commit = false } = {}) {
 	if (__DEV__) {
 		files.forEach((file) => {
 			if (!file.size) {
-				file.size = estimateFileSize(file.data);
+				const errorMargin = 1.3;
+				file.size = estimateFileSize(file.data, errorMargin);
 			}
 		});
 
 		const limitInMb = 100;
+		/** @type {{ files: File[], commit: boolean }} */
 		const body = {
 			files: [],
+			commit: false,
 		};
 
 		let size = 0;
 
 		for (let i = 0; i < files.length; i++) {
 			const file = files[i];
-			if (size < limitInMb) {
+
+			if (size + (file.size ?? 0) < limitInMb) {
 				body.files.push(file);
-				size += file.size;
+				size += file.size || 0;
 			} else {
 				break;
 			}
 		}
 
+		const isLastBatch = body.files.length - files.length === 0;
+
+		if (isLastBatch) {
+			body.commit = commit;
+		}
+
 		const response = await fetch('/save', {
 			method: 'POST',
 			body: JSON.stringify(body),
@@ -200,13 +238,21 @@ export async function saveFiles(files = [], out = []) {
 				'Content-Type': 'application/json',
 			},
 		});
-		const { filepaths, error } = await response.json();
+		/** @type {{ filepaths: string[], warnings: string[], errors: string[]}} */
+		const { filepaths, warnings, errors } = await response.json();
 
-		if (response.ok && filepaths?.length) {
+		if (errors?.length > 0) {
+			errors.forEach((error) => {
+				console.error(`[fragment] ${error}`);
+			});
+			await saveInBrowser(files);
+		} else if (response.ok && filepaths?.length) {
 			out.push(...filepaths);
 
 			if (body.files.length < files.length) {
-				return saveFiles(files.slice(body.files.length), out);
+				return saveFiles(files.slice(body.files.length), out, {
+					commit,
+				});
 			}
 
 			if (out.length < 15) {
@@ -219,10 +265,17 @@ export async function saveFiles(files = [], out = []) {
 				});
 			}
 
+			if (warnings?.length > 0) {
+				warnings.forEach((warning) => {
+					console.warn(`[fragment] ${warning}`);
+				});
+			} else {
+				if (commit) {
+					console.log(`[fragment] Committed latest changes.`);
+				}
+			}
+
 			return out;
-		} else {
-			console.error(`[fragment] Error while saving files on disk.`);
-			await saveInBrowser(files);
 		}
 	} else {
 		await saveInBrowser(files);
@@ -233,7 +286,9 @@ export async function saveFiles(files = [], out = []) {
  * Save a blob on disk
  * @param {Blob} blob
  * @param {object} options
- * @returns {Promise<string[]>}
+ * @param {string} options.filename
+ * @param {string} options.exportDir
+ * @returns {Promise<string[] | void>}
  */
 export async function saveBlob(blob, { filename, exportDir }) {
 	const data = await createDataURLFromBlob(blob);

package/src/client/app/utils/glsl.utils.js

@@ -1,10 +1,19 @@
-const regex = /<filepath:\/\/(.*)>/;
-
+/**
+ * Extract the file path from a shader string
+ * @param {string} [shader=''] - The shader source code
+ * @returns {string | null} The extracted file path, or null if not found
+ */
 export function getShaderPath(shader = '') {
 	const match = shader.match(/<filepath:\/\/(.*)>/);
 	return match && match[1];
 }
 
+/**
+ * Remove the file path comment from a shader string
+ * @param {string} shader - The shader source code
+ * @param {string | null} [filepath] - Optional filepath to remove (defaults to extracted path)
+ * @returns {string} The shader with the filepath comment removed
+ */
 export function removeShaderPath(shader, filepath = getShaderPath(shader)) {
 	if (filepath) {
 		return shader.replace(`// <filepath://${filepath}>`, '');

package/src/client/app/utils/glslErrors.js

@@ -4,6 +4,7 @@ import { getShaderPath, removeShaderPath } from './glsl.utils';
 const methods = ['attachShader'];
 
 const contexts = [WebGLRenderingContext, WebGL2RenderingContext];
+/** @type {Record<string, any>} */
 const references = {};
 
 for (let i = 0; i < methods.length; i++) {
@@ -50,6 +51,14 @@ const FRAGMENT_SHADER = 35632;
 const VERTEX_SHADER = 35633;
 
 class ShaderCompileError extends Error {
+	/**
+	 *
+	 * @param {Object} params
+	 * @param {string} [params.source]
+	 * @param {string} [params.filename]
+	 * @param {string} [params.message]
+	 * @param {number} [params.lineNumber]
+	 */
 	constructor({
 		source,
 		filename = '',
@@ -112,30 +121,33 @@ e('compileShader', function (res, args) {
 	const filename = shader.__filename;
 
 	if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
-		const { source, lineNumber, message } = getShaderError(
-			gl,
-			shader,
-			shader.__type,
-		);
-
-		const error = new ShaderCompileError({
-			source,
-			message,
-			filename,
-			lineNumber,
-		});
-
-		displayError(error, this.__uuid);
+		const shaderError = getShaderError(gl, shader, shader.__type);
+
+		if (shaderError) {
+			const { source, message, lineNumber } = shaderError;
+			const shaderCompileError = new ShaderCompileError({
+				source,
+				message,
+				filename,
+				lineNumber,
+			});
+			displayError(shaderCompileError, this.__uuid);
+		}
 	}
 });
 
+/**
+ *
+ * @param {WebGL2RenderingContext} gl
+ * @param {WebGLShader} shader
+ * @param {number} type
+ * @returns {{ message: string, source: string, lineNumber: number} | undefined}
+ */
 function getShaderError(gl, shader, type) {
+	console.log(`getShaderError`, gl, shader, type);
 	const status = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
-	const errors = gl.getShaderInfoLog(shader).trim();
-
-	if (status && errors === '') return '';
-
-	const errorMatches = errors.match(/ERROR: 0:(\d+):([\s\S]*$)/);
+	const errors = gl.getShaderInfoLog(shader)?.trim() ?? '';
+	const errorMatches = errors && errors.match(/ERROR: 0:(\d+):([\s\S]*$)/);
 
 	if (errorMatches) {
 		const lineNumber = parseInt(errorMatches[1]);
@@ -148,8 +160,6 @@ function getShaderError(gl, shader, type) {
 			source: source,
 			lineNumber,
 		};
-	} else {
-		return errors;
 	}
 }
 

package/src/client/app/utils/index.js

@@ -1,26 +1,42 @@
 /**
- *
- * @param {Map} map
- * @param {string} key
- * @param {any} find
+ * @template K, V
+ * @callback FindIndexCallback
+ * @param {V} item - The item to test
+ * @param {number} index - The index of the item
+ * @param {V[]} array - The array being searched
+ * @returns {boolean}
+ */
+
+/**
+ * Add an item to an array stored in a Map
+ * @template K, V
+ * @param {Map<K, V[]>} map - The Map containing arrays as values
+ * @param {K} key - The key to store the item under
+ * @param {V} item - The item to add to the array
+ * @returns {void}
  */
 export const addToMapArray = (map, key, item) => {
-	if (map.has(key)) {
-		map.set(key, [...map.get(key), item]);
+	const previous = map.get(key);
+
+	if (Array.isArray(previous)) {
+		map.set(key, [...previous, item]);
 	} else {
 		map.set(key, [item]);
 	}
 };
 
 /**
- *
- * @param {Map} map
- * @param {string} key
- * @param {function} findIndex
+ * Remove an item from an array stored in a Map
+ * @template K, V
+ * @param {Map<K, V[]>} map - The Map containing arrays as values
+ * @param {K} key - The key where the array is stored
+ * @param {(item: V, index: number, array: V[]) => boolean} findIndex - Callback to find the item to remove
+ * @returns {void}
  */
 export const removeFromMapArray = (map, key, findIndex) => {
-	if (map.has(key)) {
-		const items = map.get(key);
+	const items = map.get(key);
+
+	if (Array.isArray(items)) {
 		const index = items.findIndex(findIndex);
 
 		if (index >= 0) {

package/src/client/main.js

@@ -1,8 +1,14 @@
 import { mount } from 'svelte';
 import App from './app/App.svelte';
 
+const target = document.getElementById('app');
+
+if (!target) {
+	throw new Error('App mount target not found');
+}
+
 const app = mount(App, {
-	target: document.getElementById('app'),
+	target,
 	props: {},
 });
 

package/src/types/global.d.ts

@@ -0,0 +1,143 @@
+/// <reference types="vite/client" />
+
+declare const __DEV__: boolean;
+declare const __CWD__: string;
+declare const __FRAGMENT_PORT__: number | undefined;
+declare const __START_TIME__: number;
+declare const __SEED__: number;
+declare const __BUILD__: boolean;
+
+declare module 'virtual:sketches' {
+	/**
+	 * Collection of sketch modules
+	 */
+	export const sketches: Record<string, () => Promise<any>>;
+}
+
+declare module 'changedpi' {
+	/**
+	 * Collection of sketch modules
+	 */
+	export function changeDpiDataUrl(data: string, ppi: number);
+}
+
+declare module 'gifenc' {
+	/**
+	 * RGB color palette entry
+	 */
+	export type PaletteEntry = [number, number, number];
+
+	/**
+	 * RGBA color
+	 */
+	export type RGBAColor = [number, number, number, number];
+
+	/**
+	 * Quantization options
+	 */
+	export interface QuantizeOptions {
+		/**
+		 * Enable oneBitTransparency
+		 */
+		oneBitTransparency?: boolean;
+		/**
+		 * Format of input data
+		 */
+		format?: 'rgb565' | 'rgba4444' | 'rgba5551';
+		/**
+		 * Clear hash between frames
+		 */
+		clearHash?: boolean;
+		/**
+		 * Clear hash modulo
+		 */
+		clearHashModulo?: number;
+	}
+
+	/**
+	 * Frame write options
+	 */
+	export interface WriteFrameOptions {
+		/**
+		 * Color palette for the frame
+		 */
+		palette?: PaletteEntry[];
+		/**
+		 * Delay in milliseconds
+		 */
+		delay?: number;
+		/**
+		 * Transparent color index
+		 */
+		transparent?: number;
+		/**
+		 * Disposal method
+		 */
+		dispose?: number;
+		/**
+		 * Enable repeat
+		 */
+		repeat?: number;
+	}
+
+	/**
+	 * GIF Encoder instance
+	 */
+	export interface GIFEncoderInstance {
+		/**
+		 * Write a frame to the GIF
+		 */
+		writeFrame(
+			index: Uint8Array,
+			width: number,
+			height: number,
+			options?: WriteFrameOptions,
+		): void;
+		/**
+		 * Finish encoding and finalize the GIF
+		 */
+		finish(): void;
+		/**
+		 * Get the encoded bytes
+		 */
+		bytes(): Uint8Array<ArrayBuffer>;
+		/**
+		 * Get the byte length
+		 */
+		bytesView(): Uint8Array;
+	}
+
+	/**
+	 * Create a new GIF encoder
+	 */
+	export function GIFEncoder(): GIFEncoderInstance;
+
+	/**
+	 * Quantize RGBA pixel data to a color palette
+	 */
+	export function quantize(
+		rgba: Uint8Array | Uint8ClampedArray,
+		maxColors: number,
+		options?: QuantizeOptions,
+	): PaletteEntry[];
+
+	/**
+	 * Apply a palette to RGBA pixel data
+	 */
+	export function applyPalette(
+		rgba: Uint8Array | Uint8ClampedArray,
+		palette: PaletteEntry[],
+		format?: 'rgb565' | 'rgba4444' | 'rgba5551',
+	): Uint8Array;
+
+	/**
+	 * Prequantize RGBA data
+	 */
+	export function prequantize(
+		rgba: Uint8Array | Uint8ClampedArray,
+		options?: QuantizeOptions,
+	): {
+		rgba: Uint8Array;
+		palette: PaletteEntry[];
+	};
+}

package/src/types/props.d.ts

@@ -11,19 +11,23 @@ type BaseProp<Value, Params, Type> = {
 };
 
 type SelectProp = BaseProp<
-	number | string,
+	number | string | undefined,
 	{
 		options?:
 			| number[]
 			| string[]
+			| undefined[]
 			| Array<{ label?: string; value: number }>
-			| Array<{ label?: string; value: string }>;
+			| Array<{ label?: string; value: string | undefined }>;
 	},
 	'select'
 >;
 type NumberProp = BaseProp<
 	number,
-	{ disabled?: boolean; step?: number } | { min: number; max: number },
+	({ min?: never; max?: never } | { min: number; max: number }) & {
+		step?: number;
+		suffix?: string;
+	},
 	'number'
 >;
 
@@ -56,24 +60,40 @@ type VecParams<V extends VecValue> = V extends readonly number[]
 
 type VecProp<V extends VecValue = VecValue> = BaseProp<
 	V,
-	{ locked?: boolean } | VecParams<V>,
+	{ locked?: boolean; suffix?: string } & VecParams<V>,
 	'vec'
 >;
 type CheckboxProp = BaseProp<boolean, never, 'checkbox'>;
-type TextProp = BaseProp<string, { disabled?: boolean }, 'text'>;
-type ListProp = BaseProp<any[], { disabled?: boolean }, 'list'>;
-type ColorProp = BaseProp<
-	string | THREE.Color | { r: number; g: number; b: string; a?: number },
-	never,
-	'color'
+type TextProp = BaseProp<string, { label?: string }, 'text'>;
+type TextareaProp = BaseProp<string, { height?: string }, 'textarea'>;
+type ListProp = BaseProp<any[], never, 'list'>;
+type ColorRepresentation =
+	| string
+	| THREE.Color
+	| { r: number; g: number; b: string; a?: number };
+type ColorProp = BaseProp<ColorRepresentation, never, 'color'>;
+type PaletteProp = BaseProp<
+	ColorRepresentation[],
+	{ extensible?: boolean; editable?: boolean },
+	'palette'
+>;
+type ButtonProp = BaseProp<() => void, { label?: string }, 'button'>;
+type ImportProp = BaseProp<
+	(event: ProgressEvent) => void,
+	{ label?: string; accept?: string },
+	'import'
 >;
-type ButtonProp = BaseProp<
-	() => void,
-	{ disabled?: boolean; label?: string },
-	'button' | 'download'
+type DownloadProp = BaseProp<
+	() => [any, string],
+	{ label?: string },
+	'download'
 >;
 type ImageProp = BaseProp<string, never, 'image'>;
 
+type GradientStop = { color: ColorRepresentation; position: number };
+
+type GradientProp = BaseProp<GradientStop[], never, 'gradient'>;
+
 type Prop =
 	| SelectProp
 	| NumberProp
@@ -81,10 +101,15 @@ type Prop =
 	| VecProp<VecArray>
 	| CheckboxProp
 	| TextProp
+	| TextareaProp
 	| ListProp
 	| ColorProp
+	| PaletteProp
+	| ImportProp
+	| DownloadProp
 	| ButtonProp
-	| ImageProp;
+	| ImageProp
+	| GradientProp;
 
 export type Props = Record<string, Prop>;
 

package/tsconfig.json

@@ -20,7 +20,7 @@
 		/* Linting */
 		"strict": true,
 		"allowJs": true,
-		"checkJs": false,
+		"checkJs": true,
 		"noUnusedLocals": true,
 		"noUnusedParameters": true,
 		"noFallthroughCasesInSwitch": true,