@voluma/vlam 0.1.0 → 0.2.0

package/dist/load-scene.d.ts

@@ -0,0 +1,50 @@
+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 {
+    /** Parser selection; URL extension detection is used only for `auto`. */
+    format?: SplatFormat;
+}
+/**
+ * Fetches and decodes a splat scene (`.sog`, `.ply`, `.spz`, `.splat` or
+ * `.ksplat`) in a Web Worker, so
+ * 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`
+ * directly when loading many chunks or when cancellation is needed.
+ *
+ * @param input - Scene 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
+ * failures - `error.phase` says which) or a `DOMException` named `AbortError`
+ * when `options.signal` fires.
+ *
+ * @example
+ * const splats = new SplatMesh(await loadScene('/scene.sog'));
+ * scene.add(splats);
+ */
+export declare function loadScene(input: string | URL, options?: SplatLoadOptions): 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
+ * worker-side and the decoded arrays are transferred back, not copied.
+ *
+ * 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}.
+ *
+ * @param file - The file; its name selects the parser unless an explicit
+ * `format` option is provided.
+ * @returns The decoded splat data, ready for {@link SplatMesh}.
+ * @throws Rejects only with `SplatLoadError` (unknown extension, read or
+ * decode failures) or a `DOMException` named `AbortError` when
+ * `options.signal` fires.
+ *
+ * @example
+ * const splats = new SplatMesh(await loadSceneFile(event.dataTransfer.files[0]));
+ * scene.add(splats);
+ */
+export declare function loadSceneFile(file: File, options?: SplatFileLoadOptions): Promise<SplatData>;

package/dist/load-worker-protocol.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Wire protocol for the loading worker (`load-worker.ts`).
+ *
+ * These message types live outside the worker module on purpose: the worker
+ * itself is bundled into a blob URL and is not part of the published entry
+ * graph, so keeping the shared interfaces here is what lets the main-thread
+ * client ({@link ChunkLoader}) be typed without dragging worker source into
+ * the shipped declarations.
+ */
+import type { LccChunkParams } from './formats/lcc/parse-lcc';
+import type { RadShCodebook, SplatData } from './splat-data';
+import type { ChunkFileFormat, SerializedSplatLoadError, SplatRequestOptions } from './loading';
+/** Where a load's bytes come from. `File` crosses the worker boundary by
+ * structured clone, so a local file is read (and decoded) in the worker. */
+export type LoadWorkerSource = {
+    from: 'url';
+    /** Absolute URL to a supported file, or a SOG chunk directory. */
+    url: string;
+    /** 'file' decodes by extension; 'directory' is an unbundled SOG. */
+    kind: 'file' | 'directory';
+    /** Serializable fetch settings supplied by the consumer. */
+    request?: SplatRequestOptions;
+} | {
+    from: 'file';
+    file: File;
+};
+export type LoadWorkerRequest = {
+    type: 'load';
+    id: number;
+    source: LoadWorkerSource;
+    /** Explicit parser selection; 'directory' sources ignore it. */
+    format: ChunkFileFormat;
+    /** Byte range and dequantization ranges; required by `lcc-bin`. */
+    lcc?: LccChunkParams;
+    /** Byte range within the single-file `.rad`; required by `rad-chunk`. */
+    rad?: RadChunkRangeRequest;
+    /** Convert a SOG chunk's palette shN into packed shN at decode (M11). */
+    sog?: {
+        packShBands: 1 | 2 | 3;
+    };
+    /** A 'directory' chunk's files by name, when it has no directory URL. */
+    files?: Readonly<Record<string, string>>;
+    /** Report read progress; off unless the caller passed `onProgress`. */
+    progress?: boolean;
+} | {
+    type: 'cancel';
+    id: number;
+};
+/** A `rad-chunk`'s location. A single-file `.rad` gives a byte range; a
+ * `--rad-chunked` set gives no range - the URL is the whole `.radc` file. */
+export interface RadChunkRangeRequest {
+    /** Byte offset within the single-file `.rad`; omitted for an external
+     * `.radc` file (fetched whole). */
+    readonly start?: number;
+    /** Byte length of the range; omitted for an external `.radc` file. */
+    readonly length?: number;
+    /** Spark writes clustered SH coefficients only in chunk zero. */
+    readonly shCodebook?: RadShCodebook;
+    /** Scene-wide SH quantization extent established by chunk zero, so every
+     * chunk's packed SH shares the one range the pool decodes against. */
+    readonly shExtent?: number;
+    /** Reorder splats leaves-first for the prefix reader (default). The foveation
+     * reader passes `false` to keep file order (see `parseRadChunkStreaming`). */
+    readonly reorder?: boolean;
+}
+export type LoadWorkerResponse = {
+    type: 'result';
+    id: number;
+    ok: true;
+    data: SplatData;
+} | {
+    type: 'result';
+    id: number;
+    ok: false;
+    error: SerializedSplatLoadError;
+    cancelled: boolean;
+} | {
+    type: 'progress';
+    id: number;
+    loaded: number;
+    total: number;
+};

