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

package/src/styles/polygons/polygons_wgsl.ts

@@ -0,0 +1,127 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import Geo from '../../utils/geo';
+import {GLOBE_PROJECTION_WGSL, GLOBE_NORMAL_WGSL, TERRAIN_DRAPING_WGSL, TERRAIN_GLOBE_ATTRIBUTES_WGSL} from '../../scene/projection_shaders';
+import {buildLightingWGSL} from '../../lights/lighting-wgsl';
+
+const LAYER_DELTA = 1 / (1 << 14);
+
+/**
+ * Build the portable polygon shader used by the luma.gl WebGPU renderer.
+ *
+ * Tangram's existing GLSL shader composer remains authoritative for WebGL.
+ * This deliberately small WGSL program establishes the native-device path for
+ * flat polygons and raster tiles before the remaining style features are ported.
+ */
+export function buildPolygonsWGSL({ raster = false, lighting, lightCount, cpuProjection = false, terrain = false, selection = false }: {
+    /** Physical ground displacement and slope normals from worker attributes. */
+    terrain?: boolean;
+    /** Emit the worker selection key without lighting or color blending. */
+    selection?: boolean;
+    /** Include raster color sampling. */
+    raster?: boolean;
+    /** Opt into configured lights; undefined retains historical portable wall shading. */
+    lighting?: 'vertex' | 'fragment' | false;
+    /** Active scene light count, used to specialize shader compilation. */
+    lightCount?: number;
+    /** Use worker-projected common positions while retaining tile-local UVs. */
+    cpuProjection?: boolean;
+} = {}) {
+    const raster_declarations = raster ? `
+@group(0) @binding(3) var u_rasters: texture_2d<f32>;
+@group(0) @binding(4) var u_rastersSampler: sampler;
+` : '';
+    const raster_fragment = raster ? `
+    // Tangram's raster images are uploaded without a WebGL Y flip on WebGPU,
+    // so use top-left texture coordinates for the tile-local geometry.
+    let raster_color = textureSample(u_rasters, u_rastersSampler, input.raster_uv);
+    var color = input.color * raster_color;
+` : '    var color = input.color;\n';
+    const configured = lighting === 'vertex' || lighting === 'fragment';
+    const shade = lighting === 'fragment' ? 'color = tangramCalculateLighting(input.eye_position, normalize(input.normal), color);' :
+        lighting === 'vertex' ? 'color *= input.lighting;' : '';
+
+    return `
+${raster_declarations}
+${GLOBE_PROJECTION_WGSL}
+${GLOBE_NORMAL_WGSL}
+${terrain ? TERRAIN_DRAPING_WGSL : ''}
+${configured ? buildLightingWGSL(lightCount) : ''}
+struct PolygonAttributes {
+    ${terrain ? TERRAIN_GLOBE_ATTRIBUTES_WGSL : ''}
+    ${terrain ? '@location(14) a_terrain: vec4<f32>, @location(15) a_terrain_previous: vec4<f32>,' : ''}
+    @location(0) a_position: vec4<${terrain ? 'f32' : 'i32'}>,
+    @location(1) a_normal: vec4<f32>,
+    @location(2) a_color: vec4<f32>,
+    ${selection ? '@location(5) a_selection_color: vec4<f32>,' : ''}
+    ${cpuProjection ? '@location(3) a_projected_position: vec3<f32>, @location(4) a_projected_normal: vec3<f32>,' : ''}
+};
+
+struct PolygonVaryings {
+    @builtin(position) position: vec4<f32>,
+    @location(0) color: vec4<f32>,
+    @location(1) raster_uv: vec2<f32>,
+    @location(2) normal: vec3<f32>,
+    @location(3) eye_position: vec3<f32>,
+    @location(4) lighting: vec4<f32>,
+    @location(5) tile_position: vec2<f32>,
+    ${selection ? '@location(6) @interpolate(flat) selection_color: vec4<f32>,' : ''}
+};
+
+@vertex
+fn vertexMain(attributes: PolygonAttributes) -> PolygonVaryings {
+    var output: PolygonVaryings;
+    ${selection ? 'output.selection_color = attributes.a_selection_color;' : ''}
+    let local_position = vec4<f32>(
+        f32(attributes.a_position.x),
+        f32(attributes.a_position.y),
+        f32(attributes.a_position.z) / ${Geo.height_scale}.0 ${terrain ? '+ tangramTerrainHeight(attributes.a_terrain, attributes.a_terrain_previous)' : ''},
+        1.0
+    );
+    let eye_position = ${cpuProjection ? 'vec4<f32>(attributes.a_projected_position, 1.0)' : terrain ? 'tangramTerrainModelView(local_position, attributes.a_terrain, attributes.a_terrain_previous, attributes.a_terrain_globe_base, attributes.a_terrain_globe_relief, attributes.a_terrain_globe_base_previous, attributes.a_terrain_globe_relief_previous)' : 'tangramModelView(local_position)'};
+    var clip_position = TangramCamera.u_projection * eye_position;
+    ${cpuProjection ? '// deck orthographic matrices use WebGL [-w, w] depth; WebGPU requires [0, w].\n    clip_position.z = (clip_position.z + clip_position.w) * 0.5;' : ''}
+    let layer = f32(attributes.a_position.w) +
+        TangramTile.u_tile_proxy_order_offset + 1.0;
+    clip_position.z -= layer * ${cpuProjection ? LAYER_DELTA * 0.5 : LAYER_DELTA} * clip_position.w;
+
+    var surface_normal = normalize(attributes.a_normal.xyz);
+    ${terrain ? 'surface_normal = tangramTerrainNormal(surface_normal, attributes.a_terrain, attributes.a_terrain_previous, vec2<f32>(attributes.a_position.xy));' : ''}
+    if (TangramView.u_projection_mode == 1) {
+        let world_position = TangramTile.u_model * local_position;
+        surface_normal = tangramGlobeNormal(world_position.xyz, surface_normal);
+    }
+    ${configured ? `else { surface_normal = normalize(TangramTile.u_normalMatrix * surface_normal); }` : ''}
+    ${cpuProjection ? 'surface_normal = normalize(attributes.a_projected_normal);' : ''}
+    let light_direction = normalize(vec3<f32>(0.35, -0.45, 0.82));
+    let diffuse = max(dot(surface_normal, light_direction), 0.0);
+    // Roof/wall classification stays local; geographic north is not surface up.
+    let side_amount = 1.0 - smoothstep(0.8, 0.98, abs(normalize(attributes.a_normal.xyz).z));
+    let light = mix(1.0, 0.58 + 0.52 * diffuse, side_amount);
+
+    output.position = clip_position;
+    output.tile_position = local_position.xy;
+    output.normal = surface_normal;
+    output.eye_position = eye_position.xyz - TangramCamera.u_eye;
+    output.lighting = ${lighting === 'vertex' ? 'tangramCalculateLighting(output.eye_position, surface_normal, vec4<f32>(1.0))' : 'vec4<f32>(1.0)'};
+    output.color = ${lighting === undefined ? 'vec4<f32>(attributes.a_color.rgb * light, attributes.a_color.a)' : 'attributes.a_color'};
+    output.raster_uv = vec2<f32>(
+        f32(attributes.a_position.x) / ${Geo.tile_scale}.0,
+        -f32(attributes.a_position.y) / ${Geo.tile_scale}.0
+    );
+    return output;
+}
+
+@fragment
+fn fragmentMain(input: PolygonVaryings) -> @location(0) vec4<f32> {
+    if (TangramTile.u_tile_clip_bounds.z > TangramTile.u_tile_clip_bounds.x &&
+        (any(input.tile_position < TangramTile.u_tile_clip_bounds.xy) ||
+         any(input.tile_position >= TangramTile.u_tile_clip_bounds.zw))) { discard; }
+${raster_fragment}
+    ${shade}
+    return ${selection ? 'input.selection_color' : 'color'};
+}
+`;
+}

