@nebula-spatial/cad-loader 0.1.0 → 0.2.0

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

@@ -2,7 +2,7 @@ import type { ExternalBlockVariantManifestEntry, ParsedGeoPayload, TextEntity }
 import { type CadLoadSource } from '../shared/cad-load-source';
 import { GeoNode } from './internal/geo-node';
 import type { ResolveTextFont } from '../shared/text-font';
-import { type DecodedAnnotationSidecar, type ExternalVariantDependencyOptions, type ExternalVariantDependencyPlan, type ParsedHeader, type CadExternalVariantDelta as GeoNodeExternalVariantDelta } from '../core';
+import { type ExternalVariantDependencyOptions, type ExternalVariantDependencyPlan, type ParsedHeader, type CadExternalVariantDelta as GeoNodeExternalVariantDelta } from '../core';
 export type { ExternalVariantDependencyOptions, ExternalVariantDependencyPlan } from '../core';
 export interface ExternalVariantFetchSource {
     readonly baseUrl: string;
@@ -25,6 +25,7 @@ export interface LoadGeoOptions {
     externalVariantGeometryFetchIds?: readonly number[];
 }
 export interface LoadExternalVariantDeltaOptions {
+    signal?: AbortSignal;
     beforeTextAppend?: (texts: readonly TextEntity[]) => void | Promise<void>;
     hiddenInstanceIds?: readonly number[];
     externalVariantFetchSource?: ExternalVariantFetchSource;
@@ -47,7 +48,7 @@ export declare function readBufferExternalAnnotationManifest(buf: ArrayBuffer):
 export declare function readBufferExternalBlockAnnotations(buf: ArrayBuffer, options?: {
     externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
     hiddenInstanceIds?: ReadonlySet<number>;
-}): DecodedAnnotationSidecar | null;
+}): import("..").DecodedAnnotationSidecar | null;
 export declare function loadExternalVariantDeltaFromBuffer(buf: ArrayBuffer, options: LoadExternalVariantDeltaFetchSourceOptions): GeoNodeExternalVariantDelta;
 export declare function loadExternalVariantDeltaFromBuffer(buf: ArrayBuffer, options: LoadExternalVariantDeltaOptions): GeoNodeExternalVariantDelta;
 export declare function assertValidSourceOrThrow(source: unknown): asserts source is import('../shared/types').GeoLoadSource;

package/dist/loader/internal/automatic-external-resources.d.ts

@@ -0,0 +1,26 @@
+import type { GeoLoadSource } from '../../shared/types';
+import { readExternalAnnotationManifest, type DecodedAnnotationSidecar, type ExternalVariantDependencyOptions } from '../../core';
+export type AutomaticExternalResourceOptions = {
+    readonly loadBlocks?: boolean;
+    readonly loadAnnotations?: boolean;
+    readonly externalVariantFetchSource?: unknown;
+    readonly externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
+    readonly requiredExternalVariantIds?: readonly number[];
+    readonly externalVariantGeometryFetchIds?: readonly number[];
+};
+export type AutomaticExternalResources = {
+    readonly requiredExternalVariantIds?: readonly number[];
+    readonly externalVariantGeometryFetchIds?: readonly number[];
+    readonly externalVariantBuffers?: ReadonlyMap<number, ArrayBuffer>;
+    readonly annotations: readonly DecodedAnnotationSidecar[];
+};
+export declare function resolveAbsoluteSourceUrl(source: GeoLoadSource): string | null;
+export declare function hasAnnotationPayload(annotation: DecodedAnnotationSidecar | null): annotation is DecodedAnnotationSidecar;
+export declare function fetchSceneAnnotation(baseUrl: string, manifest: NonNullable<ReturnType<typeof readExternalAnnotationManifest>>['scene'], signal: AbortSignal): Promise<DecodedAnnotationSidecar | null>;
+export declare function resolveAutomaticExternalResources(source: GeoLoadSource, buffer: ArrayBuffer, options: AutomaticExternalResourceOptions, hiddenInstanceIds: ReadonlySet<number> | undefined, signal: AbortSignal): Promise<AutomaticExternalResources>;
+export declare function buildExternalVariantDependencyOptions(input: {
+    readonly loadBlocks?: boolean;
+    readonly hiddenInstanceIds?: ReadonlySet<number>;
+    readonly viewport?: ExternalVariantDependencyOptions['viewport'];
+    readonly worldUnitsPerPixel?: number;
+}): ExternalVariantDependencyOptions;

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

