@voluma/vlam 0.2.3 → 0.3.0

package/dist/{load-scene.d.ts → load-splat-data.d.ts}

@@ -1,8 +1,8 @@
 import type { SplatData } from './splat-data';
-import type { SplatFormat, SplatFileLoadOptions, SplatInputOptions } from './loading';
-export type { SplatFileLoadOptions };
-/** Options for {@link loadScene}. */
-export interface SplatLoadOptions extends SplatInputOptions {
+import type { SplatFormat, SplatDataFileLoadOptions, SplatInputOptions } from './loading';
+export type { SplatDataFileLoadOptions };
+/** Options for {@link loadSplatData}. */
+export interface SplatDataLoadOptions extends SplatInputOptions {
     /** Parser selection; URL extension detection is used only for `auto`. */
     format?: SplatFormat;
 }
@@ -12,10 +12,10 @@ export interface SplatLoadOptions extends SplatInputOptions {
  * even multi-million-splat decodes never block the main thread. The
  * decoded arrays are transferred back, not copied.
  *
- * One-shot convenience over {@link ChunkLoader}; use `ChunkLoader`
+ * Whole-file convenience over {@link ChunkLoader}; use `ChunkLoader`
  * directly when loading many chunks or when cancellation is needed.
  *
- * @param input - Scene URL; its extension selects the parser unless an
+ * @param input - Capture URL; its extension selects the parser unless an
  * explicit `format` option is provided.
  * @returns The decoded splat data, ready for {@link SplatMesh}.
  * @throws Rejects only with `SplatLoadError` (resolve, fetch or decode
@@ -23,10 +23,11 @@ export interface SplatLoadOptions extends SplatInputOptions {
  * when `options.signal` fires.
  *
  * @example
- * const splats = new SplatMesh(await loadScene('/scene.sog'));
- * scene.add(splats);
+ * import { SplatMesh } from '@voluma/vlam';
+ * import { loadSplatData } from '@voluma/vlam/loaders';
+ * const splats = new SplatMesh(await loadSplatData('/scene.sog'));
  */
-export declare function loadScene(input: string | URL, options?: SplatLoadOptions): Promise<SplatData>;
+export declare function loadSplatData(input: string | URL, options?: SplatDataLoadOptions): Promise<SplatData>;
 /**
  * Decodes a local splat file - from a `<input type="file">` or a drag-and-drop
  * - in a Web Worker, without uploading it anywhere. The file's bytes are read
@@ -34,7 +35,7 @@ export declare function loadScene(input: string | URL, options?: SplatLoadOption
  *
  * Only self-contained files are supported: `.ply`, `.spz`, `.splat`, `.ksplat`
  * and bundled `.sog`. An unbundled SOG directory needs sibling fetches, so it
- * must be served over HTTP and loaded with {@link loadScene}.
+ * must be served over HTTP and loaded with {@link loadSplatData}.
  *
  * @param file - The file; its name selects the parser unless an explicit
  * `format` option is provided.
@@ -44,7 +45,8 @@ export declare function loadScene(input: string | URL, options?: SplatLoadOption
  * `options.signal` fires.
  *
  * @example
- * const splats = new SplatMesh(await loadSceneFile(event.dataTransfer.files[0]));
- * scene.add(splats);
+ * import { SplatMesh } from '@voluma/vlam';
+ * import { loadSplatDataFile } from '@voluma/vlam/loaders';
+ * const splats = new SplatMesh(await loadSplatDataFile(event.dataTransfer.files[0]));
  */
-export declare function loadSceneFile(file: File, options?: SplatFileLoadOptions): Promise<SplatData>;
+export declare function loadSplatDataFile(file: File, options?: SplatDataFileLoadOptions): Promise<SplatData>;

package/dist/loaders.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@voluma/vlam/loaders` - whole-file splat decode and the shared chunk worker.
+ *
+ * {@link loadSplatData} / {@link loadSplatDataFile} decode a whole file into
+ * {@link SplatData} for {@link SplatMesh}. {@link ChunkLoader} is the
+ * multiplexed worker behind those helpers and behind streamed chunk fetches.
+ *
+ * Format-specific parsers stay on `@voluma/vlam/formats/*`; this entry loads
+ * them on demand through the worker.
+ *
+ * @module loaders
+ */
+export { loadSplatData, loadSplatDataFile, type SplatDataLoadOptions, type SplatDataFileLoadOptions, } from './load-splat-data';
+export { ChunkLoader } from './chunk-loader';
+export { SplatLoadError, isAbortError, type SplatProgressCallback, type SplatFormat, type SplatDataFormat, type StreamedSplatFormat, type SplatRequestOptions, type SplatLoadPhase, type SplatInputOptions, type ChunkFileFormat, } from './loading';

package/dist/loaders.js

@@ -0,0 +1,26 @@
+import { C as t } from "./chunk-loader-DlNwggfG.js";
+import { S as d, i as f } from "./loading-wLo8vRbA.js";
+async function l(a, r = {}) {
+  const o = new t();
+  try {
+    return await o.load(a instanceof URL ? a.href : a, r);
+  } finally {
+    o.dispose();
+  }
+}
+async function n(a, r = {}) {
+  const o = new t();
+  try {
+    return await o.loadFile(a, r);
+  } finally {
+    o.dispose();
+  }
+}
+export {
+  t as ChunkLoader,
+  d as SplatLoadError,
+  f as isAbortError,
+  l as loadSplatData,
+  n as loadSplatDataFile
+};
+//# sourceMappingURL=loaders.js.map

package/dist/loaders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaders.js","sources":["../src/lib/load-splat-data.ts"],"sourcesContent":["import type { SplatData } from './splat-data';\nimport { ChunkLoader } from './chunk-loader';\nimport type { SplatFormat, SplatDataFileLoadOptions, SplatInputOptions } from './loading';\n\nexport type { SplatDataFileLoadOptions };\n\n/** Options for {@link loadSplatData}. */\nexport interface SplatDataLoadOptions extends SplatInputOptions {\n  /** Parser selection; URL extension detection is used only for `auto`. */\n  format?: SplatFormat;\n}\n\n/**\n * Fetches and decodes a splat scene (`.sog`, `.ply`, `.spz`, `.splat` or\n * `.ksplat`) in a Web Worker, so\n * even multi-million-splat decodes never block the main thread. The\n * decoded arrays are transferred back, not copied.\n *\n * Whole-file convenience over {@link ChunkLoader}; use `ChunkLoader`\n * directly when loading many chunks or when cancellation is needed.\n *\n * @param input - Capture URL; its extension selects the parser unless an\n * explicit `format` option is provided.\n * @returns The decoded splat data, ready for {@link SplatMesh}.\n * @throws Rejects only with `SplatLoadError` (resolve, fetch or decode\n * failures - `error.phase` says which) or a `DOMException` named `AbortError`\n * when `options.signal` fires.\n *\n * @example\n * import { SplatMesh } from '@voluma/vlam';\n * import { loadSplatData } from '@voluma/vlam/loaders';\n * const splats = new SplatMesh(await loadSplatData('/scene.sog'));\n */\nexport async function loadSplatData(\n  input: string | URL,\n  options: SplatDataLoadOptions = {},\n): Promise<SplatData> {\n  const loader = new ChunkLoader();\n  try {\n    return await loader.load(input instanceof URL ? input.href : input, options);\n  } finally {\n    loader.dispose();\n  }\n}\n\n/**\n * Decodes a local splat file - from a `<input type=\"file\">` or a drag-and-drop\n * - in a Web Worker, without uploading it anywhere. The file's bytes are read\n * worker-side and the decoded arrays are transferred back, not copied.\n *\n * Only self-contained files are supported: `.ply`, `.spz`, `.splat`, `.ksplat`\n * and bundled `.sog`. An unbundled SOG directory needs sibling fetches, so it\n * must be served over HTTP and loaded with {@link loadSplatData}.\n *\n * @param file - The file; its name selects the parser unless an explicit\n * `format` option is provided.\n * @returns The decoded splat data, ready for {@link SplatMesh}.\n * @throws Rejects only with `SplatLoadError` (unknown extension, read or\n * decode failures) or a `DOMException` named `AbortError` when\n * `options.signal` fires.\n *\n * @example\n * import { SplatMesh } from '@voluma/vlam';\n * import { loadSplatDataFile } from '@voluma/vlam/loaders';\n * const splats = new SplatMesh(await loadSplatDataFile(event.dataTransfer.files[0]));\n */\nexport async function loadSplatDataFile(\n  file: File,\n  options: SplatDataFileLoadOptions = {},\n): Promise<SplatData> {\n  const loader = new ChunkLoader();\n  try {\n    return await loader.loadFile(file, options);\n  } finally {\n    loader.dispose();\n  }\n}\n"],"names":["loadSplatData","input","options","loader","ChunkLoader","loadSplatDataFile","file"],"mappings":";;AAiCA,eAAsBA,EACpBC,GACAC,IAAgC,IACZ;AACpB,QAAMC,IAAS,IAAIC,EAAA;AACnB,MAAI;AACF,WAAO,MAAMD,EAAO,KAAKF,aAAiB,MAAMA,EAAM,OAAOA,GAAOC,CAAO;AAAA,EAC7E,UAAA;AACE,IAAAC,EAAO,QAAA;AAAA,EACT;AACF;AAuBA,eAAsBE,EACpBC,GACAJ,IAAoC,IAChB;AACpB,QAAMC,IAAS,IAAIC,EAAA;AACnB,MAAI;AACF,WAAO,MAAMD,EAAO,SAASG,GAAMJ,CAAO;AAAA,EAC5C,UAAA;AACE,IAAAC,EAAO,QAAA;AAAA,EACT;AACF;"}

package/dist/loading-wLo8vRbA.js.map

@@ -1 +1 @@
-{"version":3,"file":"loading-wLo8vRbA.js","sources":["../src/lib/loading.ts"],"sourcesContent":["/**\n * The self-contained scene formats - files (or bundles) that decode to a whole\n * scene on their own, with no external manifest. This is the value set of\n * {@link SplatData.sourceFormat} and the non-`auto` half of {@link SplatFormat}.\n */\nexport type SplatSourceFormat = 'ply' | 'sog' | 'spz' | 'splat' | 'ksplat' | 'rad';\n\n/** Explicit formats accepted by {@link loadScene}. */\nexport type SplatFormat = 'auto' | SplatSourceFormat;\n\n/** Explicit formats accepted by {@link StreamedSplatMesh.load}. */\nexport type StreamedSplatFormat = 'auto' | 'streamed-sog' | 'lcc2' | 'lcc' | 'rad';\n\n/**\n * Parsers the loading worker can run on a chunk. This extends {@link SplatFormat}\n * with formats that are only ever reached as a streamed chunk, never as a\n * standalone scene handed to {@link loadScene}: `lcc-bin` is a byte range of an\n * LCC (`.lcc`) `data.bin`, and `rad-chunk` a byte range of a single-file `.rad` -\n * both meaningless without their manifest/header.\n */\nexport type ChunkFileFormat = Exclude<SplatFormat, 'auto'> | 'lcc-bin' | 'rad-chunk';\n\n/** Serializable fetch settings that can cross the loading-worker boundary. */\nexport interface SplatRequestOptions {\n  headers?: Readonly<Record<string, string>>;\n  credentials?: RequestCredentials;\n  mode?: RequestMode;\n  cache?: RequestCache;\n}\n\n/**\n * Reports load progress in bytes, for a determinate progress indicator.\n *\n * `total` is 0 when the size is not known ahead of time (a response with no\n * `Content-Length`), which means \"still working\" rather than \"finished\".\n */\nexport type SplatProgressCallback = (loaded: number, total: number) => void;\n\n/** Shortest gap between two progress reports, in milliseconds (~10/s). */\nconst PROGRESS_INTERVAL_MS = 100;\n\n/**\n * Rate-limits progress reports to ~10/s.\n *\n * A body arrives in ~64 KB chunks, so an unthrottled report would post\n * thousands of messages no indicator can render. The final report is exempt -\n * it is what leaves a determinate bar exactly full rather than at 97%.\n *\n * Identifying that final report needs a known size, so the exemption requires\n * `total > 0`. When the size is unknown there is no bar to fill (the caller\n * shows a spinner) and every report is throttled alike - without the `total`\n * check, `loaded < total` would be false for all of them and the throttle\n * would never engage at all.\n */\nexport function createProgressThrottle(\n  report: SplatProgressCallback,\n  intervalMs: number = PROGRESS_INTERVAL_MS,\n): SplatProgressCallback {\n  let lastReportAt = -Infinity;\n  return (loaded: number, total: number): void => {\n    const isFinal = total > 0 && loaded >= total;\n    const now = monotonicNow();\n    if (!isFinal && now - lastReportAt < intervalMs) return;\n    lastReportAt = now;\n    report(loaded, total);\n  };\n}\n\n/**\n * Options for decoding a local file.\n *\n * Shared by {@link loadSceneFile} and `ChunkLoader.loadFile`. There is no\n * `baseUrl`/`request` counterpart to {@link SplatInputOptions} here: a file has\n * no URL to resolve and no request to configure.\n */\nexport interface SplatFileLoadOptions {\n  signal?: AbortSignal;\n  /** Parser selection; the file name's extension is used only for `auto`. */\n  format?: SplatFormat;\n  /**\n   * Called as the file is read, for a determinate progress bar. A multi-\n   * gigabyte PLY takes tens of seconds, so the streamed PLY path reports as it\n   * goes; the whole-buffer formats have nothing to report until they are done.\n   */\n  onProgress?: SplatProgressCallback;\n}\n\n/** Shared URL, cancellation, and request options for package loaders. */\nexport interface SplatInputOptions {\n  signal?: AbortSignal;\n  baseUrl?: string | URL;\n  request?: SplatRequestOptions;\n  /**\n   * Called as bytes are read. Fires from the loading worker, so it is\n   * throttled to whole read windows rather than every byte.\n   */\n  onProgress?: SplatProgressCallback;\n}\n\n/** The stage at which a splat load failed. */\nexport type SplatLoadPhase = 'resolve' | 'manifest' | 'fetch' | 'decode' | 'worker';\n\n/** Serializable error details returned by the loading worker. */\nexport interface SerializedSplatLoadError {\n  name: string;\n  message: string;\n  phase: SplatLoadPhase;\n  url: string;\n  status?: number;\n  retryable: boolean;\n}\n\n/** Structured error thrown for non-cancellation loading failures. */\nexport class SplatLoadError extends Error {\n  readonly phase: SplatLoadPhase;\n  readonly url: string;\n  readonly status?: number;\n  readonly retryable: boolean;\n\n  constructor(\n    message: string,\n    options: {\n      phase: SplatLoadPhase;\n      url: string;\n      status?: number;\n      retryable: boolean;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options.cause });\n    this.name = 'SplatLoadError';\n    this.phase = options.phase;\n    this.url = options.url;\n    this.status = options.status;\n    this.retryable = options.retryable;\n  }\n}\n\n/** Resolves a loader input without assuming that a browser location exists. */\nexport function resolveSplatUrl(input: string | URL, baseUrl?: string | URL): URL {\n  if (input instanceof URL) return new URL(input.href);\n  try {\n    const fallbackBase = baseUrl ?? globalThis.location?.href;\n    if (fallbackBase === undefined) return new URL(input);\n    return new URL(input, fallbackBase);\n  } catch (cause) {\n    throw new SplatLoadError(`Unable to resolve splat URL \"${input}\".`, {\n      phase: 'resolve',\n      url: input,\n      retryable: false,\n      cause,\n    });\n  }\n}\n\n/** Returns the lower-case pathname extension, excluding query/hash text. */\nexport function splatUrlExtension(url: URL): string {\n  return splatNameExtension(url.pathname);\n}\n\n/** Returns the lower-case extension of a plain file name or path. */\nexport function splatNameExtension(name: string): string {\n  const lower = name.toLowerCase();\n  const dot = lower.lastIndexOf('.');\n  return dot < 0 ? '' : lower.slice(dot);\n}\n\n/**\n * Maps a file extension to its parser. `label` names the input in the\n * failure message - a URL for a fetched scene, a file name for a local one.\n *\n * @throws {SplatLoadError} (phase `'resolve'`, not retryable) for an unknown\n * extension, keeping the loader contract uniform: callers of the loading\n * pipeline only ever see `SplatLoadError` or `AbortError`.\n */\nexport function splatFormatForExtension(extension: string, label: string): SplatSourceFormat {\n  switch (extension) {\n    case '.ply':\n      return 'ply';\n    case '.spz':\n      return 'spz';\n    case '.splat':\n      return 'splat';\n    case '.ksplat':\n      return 'ksplat';\n    case '.sog':\n      return 'sog';\n    case '.rad':\n      return 'rad';\n    default:\n      throw new SplatLoadError(`Unsupported splat file extension in ${label}.`, {\n        phase: 'resolve',\n        url: label,\n        retryable: false,\n      });\n  }\n}\n\n/** Creates a fetch init object without sharing mutable header state. */\nexport function toRequestInit(options?: SplatRequestOptions, signal?: AbortSignal): RequestInit {\n  return {\n    ...(options?.headers ? { headers: { ...options.headers } } : {}),\n    ...(options?.credentials ? { credentials: options.credentials } : {}),\n    ...(options?.mode ? { mode: options.mode } : {}),\n    ...(options?.cache ? { cache: options.cache } : {}),\n    ...(signal ? { signal } : {}),\n  };\n}\n\n/**\n * The largest `ArrayBuffer` a browser will allocate: 2 GiB, in every current\n * engine. A file bigger than this cannot be read in one piece at all - the\n * read fails rather than the decode.\n */\nexport const MAX_ARRAY_BUFFER_BYTES = 2 ** 31;\n\n/** Bytes as a short \"1.7 GB\" for a message. */\nfunction gigabytes(bytes: number): string {\n  return `${(bytes / 1e9).toFixed(1)} GB`;\n}\n\n/**\n * Reads a whole local file, turning the browser's two unhelpful failure modes\n * into messages that name the real cause.\n *\n * Chrome reports an over-2 GiB read as `NotReadableError`, whose stock text\n * blames file permissions - so a perfectly good 4 GB capture reads as \"your\n * file is broken\". Check the size up front instead.\n *\n * Formats with a streaming parser (see `parseSplatPlyFile`) never come here.\n */\nexport async function readWholeFile(file: File): Promise<ArrayBuffer> {\n  if (file.size > MAX_ARRAY_BUFFER_BYTES) {\n    throw new Error(\n      `${file.name} is ${gigabytes(file.size)}. A browser cannot read more than 2 GB of a file ` +\n        'at once, and this format has to be decoded in one piece. Convert it to SOG ' +\n        '(npx @playcanvas/splat-transform in.ply out.sog) or a compressed .ply.',\n    );\n  }\n  try {\n    return await file.arrayBuffer();\n  } catch (error) {\n    if (isAbortError(error)) throw error;\n    // NotReadableError also covers a file that moved or changed since the drop\n    // - the reference is a snapshot, and reading revalidates it.\n    if (error instanceof Error && error.name === 'NotReadableError') {\n      throw new Error(\n        `${file.name} could not be read. It may have been moved, renamed or changed since it ` +\n          'was dropped, or it may be on a drive the browser cannot reach.',\n        { cause: error },\n      );\n    }\n    throw error;\n  }\n}\n\n/** Creates an AbortError even where DOMException is unavailable. */\nexport function createAbortError(message: string): Error {\n  if (typeof DOMException !== 'undefined') return new DOMException(message, 'AbortError');\n  const error = new Error(message);\n  error.name = 'AbortError';\n  return error;\n}\n\n/** Whether an unknown failure represents cancellation. */\nexport function isAbortError(error: unknown): boolean {\n  return error instanceof Error && error.name === 'AbortError';\n}\n\n/** Maps an arbitrary failure to the package's structured loading error. */\nexport function toSplatLoadError(\n  error: unknown,\n  options: { phase: SplatLoadPhase; url: string; status?: number },\n): SplatLoadError {\n  if (error instanceof SplatLoadError) return error;\n  const message = error instanceof Error ? error.message : String(error);\n  return new SplatLoadError(message, {\n    ...options,\n    retryable: isRetryableFailure(options.status, options.phase),\n    cause: error,\n  });\n}\n\n/** Converts a structured load failure into worker-safe data. */\nexport function serializeSplatLoadError(error: SplatLoadError): SerializedSplatLoadError {\n  return {\n    name: error.name,\n    message: error.message,\n    phase: error.phase,\n    url: error.url,\n    ...(error.status === undefined ? {} : { status: error.status }),\n    retryable: error.retryable,\n  };\n}\n\n/** Reconstructs a package error received from a loading worker. */\nexport function deserializeSplatLoadError(error: SerializedSplatLoadError): SplatLoadError {\n  return new SplatLoadError(error.message, error);\n}\n\n/** Monotonic time where available, with an SSR-safe fallback. */\nexport function monotonicNow(): number {\n  return globalThis.performance?.now() ?? Date.now();\n}\n\nfunction isRetryableFailure(status: number | undefined, phase: SplatLoadPhase): boolean {\n  if (status !== undefined)\n    return status === 408 || status === 425 || status === 429 || status >= 500;\n  return phase === 'fetch' || phase === 'manifest' || phase === 'worker';\n}\n"],"names":["SplatLoadError","message","options","__publicField","resolveSplatUrl","input","baseUrl","_a","fallbackBase","cause","splatUrlExtension","url","splatNameExtension","name","lower","dot","splatFormatForExtension","extension","label","toRequestInit","signal","createAbortError","error","isAbortError","toSplatLoadError","isRetryableFailure","deserializeSplatLoadError","status","phase"],"mappings":"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"}
+{"version":3,"file":"loading-wLo8vRbA.js","sources":["../src/lib/loading.ts"],"sourcesContent":["/**\n * The self-contained scene formats - files (or bundles) that decode to a whole\n * scene on their own, with no external manifest. This is the value set of\n * {@link SplatData.format} and the non-`auto` half of {@link SplatFormat}.\n */\nexport type SplatDataFormat = 'ply' | 'sog' | 'spz' | 'splat' | 'ksplat' | 'rad';\n\n/** Explicit formats accepted by {@link loadSplatData}. */\nexport type SplatFormat = 'auto' | SplatDataFormat;\n\n/** Explicit formats accepted by {@link StreamedSplatMesh.load}. */\nexport type StreamedSplatFormat = 'auto' | 'streamed-sog' | 'lcc2' | 'lcc' | 'rad';\n\n/**\n * Parsers the loading worker can run on a chunk. This extends {@link SplatFormat}\n * with formats that are only ever reached as a streamed chunk, never as a\n * standalone scene handed to {@link loadSplatData}: `lcc-bin` is a byte range of an\n * LCC (`.lcc`) `data.bin`, and `rad-chunk` a byte range of a single-file `.rad` -\n * both meaningless without their manifest/header.\n */\nexport type ChunkFileFormat = Exclude<SplatFormat, 'auto'> | 'lcc-bin' | 'rad-chunk';\n\n/** Serializable fetch settings that can cross the loading-worker boundary. */\nexport interface SplatRequestOptions {\n  headers?: Readonly<Record<string, string>>;\n  credentials?: RequestCredentials;\n  mode?: RequestMode;\n  cache?: RequestCache;\n}\n\n/**\n * Reports load progress in bytes, for a determinate progress indicator.\n *\n * `total` is 0 when the size is not known ahead of time (a response with no\n * `Content-Length`), which means \"still working\" rather than \"finished\".\n */\nexport type SplatProgressCallback = (loaded: number, total: number) => void;\n\n/** Shortest gap between two progress reports, in milliseconds (~10/s). */\nconst PROGRESS_INTERVAL_MS = 100;\n\n/**\n * Rate-limits progress reports to ~10/s.\n *\n * A body arrives in ~64 KB chunks, so an unthrottled report would post\n * thousands of messages no indicator can render. The final report is exempt -\n * it is what leaves a determinate bar exactly full rather than at 97%.\n *\n * Identifying that final report needs a known size, so the exemption requires\n * `total > 0`. When the size is unknown there is no bar to fill (the caller\n * shows a spinner) and every report is throttled alike - without the `total`\n * check, `loaded < total` would be false for all of them and the throttle\n * would never engage at all.\n */\nexport function createProgressThrottle(\n  report: SplatProgressCallback,\n  intervalMs: number = PROGRESS_INTERVAL_MS,\n): SplatProgressCallback {\n  let lastReportAt = -Infinity;\n  return (loaded: number, total: number): void => {\n    const isFinal = total > 0 && loaded >= total;\n    const now = monotonicNow();\n    if (!isFinal && now - lastReportAt < intervalMs) return;\n    lastReportAt = now;\n    report(loaded, total);\n  };\n}\n\n/**\n * Options for decoding a local file.\n *\n * Shared by {@link loadSplatDataFile} and `ChunkLoader.loadFile`. There is no\n * `baseUrl`/`request` counterpart to {@link SplatInputOptions} here: a file has\n * no URL to resolve and no request to configure.\n */\nexport interface SplatDataFileLoadOptions {\n  signal?: AbortSignal;\n  /** Parser selection; the file name's extension is used only for `auto`. */\n  format?: SplatFormat;\n  /**\n   * Called as the file is read, for a determinate progress bar. A multi-\n   * gigabyte PLY takes tens of seconds, so the streamed PLY path reports as it\n   * goes; the whole-buffer formats have nothing to report until they are done.\n   */\n  onProgress?: SplatProgressCallback;\n}\n\n/** Shared URL, cancellation, and request options for package loaders. */\nexport interface SplatInputOptions {\n  signal?: AbortSignal;\n  baseUrl?: string | URL;\n  request?: SplatRequestOptions;\n  /**\n   * Called as bytes are read. Fires from the loading worker, so it is\n   * throttled to whole read windows rather than every byte.\n   */\n  onProgress?: SplatProgressCallback;\n}\n\n/** The stage at which a splat load failed. */\nexport type SplatLoadPhase = 'resolve' | 'manifest' | 'fetch' | 'decode' | 'worker';\n\n/** Serializable error details returned by the loading worker. */\nexport interface SerializedSplatLoadError {\n  name: string;\n  message: string;\n  phase: SplatLoadPhase;\n  url: string;\n  status?: number;\n  retryable: boolean;\n}\n\n/** Structured error thrown for non-cancellation loading failures. */\nexport class SplatLoadError extends Error {\n  readonly phase: SplatLoadPhase;\n  readonly url: string;\n  readonly status?: number;\n  readonly retryable: boolean;\n\n  constructor(\n    message: string,\n    options: {\n      phase: SplatLoadPhase;\n      url: string;\n      status?: number;\n      retryable: boolean;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options.cause });\n    this.name = 'SplatLoadError';\n    this.phase = options.phase;\n    this.url = options.url;\n    this.status = options.status;\n    this.retryable = options.retryable;\n  }\n}\n\n/** Resolves a loader input without assuming that a browser location exists. */\nexport function resolveSplatUrl(input: string | URL, baseUrl?: string | URL): URL {\n  if (input instanceof URL) return new URL(input.href);\n  try {\n    const fallbackBase = baseUrl ?? globalThis.location?.href;\n    if (fallbackBase === undefined) return new URL(input);\n    return new URL(input, fallbackBase);\n  } catch (cause) {\n    throw new SplatLoadError(`Unable to resolve splat URL \"${input}\".`, {\n      phase: 'resolve',\n      url: input,\n      retryable: false,\n      cause,\n    });\n  }\n}\n\n/** Returns the lower-case pathname extension, excluding query/hash text. */\nexport function splatUrlExtension(url: URL): string {\n  return splatNameExtension(url.pathname);\n}\n\n/** Returns the lower-case extension of a plain file name or path. */\nexport function splatNameExtension(name: string): string {\n  const lower = name.toLowerCase();\n  const dot = lower.lastIndexOf('.');\n  return dot < 0 ? '' : lower.slice(dot);\n}\n\n/**\n * Maps a file extension to its parser. `label` names the input in the\n * failure message - a URL for a fetched scene, a file name for a local one.\n *\n * @throws {SplatLoadError} (phase `'resolve'`, not retryable) for an unknown\n * extension, keeping the loader contract uniform: callers of the loading\n * pipeline only ever see `SplatLoadError` or `AbortError`.\n */\nexport function splatFormatForExtension(extension: string, label: string): SplatDataFormat {\n  switch (extension) {\n    case '.ply':\n      return 'ply';\n    case '.spz':\n      return 'spz';\n    case '.splat':\n      return 'splat';\n    case '.ksplat':\n      return 'ksplat';\n    case '.sog':\n      return 'sog';\n    case '.rad':\n      return 'rad';\n    default:\n      throw new SplatLoadError(`Unsupported splat file extension in ${label}.`, {\n        phase: 'resolve',\n        url: label,\n        retryable: false,\n      });\n  }\n}\n\n/** Creates a fetch init object without sharing mutable header state. */\nexport function toRequestInit(options?: SplatRequestOptions, signal?: AbortSignal): RequestInit {\n  return {\n    ...(options?.headers ? { headers: { ...options.headers } } : {}),\n    ...(options?.credentials ? { credentials: options.credentials } : {}),\n    ...(options?.mode ? { mode: options.mode } : {}),\n    ...(options?.cache ? { cache: options.cache } : {}),\n    ...(signal ? { signal } : {}),\n  };\n}\n\n/**\n * The largest `ArrayBuffer` a browser will allocate: 2 GiB, in every current\n * engine. A file bigger than this cannot be read in one piece at all - the\n * read fails rather than the decode.\n */\nexport const MAX_ARRAY_BUFFER_BYTES = 2 ** 31;\n\n/** Bytes as a short \"1.7 GB\" for a message. */\nfunction gigabytes(bytes: number): string {\n  return `${(bytes / 1e9).toFixed(1)} GB`;\n}\n\n/**\n * Reads a whole local file, turning the browser's two unhelpful failure modes\n * into messages that name the real cause.\n *\n * Chrome reports an over-2 GiB read as `NotReadableError`, whose stock text\n * blames file permissions - so a perfectly good 4 GB capture reads as \"your\n * file is broken\". Check the size up front instead.\n *\n * Formats with a streaming parser (see `parseSplatPlyFile`) never come here.\n */\nexport async function readWholeFile(file: File): Promise<ArrayBuffer> {\n  if (file.size > MAX_ARRAY_BUFFER_BYTES) {\n    throw new Error(\n      `${file.name} is ${gigabytes(file.size)}. A browser cannot read more than 2 GB of a file ` +\n        'at once, and this format has to be decoded in one piece. Convert it to SOG ' +\n        '(npx @playcanvas/splat-transform in.ply out.sog) or a compressed .ply.',\n    );\n  }\n  try {\n    return await file.arrayBuffer();\n  } catch (error) {\n    if (isAbortError(error)) throw error;\n    // NotReadableError also covers a file that moved or changed since the drop\n    // - the reference is a snapshot, and reading revalidates it.\n    if (error instanceof Error && error.name === 'NotReadableError') {\n      throw new Error(\n        `${file.name} could not be read. It may have been moved, renamed or changed since it ` +\n          'was dropped, or it may be on a drive the browser cannot reach.',\n        { cause: error },\n      );\n    }\n    throw error;\n  }\n}\n\n/** Creates an AbortError even where DOMException is unavailable. */\nexport function createAbortError(message: string): Error {\n  if (typeof DOMException !== 'undefined') return new DOMException(message, 'AbortError');\n  const error = new Error(message);\n  error.name = 'AbortError';\n  return error;\n}\n\n/** Whether an unknown failure represents cancellation. */\nexport function isAbortError(error: unknown): boolean {\n  return error instanceof Error && error.name === 'AbortError';\n}\n\n/** Maps an arbitrary failure to the package's structured loading error. */\nexport function toSplatLoadError(\n  error: unknown,\n  options: { phase: SplatLoadPhase; url: string; status?: number },\n): SplatLoadError {\n  if (error instanceof SplatLoadError) return error;\n  const message = error instanceof Error ? error.message : String(error);\n  return new SplatLoadError(message, {\n    ...options,\n    retryable: isRetryableFailure(options.status, options.phase),\n    cause: error,\n  });\n}\n\n/** Converts a structured load failure into worker-safe data. */\nexport function serializeSplatLoadError(error: SplatLoadError): SerializedSplatLoadError {\n  return {\n    name: error.name,\n    message: error.message,\n    phase: error.phase,\n    url: error.url,\n    ...(error.status === undefined ? {} : { status: error.status }),\n    retryable: error.retryable,\n  };\n}\n\n/** Reconstructs a package error received from a loading worker. */\nexport function deserializeSplatLoadError(error: SerializedSplatLoadError): SplatLoadError {\n  return new SplatLoadError(error.message, error);\n}\n\n/** Monotonic time where available, with an SSR-safe fallback. */\nexport function monotonicNow(): number {\n  return globalThis.performance?.now() ?? Date.now();\n}\n\nfunction isRetryableFailure(status: number | undefined, phase: SplatLoadPhase): boolean {\n  if (status !== undefined)\n    return status === 408 || status === 425 || status === 429 || status >= 500;\n  return phase === 'fetch' || phase === 'manifest' || phase === 'worker';\n}\n"],"names":["SplatLoadError","message","options","__publicField","resolveSplatUrl","input","baseUrl","_a","fallbackBase","cause","splatUrlExtension","url","splatNameExtension","name","lower","dot","splatFormatForExtension","extension","label","toRequestInit","signal","createAbortError","error","isAbortError","toSplatLoadError","isRetryableFailure","deserializeSplatLoadError","status","phase"],"mappings":"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"}

package/dist/loading.d.ts

@@ -1,17 +1,17 @@
 /**
  * The self-contained scene formats - files (or bundles) that decode to a whole
  * scene on their own, with no external manifest. This is the value set of
- * {@link SplatData.sourceFormat} and the non-`auto` half of {@link SplatFormat}.
+ * {@link SplatData.format} and the non-`auto` half of {@link SplatFormat}.
  */
-export type SplatSourceFormat = 'ply' | 'sog' | 'spz' | 'splat' | 'ksplat' | 'rad';
-/** Explicit formats accepted by {@link loadScene}. */
-export type SplatFormat = 'auto' | SplatSourceFormat;
+export type SplatDataFormat = 'ply' | 'sog' | 'spz' | 'splat' | 'ksplat' | 'rad';
+/** Explicit formats accepted by {@link loadSplatData}. */
+export type SplatFormat = 'auto' | SplatDataFormat;
 /** Explicit formats accepted by {@link StreamedSplatMesh.load}. */
 export type StreamedSplatFormat = 'auto' | 'streamed-sog' | 'lcc2' | 'lcc' | 'rad';
 /**
  * Parsers the loading worker can run on a chunk. This extends {@link SplatFormat}
  * with formats that are only ever reached as a streamed chunk, never as a
- * standalone scene handed to {@link loadScene}: `lcc-bin` is a byte range of an
+ * standalone scene handed to {@link loadSplatData}: `lcc-bin` is a byte range of an
  * LCC (`.lcc`) `data.bin`, and `rad-chunk` a byte range of a single-file `.rad` -
  * both meaningless without their manifest/header.
  */
@@ -47,11 +47,11 @@ export declare function createProgressThrottle(report: SplatProgressCallback, in
 /**
  * Options for decoding a local file.
  *
- * Shared by {@link loadSceneFile} and `ChunkLoader.loadFile`. There is no
+ * Shared by {@link loadSplatDataFile} and `ChunkLoader.loadFile`. There is no
  * `baseUrl`/`request` counterpart to {@link SplatInputOptions} here: a file has
  * no URL to resolve and no request to configure.
  */
-export interface SplatFileLoadOptions {
+export interface SplatDataFileLoadOptions {
     signal?: AbortSignal;
     /** Parser selection; the file name's extension is used only for `auto`. */
     format?: SplatFormat;
@@ -112,7 +112,7 @@ export declare function splatNameExtension(name: string): string;
  * extension, keeping the loader contract uniform: callers of the loading
  * pipeline only ever see `SplatLoadError` or `AbortError`.
  */
-export declare function splatFormatForExtension(extension: string, label: string): SplatSourceFormat;
+export declare function splatFormatForExtension(extension: string, label: string): SplatDataFormat;
 /** Creates a fetch init object without sharing mutable header state. */
 export declare function toRequestInit(options?: SplatRequestOptions, signal?: AbortSignal): RequestInit;
 /**