package/src/styles/property-types.ts

@@ -0,0 +1,125 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Feature data available to dynamic scene expressions. */
+export interface StyleFeature {
+    id?: string | number;
+    geometry: {type: string};
+    properties: Record<string, unknown>;
+}
+
+/** Tile conversions used when constructing a feature evaluation context. */
+export interface StyleParseTile {
+    style_z: number;
+    meters_per_pixel: number;
+    meters_per_pixel_sq: number;
+    units_per_meter_overzoom: number;
+}
+
+/** Context may be partial for static expressions; feature evaluation supplies all required fields. */
+export interface PropertyContext {
+    zoom?: number;
+    feature?: StyleFeature;
+    layers?: string[];
+    global?: unknown;
+    [name: string]: unknown;
+}
+
+/** Dynamic values are intentionally unknown until the owning property parser normalizes them. */
+export type PropertyFunction = ((context: PropertyContext) => unknown) & {source?: string};
+
+/** Mutable cache shared by static, dynamic, and zoom-interpolated scene properties. */
+export interface PropertyCache {
+    /** Original or once-normalized property; dynamic results are not stored here. */
+    value: unknown;
+    /** Legacy cache category, populated during construction. */
+    type?: number;
+    /** Lazily evaluated static value (including falsy values). */
+    static?: unknown;
+    /** Lazily interpolated results keyed by style zoom. */
+    zoom?: Record<number, unknown> | null;
+    /** Compiled per-feature evaluator, installed on first evaluation. */
+    dynamic?: PropertyFunction;
+    /** Optional post-evaluation normalization for dynamic values. */
+    dynamic_transform?: ((value: unknown) => unknown) | null;
+    /** Whether authored string colors have been normalized within zoom stops. */
+    zoom_preprocessed?: boolean;
+}
+
+/** Coordinate/value stop consumed by the legacy interpolation procedure. */
+export type PropertyStop = [number, unknown];
+
+/** Unit value normalized before distance interpolation. */
+export interface UnitValue {
+    value: number | number[];
+    units?: 'px';
+}
+
+/** Texture/sprite metadata used for percent and aspect-ratio sizing. */
+export interface PointSizeImage {
+    sprite?: string;
+    css_size: number[];
+    aspect: number;
+}
+
+/** Per-stop flags retain the legacy scalar/array representation. */
+export type PointSizeFlags = (boolean | boolean[])[];
+
+/** Point sizes using image-relative percentages or an automatic dimension. */
+export interface PointSizeCache extends PropertyCache {
+    /** Percentage flags matching the original scalar/vector stop shape. */
+    has_pct?: PointSizeFlags | null;
+    /** Aspect-ratio flags matching the original scalar/vector stop shape. */
+    has_ratio?: PointSizeFlags | null;
+    /** Independent evaluated caches keyed by sprite name. */
+    sprites?: Record<string, PropertyCache | undefined>;
+    /** Evaluated cache for an entire texture rather than a named sprite. */
+    texture?: PropertyCache;
+}
+
+/** A one-time property normalization, with its zoom-stop index. */
+export type PropertyTransform = (value: unknown, index: number) => unknown;
+
+/** Checked callable surface of the incrementally initialized legacy parser object. */
+export interface StyleParserRuntime {
+    /** Retains Math.max coercion, including array results from legacy nested inputs. */
+    clampPositive(value: unknown): number;
+    noNaN(value: number): number;
+    parseNumber(value: unknown[]): number[];
+    parseNumber(value: string | number | boolean | null | undefined): number;
+    parseNumber(value: unknown): number | number[];
+    parsePositiveNumber(value: unknown[]): number[];
+    parsePositiveNumber(value: string | number | boolean | null | undefined): number;
+    parsePositiveNumber(value: unknown): number | number[];
+    /** Preserve NaN only for properties that validate their own numeric contract. */
+    wrapFunction(source: string | (() => number[]), preserveNaN?: boolean): string;
+    zeroPair: readonly [number, number];
+    defaults: {
+        color: number[]; width: number; size: number; extrude: boolean;
+        height: number; min_height: number; order: number; z: number;
+        outline: {color: number[]; width: number}; material: {ambient: number; diffuse: number};
+    };
+    macros: Record<string, () => number[]>;
+    CACHE_TYPE: {STATIC: number; DYNAMIC: number; ZOOM: number};
+    getFeatureParseContext(feature: StyleFeature, tile: StyleParseTile, global: unknown): PropertyContext & {feature: StyleFeature; zoom: number};
+    createPropertyCache(value: unknown, transform?: PropertyTransform | null, dynamicTransform?: ((value: unknown) => unknown) | null): PropertyCache | undefined;
+    createColorPropertyCache(value: unknown): PropertyCache | undefined;
+    createPointSizePropertyCache(value: unknown, texture?: unknown): PointSizeCache | undefined;
+    evalCachedPointSizeProperty(value: PointSizeCache | null | undefined, sprite: PointSizeImage | null | undefined, texture: PointSizeImage | null | undefined, context: PropertyContext): unknown;
+    evalCachedProperty(value: PropertyCache | null | undefined, context: PropertyContext): unknown;
+    convertUnits(value: unknown, context: PropertyContext): unknown;
+    parseUnits(value: unknown): UnitValue;
+    /** Cache projected annotation heights without legacy NaN-to-zero coercion. */
+    createProjectedHeightPropertyCache(value: unknown): PropertyCache | undefined;
+    /** Evaluate projected heights without swallowing dynamic expression errors. */
+    evalProjectedHeightProperty(value: PropertyCache | undefined, context: PropertyContext): unknown;
+    evalCachedDistanceProperty(value: PropertyCache | null | undefined, context: PropertyContext): unknown;
+    string_colors: Record<string, number[]>;
+    colorForString(value: string): number[];
+    evalCachedColorProperty(value: PropertyCache | null | undefined, context?: PropertyContext): number[] | undefined;
+    evalCachedColorPropertyWithAlpha(value: PropertyCache | null | undefined, alpha: PropertyCache | null | undefined, context: PropertyContext): unknown[] | undefined;
+    parseColor(value: unknown, context?: PropertyContext): number[];
+    calculateOrder(value: unknown, context: PropertyContext): unknown;
+    evalProperty(value: unknown, context: PropertyContext): unknown;
+}

