@honua/app-platform 0.1.0-beta.0 → 0.1.1-beta.0

package/source-capability-registry.d.ts

@@ -0,0 +1 @@
+export { isRegisteredCapabilityProfile, matchesRegisteredCapabilityProfileSource } from "@honua/sdk/internal/source-capability-profile-verifier";

package/source-capability-registry.js

@@ -0,0 +1 @@
+export { isRegisteredCapabilityProfile, matchesRegisteredCapabilityProfileSource } from "@honua/sdk/internal/source-capability-profile-verifier";

package/source-capability-types.d.ts

@@ -0,0 +1,186 @@
+import type { JsonValue, ResolvedCrsDefinition, SourceProtocol } from "./contract/schema.js";
+import type { Capability as BuiltInCapabilityId } from "./contract/types.js";
+export declare const CAPABILITY_EVIDENCE_PROFILE_KIND: "honua.capability-evidence";
+export declare const CAPABILITY_EVIDENCE_PROFILE_VERSION: "1.0";
+export declare const CAPABILITY_EVIDENCE_FINGERPRINT_DOMAIN: "honua:capability-evidence:1.0";
+export declare const CAPABILITY_SOURCE_ENDPOINT_FINGERPRINT_DOMAIN: "honua:capability-source-endpoint:1.0";
+export declare const CAPABILITY_PROFILE_KIND: "honua.capabilities";
+export declare const CAPABILITY_PROFILE_VERSION: "1.0";
+export declare const CAPABILITY_PROFILE_FINGERPRINT_DOMAIN: "honua:capabilities:1.0";
+export type ExtensionIdentifier = `${string}.${string}`;
+export type Sha256 = `sha256:${string}`;
+export type IsoInstant = string;
+export type CapabilityId = BuiltInCapabilityId | ExtensionIdentifier;
+export type CapabilityTruth = "supported" | "unsupported" | "unknown";
+export type ObservedCapabilityTruth = CapabilityTruth | "not-observed";
+export type CapabilityClaimEvidenceKind = "protocol-default" | "declaration";
+export type CapabilityObservationEvidenceKind = "metadata" | "conformance" | "probe";
+export type CapabilityEvidenceKind = CapabilityClaimEvidenceKind | CapabilityObservationEvidenceKind;
+interface CapabilityEvidenceBase {
+    readonly truth: CapabilityTruth;
+    /**
+     * Stable evidence identity. Common credential-shaped forms are rejected, but
+     * callers must still treat accepted values as potentially sensitive and must
+     * not supply credentials, signed URLs, or secrets.
+     */
+    readonly reference: string;
+    /** Evidence identity only; when present it must match the enclosing source profile. */
+    readonly sourceFingerprint?: Sha256;
+}
+export interface CapabilityClaimEvidence extends CapabilityEvidenceBase {
+    readonly kind: CapabilityClaimEvidenceKind;
+    readonly observedAt?: never;
+    readonly expiresAt?: never;
+}
+export interface CapabilityObservationEvidence extends CapabilityEvidenceBase {
+    readonly kind: CapabilityObservationEvidenceKind;
+    readonly observedAt: IsoInstant;
+    /** Exclusive freshness boundary. */
+    readonly expiresAt: IsoInstant;
+}
+export type CapabilityEvidence = CapabilityClaimEvidence | CapabilityObservationEvidence;
+export type TopologicalSpatialPredicate = "equals" | "intersects" | "within" | "contains" | "disjoint" | "touches" | "overlaps" | "crosses";
+export type DistanceSpatialPredicate = "within-distance" | "beyond-distance";
+export type SpatialPredicate = TopologicalSpatialPredicate | "bbox-intersects" | DistanceSpatialPredicate;
+export type TemporalPredicate = "before" | "after" | "during" | "time-intersects";
+export type BuiltInFilterOperator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "between" | "is-null" | "is-not-null" | "like" | "and" | "or" | "not" | SpatialPredicate | TemporalPredicate;
+export type FilterOperatorId = BuiltInFilterOperator | ExtensionIdentifier;
+export type PaginationMode = "offset" | "cursor" | "next-link";
+export type ExtensionMap = Readonly<Record<ExtensionIdentifier, JsonValue>>;
+export interface CapabilityConstraints {
+    readonly inputFormats?: readonly string[];
+    readonly outputFormats?: readonly string[];
+    readonly filterOperators?: readonly FilterOperatorId[];
+    readonly spatialPredicates?: readonly SpatialPredicate[];
+    readonly temporalPredicates?: readonly TemporalPredicate[];
+    readonly supportedCrs?: readonly ResolvedCrsDefinition[];
+    readonly pagination?: {
+        readonly modes: readonly PaginationMode[];
+        readonly maxPageSize?: number;
+    };
+    readonly limits?: {
+        readonly maxRecords?: number;
+        readonly maxRequestBytes?: number;
+        readonly maxResponseBytes?: number;
+    };
+    /** Caller metadata. Sensitive keys/forms are rejected; credentials remain prohibited. */
+    readonly extensions?: ExtensionMap;
+}
+export type CapabilityRuntimeEnvironment = "browser" | "worker" | "node" | "edge" | ExtensionIdentifier;
+/**
+ * Credential-free source endpoint coordinates used only to derive a digest.
+ * Query strings, fragments, URL user-info, and credential-shaped source ids
+ * are rejected before hashing and the raw coordinates are never transported.
+ */
+export interface CapabilitySourceEndpointIdentity {
+    readonly endpoint: string;
+    readonly protocol: SourceProtocol;
+    readonly sourceId?: string;
+}
+/** Static execution requirements retained in evidence and evaluated decisions. */
+export interface CapabilityRequirements {
+    readonly environments?: readonly CapabilityRuntimeEnvironment[];
+    /** Structural package/runtime identifiers; credential values are prohibited. */
+    readonly peers?: readonly string[];
+}
+/** One normalized, cacheable claimed/observed entry. */
+export interface CapabilityEvidenceEntry {
+    readonly id: CapabilityId;
+    readonly claimed: CapabilityTruth;
+    readonly observed: ObservedCapabilityTruth;
+    readonly evidence: readonly CapabilityEvidence[];
+    /** Structural scope identifiers only. Tokens and credentials are prohibited. */
+    readonly authorizationScopes?: readonly string[];
+    readonly constraints?: CapabilityConstraints;
+    readonly requirements?: CapabilityRequirements;
+}
+/** @deprecated Use {@link CapabilityEvidenceEntry}. */
+export type CapabilityEvaluationEntry = CapabilityEvidenceEntry;
+export interface CapabilityEvidenceProfileOptions {
+    /** SourceSchemaV2 SHA-256 identity. May be derived only from consistent evidence. */
+    readonly sourceFingerprint?: Sha256;
+    /** Required credential-free endpoint coordinates; only their derived digest is retained. */
+    readonly sourceEndpoint: CapabilitySourceEndpointIdentity;
+}
+export interface CapabilitySourceVerificationOptions {
+    /** Current SourceSchemaV2 SHA-256 identity. Must be paired with expectedSourceEndpoint. */
+    readonly expectedSourceFingerprint?: Sha256;
+    /** Current credential-free endpoint coordinates. Must be paired with expectedSourceFingerprint. */
+    readonly expectedSourceEndpoint?: CapabilitySourceEndpointIdentity;
+}
+/** Heavy, one-time validated transport/cache envelope for one source. */
+export interface CapabilityEvidenceProfile {
+    readonly kind: typeof CAPABILITY_EVIDENCE_PROFILE_KIND;
+    readonly version: typeof CAPABILITY_EVIDENCE_PROFILE_VERSION;
+    readonly fingerprint: Sha256;
+    /** Required SourceSchemaV2 identity for cache invalidation and source binding. */
+    readonly sourceFingerprint: Sha256;
+    /** Required digest of normalized protocol/endpoint/source coordinates. */
+    readonly sourceEndpointFingerprint: Sha256;
+    readonly entries: readonly CapabilityEvidenceEntry[];
+}
+/** Dynamic policy for the canonical claimed/observed/effective evaluator. */
+export interface CapabilityEvaluationPolicy {
+    /** Optional allow-list. An omitted list allows every evidence-supported entry. */
+    readonly allow?: readonly CapabilityId[];
+    /** Explicit deny-list. Denial wins when an id appears in both lists. */
+    readonly deny?: readonly CapabilityId[];
+}
+export interface CapabilityAuthorizationContext {
+    /** Structural scope identifiers; credential/token values are prohibited. */
+    readonly grantedScopes?: readonly string[];
+    /** Scopes the current principal is known not to be allowed to acquire. */
+    readonly deniedScopes?: readonly string[];
+}
+/** Dynamic inputs refreshed for each lightweight evaluation. */
+export interface CapabilityEvaluationContext {
+    /** Explicit deterministic clock input. Omission makes observation freshness unknown. */
+    readonly evaluatedAt?: IsoInstant;
+    readonly policy?: CapabilityEvaluationPolicy;
+    readonly environment?: CapabilityRuntimeEnvironment;
+    /** Structural package/runtime identifiers; credential values are prohibited. */
+    readonly availablePeers?: readonly string[];
+    readonly authorization?: CapabilityAuthorizationContext;
+}
+/**
+ * Normalized caller-controlled context retained so transported decisions can
+ * be reverified. It is not a sanitizer; profiles remain potentially sensitive.
+ */
+export interface CapabilityEvaluationContextSnapshot {
+    readonly policy?: {
+        readonly allow?: readonly CapabilityId[];
+        readonly deny: readonly CapabilityId[];
+    };
+    readonly environment?: CapabilityRuntimeEnvironment;
+    readonly availablePeers: readonly string[];
+    readonly authorization: {
+        readonly grantedScopes: readonly string[];
+        readonly deniedScopes: readonly string[];
+    };
+}
+export type EffectiveCapabilityState = "supported" | "unsupported" | "unknown" | "policy-disabled" | "peer-unavailable" | "authorization-required" | "authorization-denied";
+/** Stable codes; suffixed forms name the missing environment, peer, or scope. */
+export type CapabilityDecisionReason = "supported-by-claim-and-observation" | "unsupported-by-claim" | "unsupported-by-observation" | "claim-unknown" | "observation-unknown" | "observation-not-observed" | "freshness-not-evaluated" | "evidence-not-yet-current" | "evidence-stale" | "policy-disabled" | `environment-unavailable:${string}` | `peer-unavailable:${string}` | `authorization-required:${string}` | `authorization-denied:${string}`;
+export interface CapabilityDecision extends CapabilityEvidenceEntry {
+    readonly effective: EffectiveCapabilityState;
+    readonly reasons: readonly CapabilityDecisionReason[];
+}
+/**
+ * Auditable evaluated truth derived from one evidence envelope and one dynamic
+ * context. Caller-controlled values make serialized profiles potentially sensitive.
+ */
+export interface CapabilityProfile {
+    readonly kind: typeof CAPABILITY_PROFILE_KIND;
+    readonly version: typeof CAPABILITY_PROFILE_VERSION;
+    readonly fingerprint: Sha256;
+    readonly evidenceFingerprint: Sha256;
+    readonly sourceFingerprint: Sha256;
+    readonly sourceEndpointFingerprint: Sha256;
+    readonly evaluatedAt: IsoInstant | null;
+    /** Exclusive conservative boundary; null means no freshness window was established. */
+    readonly validUntil: IsoInstant | null;
+    readonly context: CapabilityEvaluationContextSnapshot;
+    readonly entries: readonly CapabilityDecision[];
+}
+export {};
+//# sourceMappingURL=source-capability-types.d.ts.map