package/dist/loading-wLo8vRbA.js

@@ -0,0 +1,102 @@
+var c = Object.defineProperty;
+var l = (e, r, a) => r in e ? c(e, r, { enumerable: !0, configurable: !0, writable: !0, value: a }) : e[r] = a;
+var s = (e, r, a) => l(e, typeof r != "symbol" ? r + "" : r, a);
+class n extends Error {
+  constructor(a, t) {
+    super(a, { cause: t.cause });
+    s(this, "phase");
+    s(this, "url");
+    s(this, "status");
+    s(this, "retryable");
+    this.name = "SplatLoadError", this.phase = t.phase, this.url = t.url, this.status = t.status, this.retryable = t.retryable;
+  }
+}
+function h(e, r) {
+  var a;
+  if (e instanceof URL) return new URL(e.href);
+  try {
+    const t = r ?? ((a = globalThis.location) == null ? void 0 : a.href);
+    return t === void 0 ? new URL(e) : new URL(e, t);
+  } catch (t) {
+    throw new n(`Unable to resolve splat URL "${e}".`, {
+      phase: "resolve",
+      url: e,
+      retryable: !1,
+      cause: t
+    });
+  }
+}
+function E(e) {
+  return u(e.pathname);
+}
+function u(e) {
+  const r = e.toLowerCase(), a = r.lastIndexOf(".");
+  return a < 0 ? "" : r.slice(a);
+}
+function i(e, r) {
+  switch (e) {
+    case ".ply":
+      return "ply";
+    case ".spz":
+      return "spz";
+    case ".splat":
+      return "splat";
+    case ".ksplat":
+      return "ksplat";
+    case ".sog":
+      return "sog";
+    case ".rad":
+      return "rad";
+    default:
+      throw new n(`Unsupported splat file extension in ${r}.`, {
+        phase: "resolve",
+        url: r,
+        retryable: !1
+      });
+  }
+}
+function b(e, r) {
+  return {
+    ...e != null && e.headers ? { headers: { ...e.headers } } : {},
+    ...e != null && e.credentials ? { credentials: e.credentials } : {},
+    ...e != null && e.mode ? { mode: e.mode } : {},
+    ...e != null && e.cache ? { cache: e.cache } : {},
+    ...r ? { signal: r } : {}
+  };
+}
+function w(e) {
+  if (typeof DOMException < "u") return new DOMException(e, "AbortError");
+  const r = new Error(e);
+  return r.name = "AbortError", r;
+}
+function o(e) {
+  return e instanceof Error && e.name === "AbortError";
+}
+function m(e, r) {
+  if (e instanceof n) return e;
+  const a = e instanceof Error ? e.message : String(e);
+  return new n(a, {
+    ...r,
+    retryable: f(r.status, r.phase),
+    cause: e
+  });
+}
+function y(e) {
+  return new n(e.message, e);
+}
+function f(e, r) {
+  return e !== void 0 ? e === 408 || e === 425 || e === 429 || e >= 500 : r === "fetch" || r === "manifest" || r === "worker";
+}
+export {
+  n as S,
+  m as a,
+  u as b,
+  w as c,
+  y as d,
+  E as e,
+  o as i,
+  h as r,
+  i as s,
+  b as t
+};
+//# sourceMappingURL=loading-wLo8vRbA.js.map

package/dist/loading-wLo8vRbA.js.map

@@ -0,0 +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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"}

