@voluma/vlam 0.1.0 → 0.2.0

package/dist/lod-scheduler.d.ts

@@ -0,0 +1,229 @@
+import * as THREE from 'three/webgpu';
+import type { LodManifest } from './lod-manifest';
+import type { LodSource } from './lod-source';
+/**
+ * A contiguous splat range within one chunk file, at one LOD level - the
+ * unit the pool activates. Adjacent manifest leaves that resolve to the same
+ * `(file, level)` and whose ranges abut are coalesced into one run, so the
+ * pool sees a handful of large ranges instead of thousands of tiny leaves.
+ */
+export interface LodRun {
+    readonly file: number;
+    readonly level: number;
+    readonly offset: number;
+    readonly count: number;
+    /** First manifest-leaf index this run covers. */
+    readonly leafStart: number;
+    /** One past the last covered leaf index. */
+    readonly leafEnd: number;
+    /**
+     * Physical-coverage identity when several manifest leaves form one region.
+     * A classic LCC cell may be split into fetch-sized leaves, but its slices
+     * must still swap as one visible unit. Undefined retains interval-based
+     * grouping for hierarchical sources.
+     */
+    readonly coverageGroup?: number;
+    /**
+     * Camera distance (mesh-local) of the nearest leaf in this run, from the
+     * last {@link LodScheduler.computeDesiredRuns} pass. Streamed meshes use it
+     * to fetch near detail before far coarse coverage. Absent on sources that
+     * do not track per-leaf distance.
+     */
+    readonly distance?: number;
+    /**
+     * True when any leaf in this run intersects the view frustum (with the
+     * scheduler's edge margin). Used to rank classic-path fetches so in-view
+     * detail beats behind-camera work; absent when the source does not track it.
+     */
+    readonly inView?: boolean;
+    /**
+     * Fetch-only angular distance from the camera's forward axis. Smaller values
+     * are nearer the screen centre. It never affects LOD selection or budget.
+     */
+    readonly screenImportance?: number;
+}
+/** Stable identity of a run, for diffing desired vs. resident sets. */
+export declare function runKey(run: LodRun): string;
+/**
+ * Chooses a level of detail per spatial leaf from the camera, keeps the
+ * total within a splat budget, and coalesces the result into runs.
+ *
+ * The scheduler is pure with respect to rendering: it takes a camera
+ * position and frustum (both in the mesh's local space) and returns the set
+ * of runs that should be resident. It owns only the small amount of state
+ * needed for temporal stability (each leaf's current level and when it last
+ * changed), so it is straightforward to drive from a test harness.
+ *
+ * LOD distance model (PlayCanvas-compatible): level 0 is used within
+ * `lodBaseDistance`; each successive level covers a band `lodMultiplier`×
+ * farther out. By default out-of-frustum leaves act {@link FRUSTUM_PENALTY}×
+ * farther away. Formats with broad spatial cells can disable that bias so an
+ * orbit does not churn already-refined cells at the frustum edges.
+ *
+ * The distance model only sets the *floor* and the *priority*: when the
+ * distance-chosen set leaves budget unused, {@link fillBudget} promotes
+ * in-frustum leaves nearest-first until its configured headroom target is
+ * spent (90% by default). Formats can cap that optional refinement and avoid
+ * a full-finest cut even when an explicitly large budget could hold it. The
+ * budget
+ * therefore decides how far refinement reaches - a desktop budget yields
+ * full detail even with the whole scene in view, a mobile budget refines
+ * only near the camera.
+ */
+export declare class LodScheduler implements LodSource {
+    /** World-unit distance inside which the finest level (0) is used. */
+    lodBaseDistance: number;
+    /** Distance ratio between successive LOD levels. */
+    lodMultiplier: number;
+    /** Maximum active splats; the desired set is demoted to fit. */
+    budget: number;
+    private readonly leaves;
+    private readonly coarsest;
+    /** Per leaf: lowest/highest LOD level that has data. */
+    private readonly minLevel;
+    private readonly maxLevel;
+    /**
+     * Per leaf: the distance *ambition* - the finest level the camera distance
+     * asks for, with hysteresis/dwell applied. This is the hysteresis *state*:
+     * only {@link selectLevels} writes it, so budget demotion can never feed
+     * back into the dead-band/dwell logic and oscillate. With `fillPastDistance`
+     * false, {@link fillBudget} restores {@link resolved} only up to here.
+     */
+    private readonly level;
+    /**
+     * Per leaf: the resolved target - the ambition capped to fit the budget by
+     * {@link enforceBudget}, then refilled from leftover headroom by
+     * {@link fillBudget} (or DROPPED). This is what {@link coalesceRuns} emits.
+     */
+    private readonly resolved;
+    /** Per leaf: timestamp of the last distance-level change, for dwell. */
+    private readonly changedAt;
+    private readonly distance;
+    private readonly inFrustum;
+    /** Leaves that must move through the budget cut together. */
+    private readonly budgetGroups;
+    /** Per-leaf physical coverage group, when the manifest defines one. */
+    private readonly coverageGroups;
+    /** Whether view-frustum membership affects distance and fill priority. */
+    private readonly frustumAware;
+    /** Fraction of the usable budget that optional refinement may consume. */
+    private readonly budgetFillFraction;
+    /** Absolute cap on optional refinement; distance-selected detail may exceed it. */
+    private readonly budgetFillCap;
+    /** Whether a budget that holds every finest leaf forces a full-finest cut. */
+    private readonly forceFinestWhenFits;
+    /**
+     * Leaves at or inside this camera distance always resolve to their finest
+     * available level (no hysteresis climb). Classic LCC uses a multi-band
+     * radius so adjacent broad cells do not paint coarse discs at startup.
+     */
+    private readonly forceFinestWithin;
+    /**
+     * When false, {@link fillBudget} only restores toward each leaf's
+     * distance-selected {@link level} - never finer. Classic LCC sets this so
+     * a mid-range cell does not fetch L0 only to demote to L1 once the cut
+     * settles.
+     */
+    private readonly fillPastDistance;
+    /**
+     * What the last cut actually decided, for the HUD.
+     *
+     * The resident splat count alone cannot distinguish "the scheduler asked for
+     * this" from "the scheduler asked for more and the mesh could not apply it",
+     * and those have opposite fixes. Measured rather than inferred after a
+     * zoomed-out `sandwijck` sat at exactly its coarsest total (190,730) with a
+     * 600k budget - 68% of the budget unspent, with no way to see which stage
+     * declined to spend it.
+     */
+    readonly stats: {
+        /** Leaves the frustum test accepted - `fillBudget`'s candidate set. */
+        inFrustum: number;
+        /** Total leaves in the tree. */
+        leaves: number;
+        /** Splats implied by the resolved cut, before the mesh applies anything. */
+        desired: number;
+        /** Splats `fillBudget` added on top of the distance-chosen levels. */
+        filled: number;
+    };
+    private readonly scratchBox;
+    private readonly scratchSize;
+    private readonly scratchCenter;
+    private readonly screenImportance;
+    /** Whether the last selection pass received a camera-forward vector. */
+    private hasScreenImportance;
+    /**
+     * Persistent leaf-index ordering scratch for {@link enforceBudget} and
+     * {@link fillBudget}, sorted in place per call instead of allocating a
+     * fresh `[...keys]` array. Comparators break ties on the index itself so
+     * the order is identical to the stable `Array#sort` this replaces
+     * (`TypedArray#sort` stability is not guaranteed).
+     */
+    private readonly orderScratch;
+    constructor(manifest: LodManifest, options: {
+        budget: number;
+        lodBaseDistance: number;
+        lodMultiplier: number;
+        frustumAware?: boolean;
+        budgetFillFraction?: number;
+        budgetFillCap?: number;
+        forceFinestWhenFits?: boolean;
+        forceFinestWithin?: number;
+        /**
+         * When false, leftover-budget fill never refines past the distance-
+         * selected level (see {@link fillPastDistance}). Default true.
+         */
+        fillPastDistance?: boolean;
+    });
+    /**
+     * Recomputes the desired resident run set for the current camera.
+     *
+     * @param cameraLocal - Camera position in the mesh's local space.
+     * @param frustum - View frustum in the mesh's local space.
+     * @param now - Monotonic timestamp (ms) for dwell hysteresis.
+     */
+    computeDesiredRuns(cameraLocal: THREE.Vector3, frustum: THREE.Frustum, now: number, cameraForward?: THREE.Vector3): LodRun[];
+    /** Total active splats implied by the current resolved levels. */
+    private activeTotal;
+    /** Splats if every leaf sat at its finest available level (none dropped). */
+    private finestTotal;
+    private selectLevels;
+    /**
+     * Pure distance→level band (independent of the leaf's current level), so a
+     * classic LCC cut never has to dwell through intermediate rungs.
+     */
+    private distanceBandLevel;
+    /**
+     * Stable level from distance: coarsen only past `threshold·(1 + margin)`,
+     * refine only within `threshold·(1 − margin)`. The available-level clamp
+     * keeps leaves that lack a level on their nearest coarser one.
+     */
+    private hysteresisLevel;
+    private resolveAvailable;
+    /** Demotes/drops lowest-priority leaves until the total fits the budget. */
+    private enforceBudget;
+    /**
+     * Uses leftover budget to restore detail after {@link enforceBudget}
+     * demoted leaves, nearest first, while the total stays under the fill
+     * target. By default this may also refine *past* the distance-chosen level
+     * when headroom remains (octree / pagetable streams). With
+     * {@link fillPastDistance} false (classic LCC), fill never goes finer than
+     * each leaf's distance-selected level - so a cell at the L1 band does not
+     * fetch L0 only to demote moments later with the camera still.
+     */
+    private fillBudget;
+    private coalesceRuns;
+    /**
+     * Runs covering [from, to) at each leaf's coarsest available level - used
+     * to substitute always-cached coverage while a finer level is fetching.
+     */
+    coarsestRunsFor(from: number, to: number): LodRun[];
+    /**
+     * Runs covering [from, to) at `level`, clamped per leaf to an available rung
+     * (prefer the requested level, else the next coarser, else the next finer).
+     */
+    runsAtLevelFor(from: number, to: number, level: number): LodRun[];
+    /** Prefer `wanted`, else next coarser, else next finer; {@link DROPPED} if none. */
+    private clampLeafLevel;
+    /** Coalesces leaves [from, to) at `levelOf(leaf)` into contiguous runs. */
+    private buildRuns;
+}

