@nebula-spatial/cad-loader 0.2.2 → 0.2.4

package/dist/loader/internal/external-variant-sidecar-fetch.d.ts

@@ -5,7 +5,7 @@ export type FetchExternalVariantSidecarsOptions = {
     readonly requiredVariantIds: readonly number[];
     readonly fetchImpl?: typeof fetch;
     readonly signal?: AbortSignal;
-    readonly concurrency?: number;
+    readonly onBuffer?: (variantId: number, buffer: ArrayBuffer) => void | Promise<void>;
 };
 export declare function fetchExternalVariantSidecars(options: FetchExternalVariantSidecarsOptions): Promise<{
     readonly buffers: ReadonlyMap<number, ArrayBuffer>;

package/dist/loader/internal/geo-loader-pipeline.d.ts

@@ -43,7 +43,9 @@ export interface GeoLoaderPipelineAdapterInput {
     externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
     requiredExternalVariantIds?: ReadonlySet<number>;
     externalVariantGeometryFetchIds?: ReadonlySet<number>;
+    deferExternalVariantGeometry?: boolean;
     externalVariantDeltaOnly?: boolean;
+    cacheDocument?: boolean;
 }
 export interface GeoLoaderPipelineSession {
     completion: Promise<void>;
@@ -53,6 +55,12 @@ export interface GeoLoaderPipelineSession {
     dispose: () => void;
 }
 export interface GeoLoaderPipelineAdapter {
+    /**
+     * Reusable worker adapters expose this once the worker owns the document's
+     * main buffer. Builders may then pass the caller-owned buffer by reference;
+     * the adapter will omit it from the parse message and use its retained copy.
+     */
+    readonly mainBufferReuseReady?: boolean;
     start(input: GeoLoaderPipelineAdapterInput, emit: GeoLoaderPipelineEmit): GeoLoaderPipelineSession;
 }
 export interface RunGeoLoaderPipelineOptions {
@@ -62,6 +70,7 @@ export interface RunGeoLoaderPipelineOptions {
     signal?: AbortSignal;
     beforeTextAppend?: BeforeTextAppend;
     beforeFinalize?: () => void | Promise<void>;
+    onFirstRenderableAppend?: () => void;
     hiddenInstanceIds?: ReadonlySet<number>;
     keepTextsForHiddenInstances?: boolean;
     loadBlocks?: boolean;
@@ -71,7 +80,9 @@ export interface RunGeoLoaderPipelineOptions {
     externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
     requiredExternalVariantIds?: ReadonlySet<number>;
     externalVariantGeometryFetchIds?: ReadonlySet<number>;
+    deferExternalVariantGeometry?: boolean;
     externalVariantDeltaOnly?: boolean;
+    cacheDocument?: boolean;
     appendExternalVariantDelta?: boolean;
     onYield?: YieldCallback;
     scheduler?: Partial<FrameBudgetSchedulerOptions>;

package/dist/loader/internal/geo-loader-worker-adapter.d.ts

@@ -3,5 +3,11 @@ export interface WorkerGeoLoaderAdapterOptions {
     workerUrl?: string | URL;
     workerFactory?: () => Worker;
 }
+export interface DisposableGeoLoaderPipelineAdapter extends GeoLoaderPipelineAdapter {
+    /** True when a reusable worker owns the main buffer for the current document. */
+    readonly mainBufferReuseReady: boolean;
+    dispose(): void;
+}
 export declare function canUsePrepareWorker(workerFactory?: () => Worker): boolean;
 export declare function createWorkerGeoLoaderAdapter(options?: WorkerGeoLoaderAdapterOptions): GeoLoaderPipelineAdapter;
+export declare function createReusableWorkerGeoLoaderAdapter(options?: WorkerGeoLoaderAdapterOptions): DisposableGeoLoaderPipelineAdapter;

package/dist/loader/internal/geo-node-builder.d.ts

@@ -1,5 +1,6 @@
 import type { FrameBudgetSchedulerOptions } from './frame-budget-scheduler';
 import type { LoaderFlowControlOptions } from './flow-control';
+import { type GeoLoaderPipelineAdapter } from './geo-loader-pipeline';
 import { GeoNode } from './geo-node';
 import type { TextEntity } from '../../shared/types';
 import type { ExternalVariantFetchSource } from '../geo-loader';
@@ -15,6 +16,7 @@ export interface BuildGeoNodeOptions {
     preferWorker?: boolean;
     workerUrl?: string | URL;
     workerFactory?: () => Worker;
+    workerAdapter?: GeoLoaderPipelineAdapter;
     keepTextsForHiddenInstances?: boolean;
     loadBlocks?: boolean;
     maxExpandedInstanceVertices?: number;
@@ -22,7 +24,10 @@ export interface BuildGeoNodeOptions {
     externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
     requiredExternalVariantIds?: ReadonlySet<number> | readonly number[];
     externalVariantGeometryFetchIds?: ReadonlySet<number> | readonly number[];
+    deferExternalVariantGeometry?: boolean;
     externalVariantDeltaOnly?: boolean;
+    cacheDocument?: boolean;
+    onFirstRenderableAppend?: () => void;
 }
 export declare function buildGeoNodeFromBuffer(node: GeoNode, buf: ArrayBuffer, onYield?: YieldCallback, options?: BuildGeoNodeOptions): Promise<void>;
 export declare function appendExternalVariantDeltaToGeoNode(node: GeoNode, buf: ArrayBuffer, onYield?: YieldCallback, options?: BuildGeoNodeOptions): Promise<void>;

package/dist/loader/internal/geo-prepare-worker-types.d.ts

@@ -5,7 +5,13 @@ import type { ExternalVariantFetchSource } from '../geo-loader';
 export type { GeometryKind, PreparedLayerChunk } from './geo-prepare';
 export interface GeoPrepareParseRequest {
     type: 'parse';
-    buffer: ArrayBuffer;
+    /**
+     * Main DXB3 payload. Omitted when the worker already retained the document
+     * buffer from an earlier parse in the same document session.
+     */
+    buffer?: ArrayBuffer;
+    /** Use the main buffer retained by the worker instead of transferring one. */
+    useRetainedMainBuffer?: boolean;
     hiddenInstanceIds?: number[];
     keepTextsForHiddenInstances?: boolean;
     loadBlocks?: boolean;
@@ -20,6 +26,7 @@ export interface GeoPrepareParseRequest {
     requiredExternalVariantIds?: number[];
     externalVariantGeometryFetchIds?: number[];
     externalVariantDeltaOnly?: boolean;
+    cacheDocument?: boolean;
 }
 export interface GeoPrepareGrantMessage {
     type: 'grant';

package/dist/session/cad-document-session.d.ts

@@ -80,6 +80,23 @@ export interface CadSessionDemandProgressEvent {
     readonly loaded: number;
     readonly settled: boolean;
 }
+/** A monotonic start clock plus load milestones elapsed from session creation. */
+export interface CadSessionLoadTiming {
+    readonly startedAtMs: number;
+    readonly mainBufferLoadedMs?: number;
+    readonly headerReadyMs?: number;
+    readonly initialSidecarFetchStartedMs?: number;
+    readonly firstRenderableReadyMs?: number;
+    readonly baseGeometryReadyMs?: number;
+    readonly initialContentReadyMs?: number;
+    readonly initialSidecarFetchSettledMs?: number;
+    readonly initialExternalContentReadyMs?: number;
+    readonly initialViewportSettledMs?: number;
+    readonly failedMs?: number;
+    readonly initialRequiredVariantCount: number;
+    readonly initialSidecarLoadedCount: number;
+    readonly initialSidecarBytes: number;
+}
 export interface CadSessionPhaseChangeEvent {
     readonly phase: CadSessionPhase;
 }
@@ -91,6 +108,9 @@ export interface CadSessionEventMap {
     'content-appended': CadSessionContentAppendedEvent;
     'initial-content-ready': void;
     'demand-progress': CadSessionDemandProgressEvent;
+    'load-timing': {
+        readonly timing: CadSessionLoadTiming;
+    };
     'phase-change': CadSessionPhaseChangeEvent;
     'non-fatal-error': CadSessionErrorEvent;
     'fatal-error': CadSessionErrorEvent;
@@ -124,6 +144,7 @@ export interface CadInsertUsageSummary {
 }
 export interface CadDocumentSession {
     readonly phase: CadSessionPhase;
+    readonly loadTiming: CadSessionLoadTiming;
     readonly headerReady: Promise<CadDocumentHeader>;
     readonly initialContentReady: Promise<void>;
     setViewportDemand(demand: CadViewportDemand): void;

package/dist/shared/text-builder.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Options accepted by Troika's global text builder configuration.
+ *
+ * This is intentionally a thin public surface over Troika. The configuration
+ * remains global to the module instance and must be supplied before the first
+ * font request. No defaults are applied here so an omitted configuration keeps
+ * Troika's original built-in behavior unchanged.
+ */
+export interface CadTextBuilderOptions {
+    readonly defaultFontURL?: string;
+    readonly unicodeFontsURL?: string;
+    readonly sdfGlyphSize?: number;
+    readonly sdfMargin?: number;
+    readonly sdfExponent?: number;
+    readonly textureWidth?: number;
+    readonly useWorker?: boolean;
+}
+/**
+ * Configures the Troika text builder used by cad-loader.
+ *
+ * This function deliberately does not add its own lifecycle, retry, fallback,
+ * or per-viewer state. Troika remains responsible for its existing
+ * module-level, one-time configuration semantics.
+ */
+export declare function configureCadTextBuilder(options: CadTextBuilderOptions): void;