package/source-capability-types.js

@@ -0,0 +1,7 @@
+export const CAPABILITY_EVIDENCE_PROFILE_KIND = "honua.capability-evidence";
+export const CAPABILITY_EVIDENCE_PROFILE_VERSION = "1.0";
+export const CAPABILITY_EVIDENCE_FINGERPRINT_DOMAIN = "honua:capability-evidence:1.0";
+export const CAPABILITY_SOURCE_ENDPOINT_FINGERPRINT_DOMAIN = "honua:capability-source-endpoint:1.0";
+export const CAPABILITY_PROFILE_KIND = "honua.capabilities";
+export const CAPABILITY_PROFILE_VERSION = "1.0";
+export const CAPABILITY_PROFILE_FINGERPRINT_DOMAIN = "honua:capabilities:1.0";

package/style/index.d.ts

@@ -22,4 +22,6 @@ export { isHonuaSource, isFeatureServiceSource, isMapServiceSource, isOgcFeature
 export type { HonuaSourceBase, HonuaFeatureServiceSourceSpecification, HonuaMapServiceSourceSpecification, HonuaOgcFeaturesSourceSpecification, HonuaWmsSourceSpecification, HonuaWmtsSourceSpecification, HonuaSourceSpecification, HonuaLayerSpecification, HonuaStyleSpecification, ParsedOgcFeaturesUrl, StyleValidationError, } from "./specification.js";
 export { createSources } from "./factory.js";
 export type { ResolvedSource } from "./factory.js";
+export { classBreaksRenderer, clusterRenderer, heatmapRenderer, isRenderer, rendererFromJSON, uniqueValueRenderer, } from "./renderers.js";
+export type { ClassBreakEntry, ClassBreaksRenderer, ClassBreaksRendererDescriptor, ClassBreaksRendererOptions, ClusterRenderer, ClusterRendererDescriptor, ClusterRendererOptions, ClusterStep, HeatmapColorStop, HeatmapRenderer, HeatmapRendererDescriptor, HeatmapRendererOptions, Renderer, RendererDescriptor, RendererGeometryType, RendererLayerFragment, RendererLegendItem, RendererStyle, UniqueValueEntry, UniqueValueRenderer, UniqueValueRendererDescriptor, UniqueValueRendererOptions, } from "./renderers.js";
 //# sourceMappingURL=index.d.ts.map

package/style/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/style/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,eAAe,EACf,sCAAsC,EACtC,kCAAkC,EAClC,mCAAmC,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/style/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,eAAe,EACf,sCAAsC,EACtC,kCAAkC,EAClC,mCAAmC,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,6BAA6B,EAC7B,0BAA0B,EAC1B,eAAe,EACf,yBAAyB,EACzB,sBAAsB,EACtB,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,yBAAyB,EACzB,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC"}

package/style/index.js

@@ -20,5 +20,7 @@
  */
 export { isHonuaSource, isFeatureServiceSource, isMapServiceSource, isOgcFeaturesSource, isWmsSource, isWmtsSource, parseOgcFeaturesUrl, validateHonuaStyle, } from "./specification.js";
 export { createSources } from "./factory.js";
+// First-class renderer objects (issue #497). All @experimental.
+export { classBreaksRenderer, clusterRenderer, heatmapRenderer, isRenderer, rendererFromJSON, uniqueValueRenderer, } from "./renderers.js";
 // Feature Service and Map Service URL parsers are exported from
 // esri-compat/url.ts via the main index.ts barrel — no re-export needed here.

package/style/renderers.d.ts

@@ -0,0 +1,326 @@
+/**
+ * First-class renderer objects (issue #497): serializable, renderer-neutral
+ * descriptions of smart-mapping styles (class breaks, unique values, heatmap,
+ * clustering) that compile deterministically to MapLibre style fragments
+ * through the `/expr` builder.
+ *
+ * A renderer object is a pure value: construct it from options (or revive it
+ * from JSON with {@link rendererFromJSON}), read legend metadata with
+ * `legendItems()`, and compile MapLibre layer fragments with
+ * `toMapLibre(geometryType)`. Compilation is a pure function of the
+ * descriptor — no caching, no map access — so the same descriptor always
+ * produces byte-identical style JSON.
+ *
+ * The WebMap JSON converter (`src/webmap/convert-renderer.ts`) and the
+ * esri-compat renderer shims emit these objects instead of private
+ * transforms, so there is exactly one class-breaks/unique-value compiler in
+ * the SDK.
+ *
+ * @module
+ */
+import { type Expr } from "../expr/expression.js";
+/** Coarse geometry classification a renderer compiles against. @experimental */
+export type RendererGeometryType = "point" | "line" | "polygon";
+/**
+ * Advanced multi-property style override for one renderer class. When
+ * present it replaces the single `color` shorthand and may carry any
+ * MapLibre paint/layout properties (this is how WebMap symbols round-trip
+ * through renderer objects without loss).
+ *
+ * @experimental
+ */
+export interface RendererStyle {
+    readonly paint?: Readonly<Record<string, unknown>>;
+    readonly layout?: Readonly<Record<string, unknown>>;
+}
+/**
+ * One MapLibre layer fragment compiled from a renderer. `paint`/`layout`
+ * values are plain MapLibre style JSON (expressions included) that
+ * `map.addLayer` accepts verbatim; the caller owns layer ids and source
+ * wiring.
+ *
+ * @experimental
+ */
+export interface RendererLayerFragment {
+    /**
+     * Which part of the renderer this fragment draws. Single-layer renderers
+     * emit one `"symbolizer"` fragment; the cluster renderer emits
+     * `"clusters"`, `"cluster-count"`, and `"unclustered"` fragments.
+     */
+    readonly role: "symbolizer" | "clusters" | "cluster-count" | "unclustered";
+    /** MapLibre layer type (`circle`, `line`, `fill`, `heatmap`, `symbol`). */
+    readonly type: string;
+    readonly paint: Record<string, unknown>;
+    readonly layout: Record<string, unknown>;
+    /** Optional MapLibre filter expression the fragment requires. */
+    readonly filter?: unknown;
+}
+/**
+ * One legend entry derived from a renderer descriptor. This is a stable
+ * contract (issue #497 REQ-005): `label` and `color` are always present;
+ * `value` is set for unique-value entries, `minValue`/`maxValue` for ranged
+ * entries (class breaks, cluster steps), and heatmap stops carry the ramp
+ * position in `value`.
+ *
+ * @experimental
+ */
+export interface RendererLegendItem {
+    readonly kind: "class-break" | "unique-value" | "heatmap-stop" | "cluster-step" | "default";
+    readonly label: string;
+    /** CSS color for the legend swatch. */
+    readonly color: string;
+    readonly value?: string | number | boolean | null;
+    readonly minValue?: number;
+    readonly maxValue?: number;
+}
+/** Union of the serializable renderer descriptors. @experimental */
+export type RendererDescriptor = ClassBreaksRendererDescriptor | UniqueValueRendererDescriptor | HeatmapRendererDescriptor | ClusterRendererDescriptor;
+/** Union of the four renderer object kinds. @experimental */
+export type Renderer = ClassBreaksRenderer | UniqueValueRenderer | HeatmapRenderer | ClusterRenderer;
+interface RendererBase<D extends RendererDescriptor> {
+    readonly kind: D["kind"];
+    /** Serializable descriptor — `rendererFromJSON(renderer.toJSON())` revives it. */
+    toJSON(): D;
+    /** Legend metadata derived from the descriptor (stable contract, REQ-005). */
+    legendItems(): readonly RendererLegendItem[];
+    /** Compile MapLibre layer fragments for one geometry kind. Pure and deterministic. */
+    toMapLibre(geometry: RendererGeometryType): readonly RendererLayerFragment[];
+}
+/** One graduated class. @experimental */
+export interface ClassBreakEntry {
+    /** Inclusive lower bound; used as the MapLibre `step` threshold (`min ?? max`). */
+    readonly min?: number;
+    readonly max?: number;
+    /** Swatch color shorthand; positional `colors` apply when omitted. */
+    readonly color?: string;
+    readonly label?: string;
+    /** Advanced multi-property override; replaces the color shorthand. */
+    readonly style?: RendererStyle;
+}
+/** Options for {@link classBreaksRenderer}. @experimental */
+export interface ClassBreaksRendererOptions {
+    /** Numeric feature property driving the classification. */
+    readonly field: string;
+    /** Ordered class breaks (ascending thresholds). */
+    readonly breaks: readonly ClassBreakEntry[];
+    /** Positional palette applied to breaks without an explicit `color`. */
+    readonly colors?: readonly string[];
+    /** Color for values below the first threshold (and legend default swatch). */
+    readonly defaultColor?: string;
+    readonly defaultLabel?: string;
+    /** Advanced default override; replaces `defaultColor`. */
+    readonly defaultStyle?: RendererStyle;
+    /** Force a MapLibre layer type instead of deriving it from geometry. */
+    readonly layerType?: string;
+}
+/** Serializable class-breaks descriptor. @experimental */
+export interface ClassBreaksRendererDescriptor extends ClassBreaksRendererOptions {
+    readonly kind: "class-breaks";
+}
+/** Class-breaks renderer object. @experimental */
+export interface ClassBreaksRenderer extends RendererBase<ClassBreaksRendererDescriptor> {
+}
+/**
+ * Create a graduated (class-breaks) renderer: a `step` expression over a
+ * numeric field.
+ *
+ * @example
+ * ```ts
+ * const renderer = classBreaksRenderer({
+ *   field: "magnitude",
+ *   breaks: [
+ *     { min: 0, max: 3, label: "Minor" },
+ *     { min: 3, max: 5, label: "Moderate" },
+ *     { min: 5, label: "Strong" },
+ *   ],
+ *   colors: ["#fed976", "#fd8d3c", "#b10026"],
+ *   defaultColor: "#cccccc",
+ * });
+ * const [fragment] = renderer.toMapLibre("point");
+ * // fragment.paint["circle-color"] → ["step", ["get", "magnitude"], "#cccccc", 0, "#fed976", …]
+ * ```
+ *
+ * @experimental
+ */
+export declare function classBreaksRenderer(options: ClassBreaksRendererOptions): ClassBreaksRenderer;
+/** One categorical class. @experimental */
+export interface UniqueValueEntry {
+    readonly value: string | number | boolean;
+    readonly color?: string;
+    readonly label?: string;
+    /** Advanced multi-property override; replaces the color shorthand. */
+    readonly style?: RendererStyle;
+}
+/** Options for {@link uniqueValueRenderer}. @experimental */
+export interface UniqueValueRendererOptions {
+    /** Feature property driving the categories. */
+    readonly field: string;
+    /** Optional second/third fields concatenated with `fieldDelimiter`. */
+    readonly field2?: string;
+    readonly field3?: string;
+    /** Delimiter for multi-field matching. @default "," */
+    readonly fieldDelimiter?: string;
+    readonly values: readonly UniqueValueEntry[];
+    /** Fallback color for unmatched values (and legend default swatch). */
+    readonly defaultColor?: string;
+    readonly defaultLabel?: string;
+    /** Advanced default override; replaces `defaultColor`. */
+    readonly defaultStyle?: RendererStyle;
+    /** Force a MapLibre layer type instead of deriving it from geometry. */
+    readonly layerType?: string;
+}
+/** Serializable unique-value descriptor. @experimental */
+export interface UniqueValueRendererDescriptor extends UniqueValueRendererOptions {
+    readonly kind: "unique-value";
+}
+/** Unique-value renderer object. @experimental */
+export interface UniqueValueRenderer extends RendererBase<UniqueValueRendererDescriptor> {
+}
+/**
+ * Create a categorical (unique-value) renderer: a `match` expression over a
+ * feature property (or a delimited concatenation of up to three).
+ *
+ * @example
+ * ```ts
+ * const renderer = uniqueValueRenderer({
+ *   field: "priority",
+ *   values: [
+ *     { value: "high", color: "#b91c1c", label: "High priority" },
+ *     { value: "low", color: "#0f766e", label: "Low priority" },
+ *   ],
+ *   defaultColor: "#334155",
+ * });
+ * renderer.legendItems(); // [{ kind: "unique-value", label: "High priority", … }, …]
+ * ```
+ *
+ * @experimental
+ */
+export declare function uniqueValueRenderer(options: UniqueValueRendererOptions): UniqueValueRenderer;
+/** One kernel-density ramp stop (density is 0..1). @experimental */
+export interface HeatmapColorStop {
+    readonly stop: number;
+    readonly color: string;
+}
+/** Options for {@link heatmapRenderer}. @experimental */
+export interface HeatmapRendererOptions {
+    /** Numeric property weighting each point (defaults to weight 1). */
+    readonly weightField?: string;
+    /** Kernel radius in pixels. @default 30 */
+    readonly radius?: number;
+    /** Global intensity multiplier. @default 1 */
+    readonly intensity?: number;
+    /** Layer opacity (0..1). */
+    readonly opacity?: number;
+    /**
+     * Density → color ramp. Either explicit stops or a color list spread
+     * evenly across 0..1 (the first color should usually be transparent).
+     */
+    readonly colorRamp?: readonly HeatmapColorStop[] | readonly string[];
+}
+/** Serializable heatmap descriptor. @experimental */
+export interface HeatmapRendererDescriptor extends HeatmapRendererOptions {
+    readonly kind: "heatmap";
+}
+/** Heatmap renderer object. @experimental */
+export interface HeatmapRenderer extends RendererBase<HeatmapRendererDescriptor> {
+}
+/**
+ * Create a MapLibre-native heatmap renderer. Compiles to a single `heatmap`
+ * layer fragment regardless of the requested geometry (heatmaps render
+ * point data).
+ *
+ * @experimental
+ */
+export declare function heatmapRenderer(options?: HeatmapRendererOptions): HeatmapRenderer;
+/** One cluster size class (thresholds are feature counts). @experimental */
+export interface ClusterStep {
+    /** Inclusive minimum count for this class; the first step is the base class. */
+    readonly threshold: number;
+    readonly color: string;
+    /** Cluster circle radius in pixels. Defaults to `14 + 6 * index`. */
+    readonly radius?: number;
+    readonly label?: string;
+}
+/** Options for {@link clusterRenderer}. @experimental */
+export interface ClusterRendererOptions {
+    /** Cluster radius in pixels (GeoJSON source `clusterRadius`). @default 50 */
+    readonly radius?: number;
+    /** Max zoom to cluster at (GeoJSON source `clusterMaxZoom`). @default 14 */
+    readonly maxZoom?: number;
+    /**
+     * Numeric property summed per cluster instead of the raw point count.
+     * Adds a `<countField>_sum` cluster property and drives the step/count
+     * expressions from it.
+     */
+    readonly countField?: string;
+    /** Ascending count classes driving cluster color/size. */
+    readonly steps: readonly ClusterStep[];
+    /** Style for unclustered points. @default "#16735b" */
+    readonly unclusteredColor?: string;
+    /** @default 5 */
+    readonly unclusteredRadius?: number;
+}
+/** Serializable cluster descriptor. @experimental */
+export interface ClusterRendererDescriptor extends ClusterRendererOptions {
+    readonly kind: "cluster";
+}
+/** Cluster renderer object. @experimental */
+export interface ClusterRenderer extends RendererBase<ClusterRendererDescriptor> {
+    /**
+     * GeoJSON source options enabling MapLibre-native clustering
+     * (`cluster`, `clusterRadius`, `clusterMaxZoom`, `clusterProperties`).
+     * Merge these into the GeoJSON source spec that feeds the layers.
+     */
+    toMapLibreSource(): Record<string, unknown>;
+}
+/**
+ * Create a MapLibre-native cluster renderer. Compiles to three fragments —
+ * cluster circles, cluster count labels, and unclustered points — plus
+ * GeoJSON source cluster options via {@link ClusterRenderer.toMapLibreSource}.
+ *
+ * @experimental
+ */
+export declare function clusterRenderer(options: ClusterRendererOptions): ClusterRenderer;
+/**
+ * Revive a renderer object from its serializable descriptor
+ * (`renderer.toJSON()` output).
+ *
+ * @experimental
+ */
+export declare function rendererFromJSON(descriptor: RendererDescriptor): Renderer;
+/** True when a value looks like a renderer object from this module. @experimental */
+export declare function isRenderer(value: unknown): value is Renderer;
+/**
+ * MapLibre properties that live in `layout` rather than `paint`. Shared with
+ * the WebMap converter so both route properties identically.
+ *
+ * @internal
+ */
+export declare const RENDERER_LAYOUT_PROPERTIES: ReadonlySet<string>;
+/** Resolved per-class style used by the shared compiler. @internal */
+export interface ResolvedRendererStyle {
+    readonly paint: Record<string, unknown>;
+    readonly layout: Record<string, unknown>;
+}
+/** One class entry for the shared compiler. @internal */
+export interface DataDrivenStyleEntry {
+    /** Match value (unique value) or step threshold (class breaks). */
+    readonly key: unknown;
+    readonly style: ResolvedRendererStyle;
+}
+/**
+ * The single class-breaks/unique-value property compiler (issue #497
+ * REQ-002). For every paint/layout property present on any class it builds
+ * one `match` (categorical) or `step` (graduated) expression through the
+ * `/expr` builder. When `defaultStyle` is omitted the first entry's style
+ * provides per-property defaults; missing values fall back to
+ * `"transparent"`.
+ *
+ * @internal
+ */
+export declare function compileDataDrivenStyle(mode: "match" | "step", input: Expr<unknown>, entries: readonly DataDrivenStyleEntry[], defaultStyle: ResolvedRendererStyle | undefined): {
+    paint: Record<string, unknown>;
+    layout: Record<string, unknown>;
+};
+export {};
+//# sourceMappingURL=renderers.d.ts.map

package/style/renderers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderers.d.ts","sourceRoot":"","sources":["../../../src/style/renderers.ts"],"names":[],"mappings":"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"}