package/dist/lod-source.d.ts

@@ -0,0 +1,207 @@
+import * as THREE from 'three/webgpu';
+import { type LodRun } from './lod-scheduler';
+import type { ChunkFileFormat } from './loading';
+import type { RadChunkRangeRequest } from './load-worker-protocol';
+import type { LccChunkParams } from './formats/lcc/parse-lcc';
+import type { SplatData } from './splat-data';
+import type { SplatDatasetSource } from './dataset-source';
+/**
+ * Per-frame LOD decision maker: given the camera, returns the set of runs
+ * (`{file, offset, count}` slices with a leaf interval) that should be
+ * resident. Two implementations exist - {@link LodScheduler} for the flat
+ * Streamed SOG leaves-with-levels model, and `OctreeLodSource` for the
+ * cut-based LCC2 octree - so {@link StreamedSplatMesh} is format-agnostic.
+ */
+export interface LodSource {
+    /** Active-splat budget the returned set stays within. */
+    budget: number;
+    /** World-unit distance inside which the finest LOD is used. */
+    lodBaseDistance: number;
+    /** Distance ratio between successive LOD levels. */
+    lodMultiplier: number;
+    /** The runs that should be resident for the given camera. */
+    computeDesiredRuns(cameraLocal: THREE.Vector3, frustum: THREE.Frustum, now: number, cameraForward?: THREE.Vector3): LodRun[];
+    /** Coarsest-level runs covering finest cells `[from, to)` - always-cached
+     * substitute coverage while a finer level is fetching. */
+    coarsestRunsFor(from: number, to: number): LodRun[];
+    /**
+     * Runs covering `[from, to)` at a requested LOD level (clamped per leaf to an
+     * available rung). Used by classic-LCC startup hold to coarsen a nearby home
+     * cell when the resolved L0 cut overflows the pool. Optional: sources without
+     * a flat leaf ladder leave it undefined.
+     */
+    runsAtLevelFor?(from: number, to: number, level: number): LodRun[];
+    /**
+     * Notified when a chunk finishes decoding, so a source that discovers its
+     * structure from chunk payloads (a `.rad` LOD tree lives in the chunks, not
+     * a manifest) can incorporate it. Sources with a fully-known manifest
+     * (Streamed SOG, LCC) leave this undefined.
+     */
+    onChunkDecoded?(file: number, data: SplatData): void;
+}
+/**
+ * Per-chunk fetch and decode settings, for formats where the URL alone is not
+ * enough. LCC (`.lcc`, manifest v3–v5) uses this to name a byte range inside the one big
+ * `data.bin` and to carry that range's dequantization ranges. LCC2 and local
+ * Streamed SOG use it so a `blob:` URL (no file extension) still selects the
+ * SOG parser.
+ */
+export interface StreamedChunkOptions {
+    readonly format: ChunkFileFormat;
+    readonly lcc?: LccChunkParams;
+    /** Byte range within the single-file `.rad`; carried by a `rad-chunk`. */
+    readonly rad?: RadChunkRangeRequest;
+    /**
+     * Convert this SOG chunk's palette-compressed shN into per-splat packed shN
+     * at decode, keeping this many bands, so it survives the shared pool (M11).
+     * Absent leaves the palette shN to be dropped, as streamed scenes did before.
+     */
+    readonly sog?: {
+        readonly packShBands: 1 | 2 | 3;
+    };
+    /**
+     * For an unbundled SOG chunk from a dropped folder: the directory's files as
+     * `name → blob URL`. Absent over HTTP, where the worker resolves each image
+     * against the chunk's directory URL instead.
+     */
+    readonly files?: Readonly<Record<string, string>>;
+}
+/**
+ * A single always-resident environment/background tile a format ships outside
+ * its LOD structure - the `.lcc2` `env.sog` sky, loaded once and toggled with
+ * {@link StreamedSplatMesh.setEnvironmentEnabled} rather than scheduled by
+ * camera distance. Its splat count is absent from the manifest and measured
+ * when the tile decodes (see `docs/formats/lcc2-notes.md`).
+ */
+export interface EnvironmentTile {
+    /** Chunk-file index (into {@link StreamedScene.chunkUrls}) of the tile. */
+    readonly file: number;
+}
+/** One collision-mesh tile a scene ships alongside its splats. */
+export interface CollisionMeshDescriptor {
+    /**
+     * Fetchable URL of the tile: a binary triangle-mesh PLY (`.lcc2`), or a
+     * classic-LCC `collision.lci` that expands into per-cell meshes at load.
+     */
+    readonly url: string;
+    /**
+     * The tile's source-local bounds, when the format declares them. Lets a host
+     * order or cull tile work without parsing them first. Unused for a whole-file
+     * `.lci` descriptor - per-cell bounds come from the parser.
+     */
+    readonly bounds?: THREE.Box3;
+}
+/**
+ * Collision geometry a format ships next to its splats - absent for formats
+ * that carry none (Streamed SOG), present for XGRIDS `.lcc` / `.lcc2` captures
+ * that include a collision sidecar.
+ *
+ * Coordinates are source-local, the same frame as {@link StreamedScene.bounds}:
+ * {@link StreamedScene.formatTransform} maps them to world.
+ */
+export interface SceneCollision {
+    readonly meshes: readonly CollisionMeshDescriptor[];
+}
+/**
+ * Everything {@link StreamedSplatMesh} needs about a scene, independent of
+ * whether it came from a Streamed SOG manifest or an LCC dataset.
+ */
+export interface StreamedScene {
+    readonly source: LodSource;
+    /** Chunk-file URLs, indexed by a run's `file`. */
+    readonly chunkUrls: readonly string[];
+    /** How each chunk URL is fetched: an unbundled SOG directory (Streamed
+     * SOG) or a single bundled `.sog`/`.ply` file (LCC2 tiles). */
+    readonly chunkKind: 'directory' | 'file';
+    /** Optional per-chunk overrides, aligned with {@link chunkUrls}. */
+    readonly chunkOptions?: readonly (StreamedChunkOptions | undefined)[];
+    /**
+     * Per-splat SH bands this scene's chunks actually carry, after the format
+     * has had its say - a `Portable` LCC capture reports 0 however many bands
+     * the caller asked for. The pool sizes its SH textures from this, so it
+     * never allocates ~64 B/splat for SH that will never arrive.
+     */
+    readonly shBands?: 0 | 1 | 2 | 3;
+    /** Root bounds of the whole scene (valid before any chunk loads). */
+    readonly bounds: THREE.Box3;
+    /** Files backing the coarsest levels - pinned in cache as substitutes. */
+    readonly pinnedFiles: ReadonlySet<number>;
+    /** Finest-level splat total, for sizing the pool. */
+    readonly maxResidentSplats: number;
+    /**
+     * The capture's real content size - the splat count a host would need to hold
+     * it at full resolution. Distinct from {@link maxResidentSplats}, which a
+     * foveated source reports as the *requested budget* because its pool holds a
+     * camera-directed resident set rather than the whole tree. A host budgeting
+     * across several streamed meshes needs the real number: a mesh cannot spend
+     * more than it contains, so this is the clamp on any share handed to it.
+     *
+     * Undefined when the format does not declare it.
+     */
+    readonly contentSplatCount?: number;
+    /** Smallest budget that can retain full-scene coarsest coverage. */
+    readonly minimumCoverageSplats: number;
+    /**
+     * Optional local-to-world format correction applied once to the mesh at
+     * load time. Bounds and LOD data remain source-local so scheduling and
+     * picking consistently use the encoded coordinate frame.
+     */
+    readonly formatTransform?: THREE.Matrix4;
+    /** Optional collision geometry the format ships; undefined when it has none. */
+    readonly collision?: SceneCollision;
+    /**
+     * Optional always-resident environment tile the format ships outside its LOD
+     * structure (the `.lcc2` sky) - present only when the dataset carries one.
+     */
+    readonly environment?: EnvironmentTile;
+    /**
+     * Screen-space foveation band (px), for a scene that renders whole resident
+     * chunks and lets the material's projected-radius cull pick the LOD cut per
+     * splat - a `.rad` too large to load whole. Only splats sized `(min, max]` on
+     * screen draw, so near view rays land on fine leaves and far rays on coarse
+     * nodes. `StreamedSplatMesh` applies it as the mesh's screen-radius band.
+     */
+    readonly foveation?: {
+        readonly minScreenRadiusPx: number;
+        readonly maxScreenRadiusPx: number;
+    };
+    /**
+     * Splats per chunk file, so a `(file, localIndex)` pair maps to a stable global
+     * splat index (`file * chunkSize + local`). Set by `.rad`; the page-table
+     * renderer (`foveationMode: 'pagetable'`) keys frontier splats by that global.
+     */
+    readonly chunkSize?: number;
+    /**
+     * A chunk the scene builder already fetched and decoded (`.rad` decodes chunk
+     * 0 for the scene bounds and the SH codebook). Handing it straight to the
+     * renderer saves a second round trip - and in `pagetable` mode it is what
+     * seeds the worker's tree roots, without which the first traversals return an
+     * empty frontier and the view stays blank until chunk 0 arrives a second time.
+     */
+    readonly bootstrapChunk?: {
+        readonly file: number;
+        readonly data: SplatData;
+    };
+    /**
+     * Source-local xyz subsample of the coarsest overview (`.rad` chunk 0).
+     * Survives after pagetable mode transfers chunk-0 buffers to the worker, so
+     * a host can estimate terrain height before any later chunk decodes.
+     */
+    readonly overviewPositions?: Float32Array;
+}
+export interface LodSourceOptions {
+    budget: number;
+    lodBaseDistance: number;
+    lodMultiplier: number;
+}
+/**
+ * Builds a scene from a parsed Streamed SOG manifest (JSON already fetched).
+ *
+ * `shBands` opts into view-dependent color (M11): when ≥ 1, each chunk's
+ * palette shN is converted to per-splat packed shN at decode so it survives
+ * the shared pool, and the pool allocates that many SH bands. Unset/0 keeps
+ * the historical behavior (palette shN dropped). It is opt-in because the
+ * manifest does not declare whether the tiles carry shN; a scene with none
+ * renders unchanged but wastes the allocated SH textures, so ask deliberately.
+ */
+export declare function buildSogScene(json: unknown, source: SplatDatasetSource, options: LodSourceOptions, shBands?: 0 | 1 | 2 | 3): StreamedScene;