@@ -1,4 +1,4 @@
-import { Group } from 'three';
+import { Group, Object3D } from 'three';
 import { type ResolveTextFont } from '../../shared/text-font';
 import type { GeoMetaSnapshot, LayerBlockUsage, LayerSnapshot, LineRenderMode, TextEntity, ViewportRect } from '../../shared/types';
 import { type ViewerThemeName } from '../../shared/viewer-theme';
@@ -23,12 +23,17 @@ export type ColorPipelineStatsSnapshot = {
 };
 type BBox = ViewportRect;
 type YieldCallback = () => void | Promise<void>;
-export type GeoNodeInternalChangeKind = 'structure' | 'visual';
-export type GeoNodeInternalChange = {
-    readonly kind: GeoNodeInternalChangeKind;
+export type GeoNodeChangeKind = 'structure' | 'visual';
+export type GeoNodeChange = {
+    readonly kind: GeoNodeChangeKind;
 };
-export declare const GEO_NODE_STRUCTURE_CHANGE: GeoNodeInternalChange;
-export declare const GEO_NODE_VISUAL_CHANGE: GeoNodeInternalChange;
+export type GeoNodeChangeListener = (change: GeoNodeChange) => void;
+/** @deprecated Use GeoNodeChangeKind. */
+export type GeoNodeInternalChangeKind = GeoNodeChangeKind;
+/** @deprecated Use GeoNodeChange. */
+export type GeoNodeInternalChange = GeoNodeChange;
+export declare const GEO_NODE_STRUCTURE_CHANGE: GeoNodeChange;
+export declare const GEO_NODE_VISUAL_CHANGE: GeoNodeChange;
 type FinalizeIncrementallyOptions = Record<string, never>;
 export interface InsertInstanceMatrix2D {
     readonly matA: number;
@@ -38,6 +43,11 @@ export interface InsertInstanceMatrix2D {
     readonly tx: number;
     readonly ty: number;
 }
+export interface InsertPreviewResource {
+    readonly object: Object3D;
+    readonly bounds: ViewportRect;
+    dispose(): void;
+}
 export declare function setGeoNodeLoadAbortHook(node: GeoNode, hook: (() => void) | null): void;
 export declare class GeoNode extends Group {
     private meta;
@@ -87,6 +97,7 @@ export declare class GeoNode extends Group {
     private readonly worldSizedPointUniforms;
     private lineResolution;
     private internalChangeHook;
+    private readonly changeListeners;
     private disposed;
     private readySettled;
     private layerBlockUsages;
@@ -101,6 +112,8 @@ export declare class GeoNode extends Group {
         resolveTextFont?: ResolveTextFont;
     });
     get ready(): Promise<void>;
+    onChange(listener: GeoNodeChangeListener): () => void;
+    _notifyStructureChange(): void;
     setLayerVisible(layerIndex: number, visible: boolean): void;
     setAnnotationOverlayVisible(visible: boolean): void;
     setDisplayTheme(themeName: ViewerThemeName, options?: {
@@ -138,6 +151,7 @@ export declare class GeoNode extends Group {
     getInsertVariantGeometry(variantId: number): VariantGeometry | null;
     getInsertInstanceMatrix(instanceId: number, variantId?: number): InsertInstanceMatrix2D | null;
     getInsertPreviewRecordsForInstance(instanceId: number): readonly InsertInstanceRecord[];
+    createInsertPreviewResource(instanceId: number): InsertPreviewResource | null;
     getEffectiveLayerColorHex(layerIndex: number): number | null;
     private resolveInsertRuntimeInstance;
     updateTextEntry(textId: number, patch: Partial<{
@@ -201,7 +215,9 @@ export declare class GeoNode extends Group {
     _finalizeIncrementally(onYield?: YieldCallback, maxCompactOpsPerPass?: number, _options?: FinalizeIncrementallyOptions): Promise<void>;
     _fail(err: Error): void;
     _setInternalChangeHook(callback: ((change: GeoNodeInternalChange) => void) | null): void;
+    setViewportSize(width: number, height: number): void;
     _setViewportSize(width: number, height: number): void;
+    private updateViewportSize;
     private createPointMaterial;
     private resolvePointWorldSize;
     private appendTextChunk;

package/dist/render-resource/cad-render-node.d.ts

@@ -0,0 +1,71 @@
+import type { Object3D } from 'three';
+import type { CadDisplayContext, CadVisibilityFilter, CadWorldBounds } from '../session/cad-document-session';
+import type { RenderDebugBreakdownEntry, SplitBlockLayerDetail } from '../shared/types';
+export declare const CAD_RENDER_NODE_EDIT_METHODS: readonly ["updateTextEntry", "updateInsertInstanceTransform", "applyInsertTransform", "editBlock"];
+export type CadRenderContentKind = 'geometry' | 'annotation';
+export interface CadRenderContentChunk {
+    readonly documentFingerprint: string;
+    readonly variantId: string | number;
+    readonly chunkId: string;
+    readonly contentRevision: number;
+    readonly kind: CadRenderContentKind;
+}
+/**
+ * Disposable, read-only geometry borrowed from the CAD insert presenter.
+ * Disposing the preview releases only its presenter wrappers and materials;
+ * the document-owned block geometry remains owned by the render node.
+ */
+export interface CadInsertPreviewResource {
+    readonly object: Object3D;
+    readonly bounds: CadWorldBounds;
+    dispose(): void;
+}
+export interface CadRenderDiagnostics {
+    readonly entityCount: number;
+    readonly lineCount: number;
+    readonly fillCount: number;
+    readonly dotCount: number;
+    readonly textCount: number;
+    readonly lineRenderMode: string;
+    readonly renderableCount?: number;
+    readonly submittedVertexRefs?: number;
+    readonly blockVariantCount?: number;
+    readonly blockInstanceCount?: number;
+    readonly splitBlockLayerGroupCount?: number;
+    /** Draw-call source breakdown by renderable kind, for the debug popup. */
+    readonly renderDebugBreakdown?: RenderDebugBreakdownEntry[];
+    /** Top cross-layer block variants, for the debug popup. */
+    readonly splitBlockLayerDetails?: SplitBlockLayerDetail[];
+}
+export interface CadInsertVisibilityChange {
+    readonly insertId: string;
+    readonly visible: boolean;
+}
+/**
+ * Read-only CAD render resource. Editing methods belong to legacy GeoNode and
+ * must not appear on this type.
+ */
+export interface CadRenderNode {
+    readonly object: Object3D;
+    readonly contentRevision: number;
+    getAuthoritativeBounds(filter: CadVisibilityFilter): CadWorldBounds | null;
+    getMountedBounds(filter: CadVisibilityFilter): CadWorldBounds | null;
+    getUnmountedExternalBounds(filter: CadVisibilityFilter): CadWorldBounds | null;
+    appendContent(chunk: CadRenderContentChunk): boolean;
+    setDisplayContext(context: CadDisplayContext): void;
+    setLayerVisible(layerIndex: number, visible: boolean): void;
+    setLayerColorOverride(layerIndex: number, color: number | null): void;
+    setInsertVisible(insertId: string, visible: boolean): void;
+    /**
+     * Applies many insert visibility changes atomically: one hidden-set update,
+     * one presenter refresh, and one structure/onChange notification for the
+     * whole batch, instead of one per call.
+     */
+    setInsertVisibleBatch(changes: ReadonlyArray<CadInsertVisibilityChange>): void;
+    createInsertPreview(instanceId: number): CadInsertPreviewResource | null;
+    getDiagnostics(): CadRenderDiagnostics;
+    onChange(listener: () => void): () => void;
+    dispose(): void;
+}
+export type CadRenderNodeEditMethod = (typeof CAD_RENDER_NODE_EDIT_METHODS)[number];
+export declare function isCadRenderNodeEditMethod(value: string): value is CadRenderNodeEditMethod;

package/dist/render-resource/geo-node-cad-render-node.d.ts

@@ -0,0 +1,12 @@
+import type { GeoNode } from '../loader/internal/geo-node';
+import type { CadWorldBounds } from '../session/cad-document-session';
+import type { CadRenderNode } from './cad-render-node';
+export declare function planarBoundsFromXy(bounds: readonly [number, number, number, number] | null | undefined): CadWorldBounds | null;
+export declare function mergeWorldBounds(current: CadWorldBounds | null, next: CadWorldBounds | null): CadWorldBounds | null;
+export declare function createGeoNodeCadRenderNode(input: {
+    readonly node: GeoNode;
+    readonly getHeaderBounds: () => CadWorldBounds | null;
+    readonly getUnmountedBounds: () => CadWorldBounds | null;
+    readonly hiddenInstanceIds: Set<number>;
+    readonly onInsertVisibilityChange: () => void;
+}): CadRenderNode;

package/dist/selection/cad-text-selection.d.ts

@@ -0,0 +1,31 @@
+import type { GeoNode } from '../loader/internal/geo-node';
+export interface CadPoint2D {
+    readonly x: number;
+    readonly y: number;
+}
+export interface CadTextSelectionId {
+    readonly kind: 'text';
+    readonly textId: number;
+}
+export interface CadTextDetails {
+    readonly id: CadTextSelectionId;
+    readonly content: string;
+    readonly x: number;
+    readonly y: number;
+    readonly height: number;
+    readonly rotation: number;
+    readonly layerName: string;
+    readonly layerIndex: number;
+}
+export interface CadTextSelection {
+    readonly documentKey: string | null;
+    readonly id: CadTextSelectionId;
+    readonly details: CadTextDetails | null;
+}
+export interface CadTextPickOptions {
+    /** Optional upper bound for callers that need to cap interactive scans. */
+    readonly maxTextCount?: number;
+}
+export declare function pickCadTextAtPoint(node: Pick<GeoNode, 'getTextEntries' | 'getLayers'>, point: CadPoint2D, options?: CadTextPickOptions): CadTextSelectionId | null;
+export declare function resolveCadTextDetails(node: Pick<GeoNode, 'getTextEntries' | 'getLayers'>, id: CadTextSelectionId): CadTextDetails | null;
+export declare function cadTextSelectionEquals(a: CadTextSelectionId | null, b: CadTextSelectionId | null): boolean;

package/dist/session/annotation-idle-gate.d.ts

@@ -0,0 +1,14 @@
+import type { ViewportRect } from '../core';
+import type { ExternalBlockVariantManifestEntry, ExternalSceneAnnotationManifestEntry } from '../shared/types';
+/** Copied from the product annotation idle gate. */
+export declare const ANNOTATION_TEXT_APPEND_IDLE_DELAY_MS = 450;
+export declare const ANNOTATION_LOAD_MAX_WORLD_UNITS_PER_PIXEL = 250;
+export declare const ANNOTATION_VIEWPORT_PADDING_RATIO = 0.25;
+export declare function shouldLoadSceneAnnotations(input: {
+    readonly manifestBBox: ViewportRect | null;
+    readonly viewport: ViewportRect | null;
+    readonly worldUnitsPerPixel: number;
+}): boolean;
+export declare function sceneManifestBBox(scene: ExternalSceneAnnotationManifestEntry | null | undefined): ViewportRect | null;
+export declare function hasBlockAnnotationPayload(entry: ExternalBlockVariantManifestEntry): boolean;
+export declare function isAnnotationZoomReadable(worldUnitsPerPixel: number): boolean;

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

@@ -0,0 +1,155 @@
+import type { CadInsertDetails, CadInsertSelectionId } from '../selection/cad-insert-selection';
+import type { CadTextSelection } from '../selection/cad-text-selection';
+import type { ResolveTextFont } from '../shared/text-font';
+import type { CadTextWarmupOptions } from './cad-text-warmup';
+import type { ViewportRect } from '../core';
+export type { CadInsertDetails, CadInsertSelectionId } from '../selection/cad-insert-selection';
+export type { CadTextDetails, CadTextSelection, CadTextSelectionId } from '../selection/cad-text-selection';
+export type { CadLoadSource } from '../shared/cad-load-source';
+export type { CadTextWarmupOptions, CadTextWarmupStats } from './cad-text-warmup';
+export type { ViewportRect as CadViewportRect } from '../core';
+export type CadSessionPhase = 'created' | 'header-ready' | 'initial-loading' | 'interactive' | 'failed' | 'disposed';
+export declare const CAD_SESSION_PHASES: readonly ["created", "header-ready", "initial-loading", "interactive", "failed", "disposed"];
+export interface CadWorldPoint {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** Authoritative CAD bounds. Planar sources use a degenerate Z interval. */
+export interface CadWorldBounds {
+    readonly minX: number;
+    readonly minY: number;
+    readonly minZ: number;
+    readonly maxX: number;
+    readonly maxY: number;
+    readonly maxZ: number;
+    readonly planar: boolean;
+}
+export interface CadLayerMeta {
+    readonly index: number;
+    readonly name: string;
+    readonly color: readonly [number, number, number];
+    readonly visible: boolean;
+}
+export interface CadVisibilityFilter {
+    readonly layerVisible?: ReadonlyMap<number, boolean> | ((layerIndex: number) => boolean);
+    readonly insertVisible?: ReadonlySet<string> | ((insertId: string) => boolean);
+    readonly includeUnmountedExternal?: boolean;
+}
+export interface CadViewportDemand {
+    readonly documentRect: ViewportRect;
+    readonly worldUnitsPerPixel: number;
+    readonly viewportWidthPx: number;
+    readonly viewportHeightPx: number;
+    readonly viewMode: '2d' | '3d';
+    readonly interaction: 'active' | 'idle';
+    readonly visibilityRevision: number;
+}
+export interface CadDisplayContext {
+    /** Visible document-space bounds used to cull INSERT instances in 2D. */
+    readonly documentRect?: ViewportRect | null;
+    readonly viewportWidthPx: number;
+    readonly viewportHeightPx: number;
+    readonly devicePixelRatio: number;
+    readonly worldUnitsPerPixel: number;
+    readonly viewMode: '2d' | '3d';
+    readonly quality: 'auto' | 'full' | 'stress';
+}
+export interface CadDocumentHeader {
+    readonly bounds: CadWorldBounds | null;
+    readonly layers: readonly CadLayerMeta[];
+    readonly sourceFingerprint: string;
+    readonly format: string;
+    readonly filename: string | null;
+}
+export interface CadInsertSelection {
+    readonly documentKey: string | null;
+    readonly id: CadInsertSelectionId;
+    readonly details: CadInsertDetails | null;
+}
+export interface CadSessionHeaderEvent {
+    readonly header: CadDocumentHeader;
+}
+export interface CadSessionContentAppendedEvent {
+    readonly contentRevision: number;
+    readonly kind: 'geometry' | 'annotation';
+}
+export interface CadSessionDemandProgressEvent {
+    readonly demandRevision: number;
+    readonly pending: number;
+    readonly loaded: number;
+    readonly settled: boolean;
+}
+export interface CadSessionPhaseChangeEvent {
+    readonly phase: CadSessionPhase;
+}
+export interface CadSessionErrorEvent {
+    readonly error: Error;
+}
+export interface CadSessionEventMap {
+    header: CadSessionHeaderEvent;
+    'content-appended': CadSessionContentAppendedEvent;
+    'initial-content-ready': void;
+    'demand-progress': CadSessionDemandProgressEvent;
+    'phase-change': CadSessionPhaseChangeEvent;
+    'non-fatal-error': CadSessionErrorEvent;
+    'fatal-error': CadSessionErrorEvent;
+}
+export interface CadFontRequest {
+    readonly family?: string;
+    readonly styleName?: string;
+    readonly shxName?: string;
+    readonly weight?: number;
+    readonly italic?: boolean;
+}
+export interface CadResolvedFont {
+    readonly fontUrl?: string;
+    readonly family?: string;
+    readonly fallback: boolean;
+    readonly sourceFingerprint?: string;
+}
+export interface CadFontResolver {
+    resolve(request: CadFontRequest, signal?: AbortSignal): Promise<CadResolvedFont | null>;
+}
+export interface CadInsertUsageSummary {
+    readonly insertId: string;
+    readonly blockName: string;
+    readonly layerName: string;
+    readonly layerIndex: number;
+    readonly instanceId: number;
+    readonly variantId: number;
+    readonly label: string;
+    readonly canHighlight: boolean;
+    readonly visible: boolean;
+}
+export interface CadDocumentSession {
+    readonly phase: CadSessionPhase;
+    readonly headerReady: Promise<CadDocumentHeader>;
+    readonly initialContentReady: Promise<void>;
+    setViewportDemand(demand: CadViewportDemand): void;
+    setDisplayContext(context: CadDisplayContext): void;
+    on<K extends keyof CadSessionEventMap>(type: K, listener: (event: CadSessionEventMap[K]) => void): () => void;
+    getBounds(filter: CadVisibilityFilter): CadWorldBounds | null;
+    getLayers(): readonly CadLayerMeta[];
+    listInsertUsages(): readonly CadInsertUsageSummary[];
+    getBlockDetails(id: string): CadInsertDetails | null;
+    pickInsertAtPoint(point: CadWorldPoint, viewport: ViewportRect): CadInsertSelection | null;
+    /** Optional for compatibility with pre-text-picking session adapters. */
+    pickTextAtPoint?(point: CadWorldPoint): CadTextSelection | null;
+    abort(reason?: unknown): void;
+    dispose(): void;
+}
+export interface CadDocumentSessionOptions {
+    readonly documentKey?: string;
+    readonly filename?: string;
+    readonly loadAnnotations?: boolean;
+    readonly fontResolver?: CadFontResolver;
+    readonly resolveTextFont?: ResolveTextFont;
+    /**
+     * Troika glyph warmup policy. Defaults to enabled: characters of appended
+     * texts (initial load, delta variants, annotations) are preloaded in
+     * idle-delayed background batches. Set to `false` to disable.
+     */
+    readonly textWarmup?: boolean | CadTextWarmupOptions;
+    readonly signal?: AbortSignal;
+}

package/dist/session/cad-font-runtime.d.ts

@@ -0,0 +1,11 @@
+import { type ResolveTextFont } from '../shared/text-font';
+import type { CadFontResolver } from './cad-document-session';
+export type CadFontRuntime = {
+    readonly resolveTextFont: ResolveTextFont;
+    dispose(): void;
+};
+export declare function createCadFontRuntime(input: {
+    readonly fontResolver?: CadFontResolver;
+    readonly signal: AbortSignal;
+    readonly onNonFatalError: (error: Error) => void;
+}): CadFontRuntime;

package/dist/session/cad-insert-id.d.ts

@@ -0,0 +1,6 @@
+import type { CadInsertSelectionId } from '../selection/cad-insert-selection';
+export declare function formatCadInsertId(id: CadInsertSelectionId): string;
+export declare function parseCadInsertId(value: string): CadInsertSelectionId | {
+    readonly instanceId: number;
+} | null;
+export declare function cadInsertInstanceId(value: string): number | null;

package/dist/session/cad-text-warmup.d.ts

@@ -0,0 +1,38 @@
+import type { ResolvedTextFont } from '../shared/text-font';
+export interface CadTextWarmupOptions {
+    /** Idle delay before a scheduled warmup batch flushes. Default 600ms. */
+    readonly idleDelayMs?: number;
+    /** Max unique characters accumulated per font before capping. Default 256. */
+    readonly maxUniqueCharsPerFont?: number;
+    /** Per-preload timeout. Default 8000ms. */
+    readonly timeoutMs?: number;
+    /** Max remembered warm signatures. Default 96. */
+    readonly signatureCacheLimit?: number;
+}
+export interface CadTextWarmupStats {
+    readonly scheduledTexts: number;
+    readonly preloadCalls: number;
+    readonly skippedRepeatedSignatures: number;
+    readonly failedWarmups: number;
+    readonly timedOutWarmups: number;
+    readonly evictedSignatures: number;
+    readonly warmedSignatures: number;
+    readonly inFlightWarmups: number;
+}
+export type CadTextWarmup = {
+    /** Schedules characters of `texts` for background glyph warmup (idle, deduped). */
+    scheduleForTexts(texts: readonly string[]): void;
+    /** Cancels pending timers and in-flight bookkeeping. In-flight preloads are left to settle. */
+    dispose(): void;
+    readonly stats: CadTextWarmupStats;
+};
+/**
+ * Session-scoped Troika glyph warmup runtime. Characters are bucketed per
+ * resolved font URL, deduped by (font, charset) signature, and preloaded in a
+ * single idle-delayed background flush. SSR/headless environments are a no-op.
+ */
+export declare function createCadTextWarmup(input: {
+    readonly resolveTextFont: (text: string) => ResolvedTextFont;
+    readonly signal: AbortSignal;
+    readonly options?: CadTextWarmupOptions;
+}): CadTextWarmup;

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

@@ -0,0 +1,5 @@
+import { type CadLoadSource } from '../shared/cad-load-source';
+import type { CadRenderNode } from '../render-resource/cad-render-node';
+import type { CadDocumentSession, CadDocumentSessionOptions } from './cad-document-session';
+export declare function getCadDocumentRenderResource(session: CadDocumentSession): CadRenderNode;
+export declare function createCadDocumentSession(source: CadLoadSource, options?: CadDocumentSessionOptions): CadDocumentSession;

package/dist/session/viewport-coverage.d.ts

@@ -0,0 +1,32 @@
+import type { ViewportRect } from '../core';
+/** Copied from the product AppController viewport-sidecar refresh policy. */
+export declare const EXTERNAL_VIEWPORT_REFRESH_COVERAGE_RATIO = 0.25;
+export declare const EXTERNAL_VIEWPORT_REFRESH_SCALE_TOLERANCE_RATIO = 0.125;
+export type CadViewportCoverageState = {
+    readonly viewport: ViewportRect | null;
+    readonly worldUnitsPerPixel: number;
+};
+export declare function coarseExternalViewportSignature(state: CadViewportCoverageState): string | null;
+export declare function hiddenInstanceSignature(hiddenInstanceIds: ReadonlySet<number>): string;
+export declare function isWorldUnitsPerPixelClose(previous: number | null, next: number): boolean;
+export declare function canReuseExternalViewportPlan(input: {
+    readonly coverage: ViewportRect | null;
+    readonly coverageWorldUnitsPerPixel: number | null;
+    readonly coverageHiddenSignature: string | null;
+    readonly viewport: ViewportRect | null;
+    readonly worldUnitsPerPixel: number;
+    readonly hiddenSignature: string;
+}): boolean;
+export declare function isExternalViewportRequestStillCurrent(input: {
+    readonly requestedViewport: ViewportRect;
+    readonly requestedWorldUnitsPerPixel: number;
+    readonly requestedHiddenSignature: string;
+    readonly latestViewport: ViewportRect | null;
+    readonly latestWorldUnitsPerPixel: number;
+    readonly latestHiddenSignature: string;
+}): boolean;
+export declare function markExternalViewportCoverage(viewport: ViewportRect, worldUnitsPerPixel: number, hiddenSignature: string): {
+    readonly coverage: ViewportRect;
+    readonly worldUnitsPerPixel: number;
+    readonly hiddenSignature: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebula-spatial/cad-loader",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Browser-side DXB3/DXBS CAD pack loader runtime",
   "license": "ISC",
   "engines": {
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "package.json"
   ],
   "main": "./dist/index.js",