package/src/styles/raster/raster.ts

@@ -0,0 +1,33 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Raster tile rendering style
+
+import StyleParser from '../style_parser';
+import {Polygons} from '../polygons/polygons';
+
+export let RasterStyle: any = Object.create(Polygons);
+
+Object.assign(RasterStyle, {
+    name: 'raster',
+    super: Polygons,
+    built_in: true,
+
+    init (this: any): void {
+        // Required for raster tiles
+        this.raster = this.raster || 'color';
+
+        this.super.init.apply(this, arguments);
+
+        this.selection = false; // raster styles can't support feature selection
+    },
+
+    _preprocess (this: any, draw: any): any {
+        // Raster tiles default to white vertex color, as this color will tint the underlying texture
+        draw.color = draw.color || (StyleParser as any).defaults.color;
+        return this.super._preprocess.apply(this, arguments);
+    }
+
+});

package/src/styles/raster/raster_globals.glsl

@@ -0,0 +1,46 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+// Uniforms defining raster textures and macros for accessing them
+
+#ifdef TANGRAM_FRAGMENT_SHADER
+uniform sampler2D u_rasters[TANGRAM_NUM_RASTER_SOURCES];    // raster tile texture samplers
+uniform vec2 u_raster_sizes[TANGRAM_NUM_RASTER_SOURCES];    // raster tile texture sizes (width/height in pixels)
+uniform vec3 u_raster_offsets[TANGRAM_NUM_RASTER_SOURCES];  // raster tile texture UV starting offset for tile
+
+// Raster sources can optionally mask by the alpha channel (render with only full or no alpha, based on a threshold),
+// which is used for handling transparency outside the raster image when rendering with opaque blending
+#if defined(TANGRAM_HAS_MASKED_RASTERS) && !defined(TANGRAM_ALL_MASKED_RASTERS) // only add uniform if we need it
+uniform bool u_raster_mask_alpha;
+#endif
+
+// Note: the raster accessors below are #defines rather than functions to
+// avoid issues with constant integer expressions for array indices
+
+// Adjusts UVs in model space to account for raster tile texture overzooming
+// (applies scale and offset adjustments)
+#define adjustRasterUV(raster_index, uv) \
+    ((uv) * u_raster_offsets[raster_index].z + u_raster_offsets[raster_index].xy)
+
+// Returns the UVs of the current model position for a raster sampler
+#define currentRasterUV(raster_index) \
+    (adjustRasterUV(raster_index, v_modelpos_base_zoom.xy))
+
+// Returns pixel location in raster tile texture at current model position
+#define currentRasterPixel(raster_index) \
+    (currentRasterUV(raster_index) * rasterPixelSize(raster_index))
+
+// Samples a raster tile texture for the current model position
+#define sampleRaster(raster_index) \
+    (texture2D(u_rasters[raster_index], currentRasterUV(raster_index)))
+
+// Samples a raster tile texture for a given pixel
+#define sampleRasterAtPixel(raster_index, pixel) \
+    (texture2D(u_rasters[raster_index], (pixel) / rasterPixelSize(raster_index)))
+
+// Returns size of raster sampler in pixels
+#define rasterPixelSize(raster_index) \
+    (u_raster_sizes[raster_index])
+
+#endif

