@tresjs/core 4.3.3 → 5.0.0-next.0

package/dist/src/composables/index.d.ts

@@ -1,8 +1,8 @@
 import { default as UseLoader } from './useLoader/component.vue';
 import { default as UseTexture } from './useTexture/component.vue';
 export * from './useCamera/';
+export * from './useGraph';
 export * from './useLoader';
-export * from './useLogger';
 export * from './useLoop';
 export * from './useRaycaster';
 export * from './useRenderer/';

package/dist/src/composables/useGraph/index.d.ts

@@ -0,0 +1,4 @@
+import { Object3D } from 'three';
+import { MaybeRef } from '@vueuse/core';
+import { TresObject } from '../../types';
+export declare function useGraph(object: MaybeRef<Object3D | TresObject>): import('vue').ComputedRef<import('../..').TresObjectMap>;

package/dist/src/composables/useLoader/component.vue.d.ts

@@ -1,24 +1,38 @@
+import { LoadingManager } from 'three';
 import { LoaderProto } from './index';
-type __VLS_Props = {
-    loader: LoaderProto<unknown>;
-    url: string | string[];
-};
-declare function __VLS_template(): {
-    attrs: Partial<{}>;
+import { TresObjectMap } from '../../utils/graph';
+declare const _default: <T extends TresObjectMap>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onLoaded?: ((result: T) => any) | undefined;
+        readonly onError?: ((error: unknown) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onLoaded" | "onError"> & {
+        /**
+         * The THREE.js loader to use
+         */
+        loader: LoaderProto<T>;
+        /**
+         * Path to resource
+         */
+        path: string;
+        /**
+         * Optional THREE.js LoadingManager
+         */
+        manager?: LoadingManager;
+    } & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
     slots: {
         default?(_: {
-            data: unknown;
+            state: import('vue').UnwrapRef<T>;
+            isLoading: boolean;
+            error: unknown;
         }): any;
     };
-    refs: {};
-    rootEl: any;
+    emit: ((evt: "loaded", result: T) => void) & ((evt: "error", error: unknown) => void);
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
 };
-type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
-declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
-declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 export default _default;
-type __VLS_WithTemplateSlots<T, S> = T & {
-    new (): {
-        $slots: S;
-    };
-};
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/src/composables/useLoader/index.d.ts