package/dist/loading.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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}.
+ */
+export type SplatSourceFormat = 'ply' | 'sog' | 'spz' | 'splat' | 'ksplat' | 'rad';
+/** Explicit formats accepted by {@link loadScene}. */
+export type SplatFormat = 'auto' | SplatSourceFormat;
+/** 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
+ * LCC (`.lcc`) `data.bin`, and `rad-chunk` a byte range of a single-file `.rad` -
+ * both meaningless without their manifest/header.
+ */
+export type ChunkFileFormat = Exclude<SplatFormat, 'auto'> | 'lcc-bin' | 'rad-chunk';
+/** Serializable fetch settings that can cross the loading-worker boundary. */
+export interface SplatRequestOptions {
+    headers?: Readonly<Record<string, string>>;
+    credentials?: RequestCredentials;
+    mode?: RequestMode;
+    cache?: RequestCache;
+}
+/**
+ * Reports load progress in bytes, for a determinate progress indicator.
+ *
+ * `total` is 0 when the size is not known ahead of time (a response with no
+ * `Content-Length`), which means "still working" rather than "finished".
+ */
+export type SplatProgressCallback = (loaded: number, total: number) => void;
+/**
+ * Rate-limits progress reports to ~10/s.
+ *
+ * A body arrives in ~64 KB chunks, so an unthrottled report would post
+ * thousands of messages no indicator can render. The final report is exempt -
+ * it is what leaves a determinate bar exactly full rather than at 97%.
+ *
+ * Identifying that final report needs a known size, so the exemption requires
+ * `total > 0`. When the size is unknown there is no bar to fill (the caller
+ * shows a spinner) and every report is throttled alike - without the `total`
+ * check, `loaded < total` would be false for all of them and the throttle
+ * would never engage at all.
+ */
+export declare function createProgressThrottle(report: SplatProgressCallback, intervalMs?: number): SplatProgressCallback;
+/**
+ * Options for decoding a local file.
+ *
+ * Shared by {@link loadSceneFile} 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 {
+    signal?: AbortSignal;
+    /** Parser selection; the file name's extension is used only for `auto`. */
+    format?: SplatFormat;
+    /**
+     * Called as the file is read, for a determinate progress bar. A multi-
+     * gigabyte PLY takes tens of seconds, so the streamed PLY path reports as it
+     * goes; the whole-buffer formats have nothing to report until they are done.
+     */
+    onProgress?: SplatProgressCallback;
+}
+/** Shared URL, cancellation, and request options for package loaders. */
+export interface SplatInputOptions {
+    signal?: AbortSignal;
+    baseUrl?: string | URL;
+    request?: SplatRequestOptions;
+    /**
+     * Called as bytes are read. Fires from the loading worker, so it is
+     * throttled to whole read windows rather than every byte.
+     */
+    onProgress?: SplatProgressCallback;
+}
+/** The stage at which a splat load failed. */
+export type SplatLoadPhase = 'resolve' | 'manifest' | 'fetch' | 'decode' | 'worker';
+/** Serializable error details returned by the loading worker. */
+export interface SerializedSplatLoadError {
+    name: string;
+    message: string;
+    phase: SplatLoadPhase;
+    url: string;
+    status?: number;
+    retryable: boolean;
+}
+/** Structured error thrown for non-cancellation loading failures. */
+export declare class SplatLoadError extends Error {
+    readonly phase: SplatLoadPhase;
+    readonly url: string;
+    readonly status?: number;
+    readonly retryable: boolean;
+    constructor(message: string, options: {
+        phase: SplatLoadPhase;
+        url: string;
+        status?: number;
+        retryable: boolean;
+        cause?: unknown;
+    });
+}
+/** Resolves a loader input without assuming that a browser location exists. */
+export declare function resolveSplatUrl(input: string | URL, baseUrl?: string | URL): URL;
+/** Returns the lower-case pathname extension, excluding query/hash text. */
+export declare function splatUrlExtension(url: URL): string;
+/** Returns the lower-case extension of a plain file name or path. */
+export declare function splatNameExtension(name: string): string;
+/**
+ * Maps a file extension to its parser. `label` names the input in the
+ * failure message - a URL for a fetched scene, a file name for a local one.
+ *
+ * @throws {SplatLoadError} (phase `'resolve'`, not retryable) for an unknown
+ * 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;
+/** Creates a fetch init object without sharing mutable header state. */
+export declare function toRequestInit(options?: SplatRequestOptions, signal?: AbortSignal): RequestInit;
+/**
+ * The largest `ArrayBuffer` a browser will allocate: 2 GiB, in every current
+ * engine. A file bigger than this cannot be read in one piece at all - the
+ * read fails rather than the decode.
+ */
+export declare const MAX_ARRAY_BUFFER_BYTES: number;
+/**
+ * Reads a whole local file, turning the browser's two unhelpful failure modes
+ * into messages that name the real cause.
+ *
+ * Chrome reports an over-2 GiB read as `NotReadableError`, whose stock text
+ * blames file permissions - so a perfectly good 4 GB capture reads as "your
+ * file is broken". Check the size up front instead.
+ *
+ * Formats with a streaming parser (see `parseSplatPlyFile`) never come here.
+ */
+export declare function readWholeFile(file: File): Promise<ArrayBuffer>;
+/** Creates an AbortError even where DOMException is unavailable. */
+export declare function createAbortError(message: string): Error;
+/** Whether an unknown failure represents cancellation. */
+export declare function isAbortError(error: unknown): boolean;
+/** Maps an arbitrary failure to the package's structured loading error. */
+export declare function toSplatLoadError(error: unknown, options: {
+    phase: SplatLoadPhase;
+    url: string;
+    status?: number;
+}): SplatLoadError;
+/** Converts a structured load failure into worker-safe data. */
+export declare function serializeSplatLoadError(error: SplatLoadError): SerializedSplatLoadError;
+/** Reconstructs a package error received from a loading worker. */
+export declare function deserializeSplatLoadError(error: SerializedSplatLoadError): SplatLoadError;
+/** Monotonic time where available, with an SSR-safe fallback. */
+export declare function monotonicNow(): number;