package/src/styles/style-mixing-types.ts

@@ -0,0 +1,101 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TileBuildStyle} from '../tile/tile-build-types';
+import type {StyleGLOptions} from './style-runtime-types';
+import type UniformBuffer from '../gl/uniform_buffer';
+import type ShaderProgram from '../gl/shader_program';
+import type VBOMesh from '../gl/vbo_mesh';
+import type {MeshRenderOptions} from '../gl/mesh-types';
+
+/** Extensible shader customization before and after mixin evaluation. */
+export interface StyleShaderDefinition {
+    defines?: Record<string, unknown>;
+    attributes?: Record<string, unknown>;
+    uniforms?: Record<string, unknown>;
+    _uniforms?: Record<string, unknown>;
+    _uniform_scopes?: Record<string, string>;
+    extensions?: string | string[];
+    blocks?: Record<string, string | string[]>;
+    block_scopes?: Record<string, string | string[]>;
+}
+
+/** Authored/intermediate style configuration; abstract styles need no GPU lifecycle. */
+export interface StyleDefinition {
+    name?: string;
+    mix?: string | string[];
+    mixed?: Record<string, boolean>;
+    base?: string | null;
+    animated?: boolean;
+    texcoords?: boolean;
+    lighting?: string | boolean;
+    texture?: string;
+    raster?: string | boolean;
+    dash?: unknown;
+    dash_background_color?: unknown;
+    blend?: string | false;
+    blend_order?: number;
+    defines?: Record<string, unknown>;
+    material?: Record<string, unknown>;
+    draw?: Record<string, unknown>;
+    shaders?: StyleShaderDefinition;
+}
+
+/** Instantiated base/custom style surface consumed by the style manager. */
+export interface ManagedStyle extends StyleDefinition, TileBuildStyle {
+    /** Abstract styles with null bases are not admitted to this initialized registry. */
+    base?: string;
+    name: string;
+    main_thread_target: string;
+    resource_context?: unknown;
+    gl?: unknown;
+    init(scene?: import('./style-runtime-types').StyleInitOptions): void;
+    destroy(): void;
+    reset(): void;
+    /** Effective initialized blend mode; abstract styles never enter the draw registry. */
+    blend: 'opaque' | 'translucent' | 'add' | 'multiply' | 'inlay' | 'overlay';
+    /** Underlying built-in geometry implementation after mixins are resolved. */
+    baseStyle(): string;
+    /** Replace worker generation without reallocating style resources. */
+    setGeneration(generation: number): void;
+    /** Install host resource factories and the caller-owned drawing context. */
+    setGL(context: WebGLRenderingContext | null, blocks: Record<string, UniformBuffer>, options: StyleGLOptions): void;
+    /** Lazily compile the color or feature-selection program. */
+    getProgram(key: 'program' | 'selection_program'): ShaderProgram | undefined;
+    /** Optional feature-ID program is owned only by the style that created it. */
+    selection_program?: ShaderProgram | null;
+    /** Optional std140 material owner, retired with its style generation. */
+    portable_material_buffer?: UniformBuffer | null;
+    /** Bind style material and shader values for the currently active program. */
+    setup(): void;
+    /** Submit a retained mesh through the active classic or portable backend. */
+    render(mesh: VBOMesh, options: MeshRenderOptions): boolean;
+    /** Snapshot captured during worker initialization, absent for ordinary flat scenes. */
+    terrain?: import('../procedures/terrain-draping').TerrainDrapingSnapshot;
+    /** View-dependent worker ribbon target, separate from physical DEM identity. */
+    terrainRibbonZoom?: number;
+    /** Initialized shader owner and proxy stencil policy used by main scene passes. */
+    program?: ShaderProgram | null;
+    stencil_proxy_tiles?: boolean;
+}
+
+/** Shader mix state populated in stages without changing the original object shape. */
+export interface MixedStyleShaders extends StyleShaderDefinition {
+    defines: Record<string, unknown>;
+    attributes: Record<string, unknown>;
+    uniforms: Record<string, unknown>;
+    _uniforms: Record<string, unknown>;
+    _uniform_scopes: Record<string, string>;
+}
+
+/** Tile mesh metadata used for active styles and ascending blend passes. */
+export interface StyleManagerTile {
+    meshes: Record<string, {variant: {blend_order?: number}}[]>;
+}
+
+/** Styles sharing one mesh blend-order pass. */
+export interface ActiveStyleBlendOrder {
+    blend_order?: number;
+    styles: string[];
+}

