@vctrl/hooks 0.25.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [1.0.0](https://github.com/Vectreal/vectreal-platform/compare/hooks-v0.25.1...hooks-v1.0.0) (2026-09-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* **core:** `OptimizationStats` fields are renamed. `vertices` -> `verticesCount`, `triangles` -> `primitivesCount`, `materials` -> `materialsCount`, `textures` -> `textureBytes`, `meshes` -> `meshBytes`. `texturesCount`, `meshesCount` and `textureResolutions` are unchanged.
+* **publisher:** `@vctrl/core` makes `ModelOptimizer.ensureModelLoaded` private (`hasModel()` answers the same question) and widens `ExportResult` to include `USDZExportResult`, which an exhaustive consumer switch will notice. `@vctrl/hooks` drops `info` from `OptimizationState`; `useOptimizeModel` still returns it, derived.
+* **hooks:** `ShadowsProps` is a plain interface rather than a union discriminated on `type`, so a consumer still passing `type: 'accumulative'` is passing an unknown property.
+* **publisher:** `@vctrl/viewer` reads `ao` off the shadow options directly rather than only when they were tagged accumulative, so a consumer passing `{ enabled: true, ao: true }` gains the ambient-occlusion pass and its per-frame cost.
+* **publisher:** `@vctrl/core` removes `GridProps`, `ShadowType`, `ShadowTypePropBase`, `ContactShadowProps`, `AccumulativeShadowsProps`, `ExportOptions`, `ExportModelOptions`, `ModifiedTextureResources` and `OptimizationStats.nodes`; `exportThreeJSGLB` takes only the object; `optimizeAll` compresses textures unless `textures: false`. `@vctrl/viewer` removes the `gridOptions` prop, `SceneGrid` and `defaultGridOptions`, and renames `defaultShadowOptions` to `defaultShadowsOptions`. `@vctrl/hooks` replaces `load(files)`, `loadFromData` and `loadFromServer` with a single `load(source)`, replaces `isFileLoading` with a `status` union, and removes the `on`/`off` event bus along with `EventTypes`, `EventHandler`, `LoadData`, `SceneLoadOptions` and `SceneDataLoadOptions`.
+
+### Features
+
+* **core,hooks:** the loader reads six formats and resolves every reference through one rule ([#882](https://github.com/Vectreal/vectreal-platform/issues/882)) ([7b52540](https://github.com/Vectreal/vectreal-platform/commit/7b52540233c8258da852be6d3d4374c119e09b16))
+* **scene:** a saved scene stores each asset under the name its glTF uses ([#883](https://github.com/Vectreal/vectreal-platform/issues/883)) ([b0f98cc](https://github.com/Vectreal/vectreal-platform/commit/b0f98cc965d67d8afe77cae1ef432adb54b572ac))
+* **viewer:** play glTF animation clips ([11ff088](https://github.com/Vectreal/vectreal-platform/commit/11ff0880eb32ef0bda03196fe74de4955452d2f1))
+
+
+### Bug Fixes
+
+* **convert:** the page describes the model that is on the stage ([#891](https://github.com/Vectreal/vectreal-platform/issues/891)) ([c2376d9](https://github.com/Vectreal/vectreal-platform/commit/c2376d974f6e7ec16ba6984836fc069059ff2153))
+* **core:** count meshes instead of weighing them ([#783](https://github.com/Vectreal/vectreal-platform/issues/783)) ([9000982](https://github.com/Vectreal/vectreal-platform/commit/900098243213a7e8eb862a77f34ef113c21acb19))
+* **core:** the loader stops claiming it can read USDZ ([#890](https://github.com/Vectreal/vectreal-platform/issues/890)) ([2a3770c](https://github.com/Vectreal/vectreal-platform/commit/2a3770c7039638cf8dee8f80a4da141c00e7a0c3))
+* **embed:** serve embeds the published GLB instead of the editor's assets ([#734](https://github.com/Vectreal/vectreal-platform/issues/734)) ([e5a0bf5](https://github.com/Vectreal/vectreal-platform/commit/e5a0bf5a77d1288abe08303ec5b547416a0ffd32))
+* **hooks:** keep a failed upload from hiding a failed scene load ([5e9676f](https://github.com/Vectreal/vectreal-platform/commit/5e9676f01f61aa53ab74ec3e3fb2d78283fe7045))
+* **publisher:** a failed load costs nothing ([90cf7be](https://github.com/Vectreal/vectreal-platform/commit/90cf7be0f81dbc9e897192c4333f85ec06cf7d25))
+* **publisher:** apply a saved scene once, not on every revalidation ([d903e6d](https://github.com/Vectreal/vectreal-platform/commit/d903e6db95d6876f1c369042fffc8cb5dd6ae860))
+* **publisher:** one answer to which scene is open ([cbcc863](https://github.com/Vectreal/vectreal-platform/commit/cbcc8632e8137e9aba446293367d6d90f1796146))
+* signup return path, search leak, field surfaces and quick wins ([#897](https://github.com/Vectreal/vectreal-platform/issues/897)) ([c3111d8](https://github.com/Vectreal/vectreal-platform/commit/c3111d84b3980d1daf0b7aaa3f4169693051c853))
+
+
+### Code Refactoring
+
+* **core:** name every metric field by its unit ([#784](https://github.com/Vectreal/vectreal-platform/issues/784)) ([2f7c7d3](https://github.com/Vectreal/vectreal-platform/commit/2f7c7d377a7bfb51199663ad1648895867ebc447))
+* **publisher:** leave each write to the one place that owns it ([0b04d08](https://github.com/Vectreal/vectreal-platform/commit/0b04d08075d455d3a963be1553d2f2e52d5c61dc))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @vctrl/core bumped to 1.0.0
+
+## [0.25.1](https://github.com/Vectreal/vectreal-platform/compare/hooks-v0.25.0...hooks-v0.25.1) (2026-08-08)
+
+
+### Bug Fixes
+
+* **core:** keep the pristine baseline when syncing the worker's output ([a2e5654](https://github.com/Vectreal/vectreal-platform/commit/a2e5654f6a2acd8dc95cb2e9dace3c32436fc826))
+* **publisher:** stale scene state across navigation and nonsensical optimization stats ([4152ab1](https://github.com/Vectreal/vectreal-platform/commit/4152ab146770f86930a53b892900978a163ae167))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @vctrl/core bumped to 0.25.1
+
 ## [0.25.0](https://github.com/Vectreal/vectreal-platform/compare/hooks-v0.24.1...hooks-v0.25.0) (2026-08-04)
 
 

package/README.md

@@ -20,7 +20,7 @@ pnpm add @vctrl/hooks
 
 | Hook               | Import path                       | Description                                                                     |
 | ------------------ | --------------------------------- | ------------------------------------------------------------------------------- |
-| `useLoadModel`     | `@vctrl/hooks/use-load-model`     | Load and parse GLTF, GLB, and USDZ files from file lists or dropped directories |
+| `useLoadModel`     | `@vctrl/hooks/use-load-model`     | Load and parse every format `@vctrl/core/model-formats` marks importable, from a file list, a dropped folder or a saved scene. `supportedFileTypes` on the return value is that list |
 | `useOptimizeModel` | `@vctrl/hooks/use-optimize-model` | Run glTF-Transform optimizations on loaded models                               |
 | `useExportModel`   | `@vctrl/hooks/use-export-model`   | Export the current scene to GLB or glTF                                         |
 
@@ -31,18 +31,19 @@ pnpm add @vctrl/hooks
 Loads 3D files and exposes the parsed Three.js `Object3D` scene.
 
 ```tsx
-import { ModelProvider, useLoadModel } from '@vctrl/hooks/use-load-model'
+import { useLoadModel } from '@vctrl/hooks/use-load-model'
 
 function Uploader() {
-	const { load, file, isFileLoading } = useLoadModel()
+	const { load, status, file, error } = useLoadModel()
 
 	const handleDrop = (e: React.DragEvent) => {
 		e.preventDefault()
-		void load(Array.from(e.dataTransfer.files))
+		void load({ kind: 'files', files: Array.from(e.dataTransfer.files) })
 	}
 
-	if (isFileLoading) return <p>Loading...</p>
-	if (file?.model) return <p>Model loaded: {file.name}</p>
+	if (status === 'loading') return <p>Loading...</p>
+	if (status === 'error') return <p>{error.message}</p>
+	if (status === 'ready') return <p>Model loaded: {file.name}</p>
 
 	return (
 		<div onDrop={handleDrop} onDragOver={(e) => e.preventDefault()}>
@@ -50,16 +51,70 @@ function Uploader() {
 		</div>
 	)
 }
+```
 
-export default function App() {
-	return (
-		<ModelProvider>
-			<Uploader />
-		</ModelProvider>
-	)
-}
+`useLoadModel` holds its own model. To share one across a tree, mount
+`ModelProvider` and read it with `useModelContext`; see below.
+
+### One entry point, one state
+
+`load` handles every way a model arrives, and the hook's state is a
+discriminated union on `status`. `status === 'ready'` and a non-null `file` are
+the same fact, so there is no separate loading flag to fall out of step with
+what is on screen.
+
+`load` never rejects. It resolves to the terminal state, and for every source
+but `files` that is also the state you are rendering from.
+
+A rejected `files` load is the exception, on purpose: 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 there is nothing to protect, and the state is the
+error as usual. Branch on what `load` returns to react to an upload that did
+not take; `reset()` is how you clear a model deliberately.
+
+A newer `load` supersedes an older one, so a slow response can never overwrite
+the load that replaced it. The superseded call still resolves, with the state it
+would have produced, so a caller acting on the resolved value rather than on the
+rendered state asks `stillCurrent()` before writing anything down - and asks it
+again after any further await, because a drop can land during an encode as
+easily as during a parse. `reset()` claims a token too, so a load in flight when
+the user clears the model also reports `false`.
+
+Resolving is not the same moment as reaching the screen. With an optimizer
+attached, the loaders publish the parsed model first and then await its ingest,
+so `load` resolves one ingest after the viewer changed. A caller that adopts on
+the resolved value therefore keeps printing the previous model's name and byte
+figures around the new one for as long as that ingest takes, and
+`stillCurrent()` cannot close the window, because during it the new load
+genuinely is the current one. Pass `onPublish` to adopt when the stage changes
+instead:
+
+```tsx
+await load({ kind: 'files', files }, {
+	onPublish: (published) => adopt(published)
+})
 ```
 
+It receives the same `LoadOutcome` the promise resolves to, carrying the same
+`stillCurrent()`. A load superseded before it published never calls it at all,
+so there is nothing to re-check on entry; ask again only after an await of your
+own, for the reason above. Where there is no ingest to wait on (no optimizer
+attached, or a scene source that has none), publishing and resolving are the
+same moment and `onPublish` gains nothing.
+
+### Sources
+
+| `kind`       | Fields                                                        | Use                                                                                              |
+| ------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `files`      | `files: (File \| FileSystemDirectoryHandle)[]`                 | A user upload: a single model, or a bundle with the siblings it refers to. A dropped folder arrives here as plain `File`s; the handle branch is for a caller that opened `showDirectoryPicker()` itself |
+| `scene-data` | `sceneData: ServerScenePayload`, `sceneId?`, `parseMode?`      | A payload you already hold. Binary assets may be referenced rather than inlined; the loader fetches them |
+| `server`     | `sceneId: string`, `serverOptions?`, `parseMode?`              | Fetch a scene from an API endpoint by id                                                         |
+
+`parseMode: 'direct'` parses the glTF JSON with its assets in memory and skips
+the optimizer: the read-only fast path for viewers. The default reconstructs
+files so the optimizer can ingest exactly what the viewer renders.
+
 ### Context and direct usage
 
 `useLoadModel` can be used in two ways:
@@ -69,52 +124,27 @@ export default function App() {
 
 ### Return values
 
-| Value                      | Type                                 | Description                                                 |
-| -------------------------- | ------------------------------------ | ----------------------------------------------------------- |
-| `file`                     | `ModelFile \| null`                  | Loaded file metadata and Three.js model                     |
-| `isFileLoading`            | `boolean`                            | True while loading and parsing                              |
-| `progress`                 | `number`                             | Progress value from 0 to 100                                |
-| `load(filesOrDirectories)` | `Promise<void>`                      | Load files or dropped `FileSystemDirectoryHandle` entries   |
-| `loadFromData(options)`    | `Promise<SceneLoadResult>`           | Load already-resolved server scene payload                  |
-| `loadFromServer(options)`  | `Promise<SceneLoadResult>`           | Fetch and load scene from an API endpoint                   |
-| `reset`                    | `() => void`                         | Clear the current model                                     |
-| `on` / `off`               | Event helpers                        | Subscribe and unsubscribe to loader lifecycle events        |
-| `optimizer`                | `OptimizerIntegrationReturn \| null` | Populated when the hook is called with `useOptimizeModel()` |
-
-### `useLoadModel` events
-
-`on` and `off` support these typed events:
-
-| Event                  | Payload             |
-| ---------------------- | ------------------- |
-| `multiple-models`      | `File[]`            |
-| `not-loaded-files`     | `File[]`            |
-| `load-start`           | `null`              |
-| `load-progress`        | `number`            |
-| `load-complete`        | `ModelFile \| null` |
-| `load-reset`           | `null`              |
-| `load-error`           | `Error \| unknown`  |
-| `server-load-start`    | `string`            |
-| `server-load-complete` | `SceneLoadResult`   |
-| `server-load-error`    | `Error \| unknown`  |
-
-### Scene loading option types
-
-`loadFromServer(options)` uses:
-
-| Field           | Type            | Description                                   |
-| --------------- | --------------- | --------------------------------------------- |
-| `sceneId`       | `string`        | Scene identifier to fetch                     |
-| `serverOptions` | `ServerOptions` | Endpoint, auth, and header configuration      |
-| `applySettings` | `boolean`       | Whether scene settings are applied after load |
-
-`loadFromData(options)` uses:
-
-| Field           | Type                  | Description                                                    |
-| --------------- | --------------------- | -------------------------------------------------------------- |
-| `sceneId`       | `string \| undefined` | Optional scene identifier                                      |
-| `sceneData`     | `ServerSceneData`     | Already-resolved payload containing glTF, settings, and assets |
-| `applySettings` | `boolean`             | Whether scene settings are applied after load                  |
+| Value          | Type                                              | Description                                                       |
+| -------------- | ------------------------------------------------- | ----------------------------------------------------------------- |
+| `status`       | `'empty' \| 'loading' \| 'ready' \| 'error'`      | The load, as one value                                            |
+| `file`         | `ModelFile \| null`                               | Loaded file metadata and Three.js model. Non-null exactly when `status` is `'ready'` |
+| `error`        | `StructuredLoadError \| null`                     | Non-null exactly when `status` is `'error'`                       |
+| `sceneData`    | `ServerSceneData \| undefined`                    | The resolved payload, for scene sources                           |
+| `progress`     | `number`                                          | Progress value from 0 to 100                                      |
+| `source`       | `'files' \| 'scene-data' \| 'server' \| null`     | What the current state came from                                  |
+| `load(source, options?)` | `Promise<LoadOutcome>`                  | Load a model; resolves to the terminal state plus `stillCurrent()`. `options.onPublish` fires earlier, when the model reaches the screen |
+| `supportedFileTypes` | `ModelFileTypes[]`                          | Every format the loader accepts, from `@vctrl/core/model-formats` |
+| `reset`        | `() => void`                                      | Clear the current model and retire any load in flight             |
+| `optimizer`    | `OptimizerIntegrationReturn<true> \| null`        | Populated when the hook is called with `useOptimizeModel()`       |
+
+### Error codes
+
+`error.code` is one of `unsupported_format`, `multiple_models`,
+`binary_load_failed`, `gltf_load_failed`, `missing_assets`,
+`server_load_failed`, `not_found`, `quota_exceeded`, `unknown`. Optimizer
+ingest is deliberately not among them: the model is already on screen by then,
+so a failure there costs the optimize step and is reported on
+`optimizer.error`.
 
 ---
 
@@ -200,20 +230,28 @@ function ExportButton({ file }: { file: ModelFile | null }) {
 
 ### Methods
 
-| Method                                                         | Description                                                         |
-| -------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `handleThreeGltfExport(file, binary)`                          | Export a loaded Three.js model to `.glb` or a zipped `.gltf` bundle |
-| `handleDocumentGltfExport(document, file, binary?, download?)` | Export from a glTF-Transform `Document`                             |
+| Method                                                         | Description                                                            |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `handleThreeGltfExport(file, binary)`                          | Export a loaded Three.js model to `.glb` or a zipped `.gltf` bundle    |
+| `handleThreeUsdzExport(file)`                                  | Export a loaded Three.js model to `.usdz` for AR QuickLook             |
+| `handleDocumentGltfExport(document, file, binary?, download?)` | Export from a glTF-Transform `Document`                                |
+| `handleDocumentGlbDracoExport(document, file)`                 | Export a `Document` to `.glb` with Draco geometry compression          |
 
-`binary = true` writes `.glb`; `binary = false` writes a zipped `.gltf` package.
+`binary = true` writes `.glb`; `binary = false` writes a zipped `.gltf` package. Pass
+`download = false` to `handleDocumentGltfExport` to get the `GLTFExportResult` back
+instead of saving a file.
 
 ---
 
 ## Additional exports
 
-- `reconstructGltfFiles` from `@vctrl/hooks`
+- `reconstructGltfFiles` and `createBrowserTextureEncoder` from `@vctrl/hooks`
 - `ModelProvider` and `useModelContext` from `@vctrl/hooks/use-load-model`
-- Shared types such as `ModelFile`, `SceneLoadResult`, and `ServerSceneData`
+- Shared types such as `ModelFile`, `SceneLoadResult`, `ServerSceneData`, and `OptimizerIntegrationReturn`
+
+`createBrowserTextureEncoder()` returns the `OffscreenCanvas` encoder the hook injects
+into `texturesOptimization`. Pass it as `ModelOptimizer#compressTextures`'s
+`encoder` option when driving the optimizer directly.
 
 ---
 
@@ -222,7 +260,12 @@ function ExportButton({ file }: { file: ModelFile | null }) {
 | Package | Version        |
 | ------- | -------------- |
 | `react` | `^18 \|\| ^19` |
-| `three` | `^0.177`       |
+| `three` | see below      |
+
+Install `three` yourself and declare it explicitly in your own `package.json`, so your
+project resolves exactly one copy: Three.js uses global singletons internally and
+duplicate instances produce subtle rendering bugs. Let your package manager resolve the
+version against the declared peer range rather than pinning one from this document.
 
 ---
 

package/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./use-load-model-CZCi6bPM.cjs"),t=require("./use-export-model-CORoAKbf.cjs"),n=require("./use-optimize-model-Fwew6qD8.cjs");exports.createBrowserTextureEncoder=n.n,exports.reconstructGltfFiles=e.r,exports.useExportModel=t.t,exports.useLoadModel=e.t,exports.useOptimizeModel=n.t;

package/index.d.ts

@@ -2,4 +2,5 @@ export { default as useLoadModel } from './use-load-model/use-load-model';
 export { default as useExportModel } from './use-export-model/use-export-model';
 export { default as useOptimizeModel } from './use-optimize-model/use-optimize-model';
 export { reconstructGltfFiles } from './use-load-model/utils/reconstruct-files';
-export type { EventTypes, EventHandler, ModelFile, LoadData, UseLoadModelReturn, SceneDataLoadOptions, SceneLoadOptions, ServerSceneData, SceneLoadResult } from './use-load-model/types';
+export { createBrowserTextureEncoder } from './use-optimize-model/utils';
+export type { LoadOptions, LoadOutcome, ModelFile, ModelSource, ModelSourceKind, ModelState, OptimizerIntegrationReturn, UseLoadModelReturn, ServerSceneData, SceneLoadResult } from './use-load-model/types';

package/index.es.js

@@ -1,4 +1,4 @@
-import { r as e, t } from "./use-load-model-C88r8-HE.js";
-import { t as n } from "./use-export-model-efFsSWe-.js";
-import { t as r } from "./use-optimize-model-D16-4Zwm.js";
-export { e as reconstructGltfFiles, n as useExportModel, t as useLoadModel, r as useOptimizeModel };
+import { r as e, t } from "./use-load-model-CRDVzrPC.js";
+import { t as n } from "./use-export-model-DXesLypI.js";
+import { n as r, t as i } from "./use-optimize-model-sNXkORNg.js";
+export { r as createBrowserTextureEncoder, e as reconstructGltfFiles, n as useExportModel, t as useLoadModel, i as useOptimizeModel };

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.25.0",
+  "version": "1.0.0",
   "name": "@vctrl/hooks",
   "description": "vctrl/hooks is a React hooks package designed to simplify 3D model loading and management within React applications. It's part of the vectreal-core ecosystem and is primarily used in the vctrl/viewer React component and the official website application.",
   "bugs": {
@@ -29,40 +29,48 @@
   },
   "license": "AGPL-3.0-only",
   "types": "./index.d.ts",
-  "main": "./index.cjs.js",
+  "main": "./index.cjs",
   "module": "./index.es.js",
   "type": "module",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "directory": "../../build/packages/vctrl/hooks"
   },
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "import": "./index.es.js",
-      "require": "./index.cjs.js"
+      "require": "./index.cjs"
     },
     "./use-load-model": {
       "types": "./use-load-model/index.d.ts",
       "import": "./use-load-model.es.js",
-      "require": "./use-load-model.cjs.js"
+      "require": "./use-load-model.cjs"
     },
     "./use-export-model": {
       "types": "./use-export-model/index.d.ts",
       "import": "./use-export-model.es.js",
-      "require": "./use-export-model.cjs.js"
+      "require": "./use-export-model.cjs"
     },
     "./use-optimize-model": {
       "types": "./use-optimize-model/index.d.ts",
       "import": "./use-optimize-model.es.js",
-      "require": "./use-optimize-model.cjs.js"
+      "require": "./use-optimize-model.cjs"
     }
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "three": "^0.177.0"
+    "three": "^0.185.1"
   },
   "dependencies": {
-    "@vctrl/core": "^0.25.0",
-    "file-saver": "^2.0.5"
+    "@gltf-transform/core": "^4.4.2",
+    "file-saver": "^2.0.5",
+    "@vctrl/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@nx/vite": "23.1.1",
+    "@vitejs/plugin-react": "^6.0.5",
+    "vite": "^8.2.1",
+    "vite-plugin-dts": "5.0.3"
   }
 }

package/{chunk-CMqjfN_6.cjs → rolldown-runtime-BocRIvOZ.cjs}

@@ -1 +1 @@
-var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}});
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,s)=>(s=n==null?{}:e(i(n)),o(r||!n||!n.__esModule||!a.call(n,`default`)?t(s,`default`,{value:n,enumerable:!0}):s,n));Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}});

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

@@ -9,7 +9,7 @@ import { ModelFile } from '../use-load-model';
  */
 declare const useExportModel: (onSaved?: () => void, onError?: (error: Error) => void) => {
     handleThreeGltfExport: (file: ModelFile | null, binary: boolean) => Promise<void>;
-    handleDocumentGltfExport: (jsonDocument: Document, file: ModelFile | null, binary?: boolean, download?: boolean) => Promise<import('../../../core/src/model-exporter/index.ts').GLTFExportResult | undefined>;
+    handleDocumentGltfExport: (jsonDocument: Document, file: ModelFile | null, binary?: boolean, download?: boolean) => Promise<import('../../../core/src/index.ts').GLTFExportResult | undefined>;
     handleThreeUsdzExport: (file: ModelFile | null) => Promise<void>;
     handleDocumentGlbDracoExport: (jsonDocument: Document, file: ModelFile | null) => Promise<void>;
 };

package/use-export-model-CORoAKbf.cjs

@@ -0,0 +1 @@
+const e=require("./rolldown-runtime-BocRIvOZ.cjs");let t=require("react"),n=require("@vctrl/core/model-exporter"),r=require("file-saver");r=e.t(r,1);var i=(e,i)=>{let a=(0,t.useRef)(new n.ModelExporter),o=(0,t.useCallback)(async(t,n)=>{let o=t?.model;if(!o){console.error(`Scene not initialized`);return}try{let i=a.current,s=t.name.replace(/\.[^/.]+$/,``);if(n){let e=await i.exportThreeJSGLB(o);if(!(e.data instanceof Uint8Array))throw Error(`Expected GLB export to return Uint8Array`);r.default.saveAs(new Blob([new Uint8Array(e.data)]),`${s}.glb`)}else{let e=await i.exportThreeJSGLTF(o),t=await i.createZIPArchive(e,s);r.default.saveAs(new Blob([new Uint8Array(t)]),`${s}.zip`)}e&&e()}catch(e){console.error(`Export failed:`,e),i&&i(e)}},[e,i]),s=(0,t.useCallback)(async t=>{let n=t?.model;if(!n){console.error(`Scene not initialized`);return}try{let i=a.current,o=t.name.replace(/\.[^/.]+$/,``),s=await i.exportThreeJSUSDZ(n);r.default.saveAs(new Blob([new Uint8Array(s.data)]),`${o}.usdz`),e&&e()}catch(e){console.error(`USDZ export failed:`,e),i&&i(e)}},[e,i]),c=(0,t.useCallback)(async(t,n)=>{try{let i=a.current,o=n?.name.replace(/\.[^/.]+$/,``)||`model`,s=await i.exportDocumentGLBDraco(t);r.default.saveAs(new Blob([new Uint8Array(s.data)]),`${o}.glb`),e&&e()}catch(e){console.error(`Draco GLB export failed:`,e),i&&i(e)}},[e,i]);return{handleThreeGltfExport:o,handleDocumentGltfExport:(0,t.useCallback)(async function(t,n,o=!1,s=!0){try{let i=a.current,c=n?.name.replace(/\.[^/.]+$/,``)||`model`;if(o){let e=await i.exportDocumentGLB(t);r.default.saveAs(new Blob([new Uint8Array(e.data)]),`${c}.glb`)}else{let e=await i.exportDocumentGLTF(t);if(!s)return e;let n=await i.createZIPArchive(e,c);r.default.saveAs(new Blob([new Uint8Array(n)]),`${c}.zip`)}e&&e()}catch(e){console.error(`Export failed:`,e),i&&i(e)}},[i,e]),handleThreeUsdzExport:s,handleDocumentGlbDracoExport:c}};Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return i}});

package/{use-export-model-efFsSWe-.js → use-export-model-DXesLypI.js}

@@ -12,7 +12,7 @@ var i = (i, a) => {
 		try {
 			let a = o.current, s = e.name.replace(/\.[^/.]+$/, "");
 			if (t) {
-				let e = await a.exportThreeJSGLB(n, {});
+				let e = await a.exportThreeJSGLB(n);
 				if (!(e.data instanceof Uint8Array)) throw Error("Expected GLB export to return Uint8Array");
 				r.saveAs(new Blob([new Uint8Array(e.data)]), `${s}.glb`);
 			} else {

package/use-export-model.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./use-export-model-CORoAKbf.cjs");exports.useExportModel=e.t;

package/use-export-model.es.js

@@ -1,2 +1,2 @@
-import { t as e } from "./use-export-model-efFsSWe-.js";
+import { t as e } from "./use-export-model-DXesLypI.js";
 export { e as useExportModel };

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

@@ -1,4 +1,9 @@
 import { StructuredLoadError } from './types';
+/**
+ * A failure that already describes itself. The loaders throw these deliberately,
+ * so normalizing one again would flatten its code and message into "unknown".
+ */
+export declare const isStructuredLoadError: (error: unknown) => error is StructuredLoadError;
 export declare const createStructuredLoadError: ({ code, message, recoverable, source, cause, context }: StructuredLoadError) => StructuredLoadError;
 export declare const toErrorMessage: (error: unknown) => string;
 export declare const normalizeLocalLoadError: (error: unknown, code: StructuredLoadError["code"], context?: Record<string, unknown>) => StructuredLoadError;

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

@@ -1,12 +1,11 @@
-import { ModelFileTypes, ModelLoader } from '../../../core/src/model-loader/index.ts';
-import { default as React } from 'react';
-import { Action, ModelFile } from './types';
-import { useOptimizeModel } from '../use-optimize-model';
-type Optimizer = ReturnType<typeof useOptimizeModel> | undefined;
-type Dispatch = React.Dispatch<Action>;
-export declare const loadBinaryModel: (file: File, fileType: ModelFileTypes, modelLoader: ModelLoader, optimizer: Optimizer, dispatch: Dispatch) => Promise<ModelFile | null>;
-export declare const loadGltfModel: (gltfFile: File, otherFiles: File[], modelLoader: ModelLoader, optimizer: Optimizer, dispatch: Dispatch, calculateReferencedBytesFromFiles: (gltfFile: File, otherFiles: File[]) => Promise<{
-    sourcePackageBytes: number;
-    textureBytes: number;
-}>) => Promise<ModelFile | null>;
-export {};
+import { InputFileOrDirectory, LoadedModel } from './types';
+import { LoadContext } from './load-context';
+/**
+ * Loads a model the user picked: a single file, or a bundle with the siblings
+ * it refers to.
+ *
+ * Throws a `StructuredLoadError` for every rejection, including "nothing usable
+ * in here" and "more than one model in here". Those used to be silent returns,
+ * which left the caller waiting on a load that would never finish.
+ */
+export declare const loadModelFromFiles: (filesOrDirectories: InputFileOrDirectory, ctx: LoadContext) => Promise<LoadedModel>;

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

@@ -1,5 +1,5 @@
 export { default as useLoadModel } from './use-load-model';
-export { type EventHandler, type EventTypes, type InputFileOrDirectory, type LoadData, type ModelFile, type SceneDataLoadOptions, type SceneLoadOptions, type SceneLoadResult, type StructuredLoadError, type UseLoadModelReturn, type ViewerLoadErrorCode, type ServerSceneData } from './types';
+export { type InputFileOrDirectory, type LoadedModel, type LoadOptions, type LoadOutcome, type ModelFile, type ModelSource, type ModelSourceKind, type ModelState, type OptimizerIntegrationReturn, type SceneLoadResult, type ServerSceneData, type StructuredLoadError, type UseLoadModelReturn, type ViewerLoadErrorCode } from './types';
 export { reconstructGltfFiles } from './utils/reconstruct-files';
 export { fetchManifestAssetData, type FetchManifestAssetsOptions } from './utils/fetch-manifest-assets';
 export * from './model-context';

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

@@ -0,0 +1,17 @@
+import { LoadedModel } from './types';
+import { useOptimizeModel } from '../use-optimize-model';
+import { ModelLoader } from '../../../core/src/model-loader/index.ts';
+export type Optimizer = ReturnType<typeof useOptimizeModel> | undefined;
+/**
+ * What every per-source loader needs, and nothing else.
+ *
+ * `publish` exists because a load has two useful moments: the model is parsed
+ * and can be rendered, and the optimizer has finished ingesting it. Publishing
+ * the first means the viewer never waits on the second.
+ */
+export interface LoadContext {
+    modelLoader: ModelLoader;
+    optimizer: Optimizer;
+    publish: (loaded: LoadedModel) => void;
+    onProgress: (progress: number) => void;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Optimizer ingest is not part of "is the model on screen".
+ *
+ * The model is always published before this runs, so a failure here must not
+ * turn a visible scene into an error state. It costs the optimize step, which
+ * `optimizer.error` and `optimizer.isPreparing` already report.
+ */
+export declare const ingestIntoOptimizer: (ingest: () => Promise<void>, fallback?: () => Promise<void>) => Promise<void>;

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

@@ -1,6 +1,5 @@
 import { ModelLoader } from '../../../core/src/model-loader/index.ts';
-import { default as React } from 'react';
-import { Action, ModelFile, OptimizerIntegrationReturn } from './types';
+import { ModelFile, OptimizerIntegrationReturn } from './types';
 import { useOptimizeModel } from '../use-optimize-model';
 /**
  * Integrates the optimizer into the model loading process.
@@ -9,8 +8,8 @@ import { useOptimizeModel } from '../use-optimize-model';
  * 1. Runs an optional optimization function
  * 2. Exports the optimized model as GLB
  * 3. Reloads it into Three.js
- * 4. Updates the model state
+ * 4. Swaps it into the loaded model, leaving the load state itself untouched
  *
  * Returns `null` when no optimizer instance is provided.
  */
-export declare function useOptimizerIntegration(instance: ReturnType<typeof useOptimizeModel> | undefined, dispatch: React.Dispatch<Action>, file: ModelFile | null, modelLoader: ModelLoader): OptimizerIntegrationReturn<boolean>;
+export declare function useOptimizerIntegration(instance: ReturnType<typeof useOptimizeModel> | undefined, replaceModel: (file: ModelFile) => void, file: ModelFile | null, modelLoader: ModelLoader): OptimizerIntegrationReturn<boolean>;

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

@@ -0,0 +1,15 @@
+import { LoadedModel, ModelSource } from './types';
+import { LoadContext } from './load-context';
+type SceneDataSource = Extract<ModelSource, {
+    kind: 'scene-data';
+}>;
+type ServerSource = Extract<ModelSource, {
+    kind: 'server';
+}>;
+export declare const loadModelFromSceneData: (source: SceneDataSource, ctx: LoadContext, assetHeaders?: HeadersInit) => Promise<LoadedModel>;
+/**
+ * Fetches a scene by id and loads it. Prefers the manifest endpoint and falls
+ * back to the legacy form-post contract for scenes the manifest cannot serve.
+ */
+export declare const loadModelFromServer: (source: ServerSource, ctx: LoadContext) => Promise<LoadedModel>;
+export {};

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

@@ -1,19 +1,19 @@
-import { Action, LoadData } from './types';
+import { ModelFileTypes } from '../../../core/src/model-loader/index.ts';
+import { LoadedModel, ModelSourceKind, ModelState, StructuredLoadError } from './types';
 /**
- * Initial state for the useReadModelFiles hook
+ * Model formats the loader accepts, reported on `useLoadModel`'s return.
  *
- * @property file - Currently loaded file
- * @property isFileLoading - Flag indicating if a file is currently being loaded
- * @property progress - Current loading progress (0-100)
- * @property supportedFileTypes - List of supported file types
+ * It was a hand-maintained array restating the three ids - one of the nine
+ * independent statements of a set nothing kept in agreement. It is now read
+ * from the owner. The export stays because it is part of `@vctrl/hooks`'
+ * published return type, and no app code reads it.
  */
-export declare const initialState: LoadData;
+export declare const supportedFileTypes: ModelFileTypes[];
 /**
- * Reducer function for the useReadModelFiles hook
- *
- * @param state - The current state of the reducer
- * @param action - The action to be performed
- * @returns The updated state
+ * The four states a load can be in. Building them here rather than spreading
+ * partial updates is what keeps `status`, `file` and `error` from drifting apart.
  */
-declare function reducer(state: LoadData, action: Action): LoadData;
-export default reducer;
+export declare const emptyModelState: ModelState;
+export declare const loadingModelState: (source: ModelSourceKind, progress?: number) => ModelState;
+export declare const readyModelState: (source: ModelSourceKind, loaded: LoadedModel) => ModelState;
+export declare const errorModelState: (source: ModelSourceKind, error: StructuredLoadError) => ModelState;