package/dist/lod-manifest.d.ts

@@ -0,0 +1,61 @@
+import * as THREE from 'three/webgpu';
+import type { SplatDatasetSource } from './dataset-source';
+/**
+ * Parser for the Streamed SOG manifest (`lod-meta.json`, version 1).
+ *
+ * The manifest describes a large scene as a binary spatial tree whose leaves
+ * each cover one region at several levels of detail. LOD level 0 is the
+ * finest; higher levels are progressively coarser. Each leaf references, per
+ * level, a contiguous `[offset, offset + count)` splat range inside one chunk
+ * file (an unbundled SOG v2 directory). One chunk file serves many leaves.
+ *
+ * Spec:
+ * https://developer.playcanvas.com/user-manual/gaussian-splatting/formats/streamed-sog/
+ */
+/** A leaf's splat range at one LOD level. */
+export interface LodRange {
+    /** Index into {@link LodManifest.chunkUrls}. */
+    readonly file: number;
+    /** First splat row within that chunk's decoded arrays. */
+    readonly offset: number;
+    /** Number of splats. */
+    readonly count: number;
+}
+/** A spatial region, present at one or more LOD levels. */
+export interface LodLeaf {
+    readonly bounds: THREE.Box3;
+    /** Range per level; `lods[level]` is undefined if absent at that level. */
+    readonly lods: readonly (LodRange | undefined)[];
+    /**
+     * Leaves with the same group are budgeted atomically. Formats may use this
+     * when one spatial region is split into several independently streamed
+     * ranges: the ranges may arrive separately, but must select one LOD cut.
+     */
+    readonly budgetGroup?: number;
+}
+export interface LodManifest {
+    /** Leaves in tree-traversal order (load-bearing: adjacent leaves within a
+     * chunk have contiguous ranges, which the scheduler coalesces into runs). */
+    readonly leaves: readonly LodLeaf[];
+    /** Absolute chunk-directory URLs, indexed by {@link LodRange.file}. */
+    readonly chunkUrls: readonly string[];
+    /**
+     * Chunk directories relative to the manifest, aligned with {@link chunkUrls}.
+     * Only the unbundled-SOG layout has them; formats whose chunks are single
+     * files (LCC of either generation) leave this out.
+     */
+    readonly chunkDirectories?: readonly string[];
+    /** Total splats per LOD level (index = level). */
+    readonly counts: readonly number[];
+    readonly lodLevels: number;
+    /** Root bounding box of the whole scene. */
+    readonly bounds: THREE.Box3;
+}
+/**
+ * Parses a `lod-meta.json` object into a flat, render-ready manifest.
+ *
+ * @param json - The parsed manifest JSON.
+ * @param baseUrl - URL of the manifest, used to resolve chunk directories.
+ * @throws {Error} on an unsupported version or malformed tree.
+ */
+export declare function parseLodManifest(json: unknown, source: SplatDatasetSource): LodManifest;