package/src/styles/style-runtime-types.ts

@@ -0,0 +1,220 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type DataSource from '../sources/data_source';
+import type Material from '../lights/material';
+import type ShaderProgram from '../gl/shader_program';
+import type VertexLayout from '../gl/vertex_layout';
+import type VertexData from '../gl/vertex_data';
+import type UniformBuffer from '../gl/uniform_buffer';
+import type {UniformBufferOptions} from '../gl/uniform_buffer';
+import type {MeshOptions, MeshElementData} from '../gl/mesh-types';
+import type {TangramGPUSceneOptions} from '../gpu/tangram_gpu_backend';
+import type {TileMeshVariant, TileMeshPayload, LayerDebugCounts, WorkerBuildTile} from '../tile/tile-build-types';
+import type {PropertyCache, PropertyContext, StyleFeature} from './property-types';
+import type {GeometryMeshVariant} from './geometry-style-types';
+import type {SceneDefinition} from '../scene/scene-resource-types';
+import type {TerrainDrapingSnapshot} from '../procedures/terrain-draping';
+import type {ProjectedBasemapOptions} from '../procedures/mesh-projector';
+import type VBOMesh from '../gl/vbo_mesh';
+import type {MeshRenderOptions} from '../gl/mesh-types';
+import type {VertexAttribute} from '../gl/vertex-types';
+
+/** Worker geometry channels used by the base dispatcher and concrete styles. */
+export type BuildGeometry = import('./text/text-types').TextGeometry;
+/** Source-normalized feature with geometry available to the style dispatcher. */
+export interface BuildFeature extends StyleFeature {geometry: BuildGeometry;}
+/** Evaluator state includes tile ownership and matching authored layers. */
+export interface BuildContext extends PropertyContext {tile: StyleFinalizeTile & Pick<WorkerBuildTile, 'generation'> & {debug?: WorkerBuildTile['debug']}; layers?: string[];}
+/** Finalization requires tile address only when a projection or raster consumes it. */
+export type StyleFinalizeTile = Pick<WorkerBuildTile, 'id'> & Partial<Pick<WorkerBuildTile, 'coords' | 'min' | 'max' | 'style_z' | 'overzoom2' | 'rasters' | 'source' | 'key' | 'canceled'>>;
+/** Mutable draw group at the cache boundary; extension values remain unresolved. */
+export interface BuildDraw {
+    layers?: string[];
+    group?: string;
+    order?: unknown;
+    blend_order?: number;
+    preprocessed?: boolean;
+    interactive?: unknown;
+    attributes?: Record<string, unknown>;
+}
+/** Shared scratch values populated incrementally by concrete feature parsers. */
+export interface BuildFeatureStyle {
+    order?: unknown;
+    interactive?: unknown;
+    selection_color?: number[];
+    attributes?: Record<string, unknown>;
+}
+/** Authored material channels before the base lifecycle creates a Material owner. */
+export interface AuthoredStyleMaterial {
+    emission?: unknown;
+    ambient?: unknown;
+    diffuse?: unknown;
+    specular?: number | number[] | {amount?: number | number[]};
+    normal?: unknown;
+}
+/** A mesh is mutable while accumulating geometry, then owns transferable bytes. */
+export interface BuildMesh<Buffer extends VertexData | Uint8Array = VertexData> extends Omit<TileMeshPayload, 'vertex_data' | 'variant'> {
+    vertex_data: Buffer;
+    variant: GeometryMeshVariant & TileMeshVariant;
+}
+/** Per-tile style output shared by collision, raster loading, and serialization. */
+export interface BuildTileData<Buffer extends VertexData | Uint8Array = VertexData> extends MeshOptions {
+    meshes: Record<string, BuildMesh<Buffer>>;
+    uniforms: Record<string, unknown>;
+    textures: string[];
+}
+/** Configuration provided to inherited style initialization in either thread. */
+export interface StyleInitOptions {
+    generation?: number;
+    styles?: Record<string, import('./style-mixing-types').ManagedStyle> | null;
+    sources?: Record<string, DataSource>;
+    introspection?: boolean;
+    shader_language?: 'glsl' | 'wgsl';
+    config?: SceneDefinition | null;
+    projection_target?: string;
+    terrain?: TerrainDrapingSnapshot;
+    /** Host view zoom for canonical road geometry; independent of immutable DEM ownership. */
+    terrainRibbonZoom?: number;
+}
+/** Renderer hooks passed to the base resource lifecycle. */
+export interface StyleGLOptions extends Omit<Partial<TangramGPUSceneOptions>, 'enableUniformBuffers' | 'deviceShaderCompilation'> {
+    enableUniformBuffers?: boolean;
+    deviceShaderCompilation?: boolean;
+    resourceContext?: object;
+    uniformBlockFactory?: (options: UniformBufferOptions) => UniformBuffer;
+    deferUniformBlocks?: boolean;
+    deferTextureBindings?: boolean;
+    deferUniformUpdates?: boolean;
+    portableLightCount?: number;
+    portableLighting?: boolean;
+}
+/** Shader customization after style-manager mixin normalization. */
+export interface RuntimeStyleShaders {
+    defines?: Record<string, unknown>;
+    uniforms?: Record<string, unknown>;
+    attributes?: Record<string, {type?: string; varying?: boolean}>;
+    blocks?: Record<string, string[] | null>;
+    block_scopes?: Record<string, (string | null)[] | null>;
+    extensions?: string | string[];
+}
+/** State written by initialization and released by the inherited lifecycle. */
+export interface StyleState {
+    name: string;
+    base?: string;
+    generation: number | undefined;
+    styles: Record<string, import('./style-mixing-types').ManagedStyle> | null | undefined;
+    sources: Record<string, DataSource>;
+    shader_language: 'glsl' | 'wgsl';
+    projection_target?: string;
+    terrain?: TerrainDrapingSnapshot;
+    /** Host view zoom for canonical road width/offset refinement. */
+    terrainRibbonZoom?: number;
+    cpu_projection?: ProjectedBasemapOptions;
+    screen_space_labels: boolean;
+    defines: Record<string, unknown>;
+    shaders: RuntimeStyleShaders;
+    introspection: boolean;
+    selection: boolean;
+    compile_setup: boolean;
+    program: ShaderProgram | null;
+    selection_program: ShaderProgram | null;
+    feature_style: BuildFeatureStyle;
+    vertex_template: number[];
+    tile_data: Record<string | number, BuildTileData | null>;
+    stencil_proxy_tiles: boolean;
+    variants: Record<string | number, GeometryMeshVariant & TileMeshVariant>;
+    vertex_layouts: Record<string | number, VertexLayout>;
+    blend: 'opaque' | 'translucent' | 'add' | 'multiply' | 'inlay' | 'overlay';
+    blend_order?: number;
+    material: Material | AuthoredStyleMaterial;
+    lighting?: string | boolean;
+    raster?: string | boolean;
+    draw?: Record<string, unknown>;
+    initialized: boolean;
+    main_thread_target: string;
+    gl: WebGLRenderingContext | null;
+    resource_context: object | null;
+    uniform_blocks: Record<string, UniformBuffer> | null;
+    uniform_block_factory: StyleGLOptions['uniformBlockFactory'] | null;
+    shader_factory?: TangramGPUSceneOptions['shaderFactory'];
+    shader_program_validator?: TangramGPUSceneOptions['shaderProgramValidator'];
+    mesh_buffer_factory?: TangramGPUSceneOptions['meshBufferFactory'];
+    texture_factory?: TangramGPUSceneOptions['textureFactory'];
+    device_shader_compilation: boolean;
+    defer_uniform_blocks: boolean;
+    defer_texture_bindings: boolean;
+    defer_uniform_updates: boolean;
+    max_texture_size: number;
+    portable_material_buffer: UniformBuffer | null;
+    portable_lighting_mode?: 'vertex' | 'fragment' | false;
+    portable_light_count?: number;
+    vertex_shader_src: string;
+    fragment_shader_src: string;
+    getWGSLShaderSource?(selection?: boolean): string;
+}
+/** Concrete styles inherit these checked methods, retaining prototype ownership. */
+export type StyleRuntime = StyleState & StyleMethods;
+/** Checked inherited operations; concrete geometry hooks may return no value on the abstract base. */
+export interface StyleMethods {
+    init(options?: StyleInitOptions): void;
+    destroy(): void;
+    reset(): void;
+    baseStyle(): string;
+    setGeneration(generation: number | undefined): void;
+    startData(tile: Pick<WorkerBuildTile, 'id'>): void;
+    endData(tile: StyleFinalizeTile): Promise<BuildTileData<Uint8Array> | null>;
+    hasDataForTile(tile: Pick<WorkerBuildTile, 'id'>): boolean;
+    getTileMesh(tile: Pick<WorkerBuildTile, 'id'>, variant: GeometryMeshVariant & TileMeshVariant): BuildMesh;
+    vertexLayoutForMeshVariant(variant: TileMeshVariant | undefined): VertexLayout | undefined;
+    meshVariantTypeForDraw(draw: BuildDraw): (GeometryMeshVariant & TileMeshVariant) | undefined;
+    addFeature(feature: BuildFeature, draw: BuildDraw, context: BuildContext): void;
+    buildGeometry(geometry: BuildGeometry, style: BuildFeatureStyle, context: BuildContext): number | undefined;
+    parseFeature(feature: BuildFeature, draw: BuildDraw, context: BuildContext): BuildFeatureStyle | undefined;
+    _parseFeature(feature: BuildFeature, draw: BuildDraw, context: BuildContext): BuildFeatureStyle | undefined;
+    preprocess(draw: BuildDraw): BuildDraw | undefined;
+    _preprocess(draw: BuildDraw): BuildDraw | undefined;
+    parseOrder(order: unknown, context: PropertyContext): unknown;
+    scaleOrder(order: number): number;
+    parseColor(color: PropertyCache | null | undefined, context: PropertyContext): number[] | undefined;
+    buildPolygons(polygons: Extract<BuildGeometry, {type: 'MultiPolygon'}>['coordinates'], style: BuildFeatureStyle, context: BuildContext): number;
+    buildLines(lines: number[][][], style: BuildFeatureStyle, context: BuildContext): number;
+    buildPoints(points: number[][], style: BuildFeatureStyle, context: BuildContext): number;
+    setGL(context: WebGLRenderingContext | null, blocks?: Record<string, UniformBuffer>, options?: StyleGLOptions): void;
+    makeMesh(vertices: Uint8Array, elements: MeshElementData, options?: Partial<import('../tile/tile-build-types').TileStylePayload>): VBOMesh;
+    render(mesh: VBOMesh, options: MeshRenderOptions): boolean;
+    getProgram(key?: 'program' | 'selection_program'): ShaderProgram | undefined;
+    compileSetup(): void;
+    addShaderBlock(key: string, block: string, scope?: string | null): void;
+    removeShaderBlock(key: string): void;
+    replaceShaderBlock(key: string, block: string, scope?: string | null): void;
+    buildDefineList(): Record<string, unknown>;
+    hasRasters(): boolean;
+    setupRasters(): void;
+    buildRasterTextures(tile: StyleFinalizeTile, data: BuildTileData<Uint8Array>): Promise<BuildTileData<Uint8Array> | null>;
+    loadTextures(tile: RasterTextureTile): Promise<RasterTextureInfo[]>;
+    setupCustomAttributes(): void;
+    addCustomAttributesToAttributeList(attributes: VertexAttribute[]): VertexAttribute[];
+    addCustomAttributesToVertexTemplate(style: BuildFeatureStyle, offset: number): void;
+    setup(): void;
+    setUniforms(): void;
+    render_states: Record<StyleState['blend'], {depth_test: boolean; depth_write: boolean}>;
+    default_blend_orders: Record<StyleState['blend'], number>;
+    getBlendOrderForDraw(draw: {blend_order?: number}): number | undefined;
+}
+/** Serializable loaded raster metadata; no GPU object crosses the worker boundary. */
+export interface RasterTextureInfo {
+    name: string;
+    width: number;
+    height: number;
+    loaded: boolean;
+    index: number;
+    coords: {x: number; y: number; z: number};
+}
+/** Main-thread raster request carries geometry metadata, not a complete worker build. */
+export type RasterTextureTile = Pick<WorkerBuildTile, 'coords' | 'source' | 'min' | 'max'> & {rasters: string[]};
+/** Nested feature counters, with no GPU or tile ownership. */
+export type LayerDebugTree = Record<string, LayerDebugCounts>;
+/** Feature-local tree records which nodes have already contributed counters. */
+export interface CountedLayerTree {[name: string]: CountedLayerTree;}