@vctrl/hooks 0.25.1 → 1.0.0

package/use-load-model/types.d.ts

@@ -1,13 +1,17 @@
 import { ModelFileTypes } from '../../../core/src/model-loader/index.ts';
-import { Object3D } from 'three';
+import { AnimationClip, Object3D } from 'three';
 import { useOptimizeModel } from '../use-optimize-model';
-import { default as eventSystem } from './event-system';
-import { initialState } from './state';
-import { ServerOptions, ServerSceneData } from '../../../core/src/index.ts';
+import { ServerOptions, ServerSceneData, ServerScenePayload } from '../../../core/src/index.ts';
 export type { ExtendedGLTFDocument, SceneAssetDataEntry, SerializedSceneAssetDataMap as SceneAssetDataMap, ServerSceneData, ServerScenePayload } from '../../../core/src/index.ts';
 /**
- * Type representing the input for file/folder uploads.
- * Can be either File objects or FileSystemDirectoryHandle for folder drag-and-drop.
+ * What the loader accepts as a user's selection.
+ *
+ * NOT the drag-and-drop path, which this was called for years. A folder dropped
+ * on a page arrives as plain `File` objects - react-dropzone has already walked
+ * it - and `expandDirectories` claims the path each one carries. The
+ * `FileSystemDirectoryHandle` branch is for a caller that opened
+ * `showDirectoryPicker()` itself and has a handle rather than files, which is a
+ * real capability and the reason the union is wider than `File[]`.
  */
 export type InputFileOrDirectory = (File | FileSystemDirectoryHandle)[];
 /**
@@ -16,7 +20,9 @@ export type InputFileOrDirectory = (File | FileSystemDirectoryHandle)[];
 export interface ModelFile {
     /** The Three.js Object3D scene containing the loaded model */
     model: Object3D;
-    /** The file type/format of the model (GLTF, GLB, USDZ) */
+    /** Animation clips carried by the model. Absent or empty when it has none. */
+    animations?: AnimationClip[];
+    /** The file type/format of the model (glTF, GLB, STL, FBX, OBJ). */
     type: ModelFileTypes;
     /** The original filename of the model */
     name: string;
@@ -26,77 +32,144 @@ export interface ModelFile {
     sourceTextureBytes?: number;
 }
 /**
- * Configuration options for loading a scene from the server.
+ * Where a model comes from. Every load in the platform is one of these three,
+ * and they all go through the single `load(source)` entry point.
  */
