@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.0

package/dist/types/tile/tile_traversal_adapter.d.ts

@@ -0,0 +1,63 @@
+import type { HostProjection } from "../types.js";
+import type { TileCoordinate, TileCoordinates } from "./tile_id.js";
+import type { GlobeVisibilityLODAdapter, VisibilityLODAdapter, VisibilityViewState } from "../scene/visibility_adapter.js";
+/** Count a finite CPU-projected footprint at data detail 0–6 without allocating tile coordinates.
+ * Uses the same XYZ endpoint and single-world clamping rules as actual traversal.
+ * This is a per-source candidate count, not a total across multiple sources.
+ */
+export declare function countProjectedTileCoordinates(bounds: readonly [number, number, number, number], tileZoom: number): number;
+/** Geographic XYZ tile bounds; an unwrapped world copy retains its longitude offset. */
+export interface GeographicTileBounds {
+    /** Western longitude in degrees. */
+    west: number;
+    /** Southern latitude in degrees. */
+    south: number;
+    /** Eastern longitude in degrees. */
+    east: number;
+    /** Northern latitude in degrees. */
+    north: number;
+}
+/** One host eye's traversal inputs, independent of deck.gl viewport classes. */
+export interface TangramTraversalEye {
+    /** Geographic view state with style and data zoom kept distinct. */
+    readonly view: VisibilityViewState;
+    /** Projection and footprint policy. */
+    readonly projection: HostProjection;
+    /** Optional globe/common-space camera position. */
+    readonly position?: ArrayLike<number>;
+    /** Host eyes need independent bounds; classic views already have calculated bounds. */
+    readonly calculateBounds?: boolean;
+    /** Projected LOD overrides per-eye automatic detail, never style zoom. */
+    readonly dataZoom?: number;
+}
+/** Shared logical traversal state; stereo consumers contribute an eye union. */
+export interface TangramTraversalState {
+    /** Empty until the view is ready. */
+    readonly eyes: readonly TangramTraversalEye[];
+    /** Host render-view collections deduplicate even a single eye; classic ordering remains unchanged. */
+    readonly union?: boolean;
+}
+/** Structured geographic bounds suitable for both Tangram and loaders.gl adapters. */
+export declare function getTileGeographicBounds(index: TileCoordinates): GeographicTileBounds;
+/**
+ * Traversal seam structurally compatible with loaders.gl Tileset2DAdapter.
+ * Tangram owns footprint/LOD inputs; source normalization and fallback pinning remain separate.
+ */
+export default class TangramTileTraversalAdapter {
+    /** Existing planar/FirstPerson visibility implementation. */
+    private readonly planar;
+    /** Existing curved globe/horizon visibility implementation. */
+    private readonly globe;
+    /** Bind the unchanged projection-specific selection procedures. */
+    constructor(planar: VisibilityLODAdapter, globe: GlobeVisibilityLODAdapter);
+    /** Select the same logical data tiles before source sparse-zoom/overzoom normalization. */
+    getTileIndices({ viewState }: {
+        viewState: TangramTraversalState;
+    }): TileCoordinate[];
+    /** Geographic tile metadata, with XYZ's north-down Y convention preserved. */
+    getTileBoundingBox(_context: {
+        viewState: TangramTraversalState;
+    }, index: TileCoordinates): GeographicTileBounds;
+    /** Original per-eye projection dispatch and explicit footprint handling. */
+    private selectEye;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,293 @@
+import type { Device, RenderPass } from '@luma.gl/core';
+import type { DecodedTileStatistics } from "./sources/decoded_tile_store.js";
+import type { GlobeVisibilityLODAdapter, VisibilityLODAdapter } from './scene/visibility_adapter.js';
+export type Matrix4 = readonly number[] | Float32Array | Float64Array;
+export type Vector3 = readonly [number, number, number];
+export type SceneDefinition = string | Record<string, unknown> | readonly SceneDefinition[];
+/** Minimal CRS options accepted by a caller-owned math.gl-compatible projection factory. */
+export interface ProjectionEngineOptions {
+    /** Source CRS, supplied by Tangram as geographic degrees. */
+    from?: string;
+    /** Destination CRS, supplied by Tangram as north-positive projected meters. */
+    to?: string;
+}
+/** Compiled projection surface used for packed worker mesh coordinates. */
+export interface ProjectionEngineTransform {
+    /** Project packed coordinates in place, preserving their typed-array representation. */
+    projectFlatSync(coordinates: Float64Array, dimension?: number): Float64Array;
+}
+/** Structural subset of math.gl's factory; ordinary consumers need not install the optional peer. */
+export interface ProjectionEngine {
+    /** Compile an independent transform synchronously. */
+    createProjection(options?: ProjectionEngineOptions): ProjectionEngineTransform;
+    /** Compile a transform after loading any registered lazy projection implementations. */
+    createProjectionAsync(options?: ProjectionEngineOptions): Promise<ProjectionEngineTransform>;
+}
+export type Viewport = {
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+};
+export type GeographicAnchor = {
+    longitude: number;
+    latitude: number;
+    altitude?: number;
+    zoom: number;
+};
+/** Geographic projection used by host-provided positions and camera matrices. */
+export type HostProjection = {
+    /** Worker-projected flat common coordinates; requires an explicit geographic footprint. */
+    type: 'projected';
+    /** Ordered unwrapped footprint in degrees; tile selection remains Web Mercator XYZ. */
+    visibleBounds: readonly [number, number, number, number];
+} | {
+    type: 'web-mercator';
+    /** Explicit unwrapped geographic footprint; null means no visible ground, omitted uses camera/legacy bounds. */
+    visibleBounds?: readonly [number, number, number, number] | null;
+} | {
+    type: 'globe';
+    /** Conservative footprint enclosing ground and elevated content: west, south, east, north. */
+    visibleBounds: readonly [number, number, number, number];
+    /**
+     * Conservative maximum rendered elevation in geographic meters above the reference sphere.
+     * Zero declares a surface-only scene. Omitted means unknown and disables horizon rejection.
+     * Includes terrain, extrusion, offsets and shader displacement; never inferred from camera altitude.
+     */
+    maxElevation?: number;
+};
+export type HostCamera = {
+    view: Matrix4;
+    projection: Matrix4;
+    position: Vector3;
+};
+export type HostRenderView = {
+    id?: string;
+    viewport?: Viewport;
+    camera: HostCamera;
+    /** Optional per-eye footprint anchor; scene/style state still uses the shared anchor. */
+    geographicAnchor?: GeographicAnchor;
+    /** Optional per-eye geographic bounds for union visibility. */
+    projection?: HostProjection;
+};
+/** Opt-in uniform data LOD estimated from projected surface scale across all eyes. */
+export type HostTileLODOptions = {
+    /** Target projected tile edge in device pixels; defaults to 512. */
+    targetTilePixels?: number;
+    /** Device pixels per viewport CSS pixel; defaults to 1. */
+    pixelRatio?: number;
+    /** Buffered candidate visits across eyes, before deduplication; defaults to 256. */
+    maxTiles?: number;
+    /** Zoom-level dead band around transitions; defaults to 0.2. */
+    hysteresis?: number;
+};
+/** Opt-in worker scheduling and completed off-screen mesh cache limits, shared by all eyes. */
+export type HostTileResourceOptions = {
+    /** Maximum concurrently submitted tile builds across sources; positive integer, omitted is unlimited. */
+    maxConcurrentBuilds?: number;
+    /** Maximum completed off-screen cache entries; non-negative integer, omitted is unlimited. */
+    maxCachedTiles?: number;
+    /** Cached vertex/index bytes, including globe variants and pending labels; non-negative integer. */
+    maxCachedMeshBytes?: number;
+};
+/** Detached renderer resource accounting; textures, CPU data and driver overhead are not included. */
+export type TileResourceStatistics = {
+    /** Tile builds submitted to workers, not individual network requests. */
+    activeBuilds: number;
+    /** Source/style tile builds waiting for a scheduling slot. */
+    queuedBuilds: number;
+    /** All retained tiles, including visible/proxy/preload and incomplete builds. */
+    residentTiles: number;
+    /** Completed tiles eligible for cache eviction. */
+    cachedTiles: number;
+    /** Vertex/index bytes owned by evictable tiles. */
+    cachedMeshBytes: number;
+    /** Tiles protected from resource-policy eviction. */
+    protectedTiles: number;
+    /** Vertex/index bytes owned by protected tiles. */
+    protectedMeshBytes: number;
+};
+/** Worker-local decoded acquisition accounting, separate from scene-wide mesh-build statistics. */
+export type TileSourceStatistics = DecodedTileStatistics & {
+    /** Index of the worker in the scene's current worker pool. */
+    workerId: number;
+    /** False for workers with external source scripts; custom pipelines always bypass sharing. */
+    sharingEnabled: boolean;
+    /** Present only for the opt-in projected worker; separate from decoded-source and GPU residency. */
+    projectionPreparation?: import("./procedures/mesh-projector.js").MeshPreparationStatistics;
+    /** Optional cumulative CPU projection/refinement work, reset when the worker source lifecycle resets. */
+    projectionWork?: import("./procedures/mesh-projector.js").MeshProjectionStatistics;
+};
+/** CSS-pixel query coordinates and view routing for asynchronous feature selection. */
+export interface FeatureSelectionOptions {
+    /** Non-negative CSS-pixel search radius. */
+    radius?: number;
+    /** Explicit eye/view identity; omitted canvas queries choose the last overlapping view. */
+    renderViewId?: string;
+    /** Default view-local pixels, or full-target top-origin CSS pixels for stereo routing. */
+    coordinateSpace?: 'view' | 'canvas';
+}
+/** Asynchronous selection of a built-in worker feature or an application-defined payload. */
+export type FeatureSelectionResult = {
+    /** Cloneable metadata from the worker; null/undefined means no hit. */
+    feature?: unknown;
+    /** Whether the selected feature differs from the previous completed query. */
+    changed?: boolean;
+    /** Caller-requested top-origin CSS pixel, in the selected coordinate space. */
+    pixel?: {
+        x: number;
+        y: number;
+    };
+    /** View/eye used for the query; pixel remains in the caller's requested coordinate space. */
+    renderViewId?: string;
+    /** Readback, cancellation or worker failure, preserving Scene's result contract. */
+    error?: unknown;
+};
+export type HostFrameOptions = {
+    viewport: Viewport;
+    geographicAnchor: GeographicAnchor;
+    projection?: HostProjection;
+    renderViews: readonly HostRenderView[];
+    activeRenderViewId?: string;
+    tileBuffer?: number;
+    /** Optional shared data-tile zoom (integer 0–22, no higher than the shared style zoom). */
+    tileZoom?: number;
+    /** Automatic shared data LOD; mutually exclusive with tileZoom. */
+    tileLOD?: HostTileLODOptions;
+    /** Opt-in scheduling/cache policy shared by every render view and source. */
+    tileResources?: HostTileResourceOptions;
+    /** Retain a global coarse level for globe loading gaps; integer 0–3, omitted disables preloading. */
+    globePreloadZoom?: number;
+    /** Shared elapsed scene animation time in seconds. */
+    animationTime?: number;
+};
+export type LegacyHostFrame = {
+    viewport: Viewport;
+    view: GeographicAnchor;
+    projection?: HostProjection;
+    camera: HostCamera;
+    tileBuffer?: number;
+    /** Optional shared data-tile zoom; omission preserves zoom-driven selection. */
+    tileZoom?: number;
+    /** Opt-in projected-scale data LOD. */
+    tileLOD?: HostTileLODOptions;
+    /** Opt-in scheduling/cache policy; omission restores unlimited scheduling/cache defaults. */
+    tileResources?: HostTileResourceOptions;
+    /** Optional bounded global globe fallback level, integer 0–3. */
+    globePreloadZoom?: number;
+    /** Shared elapsed scene animation time in seconds. */
+    animationTime?: number;
+};
+export type RendererOptions = {
+    /** Opt-in worker-side physical terrain displacement; provider loading remains host-owned. */
+    terrain?: import("./procedures/terrain-draping.js").TerrainDrapingOptions;
+    /** Optional application-owned admission pool shared with terrain source/preparation owners. Captured at creation; never sent to workers. */
+    terrainResourceBudget?: import("./map-logic/terrain-resource-budget.js").TerrainResourceBudget;
+    /** Optional caller-owned CRS factory for CPU-projected basemaps; ordinary Mercator/globe cameras are unchanged. */
+    projectionEngine?: ProjectionEngine;
+    /** Host kernel chunking policy; captured at renderer creation and independent of worker/build budgets. */
+    projectionEngineExecution?: import("./procedures/projection-batch-executor.js").ProjectionExecutionOptions;
+    device?: Device;
+    /** Optional worker script URL; otherwise the package uses its embedded worker. */
+    workerURL?: string;
+    /** Renderer-owned policy for viewport bounds and tile visibility/LOD. */
+    visibilityAdapter?: VisibilityLODAdapter;
+    /** Renderer-owned policy for selecting tiles for globe projection bounds. */
+    globeVisibilityAdapter?: GlobeVisibilityLODAdapter;
+    canvas?: HTMLCanvasElement | OffscreenCanvas;
+    requestRedraw?: () => void;
+    numWorkers?: number;
+    /** Positive safe integer limit for shared built-in tile loads in each worker; omitted is unlimited. */
+    maxConcurrentTileLoadsPerWorker?: number;
+    logLevel?: import("./utils/log.js").LogLevel;
+    highDensityDisplay?: boolean;
+    introspection?: boolean;
+    [option: string]: unknown;
+};
+export type SceneLoadOptions = {
+    base_path?: string;
+    file_type?: string;
+    blocking?: boolean;
+    [option: string]: unknown;
+};
+export type SceneUpdateOptions = {
+    loading?: boolean;
+    rebuild?: boolean | Record<string, unknown>;
+    serialize_funcs?: boolean;
+    texture_nodes?: import("./scene/scene-resource-types.js").SceneTextureNodes;
+    normalize?: boolean;
+    fade_in?: boolean;
+};
+export type SceneDataSource = {
+    type: string;
+    /** Required provider credit HTML for the host to display safely. */
+    attribution?: string;
+    url?: string;
+    tilejson?: string | Record<string, unknown>;
+    data?: unknown;
+    [property: string]: unknown;
+};
+export type SceneFeature = {
+    id?: string | number;
+    properties: Record<string, unknown>;
+    geometry?: Record<string, unknown>;
+    [property: string]: unknown;
+};
+export type SceneQueryOptions = {
+    filter?: unknown;
+    unique?: boolean | string | readonly string[];
+    group_by?: string | readonly string[] | null;
+    visible?: boolean | null;
+    geometry?: boolean;
+};
+export type SceneScreenshot = {
+    url: string;
+    blob: Blob;
+    type: 'png';
+};
+export type RenderOptions = {
+    frame?: HostFrameOptions | LegacyHostFrame;
+    renderPass?: RenderPass | null;
+    renderViewId?: string;
+    force?: boolean;
+};
+export type SceneConfigEvent = {
+    config: Record<string, unknown>;
+};
+export type SceneErrorEvent = {
+    type?: string;
+    message?: string;
+    error?: unknown;
+    [property: string]: unknown;
+};
+export type SceneEventMap = {
+    load: [event: SceneConfigEvent];
+    update: [event: SceneConfigEvent];
+    pre_update: [willRender: boolean];
+    post_update: [willRender: boolean];
+    view_complete: [event: {
+        first: boolean;
+    }];
+    error: [event: SceneErrorEvent];
+    warning: [event: SceneErrorEvent];
+    move: [];
+};
+export type SceneListener<EventName extends keyof SceneEventMap = keyof SceneEventMap> = (...arguments_: SceneEventMap[EventName]) => void;
+export type SceneListeners = {
+    [EventName in keyof SceneEventMap]?: SceneListener<EventName>;
+} & {
+    [event: string]: ((...arguments_: never[]) => void) | undefined;
+};
+export type WorkerRequest<Message = unknown> = {
+    type: 'main_send' | 'worker_send';
+    message_id: number;
+    method: string;
+    message: Message;
+};
+export type WorkerResponse<Message = unknown> = {
+    type: 'main_reply' | 'worker_reply';
+    message_id: number;
+    message?: Message;
+    error?: string;
+};
+export type WorkerBrokerMessage<Message = unknown> = WorkerRequest<Message> | WorkerResponse<Message>;

package/dist/types/utils/geo.d.ts

@@ -0,0 +1,57 @@
+export type Coordinate = number[];
+export type Meters = {
+    x: number;
+    y: number;
+};
+export type Tile = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type Bounds = {
+    sw: Meters;
+    ne: Meters;
+};
+export type Geometry = {
+    type: string;
+    coordinates: unknown;
+};
+export type Transform = (coordinate: Coordinate) => void;
+interface GeoNamespace {
+    default_source_max_zoom: number;
+    default_view_max_zoom: number;
+    max_style_zoom: number;
+    tile_size: number;
+    half_circumference_meters: number;
+    circumference_meters: number;
+    min_zoom_meters_per_pixel: number;
+    tile_scale: number;
+    units_per_pixel: number;
+    height_scale: number;
+    metersPerPixel(z: number): number;
+    metersPerTile(z: number): number;
+    unitsPerMeter(z: number): number;
+    metersForTile(tile: Tile): Meters;
+    tileForMeters(coordinates: Coordinate, zoom: number): Tile;
+    wrapTile(tile: Tile, mask?: {
+        x: boolean;
+        y: boolean;
+    }): Tile;
+    metersToLatLng(coordinates: Coordinate): Coordinate;
+    latLngToMeters(coordinates: Coordinate): Coordinate;
+    tileSpaceToLatlng(geometry: Geometry, z: number, min: Meters): Geometry;
+    copyGeometry(geometry: Geometry | null): Geometry | undefined;
+    transformGeometry(geometry: Geometry | null, transform: Transform): void;
+    boxIntersect(first: Bounds, second: Bounds): boolean;
+    findBoundingBox(polygon: Coordinate[][]): [number, number, number, number];
+    geometryType(type: string): 'point' | 'line' | 'polygon' | undefined;
+    centroid(polygon: Coordinate[][], relative?: boolean): Coordinate | undefined;
+    multiCentroid(polygons: Coordinate[][][]): Coordinate | null;
+    signedPolygonRingAreaSum(ring: Coordinate[]): number;
+    polygonRingArea(ring: Coordinate[]): number;
+    polygonArea(polygon: Coordinate[][] | null): number | undefined;
+    multiPolygonArea(polygons: Coordinate[][][]): number;
+    ringWinding(ring: Coordinate[]): 'CW' | 'CCW' | undefined;
+}
+export declare const Geo: GeoNamespace;
+export default Geo;

package/dist/types/utils/hash.d.ts

@@ -0,0 +1 @@
+export default function hashString(string: string): number;

package/dist/types/utils/log.d.ts

@@ -0,0 +1,27 @@
+import type { BrokerWorker } from "./worker-types.js";
+declare const LEVELS: {
+    readonly silent: -1;
+    readonly error: 0;
+    readonly warn: 1;
+    readonly info: 2;
+    readonly debug: 3;
+    readonly trace: 4;
+};
+/** Supported renderer log levels. */
+export type LogLevel = keyof typeof LEVELS;
+/** Per-message renderer logging options. */
+export type LogOptions = {
+    level: LogLevel;
+    once?: boolean;
+};
+/** Renderer logger with shared level and worker controls. */
+export interface Logger {
+    (options: LogLevel | LogOptions, ...messages: unknown[]): Promise<boolean>;
+    level: LogLevel;
+    workers: BrokerWorker[] | null;
+    setLevel(level: LogLevel): void;
+    setWorkers?(workers: BrokerWorker[] | null): void;
+    reset?(): void;
+}
+declare const log: Logger;
+export default log;

package/dist/types/utils/props.d.ts

@@ -0,0 +1,6 @@
+type PropertyTarget = Record<PropertyKey, unknown>;
+export type PropertyPath = readonly PropertyKey[];
+export declare function getPropertyPath(object: object, path: PropertyPath): unknown;
+export declare function setPropertyPath(object: object, path: PropertyPath, value: unknown): void;
+export declare function getPropertyPathTarget(object: object, path: PropertyPath): PropertyTarget | undefined;
+export {};

package/dist/types/utils/subscribe.d.ts

@@ -0,0 +1,10 @@
+export type EventListener = (...data: unknown[]) => void;
+export type EventListeners = Record<string, EventListener | unknown>;
+export type SubscriptionMethods = {
+    subscribe(listener: EventListeners): void;
+    unsubscribe(listener: EventListeners): void;
+    unsubscribeAll(): void;
+    trigger(event: string, ...data: unknown[]): void;
+    hasSubscribersFor(event: string): boolean;
+};
+export default function subscribeMixin<Target extends object>(target: Target): Target & SubscriptionMethods;

package/dist/types/utils/thread.d.ts

@@ -0,0 +1,6 @@
+export type ThreadState = {
+    is_worker: boolean;
+    is_main: boolean;
+};
+declare const Thread: ThreadState;
+export default Thread;

package/dist/types/utils/urls.d.ts

@@ -0,0 +1,26 @@
+type URLParameters = Record<string, string | number | boolean | null | undefined>;
+type ObjectURLSource = Blob | MediaSource;
+type URLResult = [string, Array<[string, URLParameters[string]]>];
+/** Adds a base origin to a relative URL. */
+export declare function addBaseURL(url: string, base?: string): string;
+/** An omitted resource URL remains omitted, rather than acquiring a base path. */
+export declare function addBaseURL(url: string | undefined, base?: string): string | undefined;
+/** Returns the directory path portion of a URL. */
+export declare function pathForURL(url: string | object | null | undefined): string;
+/** Returns the filename extension portion of a URL. */
+export declare function extensionForURL(url: string): string | undefined;
+/** Returns whether a URL uses a local data or blob scheme. */
+export declare function isLocalURL(url: unknown): boolean;
+/** Returns whether a URL is relative to its current document. */
+export declare function isRelativeURL(url: unknown): boolean;
+/** Resolves dot-directory components in a relative URL path. */
+export declare function flattenRelativeURL(url: string): string;
+/** Adds query parameters and returns any parameters already present in the URL. */
+export declare function addParamsToURL(url: string, params?: URLParameters): URLResult;
+/** Creates a blob URL, using the vendor-prefixed fallback when necessary. */
+export declare function createObjectURL(url: ObjectURLSource): string | ObjectURLSource;
+/** Revokes a blob URL, using the vendor-prefixed fallback when necessary. */
+export declare function revokeObjectURL(url: string): string | undefined;
+/** Finds the URL of the current script or a matching script element. */
+export declare function findCurrentURL(...paths: string[]): string | undefined;
+export {};

package/dist/types/utils/utils.d.ts

@@ -0,0 +1,26 @@
+import type { TransferEnvelope } from "./worker-types.js";
+type ControlPoint = [number, number | number[]];
+type InterpolationTransform = (value: number) => number;
+type RequestHeaders = Record<string, string>;
+type RequestResponse = {
+    body: string | ArrayBuffer | null;
+    status: number;
+};
+interface UtilsApi {
+    isSafari(): boolean;
+    isMicrosoft(): boolean;
+    _requests: Record<string, XMLHttpRequest>;
+    _proxy_requests: Record<string, boolean>;
+    /** Main-thread proxy calls return an envelope; remote worker calls unwrap the response. */
+    io<Proxy extends boolean = false>(url: string, timeout?: number, responseType?: XMLHttpRequestResponseType, method?: string, headers?: RequestHeaders, request_key?: string | null, proxy?: Proxy): Promise<Proxy extends false ? RequestResponse : RequestResponse | TransferEnvelope<[RequestResponse]>>;
+    cancelRequest(key: string): void | Promise<unknown>;
+    serializeWithFunctions(obj: unknown): string | undefined;
+    use_high_density_display: boolean;
+    device_pixel_ratio?: number;
+    updateDevicePixelRatio(): boolean;
+    isPowerOf2(value: number): boolean;
+    interpolate(x: number, points: ControlPoint[] | unknown, transform?: InterpolationTransform): unknown;
+    toCSSColor(color: number[] | null | undefined): string | undefined;
+}
+declare const Utils: UtilsApi;
+export default Utils;

package/dist/types/utils/version.d.ts

@@ -0,0 +1,2 @@
+declare const _default: string;
+export default _default;

package/dist/types/utils/worker-types.d.ts

@@ -0,0 +1,68 @@
+/** Worker transport surface; registration still requires a native Worker. */
+export type BrokerWorker = Pick<Worker, 'postMessage' | 'addEventListener'>;
+/** Remote method name and optional serialization for non-cloneable log arguments. */
+export type BrokerMethod = string | {
+    method: string;
+    stringify?: boolean;
+};
+/** Invocation crossing the main/worker boundary. Arguments are not known to the transport. */
+export interface BrokerInvocation {
+    type: 'main_send' | 'worker_send';
+    message_id: number;
+    method: string;
+    message: unknown[];
+    /** Optional diagnostic target supplied by older callers. */
+    target?: string;
+}
+/** Reply crossing the main/worker boundary. Truthy errors reject the pending invocation. */
+export interface BrokerReply {
+    type: 'main_reply' | 'worker_reply';
+    message_id: number;
+    message?: unknown;
+    error?: unknown;
+}
+/** Wire packet, decoded once at the transport boundary. */
+export type BrokerPacket = BrokerInvocation | BrokerReply;
+/** Promise callbacks retained until a reply arrives. */
+export interface PendingBrokerMessage {
+    method: string;
+    message: unknown[];
+    resolve(value: unknown): void;
+    reject(error: unknown): void;
+}
+/** Buffer and its original owner, used for legacy post-transfer cleanup. */
+export interface BrokerTransferable {
+    object: ArrayBuffer;
+    parent: object | null;
+    property: string | number | null;
+}
+/** Tuple of remote arguments or the single result wrapped for buffer transfer. */
+export interface TransferEnvelope<Values extends unknown[] = unknown[]> {
+    value: Values;
+    transferables: BrokerTransferable[];
+}
+/** The legacy wrapper supports both ordinary calls and construction. */
+export interface TransferEnvelopeFactory {
+    <Values extends unknown[]>(...value: Values): TransferEnvelope<Values>;
+    new <Values extends unknown[]>(...value: Values): TransferEnvelope<Values>;
+}
+/** Thread-specific invocation overloads; the caller supplies its remote result contract. */
+export interface BrokerPostMessage {
+    <Result = unknown>(workers: BrokerWorker[], method: BrokerMethod, ...message: unknown[]): Promise<Result[]>;
+    <Result = unknown>(worker: BrokerWorker, method: BrokerMethod, ...message: unknown[]): Promise<Result>;
+    <Result = unknown>(method: BrokerMethod, ...message: unknown[]): Promise<Result>;
+}
+/** Staged broker object shared with the logger during circular module initialization. */
+export interface WorkerBrokerApi {
+    targets: Record<string, unknown>;
+    addTarget(name: string, target: unknown): void;
+    removeTarget(name: string): void;
+    postMessage: BrokerPostMessage;
+    /** Installed on the main thread only. */
+    addWorker(worker: Worker): void;
+    /** Main-thread debugging access to pending invocations. */
+    getMessages(): Record<number, PendingBrokerMessage>;
+    /** Main-thread debugging access to the next invocation identifier. */
+    getMessageId(): number;
+    withTransferables: TransferEnvelopeFactory;
+}

package/dist/types/utils/worker_broker.d.ts

@@ -0,0 +1,3 @@
+import type { WorkerBrokerApi } from "./worker-types.js";
+export declare const WorkerBroker: WorkerBrokerApi;
+export default WorkerBroker;