@vincentt-xr/sdk 2.0.0-alpha.7 → 2.0.0-alpha.9

package/dist/assets/cache.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Refcounted, deduplicating asset cache with a byte budget.
+ *
+ * One entry per `key`. The first `acquire` starts the load; concurrent
+ * acquires share the in-flight promise; owners are tracked by id so a
+ * re-render or a StrictMode double mount never double-counts. When the last
+ * owner releases, the value stays cached (unreferenced) until the budget
+ * needs room, `disposeUnreferenced()`, or `disposeAll()`. Only unreferenced
+ * entries are ever evicted, least recently used first, and each value is
+ * disposed exactly once.
+ */
+export type XRAssetDefinition<T> = {
+    /** Cache identity (usually the URL plus any option that changes the bytes). */
+    key: string;
+    /** Produce the value. Honour `signal` to stop a load nobody wants any more. */
+    load: (signal: AbortSignal) => Promise<T>;
+    /** Release GPU / media resources. Called exactly once per loaded value. */
+    dispose?: (value: T) => void;
+    /** Estimated resident bytes (GPU + CPU) for the budget; default 0. */
+    bytes?: (value: T) => number;
+};
+export type XRAssetStatus = "idle" | "loading" | "ready" | "error";
+export type XRAssetEntryInfo = {
+    key: string;
+    status: XRAssetStatus;
+    bytes: number;
+    owners: number;
+    /** `performance.now()` of the last acquire / release. */
+    lastUsed: number;
+    error: Error | null;
+};
+export type XRAssetStats = {
+    assets: number;
+    referencedAssets: number;
+    loadingAssets: number;
+    erroredAssets: number;
+    /** Bytes of every loaded value, referenced or not. */
+    usageBytes: number;
+    /** Bytes held by unreferenced values (what eviction can reclaim). */
+    reclaimableBytes: number;
+    budgetBytes: number;
+    overBudget: boolean;
+    /** Values disposed by `evict()` — budget pressure or an explicit call — since creation. `disposeUnreferenced` / `disposeAll` do not count. */
+    evictions: number;
+    /** Loads served from an existing entry (hit) vs started (miss). */
+    hits: number;
+    misses: number;
+};
+export type XRAssetCacheOptions = {
+    /** Byte budget; eviction of unreferenced values starts above it. Default 256 MiB. `Infinity` disables. */
+    budgetBytes?: number;
+    /** Clock for `lastUsed` (tests). */
+    now?: () => number;
+};
+export declare const DEFAULT_ASSET_BUDGET_BYTES: number;
+export declare class XRAssetCache {
+    private entries;
+    private listeners;
+    private budget;
+    private readonly now;
+    private evictions;
+    private hits;
+    private misses;
+    /** Memoised `getStats()` result; cleared on every change so `useSyncExternalStore` sees a stable snapshot. */
+    private statsSnapshot;
+    constructor(options?: XRAssetCacheOptions);
+    /** Acquire `asset` on behalf of `ownerId`; shares an in-flight or loaded value. */
+    acquire<T>(asset: XRAssetDefinition<T>, ownerId: string): Promise<T>;
+    /** Start loading without holding a reference (warm the cache). */
+    preload<T>(asset: XRAssetDefinition<T>): Promise<T>;
+    /** Drop `ownerId`'s reference. The value stays cached until evicted or disposed. */
+    release(key: string, ownerId: string): void;
+    /** Synchronous read of a loaded value (or `undefined`). Does not take a reference. */
+    get<T>(key: string): T | undefined;
+    has(key: string): boolean;
+    entry(key: string): XRAssetEntryInfo | undefined;
+    list(): XRAssetEntryInfo[];
+    setBudget(bytes: number): void;
+    /**
+     * Dispose unreferenced values, least recently used first, until usage is
+     * within the budget (or `bytesToFree` is reclaimed). Referenced values are
+     * never touched. Returns the bytes reclaimed.
+     */
+    evict(bytesToFree?: number): number;
+    /** Dispose every unreferenced value (route change, scene teardown). Returns the bytes freed. */
+    disposeUnreferenced(): number;
+    /** Dispose everything, referenced or not (app / session shutdown). Owners are forgotten. */
+    disposeAll(): void;
+    /** Current statistics. The object is reused until the cache changes, so it is safe as a store snapshot. */
+    getStats(): XRAssetStats;
+    subscribe(listener: () => void): () => void;
+    private usage;
+    private enforceBudget;
+    private disposeEntry;
+    private notify;
+}
+export declare const createAssetCache: (options?: XRAssetCacheOptions) => XRAssetCache;
+/** The app-wide cache `useXRAsset` uses when no `<XRAssetCacheProvider>` is mounted. */
+export declare const getDefaultAssetCache: () => XRAssetCache;

package/dist/assets/estimate.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from "three";
+/** Resident bytes of a texture (RGBA, mip chain included when generated); 0 for an unloaded image. */
+export declare const estimateTextureBytes: (texture: THREE.Texture | null | undefined) => number;
+/** Bytes of every attribute buffer (and the index) of a geometry. */
+export declare const estimateGeometryBytes: (geometry: THREE.BufferGeometry | null | undefined) => number;
+/** Textures a material references (de-duplicated by the caller). */
+export declare const materialTextures: (material: THREE.Material) => THREE.Texture[];
+/** Sum of the geometries and textures reachable from an object, each counted once. */
+export declare const estimateObjectBytes: (object: THREE.Object3D | null | undefined) => number;
+/** Dispose every geometry, material and texture reachable from an object, each once. */
+export declare const disposeObject3D: (object: THREE.Object3D | null | undefined) => void;