@@ -1,44 +1,50 @@
-import { Loader, LoadingManager, Object3D } from 'three';
-export interface TresLoader<T> extends Loader {
-    load: (url: string | string[], onLoad: (result: T) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void) => void;
-    loadAsync: (url: string, onProgress?: (event: ProgressEvent) => void) => Promise<T>;
+import { UseAsyncStateOptions, UseAsyncStateReturn } from '@vueuse/core';
+import { Loader, LoadingManager } from 'three';
+import { MaybeRef } from 'vue';
+export interface LoaderMethods {
+    setDRACOLoader: (dracoLoader: any) => void;
+    setMeshoptDecoder: (meshoptDecoder: any) => void;
+    setKTX2Loader: (ktx2Loader: any) => void;
 }
+export type TresLoader<T> = Loader & Partial<LoaderMethods> & {
+    load: (url: string, onLoad: (result: T) => void, onProgress?: (event: ProgressEvent<EventTarget>) => void, onError?: (err: unknown) => void) => void;
+    loadAsync: (url: string, onProgress?: (event: ProgressEvent) => void) => Promise<T>;
+};
 export type LoaderProto<T> = new (manager?: LoadingManager) => TresLoader<T>;
-export type LoaderReturnType<T, L extends LoaderProto<T>> = T extends unknown ? Awaited<ReturnType<InstanceType<L>['loadAsync']>> : T;
+export interface TresLoaderOptions<T, Shallow extends boolean> {
+    manager?: LoadingManager;
+    extensions?: (loader: TresLoader<T>) => void;
+    asyncOptions?: UseAsyncStateOptions<Shallow, any | null>;
+}
 /**
- * Traverse an object and return all the nodes and materials
- *
- * @export
- * @param {Object3D} object
- * @return { [key: string]: any }
+ * Return type for the useLoader composable
+ * @template T - The type of the loaded asset (e.g., GLTF, Texture, etc.)
+ * @template Shallow - Whether to use shallow reactivity for better performance
+ * @extends {UseAsyncStateReturn<T, [string], Shallow>} - Extends VueUse's useAsyncState return type
  */
-export declare function traverseObjects(object: Object3D): {
-    [key: string]: any;
+export type UseLoaderReturn<T, Shallow extends boolean> = UseAsyncStateReturn<T, [string], Shallow> & {
+    /**
+     * Loads a new asset from the given path
+     * @param path - The URL or path to the asset to load
+     */
+    load: (path: string) => void;
+    /**
+     * Progress of the loading process
+     * @property loaded - The number of bytes loaded
+     * @property total - The total number of bytes to load
+     * @property percentage - The percentage of the loading process
+     */
+    progress: {
+        loaded: number;
+        total: number;
+        percentage: number;
+    };
 };
-export type Extensions<T extends {
-    prototype: LoaderProto<any>;
-}> = (loader: T['prototype']) => void;
 /**
- * Load resources using THREE loaders and return the result as a promise
- *
- * @see https://tresjs.org/api/composables.html#useloader
- * @see https://threejs.org/docs/index.html?q=loader#api/en/loaders/Loader
- *
- * ```ts
- * import { useLoader } from '@tresjs/core'
- * import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'
- *
- * const { scene } = await useLoader(THREE.GLTFLoader, 'path/to/asset.gltf')
- * ```
- *
- * @export
- * @template LoaderProto<T>
- * @template string | string[],
- * @param {LoaderProto<T>} Loader
- * @param {string | string[],} url
- * @param {Extensions<TresLoader<T>>} [extensions]
- * @param {(event: ProgressEvent<EventTarget>) => void} [onProgress]
- * @param {(proto: TresLoader<T>) => void} [cb]
- * @return {*}
+ * Vue composable for loading 3D models using Three.js loaders
+ * @param Loader - The Three.js loader constructor
+ * @param path - The path to the model file
+ * @param options - Optional configuration for the loader
+ * @returns UseAsyncState composable with the loaded model
  */
-export declare function useLoader<T>(Loader: LoaderProto<T>, url: string | string[], extensions?: (loader: TresLoader<T>) => void, onProgress?: (event: ProgressEvent<EventTarget>) => void, cb?: (proto: TresLoader<T>) => void): Promise<T | T[]>;
+export declare function useLoader<T, Shallow extends boolean = false>(Loader: LoaderProto<T>, path: MaybeRef<string>, options?: TresLoaderOptions<T, Shallow>): UseLoaderReturn<T, Shallow>;

package/dist/src/devtools/plugin.d.ts

@@ -1,4 +1,3 @@
-import { App as DevtoolsApp } from '@vue/devtools-api';
 import { TresContext } from '../composables';
 export interface Tags {
     label: string;
@@ -12,4 +11,4 @@ export interface SceneGraphObject {
     children: SceneGraphObject[];
     tags: Tags[];
 }
-export declare function registerTresDevtools(app: DevtoolsApp, tres: TresContext): void;
+export declare function registerTresDevtools(app: any, tres: TresContext): void;

package/dist/src/devtools/setupDevtools.d.ts

@@ -0,0 +1,2 @@
+import { TresContext } from '../composables';
+export declare function setupDevtools(ctx: TresContext): void;

package/dist/src/index.d.ts

@@ -8,6 +8,8 @@ export * from './core/catalogue';
 export * from './core/loop';
 export * from './directives';
 export * from './types';
+export * from './utils/graph';
+export * from './utils/logger';
 export interface TresOptions {
     extends?: Record<string, unknown>;
 }

package/dist/src/utils/graph.d.ts

@@ -0,0 +1,14 @@
+import { Material, Mesh, Object3D, Scene } from 'three';
+export interface TresObjectMap {
+    nodes: {
+        [name: string]: Object3D;
+    };
+    materials: {
+        [name: string]: Material;
+    };
+    meshes: {
+        [name: string]: Mesh;
+    };
+    scene?: Scene;
+}
+export declare function buildGraph(object: Object3D): TresObjectMap;

package/dist/src/utils/index.d.ts

@@ -2,6 +2,7 @@ import { nodeOps } from 'src/core/nodeOps';
 import { AttachType, LocalState, TresInstance, TresObject, TresPrimitive } from 'src/types';
 import { Material, Mesh, MeshBasicMaterial, Scene, Vector3 } from 'three';
 import { TresContext } from '../composables/useTresContextProvider';
+export * from './logger';
 export declare function toSetMethodName(key: string): string;
 export declare const merge: (target: any, source: any) => any;
 export declare const isHTMLTag: (key: string) => boolean;
@@ -14,10 +15,6 @@ export declare const get: <T>(obj: any, path: string | string[]) => T | undefine
 export declare const set: (obj: any, path: string | string[], value: any) => void;
 export declare function deepEqual(a: any, b: any): boolean;
 export declare function deepArrayEqual(arr1: any[], arr2: any[]): boolean;
-/**
- * TypeSafe version of Array.isArray
- */
-export declare const isArray: (a: any) => a is any[] | readonly any[];
 export declare function editSceneObject(scene: Scene, objectUuid: string, propertyPath: string[], value: any): void;
 export declare function createHighlightMaterial(): MeshBasicMaterial;
 export declare function animateHighlight(highlightMesh: Mesh, startTime: number): void;

package/dist/src/utils/is.d.ts

@@ -1,18 +1,251 @@
 import { TresObject, TresPrimitive } from 'src/types';
 import { BufferGeometry, Camera, Fog, Light, Material, Object3D, Scene } from 'three';
-export declare function und(u: unknown): u is undefined;
-export declare function arr(u: unknown): u is any[];
-export declare function num(u: unknown): u is number;
-export declare function str(u: unknown): u is string;
-export declare function bool(u: unknown): u is boolean;
-export declare function fun(u: unknown): u is (...args: any[]) => any;
-export declare function obj(u: unknown): u is Record<string | number | symbol, unknown>;
-export declare function object3D(u: unknown): u is Object3D;
-export declare function camera(u: unknown): u is Camera;
-export declare function bufferGeometry(u: unknown): u is BufferGeometry;
-export declare function material(u: unknown): u is Material;
-export declare function light(u: unknown): u is Light;
-export declare function fog(u: unknown): u is Fog;
-export declare function scene(u: unknown): u is Scene;
-export declare function tresObject(u: unknown): u is TresObject;
-export declare function tresPrimitive(u: unknown): u is TresPrimitive;
+/**
+ * Type guard to check if a value is undefined
+ * @param value - The value to check
+ * @returns True if the value is undefined, false otherwise
+ * @example
+ * ```ts
+ * const value = undefined
+ * if (isUndefined(value)) {
+ *   // TypeScript knows value is undefined here
+ * }
+ * ```
+ */
+export declare function isUndefined(value: unknown): value is undefined;
+/**
+ * Type guard to check if a value is an array
+ * @param value - The value to check
+ * @returns True if the value is an array, false otherwise
+ * @example
+ * ```ts
+ * const value = [1, 2, 3]
+ * if (isArray(value)) {
+ *   // TypeScript knows value is Array<unknown> here
+ *   value.length // OK
+ *   value.map(x => x) // OK
+ * }
+ * ```
+ */
+export declare function isArray(value: unknown): value is Array<unknown>;
+/**
+ * Type guard to check if a value is a number
+ * @param value - The value to check
+ * @returns True if the value is a number (including NaN and Infinity), false otherwise
+ * @example
+ * ```ts
+ * const value = 42
+ * if (isNumber(value)) {
+ *   // TypeScript knows value is number here
+ *   value.toFixed(2) // OK
+ *   value * 2 // OK
+ * }
+ * ```
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * Type guard to check if a value is a string
+ * @param value - The value to check
+ * @returns True if the value is a string, false otherwise
+ * @example
+ * ```ts
+ * const value = "hello"
+ * if (isString(value)) {
+ *   // TypeScript knows value is string here
+ *   value.length // OK
+ *   value.toUpperCase() // OK
+ * }
+ * ```
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a boolean
+ * @param value - The value to check
+ * @returns True if the value is strictly true or false, false otherwise
+ * @example
+ * ```ts
+ * const value = true
+ * if (isBoolean(value)) {
+ *   // TypeScript knows value is boolean here
+ *   !value // OK
+ *   value && true // OK
+ * }
+ * ```
+ */
+export declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Type guard to check if a value is a function
+ * @param value - The value to check
+ * @returns True if the value is a callable function, false otherwise
+ * @example
+ * ```ts
+ * const value = () => {}
+ * if (isFunction(value)) {
+ *   // TypeScript knows value is (...args: any[]) => any here
+ *   value() // OK
+ *   value.call(null) // OK
+ * }
+ * ```
+ */
+export declare function isFunction(value: unknown): value is (...args: any[]) => any;
+/**
+ * Type guard to check if a value is a plain object
+ * @param value - The value to check
+ * @returns True if the value is a plain object (not null, array, or function), false otherwise
+ * @example
+ * ```ts
+ * const value = { key: 'value' }
+ * if (isObject(value)) {
+ *   // TypeScript knows value is Record<string | number | symbol, unknown> here
+ *   Object.keys(value) // OK
+ *   value.key // OK
+ * }
+ * ```
+ */
+export declare function isObject(value: unknown): value is Record<string | number | symbol, unknown>;
+/**
+ * Type guard to check if a value is a Three.js Object3D
+ * @param value - The value to check
+ * @returns True if the value is a Three.js Object3D instance, false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.Object3D()
+ * if (isObject3D(value)) {
+ *   // TypeScript knows value is Object3D here
+ *   value.position // OK
+ *   value.rotation // OK
+ *   value.scale // OK
+ * }
+ * ```
+ */
+export declare function isObject3D(value: unknown): value is Object3D;
+/**
+ * Type guard to check if a value is a Three.js Camera
+ * @param value - The value to check
+ * @returns True if the value is a Three.js Camera instance, false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.PerspectiveCamera()
+ * if (isCamera(value)) {
+ *   // TypeScript knows value is Camera here
+ *   value.fov // OK
+ *   value.near // OK
+ *   value.far // OK
+ * }
+ * ```
+ */
+export declare function isCamera(value: unknown): value is Camera;
+/**
+ * Type guard to check if a value is a Three.js BufferGeometry
+ * @param value - The value to check
+ * @returns True if the value is a Three.js BufferGeometry instance, false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.BufferGeometry()
+ * if (isBufferGeometry(value)) {
+ *   // TypeScript knows value is BufferGeometry here
+ *   value.attributes // OK
+ *   value.index // OK
+ *   value.computeVertexNormals() // OK
+ * }
+ * ```
+ */
+export declare function isBufferGeometry(value: unknown): value is BufferGeometry;
+/**
+ * Type guard to check if a value is a Three.js Material
+ * @param value - The value to check
+ * @returns True if the value is a Three.js Material instance, false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.MeshStandardMaterial()
+ * if (isMaterial(value)) {
+ *   // TypeScript knows value is Material here
+ *   value.color // OK
+ *   value.metalness // OK
+ *   value.roughness // OK
+ * }
+ * ```
+ */
+export declare function isMaterial(value: unknown): value is Material;
+/**
+ * Type guard to check if a value is a Three.js Light
+ * @param value - The value to check
+ * @returns True if the value is a Three.js Light instance, false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.DirectionalLight()
+ * if (isLight(value)) {
+ *   // TypeScript knows value is Light here
+ *   value.intensity // OK
+ *   value.color // OK
+ *   value.position // OK
+ * }
+ * ```
+ */
+export declare function isLight(value: unknown): value is Light;
+/**
+ * Type guard to check if a value is a Three.js Fog
+ * @param value - The value to check
+ * @returns True if the value is a Three.js Fog instance, false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.Fog(0x000000, 1, 1000)
+ * if (isFog(value)) {
+ *   // TypeScript knows value is Fog here
+ *   value.color // OK
+ *   value.near // OK
+ *   value.far // OK
+ * }
+ * ```
+ */
+export declare function isFog(value: unknown): value is Fog;
+/**
+ * Type guard to check if a value is a Three.js Scene
+ * @param value - The value to check
+ * @returns True if the value is a Three.js Scene instance, false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.Scene()
+ * if (isScene(value)) {
+ *   // TypeScript knows value is Scene here
+ *   value.children // OK
+ *   value.add(new THREE.Object3D()) // OK
+ *   value.remove(new THREE.Object3D()) // OK
+ * }
+ * ```
+ */
+export declare function isScene(value: unknown): value is Scene;
+/**
+ * Type guard to check if a value is a TresObject
+ * @param value - The value to check
+ * @returns True if the value is a TresObject (Object3D | BufferGeometry | Material | Fog), false otherwise
+ * @example
+ * ```ts
+ * const value = new THREE.Mesh()
+ * if (isTresObject(value)) {
+ *   // TypeScript knows value is TresObject here
+ *   // You can use common properties and methods shared by all TresObjects
+ * }
+ * ```
+ * @remarks
+ * TresObject is a union type that represents the core Three.js objects that can be used in TresJS.
+ * This includes Object3D, BufferGeometry, Material, and Fog instances.
+ */
+export declare function isTresObject(value: unknown): value is TresObject;
+/**
+ * Type guard to check if a value is a TresPrimitive
+ * @param value - The value to check
+ * @returns True if the value is a TresPrimitive instance, false otherwise
+ * @example
+ * ```ts
+ * const value = { isPrimitive: true }
+ * if (isTresPrimitive(value)) {
+ *   // TypeScript knows value is TresPrimitive here
+ *   // You can use properties and methods specific to TresPrimitives
+ * }
+ * ```
+ * @remarks
+ * TresPrimitive is a special type in TresJS that represents primitive objects
+ * that can be used directly in the scene without needing to be wrapped in a Three.js object.
+ */
+export declare function isTresPrimitive(value: unknown): value is TresPrimitive;

package/dist/src/utils/logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Logger utility for TresJS
+ * @module logger
+ */
+export declare const isProd: boolean;
+type OneOrMore<T> = {
+    0: T;
+} & Array<T>;
+/**
+ * Logs an error message with the TresJS prefix
+ * @param args - Arguments to log
+ */
+export declare function logError(...args: OneOrMore<any>): void;
+/**
+ * Logs a warning message with the TresJS prefix
+ * @param args - Arguments to log
+ */
+export declare function logWarning(...args: OneOrMore<any>): void;
+/**
+ * Logs a message with the TresJS prefix (only in development mode)
+ * @param name - Name of the message
+ * @param value - Value to log
+ */
+export declare function logMessage(name: string, value: any): void;
+export {};

package/dist/src/utils/perf.d.ts

@@ -1,6 +1,7 @@
 import { Scene } from 'three';
 import { TresObject } from './../types';
 export declare function calculateMemoryUsage(object: TresObject | Scene): number;
+export declare function boundedPush<T>(arr: T[], value: T, max: number): void;
 export declare function bytesToKB(bytes: number): string;
 export declare function bytesToMB(bytes: number): string;
 export declare function bytesToGB(bytes: number): string;

package/dist/src/utils/primitive/createRetargetingProxy.d.ts

@@ -1 +1 @@
-export declare function createRetargetingProxy<T extends Record<string | number | symbol, any>, K extends keyof T & string & symbol>(target: T, getters?: Record<string | number | symbol, (t: T) => unknown>, setters?: Partial<Record<K, (val: T[K], t: T, proxy: T, setTarget: (newTarget: T) => void) => boolean>>): T;
+export declare function createRetargetingProxy<T extends Record<string | number | symbol, any>, K extends keyof T & string & symbol>(target: T, getters?: Record<string | number | symbol, (t: T) => unknown>, setters?: Record<K, (val: T[K], t: T, proxy: T, setTarget: (newTarget: T) => void) => boolean>): T;