@honua/react 0.1.0-beta.0 → 0.1.2-beta.0

package/runtime/terra-draw-sketch.js

@@ -0,0 +1,404 @@
+/**
+ * terra-draw binding for edit-sketch workflows.
+ *
+ * Adapts [terra-draw](https://terradraw.io) draw modes (point, linestring,
+ * polygon, rectangle, circle, freehand, select) to the renderer-neutral
+ * {@link EditSketchWorkflowModel}, so completed and edited geometries flow
+ * through the contract edit-session path — undo/redo, validation, and
+ * `applyEdits` submission all apply unchanged.
+ *
+ * terra-draw is an OPTIONAL peer dependency. This module never imports it at
+ * module scope: {@link bindTerraDrawSketch} accepts a duck-typed instance the
+ * app constructed itself, and {@link createTerraDrawSketch} pulls in
+ * `terra-draw` + `terra-draw-maplibre-gl-adapter` lazily via dynamic
+ * `import()` the first time it is called. Importing the SDK without terra-draw
+ * installed stays side-effect free.
+ *
+ * Snapping bridges through terra-draw's own pointer pipeline:
+ * {@link createTerraDrawSnapping} produces a function with terra-draw's
+ * `Snapping.toCustom` shape backed by the SDK {@link SnapIndex}, so the
+ * linestring / polygon / polyline modes snap against SDK-indexed features.
+ * Modes without a `snapping` option (point, rectangle, circle, freehand) keep
+ * terra-draw's native behavior; that seam is documented rather than papered
+ * over.
+ *
+ * @module
+ */
+import { resolveSnapCandidate, resolveSnappingConfig, } from "../contract/edit-snapping.js";
+// ── Tool / mode mapping ───────────────────────────────────────
+/**
+ * Canonical terra-draw mode for each {@link EditSketchTool}. `buffer` has no
+ * terra-draw equivalent (it needs geometry-service support) and maps to
+ * `undefined`.
+ *
+ * @experimental
+ */
+export const TERRA_DRAW_SKETCH_TOOL_MODES = Object.freeze({
+    point: "point",
+    line: "linestring",
+    polygon: "polygon",
+    rectangle: "rectangle",
+    circle: "circle",
+    buffer: undefined,
+});
+const MODE_TO_TOOL = Object.freeze({
+    point: "point",
+    marker: "point",
+    linestring: "line",
+    polyline: "line",
+    "freehand-linestring": "line",
+    polygon: "polygon",
+    freehand: "polygon",
+    sector: "polygon",
+    sensor: "polygon",
+    rectangle: "rectangle",
+    "angled-rectangle": "rectangle",
+    circle: "circle",
+});
+/**
+ * Map a terra-draw mode name to the {@link EditSketchTool} it produces.
+ * Freehand and sector/sensor modes draw polygons; marker draws points.
+ * Returns `undefined` for modes with no sketch-tool equivalent (`select`,
+ * `render`, `static`, custom modes).
+ *
+ * @experimental
+ */
+export function editSketchToolForTerraDrawMode(mode) {
+    return MODE_TO_TOOL[mode];
+}
+/**
+ * Sketch-tool capability overrides for a workflow driven by terra-draw.
+ *
+ * The contract defaults mark `rectangle` and `circle` as unsupported because
+ * they need renderer support; terra-draw provides it. Pass the registered
+ * terra-draw mode names (defaults to every canonical drawing mode) and feed
+ * the result to `createEditSketchWorkflow({ sketchTools })`.
+ *
+ * @experimental
+ */
+export function terraDrawSketchToolCapabilities(modes) {
+    const registered = new Set(modes ?? Object.keys(MODE_TO_TOOL));
+    const capabilities = {};
+    for (const tool of ["point", "line", "polygon", "rectangle", "circle"]) {
+        const supported = [...registered].some((mode) => MODE_TO_TOOL[mode] === tool);
+        capabilities[tool] = supported
+            ? "supported"
+            : { state: "unsupported", reason: `no terra-draw mode registered for the ${tool} tool` };
+    }
+    return capabilities;
+}
+/**
+ * Bind a terra-draw instance to an {@link EditSketchWorkflowModel} (REQ-001).
+ *
+ * Every terra-draw `finish` event (freshly drawn features and select-mode
+ * edits: dragged features, dragged/inserted/deleted coordinates) maps the
+ * finishing mode to an {@link EditSketchTool} and applies the feature geometry
+ * through `model.setSketchGeometry`, so workflow undo/redo and validation
+ * cover terra-draw edits. Deleting the tracked feature stages a `null`
+ * geometry through the same undoable path.
+ *
+ * The caller owns the terra-draw instance lifecycle (`start`/`stop`); the
+ * binding only attaches listeners and detaches them in `remove()`.
+ *
+ * @example
+ * ```ts
+ * const workflow = createEditSketchWorkflow({ source, sketchTools: terraDrawSketchToolCapabilities() });
+ * const handle = bindTerraDrawSketch(draw, { model: workflow });
+ * handle.setTool("polygon");        // draw.setMode("polygon") + workflow arming
+ * // ... user draws; workflow.snapshot().sketch.geometry now tracks terra-draw
+ * handle.undo();                    // workflow history, mirrored back into terra-draw
+ * await workflow.submit();          // edit-session applyEdits path, unchanged
+ * ```
+ *
+ * @experimental
+ */
+export function bindTerraDrawSketch(draw, options) {
+    const { model } = options;
+    const toolForMode = options.toolForMode ?? editSketchToolForTerraDrawMode;
+    const toolsByFeature = new Map();
+    let activeFeatureId;
+    let selectedFeatureId;
+    let syncing = false;
+    const featureById = (id) => draw.getSnapshotFeature?.(id) ?? draw.getSnapshot().find((feature) => feature.id === id);
+    const onFinish = (id, context) => {
+        if (syncing)
+            return;
+        const feature = featureById(id);
+        const mode = modeOf(feature, context);
+        const tool = toolForMode(mode);
+        const included = feature === undefined || (options.featureFilter?.(id, feature) ?? true);
+        let applied = false;
+        let geometry = null;
+        if (feature && tool && included) {
+            const cloned = cloneJsonLike(feature.geometry);
+            geometry = options.transformGeometry ? options.transformGeometry(cloned) : cloned;
+            applied = model.setSketchGeometry(tool, geometry).toolCapability(tool).state === "supported";
+            if (applied) {
+                const previousId = activeFeatureId;
+                activeFeatureId = id;
+                toolsByFeature.set(id, tool);
+                if (previousId !== undefined && previousId !== id) {
+                    // The workflow model tracks a single sketch geometry, so a newly
+                    // finished feature replaces the previous one: drop the stale
+                    // draw-store feature instead of letting duplicates accumulate.
+                    // No syncing guard needed: onChange ignores deletes whose ids do
+                    // not include the (already swapped) activeFeatureId.
+                    toolsByFeature.delete(previousId);
+                    if (draw.removeFeatures && featureById(previousId))
+                        draw.removeFeatures([previousId]);
+                }
+            }
+        }
+        options.onFinish?.({ featureId: id, ...(tool ? { tool } : {}), mode, action: context.action, geometry, applied });
+    };
+    const onChange = (ids, type) => {
+        if (syncing || type !== "delete")
+            return;
+        if (activeFeatureId === undefined || !ids.includes(activeFeatureId))
+            return;
+        const removedId = activeFeatureId;
+        const tool = toolsByFeature.get(removedId) ?? model.snapshot().sketch.tool ?? "point";
+        model.setSketchGeometry(tool, null);
+        toolsByFeature.delete(removedId);
+        activeFeatureId = undefined;
+        if (selectedFeatureId === removedId)
+            selectedFeatureId = undefined;
+        options.onDelete?.(removedId);
+    };
+    const onSelect = (id) => {
+        selectedFeatureId = id;
+        options.onSelect?.(id);
+    };
+    const onDeselect = (id) => {
+        if (selectedFeatureId === id || selectedFeatureId === undefined)
+            selectedFeatureId = undefined;
+        options.onDeselect?.(id);
+    };
+    draw.on("finish", onFinish);
+    draw.on("change", onChange);
+    draw.on("select", onSelect);
+    draw.on("deselect", onDeselect);
+    const syncFromModel = () => {
+        if (!draw.removeFeatures || !draw.addFeatures)
+            return false;
+        const snapshot = model.snapshot();
+        const geometry = snapshot.sketch.geometry ?? null;
+        syncing = true;
+        try {
+            if (activeFeatureId !== undefined && featureById(activeFeatureId)) {
+                draw.removeFeatures([activeFeatureId]);
+            }
+            if (geometry === null) {
+                if (activeFeatureId !== undefined)
+                    toolsByFeature.delete(activeFeatureId);
+                activeFeatureId = undefined;
+                return true;
+            }
+            const restored = options.restoreGeometry
+                ? options.restoreGeometry(cloneJsonLike(geometry))
+                : cloneJsonLike(geometry);
+            const tool = (activeFeatureId !== undefined ? toolsByFeature.get(activeFeatureId) : undefined) ?? snapshot.sketch.tool;
+            const mode = tool ? (TERRA_DRAW_SKETCH_TOOL_MODES[tool] ?? "polygon") : "polygon";
+            const restoreId = activeFeatureId;
+            const feature = {
+                ...(restoreId !== undefined ? { id: restoreId } : {}),
+                type: "Feature",
+                geometry: restored,
+                properties: { mode },
+            };
+            // Restoring after a delete leaves the id up to terra-draw: diff the
+            // snapshot to adopt the assigned id so the restored sketch stays
+            // tracked for later deletes/changes.
+            const priorIds = restoreId === undefined ? new Set(draw.getSnapshot().map((entry) => entry.id)) : undefined;
+            draw.addFeatures([feature]);
+            if (priorIds) {
+                const added = draw.getSnapshot().find((entry) => entry.id !== undefined && !priorIds.has(entry.id));
+                if (added?.id !== undefined) {
+                    activeFeatureId = added.id;
+                    if (tool)
+                        toolsByFeature.set(added.id, tool);
+                }
+            }
+            return true;
+        }
+        finally {
+            syncing = false;
+        }
+    };
+    return {
+        get activeFeatureId() {
+            return activeFeatureId;
+        },
+        get selectedFeatureId() {
+            return selectedFeatureId;
+        },
+        setTool(tool) {
+            const capability = model.startSketch(tool);
+            const mode = TERRA_DRAW_SKETCH_TOOL_MODES[tool];
+            if (capability.state === "supported" && mode !== undefined)
+                draw.setMode(mode);
+            return capability;
+        },
+        select() {
+            draw.setMode("select");
+        },
+        cancel() {
+            draw.setMode("static");
+        },
+        undo() {
+            const undone = model.undo();
+            if (undone)
+                syncFromModel();
+            return undone;
+        },
+        redo() {
+            const redone = model.redo();
+            if (redone)
+                syncFromModel();
+            return redone;
+        },
+        syncFromModel,
+        remove() {
+            draw.off("finish", onFinish);
+            draw.off("change", onChange);
+            draw.off("select", onSelect);
+            draw.off("deselect", onDeselect);
+        },
+    };
+}
+/**
+ * Build a snapping function with terra-draw's `Snapping.toCustom` shape backed
+ * by the SDK snapping engine (REQ-004).
+ *
+ * terra-draw exposes per-mode snapping on its linestring, polygon, and
+ * polyline modes; pass the result as `snapping.toCustom` when constructing
+ * those modes and every drawn vertex snaps against the {@link SnapIndex}
+ * with the SDK's deterministic candidate ordering. Point, rectangle, circle,
+ * and freehand modes do not accept a `snapping` option in terra-draw — for
+ * those, terra-draw's pointer pipeline has no custom-snapping seam, so only
+ * terra-draw-native behavior applies.
+ *
+ * @example
+ * ```ts
+ * const snap = createTerraDrawSnapping({ index, model: workflow });
+ * new TerraDrawPolygonMode({ snapping: { toCustom: snap } });
+ * ```
+ *
+ * @experimental
+ */
+export function createTerraDrawSnapping(options) {
+    const effectiveConfig = () => options.model && !options.config ? options.model.snappingConfig() : resolveSnappingConfig(options.config);
+    return (event, context) => {
+        const resolution = resolveSnapCandidate(options.index, {
+            point: { x: event.containerX, y: event.containerY },
+            position: [event.lng, event.lat],
+            project: (position) => context.project(position[0], position[1]),
+        }, effectiveConfig());
+        options.onResolve?.(resolution);
+        return resolution.candidate ? [resolution.candidate.position[0], resolution.candidate.position[1]] : undefined;
+    };
+}
+async function loadTerraDrawModules() {
+    let terraDraw;
+    try {
+        terraDraw = (await import("terra-draw"));
+    }
+    catch (cause) {
+        throw new Error("terra-draw-sketch: terra-draw is an optional peer dependency and is not installed. " +
+            "Install it with `npm i terra-draw terra-draw-maplibre-gl-adapter` to use createTerraDrawSketch().", { cause: cause instanceof Error ? cause : undefined });
+    }
+    let adapter;
+    try {
+        adapter = (await import("terra-draw-maplibre-gl-adapter"));
+    }
+    catch (cause) {
+        throw new Error("terra-draw-sketch: terra-draw-maplibre-gl-adapter is an optional peer dependency and is not installed. " +
+            "Install it with `npm i terra-draw-maplibre-gl-adapter` to use createTerraDrawSketch() on a MapLibre map.", { cause: cause instanceof Error ? cause : undefined });
+    }
+    return { terraDraw, adapter };
+}
+/** Default select-mode flags: every mode's features selectable and reshapeable. */
+function defaultSelectFlags(modes) {
+    const flags = {};
+    for (const mode of modes) {
+        flags[mode] = {
+            feature: {
+                draggable: true,
+                coordinates: { draggable: true, midpoints: true, deletable: true },
+            },
+        };
+    }
+    return flags;
+}
+/**
+ * One-call terra-draw sketch setup for a MapLibre map.
+ *
+ * Dynamically imports the optional `terra-draw` and
+ * `terra-draw-maplibre-gl-adapter` peers (throwing a descriptive error when
+ * either is missing), registers the canonical drawing modes (point,
+ * linestring, polygon, rectangle, circle, freehand, select), wires SDK
+ * snapping into the modes that accept a custom snapping hook, starts the
+ * instance, and returns it bound to the workflow model via
+ * {@link bindTerraDrawSketch}.
+ *
+ * Apps that need custom mode options should construct terra-draw themselves
+ * and call {@link bindTerraDrawSketch} directly.
+ *
+ * @experimental
+ */
+export async function createTerraDrawSketch(map, options) {
+    const { terraDraw, adapter } = await loadTerraDrawModules();
+    const snapping = options.snapping ? { toCustom: createTerraDrawSnapping(options.snapping) } : undefined;
+    const drawModes = ["point", "linestring", "polygon", "rectangle", "circle", "freehand"];
+    const modes = [
+        new terraDraw.TerraDrawPointMode(),
+        new terraDraw.TerraDrawLineStringMode(snapping ? { snapping } : {}),
+        new terraDraw.TerraDrawPolygonMode(snapping ? { snapping } : {}),
+        new terraDraw.TerraDrawRectangleMode(),
+        new terraDraw.TerraDrawCircleMode(),
+        new terraDraw.TerraDrawFreehandMode(),
+        new terraDraw.TerraDrawSelectMode({ flags: defaultSelectFlags(drawModes) }),
+    ];
+    const draw = new terraDraw.TerraDraw({
+        adapter: new adapter.TerraDrawMapLibreGLAdapter({ map }),
+        modes,
+    });
+    draw.start();
+    const handle = bindTerraDrawSketch(draw, options);
+    return {
+        draw,
+        model: options.model,
+        get activeFeatureId() {
+            return handle.activeFeatureId;
+        },
+        get selectedFeatureId() {
+            return handle.selectedFeatureId;
+        },
+        setTool: (tool) => handle.setTool(tool),
+        select: () => handle.select(),
+        cancel: () => handle.cancel(),
+        undo: () => handle.undo(),
+        redo: () => handle.redo(),
+        syncFromModel: () => handle.syncFromModel(),
+        remove: () => handle.remove(),
+        stop() {
+            handle.remove();
+            draw.stop();
+        },
+    };
+}
+// ── Internal helpers ──────────────────────────────────────────
+function modeOf(feature, context) {
+    const mode = feature?.properties?.mode;
+    return typeof mode === "string" ? mode : context.mode;
+}
+function cloneJsonLike(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(cloneJsonLike);
+    const out = {};
+    for (const [key, entry] of Object.entries(value))
+        out[key] = cloneJsonLike(entry);
+    return out;
+}

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.