package/dist/assets/gltfLoader.d.ts

@@ -0,0 +1,16 @@
+import { GLTFLoader, GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+/**
+ * The one GLTFLoader setup for every SDK-owned model path. The meshopt decoder
+ * ships inside three (wasm inlined) and fetches nothing. Draco and KTX2 are
+ * deliberately left unconfigured: their decoders would be fetched from a
+ * third-party CDN at view time, so such a model rejects instead.
+ */
+export declare const createGltfLoader: () => GLTFLoader;
+/** Parses GLB / glTF bytes with {@link createGltfLoader}; an unsupported compression rejects with an actionable error. */
+export declare const parseGltf: (buffer: ArrayBuffer, path?: string, label?: string) => Promise<GLTF>;
+/**
+ * A cached `url -> GLTF` loader over {@link fetchAndVerify}: SDK CDN models are
+ * hash-checked, a custom URL passes through. A failed load is evicted so the
+ * next call refetches.
+ */
+export declare const createVerifiedGltfLoader: () => (url: string) => Promise<GLTF>;

package/dist/assets/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_ASSET_BUDGET_BYTES, XRAssetCache, createAssetCache, getDefaultAssetCache, } from './cache';
+export type { XRAssetCacheOptions, XRAssetDefinition, XRAssetEntryInfo, XRAssetStats, XRAssetStatus, } from './cache';
+export { disposeObject3D, estimateGeometryBytes, estimateObjectBytes, estimateTextureBytes, materialTextures, } from './estimate';
+export { defineGltfAsset, defineTextureAsset, defineVideoAsset } from './loaders';
+export type { TextureAssetOptions, VideoAsset, VideoAssetOptions } from './loaders';
+export { XRAssetCacheProvider, useXRAsset, useXRAssetCache, useXRAssetStats } from './react';
+export type { UseXRAssetResult, XRAssetCacheProviderProps } from './react';

package/dist/assets/loaders.d.ts

@@ -0,0 +1,43 @@
+import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { XRAssetDefinition } from './cache';
+import * as THREE from "three";
+/**
+ * An asset's bytes could not be fetched: a network or CORS failure, an HTTP
+ * error status, or a failed integrity check. Decoding failures are not
+ * this (they keep their own error). Internal: lets loaders' callers tell a
+ * download failure from a decode failure.
+ */
+export declare class AssetFetchError extends Error {
+    /** The underlying error, when there was one. */
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export type TextureAssetOptions = {
+    colorSpace?: THREE.ColorSpace;
+    generateMipmaps?: boolean;
+    flipY?: boolean;
+    /** Extra key suffix when the same URL is loaded with different options. */
+    variant?: string;
+};
+/**
+ * An image texture. Loaded with the SDK's verifying fetch (CDN assets are
+ * hash-checked), decoded off the main thread, disposed on eviction.
+ */
+export declare const defineTextureAsset: (url: string, options?: TextureAssetOptions) => XRAssetDefinition<THREE.Texture>;
+/**
+ * A glTF / GLB scene via three's GLTFLoader over the verifying fetch. Loads
+ * meshopt geometry and WebP textures; a Draco or KTX2 model rejects. Disposes
+ * geometries, materials and textures.
+ */
+export declare const defineGltfAsset: (url: string) => XRAssetDefinition<GLTF>;
+export type VideoAssetOptions = {
+    loop?: boolean;
+    muted?: boolean;
+    crossOrigin?: string;
+};
+export type VideoAsset = {
+    video: HTMLVideoElement;
+    texture: THREE.VideoTexture;
+};
+/** A looping, muted video element with its `VideoTexture`. Playback is the consumer's call. */
+export declare const defineVideoAsset: (url: string, options?: VideoAssetOptions) => XRAssetDefinition<VideoAsset>;

package/dist/assets/react.d.ts

@@ -0,0 +1,33 @@
+import { PropsWithChildren } from 'react';
+import { XRAssetCache, XRAssetDefinition, XRAssetStats, XRAssetStatus } from './cache';
+export type XRAssetCacheProviderProps = PropsWithChildren<{
+    /** The cache to use below; default the app-wide cache. */
+    cache?: XRAssetCache;
+    /**
+     * On unmount (a route change away from the AR screen) dispose every value
+     * nobody references any more. Default `true`. Referenced values are never
+     * touched; their owners release them as they unmount.
+     */
+    disposeUnreferencedOnUnmount?: boolean;
+}>;
+/** Scope a cache to a subtree and release unreferenced assets when it unmounts. */
+export declare const XRAssetCacheProvider: ({ cache, disposeUnreferencedOnUnmount, children, }: XRAssetCacheProviderProps) => import("react/jsx-runtime").JSX.Element;
+/** The cache in scope (provider or the app-wide default). */
+export declare const useXRAssetCache: () => XRAssetCache;
+export type UseXRAssetResult<T> = {
+    value: T | null;
+    status: XRAssetStatus;
+    error: Error | null;
+};
+/**
+ * Hold a reference to an asset while mounted. Two components asking for the
+ * same key share one load and one value; the reference is released on
+ * unmount (and when `enabled` turns false), after which the budget decides
+ * when the value is disposed. `asset.key` is the identity: build definitions
+ * with `defineTextureAsset` / `defineGltfAsset` / `defineVideoAsset` or your own.
+ */
+export declare const useXRAsset: <T>(asset: XRAssetDefinition<T> | null | undefined, options?: {
+    enabled?: boolean;
+}) => UseXRAssetResult<T>;
+/** Live cache statistics (re-renders on every cache change). */
+export declare const useXRAssetStats: (cache?: XRAssetCache) => XRAssetStats;