-export interface SceneLoadOptions {
-    /** The unique identifier of the scene to load */
-    sceneId: string;
-    /** Server configuration (endpoint, auth, headers) */
-    serverOptions?: ServerOptions;
-    /** Whether to automatically apply scene settings (default: true) */
-    applySettings?: boolean;
-    /** 'direct' parses glTF JSON straight with GLTFLoader (view-only fast path). */
-    parseMode?: 'document' | 'direct';
+export type ModelSource = 
+/** Files or folders picked by the user (glTF + assets, GLB, STL, FBX, OBJ). */
+{
+    kind: 'files';
+    files: InputFileOrDirectory;
 }
 /**
- * Configuration options for loading an already-resolved scene payload.
+ * A scene payload the caller already has in memory (route aggregate, IDB
+ * draft). Binary assets may be referenced rather than inlined; the loader
+ * fetches them.
  */
-export interface SceneDataLoadOptions {
-    /** Optional scene identifier for resolved payloads. */
+ | {
+    kind: 'scene-data';
     sceneId?: string;
-    /** Resolved server scene payload */
-    sceneData: ServerSceneData;
-    /** Whether to automatically apply scene settings (default: true) */
-    applySettings?: boolean;
+    sceneData: ServerScenePayload;
     /** 'direct' parses glTF JSON straight with GLTFLoader (view-only fast path). */
     parseMode?: 'document' | 'direct';
 }
+/** A scene fetched from the API by id. */
+ | {
+    kind: 'server';
+    sceneId: string;
+    serverOptions?: ServerOptions;
+    parseMode?: 'document' | 'direct';
+};
+export type ModelSourceKind = ModelSource['kind'];
 /**
- * Result of a scene load operation based on server data.
- * Combines the loaded model with its settings.
+ * The loader's state, as one value.
+ *
+ * `status === 'ready'` and `file !== null` are the same fact by construction, so
+ * a consumer cannot end up rendering "no model" and "finished loading" at once.
+ * `file` and `error` are present on every variant so callers can read them
+ * without narrowing; only their types change.
  */
-export interface SceneLoadResult extends ServerSceneData {
-    /** The loaded model file */
-    file: ModelFile;
-    /** Scene ID that was loaded */
+interface ModelStateShape {
+    progress: number;
+    /** The scene payload the model came from, for sources that have one. */
+    sceneData?: ServerSceneData;
     sceneId?: string;
 }
+export type ModelState = (ModelStateShape & {
+    status: 'empty';
+    file: null;
+    error: null;
+    source: null;
+}) | (ModelStateShape & {
+    status: 'loading';
+    file: null;
+    error: null;
+    source: ModelSourceKind;
+}) | (ModelStateShape & {
+    status: 'ready';
+    file: ModelFile;
+    error: null;
+    source: ModelSourceKind;
+}) | (ModelStateShape & {
+    status: 'error';
+    file: null;
+    error: StructuredLoadError;
+    source: ModelSourceKind;
+});
 /**
- * State interface for model loading data.
- * Contains the current loaded file, loading status, and progress information.
+ * What `load` resolves to: the state it produced, and whether it still counts.
+ *
+ * A LOAD THAT LOST IS INDISTINGUISHABLE FROM ONE THAT WON, without this. The
+ * hook retires a superseded load's *state* by token, so it can never overwrite
+ * the model that replaced it - but the promise still resolves, with a `ready`
+ * state carrying a real `ModelFile`, byte-identical to the winner's. A caller
+ * acting on the resolved value rather than on the rendered state therefore had
+ * no way to tell the two apart, and every one of them had to keep a second
+ * clock of its own to compensate. Two already did, differently: a monotonic
+ * counter on the converter page and an effect-cleanup flag in `useSceneModel`.
+ *
+ * `stillCurrent` is that clock, published once. It reads the same token
+ * `setState` is gated on, so it stays truthful at any later point - including
+ * after awaits the loader knows nothing about, which is what a caller that
+ * exports or encodes the result actually needs. `reset()` claims a token too,
+ * so a load in flight when the user clears the model also reports false.
+ *
+ * It answers about *this* load, so hold the resolved value and ask it again
+ * rather than caching the boolean.
  */
-export interface LoadData {
-    /** The currently loaded model file, or null if no model is loaded */
-    file: ModelFile | null;
-    /** Whether a file is currently being loaded */
-    isFileLoading: boolean;
-    /** Loading progress percentage (0-100) */
-    progress: number;
-    /** List of supported model file types */
-    supportedFileTypes: ModelFileTypes[];
+export type LoadOutcome = ModelState & {
+    /** Whether this load is still the newest one, asked now. */
+    stillCurrent: () => boolean;
+};
+/** Optional hooks into a load, for callers that need more than its result. */
+export interface LoadOptions {
+    /**
+     * Called the moment the parsed model reaches the screen.
+     *
+     * WHY THIS EXISTS, AND WHY `await load(...)` IS NOT THE SAME MOMENT. The
+     * loaders publish as soon as the model is parsed and then await the
+     * optimizer ingest, so `load` resolves one ingest *after* the viewer changed.
+     * A caller that adopts on the resolved value therefore shows model B on the
+     * stage while everything it prints around it - the file name, the byte
+     * count, a size comparison, a live download button - still describes model A,
+     * for as long as ingesting B takes.
+     *
+     * `stillCurrent` cannot close that window: during it, B genuinely is the
+     * current load. The gap is between published and adopted, so the fix is to
+     * make those one event.
+     *
+     * **Called only for a load that is still the current one**, so there is
+     * nothing to re-check on entry. What can still go stale is whatever the
+     * callback goes on to do, so hold the outcome and ask its `stillCurrent()`
+     * again after an await of its own.
+     *
+     * Optional, and additive: a caller that does not pass it behaves exactly as
+     * before. Delaying the publish instead would have closed the same gap by
+     * making the viewer wait on work it does not need, which is the trade this
+     * deliberately does not make.
+     */
+    onPublish?: (outcome: LoadOutcome) => void;
 }
 /**
- * Action types for the model loading reducer.
- * Defines all possible state mutations for model loading operations.
+ * A model parsed into Three.js, plus whatever scene payload produced it.
+ * Internal hand-off between the per-source loaders and the hook.
  */
-export type Action = {
-    type: 'set-file';
-    payload: ModelFile;
-} | {
-    type: 'set-file-loading';
-    payload: boolean;
-} | {
-    type: 'set-progress';
-    payload: number;
-} | {
-    type: 'reset-state';
-};
+export interface LoadedModel {
+    file: ModelFile;
+    sceneId?: string;
+    sceneData?: ServerSceneData;
+}
 /**
- * Available event types emitted by the model loading system.
- * Used for subscribing to various stages of the loading process.
+ * Result of a scene load operation based on server data.
+ * Combines the loaded model with its settings.
  */
-export type EventTypes = 'multiple-models' | 'not-loaded-files' | 'load-start' | 'load-progress' | 'load-complete' | 'load-reset' | 'load-error' | 'server-load-start' | 'server-load-complete' | 'server-load-error';
-export type ViewerLoadErrorCode = 'unsupported_format' | 'binary_load_failed' | 'gltf_load_failed' | 'missing_assets' | 'server_load_failed' | 'not_found' | 'quota_exceeded' | 'unknown';
+export interface SceneLoadResult extends ServerSceneData {
+    /** The loaded model file */
+    file: ModelFile;
+    /** Scene ID that was loaded */
+    sceneId?: string;
+}
+export type ViewerLoadErrorCode = 'unsupported_format' | 'multiple_models' | 'binary_load_failed' | 'gltf_load_failed' | 'missing_assets' | 'server_load_failed' | 'not_found' | 'quota_exceeded' | 'unknown';
 export interface StructuredLoadError {
     code: ViewerLoadErrorCode;
     message: string;
@@ -105,88 +178,43 @@ export interface StructuredLoadError {
     cause?: unknown;
     context?: Record<string, unknown>;
 }
-/**
- * Maps event types to their corresponding data payloads.
- * Ensures type safety when handling events.
- */
-export type EventData = {
-    /** Array of model files when multiple are detected */
-    'multiple-models': File[];
-    /** Array of unsupported files */
-    'not-loaded-files': File[];
-    /** No data for load start event */
-    'load-start': null;
-    /** Progress value (0-100) */
-    'load-progress': number;
-    /** The loaded model file data */
-    'load-complete': LoadData['file'];
-    /** No data for reset event */
-    'load-reset': null;
-    /** Normalized error payload when loading fails */
-    'load-error': StructuredLoadError | Error | unknown;
-    /** Scene ID being loaded from server */
-    'server-load-start': string;
-    /** Complete scene load result */
-    'server-load-complete': SceneLoadResult;
-    /** Normalized error payload during server scene loading */
-    'server-load-error': StructuredLoadError | Error | unknown;
-};
-/**
- * Type-safe event handler function.
- * @template T - The event type being handled
- */
-export type EventHandler<T extends EventTypes> = (data?: EventData[T]) => void;
 /**
  * Return type for the useLoadModel hook.
  * Conditionally includes optimizer integration based on whether an optimizer was provided.
  *
  * @template HasOptimizer - Boolean indicating if optimizer integration is included
  */
-export type UseLoadModelReturn<HasOptimizer extends boolean> = typeof initialState & {
-    /**
-     * Subscribe to model loading events.
-     * @param event - The event type to listen for
-     * @param handler - Callback function to handle the event
-     */
-    on: typeof eventSystem.on;
-    /**
-     * Unsubscribe from model loading events.
-     * @param event - The event type to stop listening for
-     * @param handler - The callback function to remove
-     */
-    off: typeof eventSystem.off;
-    /**
-     * Load 3D model files from File objects or directory handles.
-     * Supports GLTF, GLB, and USDZ formats with associated assets.
-     */
-    load: (filesOrDirectories: InputFileOrDirectory) => Promise<void>;
-    /**
-     * Load a scene from already-resolved scene data.
-     * Preserves original asset payload semantics and bypasses upload-style file processing.
-     */
-    loadFromData: (options: SceneDataLoadOptions) => Promise<SceneLoadResult>;
+export type UseLoadModelReturn<HasOptimizer extends boolean> = ModelState & {
+    /** List of supported model file types */
+    supportedFileTypes: ModelFileTypes[];
     /**
-     * Load a scene from the server by scene ID.
-     * Fetches both the model and scene settings, applies them automatically.
+     * Load a model from any source.
+     *
+     * Never rejects: it resolves to the terminal state, and for every source but
+     * `files` that is also the state consumers render from.
      *
-     * @param options - Scene loading configuration
-     * @returns Promise resolving to the loaded scene data
+     * A rejected `files` load is the exception. When a model was already on
+     * screen it stays exactly as it was, so dropping the wrong file does not
+     * cost the user their scene, and the failure is reported only through the
+     * resolved value. With nothing on screen the state is the error as usual.
+     * `reset()` is how you clear a model deliberately.
+     *
+     * A newer `load` supersedes an older one, so an in-flight load can never
+     * overwrite the state of the load that replaced it. The superseded call
+     * still resolves, with the state it would have produced, so a caller that
+     * acts on the result rather than on the state must ask `stillCurrent()`
+     * before writing anything down - and ask it again after any further await,
+     * because a drop can land during an encode as easily as during a parse.
      *
      * @example
      * ```tsx
      * const model = useLoadModel()
      *
-     * // Load a scene from the server
-     * const scene = await model.loadFromServer({
-     *   sceneId: 'abc-123',
-     *   serverOptions: {
-     *     endpoint: '/api/load-scene',
-     *     apiKey: 'optional-auth-token'
-     *   }
-     * })
+     * await model.load({ kind: 'files', files })
+     * await model.load({ kind: 'server', sceneId: 'abc-123' })
      * ```
      */
-    loadFromServer: (options: SceneLoadOptions) => Promise<SceneLoadResult>;
+    load: (source: ModelSource, options?: LoadOptions) => Promise<LoadOutcome>;
     /**
      * Reset the model loading state and clear any loaded models.
      */
@@ -234,11 +262,6 @@ export type OptimizerIntegrationReturn<HasOptimizer extends boolean = false> = H
      *   optimizer.simplifyOptimization,
      *   { ratio: 0.5 }
      * )
-     *
-     * @example
-     * // Apply multiple optimizations in sequence
-     * await optimizer.applyOptimization(optimizer.dedupOptimization)
-     * await optimizer.applyOptimization(optimizer.quantizeOptimization, { bits: 12 })
      */
     applyOptimization: <TOptions>(optimizationFunction?: ((options?: TOptions) => Promise<void>) | undefined, options?: TOptions) => Promise<void>;
 } : null;

package/use-load-model/use-load-model.d.ts

@@ -1,19 +1,23 @@
 import { UseLoadModelReturn } from './types';
 import { useOptimizeModel } from '../use-optimize-model';
 /**
- * Custom hook to load and manage 3D models with optional optimization integration.
+ * Loads and holds one 3D model, from files, from a scene payload, or from the API.
  *
- * Supports GLTF, GLB, and USDZ formats via file upload or server-side scene loading.
- * When an optimizer is provided, each load path initialises the optimizer so texture
- * names and URIs are preserved for subsequent compression or simplification passes.
+ * There is a single entry point, `load(source)`, and a single state value. The
+ * state is a discriminated union, so "a model is on screen" and "loading
+ * finished" are the same fact and cannot disagree. `load` never rejects: it
+ * resolves to the terminal state.
  *
- * **Type Safety:**
- * - With optimizer: `optimizer` property is fully typed with optimization methods
- * - Without optimizer: `optimizer` property is typed as `null`
+ * One case separates the resolved value from the state. A rejected upload
+ * leaves a model that was already on screen exactly as it was, because dropping
+ * the wrong file should not cost the user their scene, so that failure is
+ * reported only through the value `load` resolves to. With nothing on screen,
+ * and for every other source, which replaces what is there, the failure is the
+ * state.
  *
  * @template T - The type of the optimizer parameter (inferred automatically)
  * @param optimizer - Optional optimizer hook returned from useOptimizeModel
- * @returns Model loading state and methods, with conditionally typed optimizer property
+ * @returns Model state and methods, with a conditionally typed optimizer property
  */
 declare function useLoadModel<T extends ReturnType<typeof useOptimizeModel> | undefined>(optimizer?: T): UseLoadModelReturn<T extends undefined ? false : true>;
 export default useLoadModel;

package/use-load-model/utils/index.d.ts

@@ -1,5 +1,5 @@
 export { default as readDirectory } from './read-directory';
 export { reconstructGltfFiles } from './reconstruct-files';
 export { calculateReferencedBytesFromFiles, calculateReferencedBytesFromServerScene } from './calculate-referenced-bytes';
-export { resolveServerSceneDataContract } from './resolve-scene-payload';
+export { resolvePublishedSceneDataContract, resolveServerSceneDataContract } from './resolve-scene-payload';
 export { fetchManifestAssetData, type FetchManifestAssetsOptions } from './fetch-manifest-assets';

package/use-load-model/utils/reconstruct-files.d.ts

@@ -1,4 +1,28 @@
 import { InputFileOrDirectory, ServerSceneData } from '../types';
+/**
+ * The file name a saved scene's glTF arrives as.
+ *
+ * A SCENE TITLE IS NOT A FILE NAME, and making it into one takes more than
+ * removing separators. Nothing validates `meta.name`, so a title reaches here
+ * however the visitor typed it, and two shapes of it break the load outright:
+ *
+ * `Chair / v2` produced the key `chair / v2.gltf`, and the loader reads a key
+ * containing a separator as a path - the model appeared to sit in a folder
+ * called `chair `, and every asset carrying its own folder fell outside that
+ * scope. Harmless while stored assets were flat, because a folderless key is in
+ * every scope; giving them their folders is what made it bite.
+ *
+ * Replacing the separator with `_` then manufactured the second shape: `./v2`
+ * became `._v2.gltf`, and `modelFormatForFileName` refuses any basename
+ * starting with `._` as a macOS AppleDouble sidecar. So the scene failed to
+ * load from its title alone again, one route over, through the fix for the
+ * first. A leading dot has no other use here either - it is a hidden file on
+ * every platform this ships to, and the title is also spent as a download name.
+ *
+ * Exported because the byte gate has to name the model the same way the loader
+ * will; two spellings of this rule is how the first defect got in.
+ */
+export declare function sceneGltfFileName(title: string | undefined): string;
 /**
  * Reconstructs GLTF and asset files from scene data received from the server.
  *
@@ -16,14 +40,12 @@ import { InputFileOrDirectory, ServerSceneData } from '../types';
  *
  * @example
  * ```typescript
- * // Load scene data from server
- * const sceneData = await ServerCommunicationService.loadScene('scene-123')
+ * const { load } = useLoadModel()
  *
- * // Reconstruct files
+ * // `sceneData` is a ServerSceneData payload, e.g. from a route loader
  * const files = reconstructGltfFiles(sceneData)
  *
- * // Load into the viewer
- * await modelLoader.load(files)
+ * await load({ kind: 'files', files })
  * ```
  */
 export declare function reconstructGltfFiles(data: ServerSceneData): InputFileOrDirectory;

package/use-load-model/utils/resolve-scene-payload.d.ts

@@ -4,3 +4,12 @@ import { ServerSceneData, ServerScenePayload } from '../../../../core/src/index.
  * This keeps payload-shape adaptation in one explicit contract boundary.
  */
 export declare function resolveServerSceneDataContract(payload: ServerScenePayload): ServerSceneData;
+/**
+ * Resolves an embed manifest, which carries a published GLB instead of a glTF
+ * document.
+ *
+ * Same settings normalization as {@link resolveServerSceneDataContract}, minus
+ * the referenced-asset cross-check: a GLB is self-contained, so there are no
+ * external URIs to reconcile against the asset map.
+ */
+export declare function resolvePublishedSceneDataContract(payload: ServerScenePayload): ServerSceneData;