package/dist/logging-BfPdd7NJ.js

@@ -0,0 +1,19 @@
+const a = (o, n, ...l) => {
+  o === "error" ? console.error(n, ...l) : console.warn(n, ...l);
+};
+let r = a;
+function c(o) {
+  r = o === void 0 ? a : o;
+}
+function e(o, ...n) {
+  r == null || r("warn", `vlam: ${o}`, ...n);
+}
+function s(o, ...n) {
+  r == null || r("error", `vlam: ${o}`, ...n);
+}
+export {
+  s as l,
+  c as s,
+  e as w
+};
+//# sourceMappingURL=logging-BfPdd7NJ.js.map

package/dist/logging-BfPdd7NJ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-BfPdd7NJ.js","sources":["../src/lib/logging.ts"],"sourcesContent":["/**\n * The library's diagnostic output, behind one replaceable hook.\n *\n * A library that writes straight to the host console gives embedders no way\n * out - and some of these sites are per-item (a malformed chunk in a large\n * streamed scene can warn on every tick). Everything routes through\n * {@link setVlamLogHandler} instead, so a host can forward VLAM! diagnostics\n * into its own logger, or silence them entirely.\n *\n * Worker scopes are the deliberate exception: `load-worker.ts` and\n * `sort-worker.ts` run in a separate realm with no access to this module's\n * state, and plumbing a handler across `postMessage` would mean serializing\n * user callbacks. Neither worker logs today - failures travel back as\n * structured messages - so there is nothing to route.\n */\n\n/** Severity of a library diagnostic. */\nexport type VlamLogLevel = 'warn' | 'error';\n\n/**\n * Receives library diagnostics. `message` is already prefixed with `vlam:`;\n * `details` carries any extra values the call site passed.\n */\nexport type VlamLogHandler = (level: VlamLogLevel, message: string, ...details: unknown[]) => void;\n\nconst defaultHandler: VlamLogHandler = (level, message, ...details) => {\n  if (level === 'error') console.error(message, ...details);\n  else console.warn(message, ...details);\n};\n\nlet handler: VlamLogHandler | null = defaultHandler;\n\n/**\n * Redirects (or silences) every diagnostic the library emits.\n *\n * @param next - A handler to receive diagnostics, `null` to drop them\n * silently, or omitted/`undefined` to restore the default console handler.\n *\n * @example\n * setVlamLogHandler((level, message) => myLogger.log(level, message));\n * setVlamLogHandler(null); // silence VLAM! entirely\n */\nexport function setVlamLogHandler(next?: VlamLogHandler | null): void {\n  handler = next === undefined ? defaultHandler : next;\n}\n\n/** Emits a `vlam:`-prefixed warning through the current handler. */\nexport function warn(message: string, ...details: unknown[]): void {\n  handler?.('warn', `vlam: ${message}`, ...details);\n}\n\n/** Emits a `vlam:`-prefixed error through the current handler. */\nexport function logError(message: string, ...details: unknown[]): void {\n  handler?.('error', `vlam: ${message}`, ...details);\n}\n"],"names":["defaultHandler","level","message","details","handler","setVlamLogHandler","next","warn","logError"],"mappings":"AAyBA,MAAMA,IAAiC,CAACC,GAAOC,MAAYC,MAAY;AACrE,EAAIF,MAAU,UAAS,QAAQ,MAAMC,GAAS,GAAGC,CAAO,IACnD,QAAQ,KAAKD,GAAS,GAAGC,CAAO;AACvC;AAEA,IAAIC,IAAiCJ;AAY9B,SAASK,EAAkBC,GAAoC;AACpE,EAAAF,IAAUE,MAAS,SAAYN,IAAiBM;AAClD;AAGO,SAASC,EAAKL,MAAoBC,GAA0B;AACjE,EAAAC,KAAA,QAAAA,EAAU,QAAQ,SAASF,CAAO,IAAI,GAAGC;AAC3C;AAGO,SAASK,EAASN,MAAoBC,GAA0B;AACrE,EAAAC,KAAA,QAAAA,EAAU,SAAS,SAASF,CAAO,IAAI,GAAGC;AAC5C;"}

package/dist/logging.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The library's diagnostic output, behind one replaceable hook.
+ *
+ * A library that writes straight to the host console gives embedders no way
+ * out - and some of these sites are per-item (a malformed chunk in a large
+ * streamed scene can warn on every tick). Everything routes through
+ * {@link setVlamLogHandler} instead, so a host can forward VLAM! diagnostics
+ * into its own logger, or silence them entirely.
+ *
+ * Worker scopes are the deliberate exception: `load-worker.ts` and
+ * `sort-worker.ts` run in a separate realm with no access to this module's
+ * state, and plumbing a handler across `postMessage` would mean serializing
+ * user callbacks. Neither worker logs today - failures travel back as
+ * structured messages - so there is nothing to route.
+ */
+/** Severity of a library diagnostic. */
+export type VlamLogLevel = 'warn' | 'error';
+/**
+ * Receives library diagnostics. `message` is already prefixed with `vlam:`;
+ * `details` carries any extra values the call site passed.
+ */
+export type VlamLogHandler = (level: VlamLogLevel, message: string, ...details: unknown[]) => void;
+/**
+ * Redirects (or silences) every diagnostic the library emits.
+ *
+ * @param next - A handler to receive diagnostics, `null` to drop them
+ * silently, or omitted/`undefined` to restore the default console handler.
+ *
+ * @example
+ * setVlamLogHandler((level, message) => myLogger.log(level, message));
+ * setVlamLogHandler(null); // silence VLAM! entirely
+ */
+export declare function setVlamLogHandler(next?: VlamLogHandler | null): void;
+/** Emits a `vlam:`-prefixed warning through the current handler. */
+export declare function warn(message: string, ...details: unknown[]): void;
+/** Emits a `vlam:`-prefixed error through the current handler. */
+export declare function logError(message: string, ...details: unknown[]): void;