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

package/contract/discovery.js

@@ -0,0 +1,554 @@
+/**
+ * Protocol-neutral discovery truth and cache identity contracts.
+ *
+ * Protocol defaults describe what an adapter can implement; they are not
+ * evidence that a particular endpoint enables those operations. These helpers
+ * keep that distinction explicit while endpoint-specific discovery lands.
+ */
+import { HonuaDiscoveryError } from "../core/errors.js";
+import { sourceSchemaV2EnvelopeFingerprint } from "./schema-envelope.js";
+/** Default adapter implementation version included in every discovery cache identity. */
+export const HONUA_DISCOVERY_ADAPTER_VERSION = "honua-discovery-adapter@1";
+/** Default normalized inspection projection version included in every discovery cache identity. */
+export const HONUA_DISCOVERY_PROJECTION_VERSION = "honua-source-inspection@1";
+import { CAPABILITIES, PROTOCOLS, PROTOCOL_DEFAULT_CAPABILITIES, } from "./types.js";
+const DISCOVERY_EVIDENCE_KINDS = ["metadata", "declared", "inferred", "unavailable"];
+/**
+ * Intersect adapter support, endpoint evidence, and caller policy.
+ *
+ * `unavailable` and unaccepted `inferred` evidence intentionally produce no
+ * effective capabilities. Callers with trusted configuration should use
+ * `declared` evidence rather than presenting protocol defaults as discovery.
+ */
+export function resolveDiscoveryCapabilities(protocol, evidence, policy = {}) {
+    const adapter = DISCOVERY_ADAPTER_MAXIMA.get(protocol);
+    if (!adapter) {
+        throw new HonuaDiscoveryError("unsupported-protocol", `Unknown discovery protocol "${String(protocol)}".`, {
+            protocol,
+        });
+    }
+    const evidenceRecords = normalizeEvidence(evidence, adapter);
+    const allow = policy.allow ? capabilitySet(policy.allow, "policy.allow") : undefined;
+    const deny = capabilitySet(policy.deny ?? [], "policy.deny");
+    const effective = [];
+    const decisions = CAPABILITIES.map((capability) => {
+        const adapterSupported = adapter.has(capability);
+        const relevant = evidenceRecords.filter((record) => record.scope.has(capability));
+        const positive = relevant.filter((record) => record.capabilities.has(capability));
+        const authoritativeNegative = relevant.some((record) => (record.kind === "metadata" || record.kind === "declared") && !record.capabilities.has(capability));
+        const metadataPositive = positive.some((record) => record.kind === "metadata");
+        const declaredPositive = positive.some((record) => record.kind === "declared");
+        const inferredPositive = positive.some((record) => record.kind === "inferred");
+        const unavailable = relevant.some((record) => record.kind === "unavailable");
+        const positiveEvidence = metadataPositive || declaredPositive || inferredPositive;
+        const policyAllowed = (allow === undefined || allow.has(capability)) && !deny.has(capability);
+        const code = !adapterSupported
+            ? "adapter-unsupported"
+            : authoritativeNegative
+                ? "not-advertised"
+                : metadataPositive
+                    ? policyAllowed
+                        ? "enabled"
+                        : "policy-denied"
+                    : declaredPositive
+                        ? policyAllowed
+                            ? "enabled"
+                            : "policy-denied"
+                        : inferredPositive
+                            ? policy.acceptInferred === true
+                                ? policyAllowed
+                                    ? "enabled"
+                                    : "policy-denied"
+                                : "inferred-not-accepted"
+                            : unavailable
+                                ? "discovery-unavailable"
+                                : "not-advertised";
+        const isEffective = code === "enabled";
+        if (isEffective)
+            effective.push(capability);
+        return Object.freeze({
+            capability,
+            effective: isEffective,
+            code,
+            evidence: Object.freeze(relevant.map((record) => evidenceSummary(record, capability))),
+            adapterSupported,
+            positiveEvidence,
+            policyAllowed,
+            reason: capabilityDecisionReason(code, capability),
+        });
+    });
+    const observed = new Set(evidenceRecords.flatMap((record) => [...record.capabilities]));
+    const outsideAdapter = [...observed].filter((capability) => !adapter.has(capability));
+    const policyRestricted = decisions
+        .filter((decision) => decision.code === "policy-denied")
+        .map((decision) => decision.capability);
+    const diagnostics = [];
+    const unavailableRecords = evidenceRecords.filter((record) => record.kind === "unavailable");
+    for (const record of unavailableRecords) {
+        diagnostics.push({
+            code: "discovery-unavailable",
+            severity: "warning",
+            message: record.reason ?? "Discovery evidence is unavailable.",
+            capabilities: orderedCapabilities(record.scope),
+        });
+    }
+    if (unavailableRecords.length > 0 && evidenceRecords.some((record) => record.kind !== "unavailable")) {
+        diagnostics.push({
+            code: "partial-discovery",
+            severity: "warning",
+            message: "Some capability evidence is available while one or more discovery sources failed.",
+        });
+    }
+    const inferredRejected = decisions
+        .filter((decision) => decision.code === "inferred-not-accepted")
+        .map((decision) => decision.capability);
+    if (inferredRejected.length > 0) {
+        diagnostics.push({
+            code: "inferred-capabilities-rejected",
+            severity: "warning",
+            message: "Inferred capabilities were recorded but not enabled without explicit caller acceptance.",
+            capabilities: Object.freeze(inferredRejected),
+        });
+    }
+    const conflicts = decisions
+        .filter((decision) => decision.code === "not-advertised" &&
+        decision.evidence.some((entry) => (entry.kind === "metadata" || entry.kind === "declared") && entry.supported) &&
+        decision.evidence.some((entry) => (entry.kind === "metadata" || entry.kind === "declared") && !entry.supported))
+        .map((decision) => decision.capability);
+    if (conflicts.length > 0) {
+        diagnostics.push({
+            code: "conflicting-evidence",
+            severity: "warning",
+            message: "Conflicting authoritative evidence was resolved conservatively by disabling the affected capabilities.",
+            capabilities: Object.freeze(conflicts),
+        });
+    }
+    if (outsideAdapter.length > 0) {
+        diagnostics.push({
+            code: "evidence-exceeds-adapter",
+            severity: "warning",
+            message: "Discovery evidence asserts operations that this SDK adapter cannot implement.",
+            capabilities: orderedCapabilities(new Set(outsideAdapter)),
+        });
+    }
+    if (policyRestricted.length > 0) {
+        diagnostics.push({
+            code: "capability-policy-restricted",
+            severity: "info",
+            message: "Caller policy removed endpoint-supported capabilities.",
+            capabilities: orderedCapabilities(new Set(policyRestricted)),
+        });
+    }
+    return Object.freeze({
+        protocol,
+        discovery: discoveryState(evidenceRecords),
+        evidence: Object.freeze(evidenceRecords.map((record) => record.original)),
+        provenance: Object.freeze(uniqueProvenance(evidenceRecords.flatMap((record) => record.provenance))),
+        capabilities: immutableCapabilities(effective),
+        decisions: Object.freeze(decisions),
+        diagnostics: Object.freeze(diagnostics.map(freezeDiagnostic)),
+    });
+}
+/** Apply one reviewed discovery resolution to a source descriptor. */
+export function inspectDiscoveredSource(descriptor, resolution) {
+    if (descriptor.protocol !== resolution.protocol) {
+        throw new HonuaDiscoveryError("protocol-mismatch", `Source protocol "${descriptor.protocol}" does not match discovery protocol "${resolution.protocol}".`, { sourceId: descriptor.id, descriptorProtocol: descriptor.protocol, discoveryProtocol: resolution.protocol });
+    }
+    assertResolutionIntegrity(resolution);
+    return Object.freeze({
+        descriptor: immutableDescriptor(descriptor, resolution.capabilities),
+        discovery: resolution.discovery,
+        provenance: resolution.provenance,
+        capabilityDecisions: resolution.decisions,
+        diagnostics: resolution.diagnostics,
+    });
+}
+function assertResolutionIntegrity(resolution) {
+    const effectiveDecisions = resolution.decisions
+        .filter((decision) => decision.effective && decision.code === "enabled")
+        .map((decision) => decision.capability);
+    const resolved = orderedCapabilities(resolution.capabilities);
+    if (effectiveDecisions.length !== resolved.length ||
+        effectiveDecisions.some((capability, index) => capability !== resolved[index])) {
+        throw new HonuaDiscoveryError("invalid-capability", "Discovery capability resolution was mutated or does not match its per-capability decisions.", { protocol: resolution.protocol });
+    }
+}
+const CREDENTIAL_ENDPOINT_PARAMETERS = new Set([
+    "access_token",
+    "api_key",
+    "apikey",
+    "authorization",
+    "bearer",
+    "client_secret",
+    "code",
+    "id_token",
+    "jwt",
+    "password",
+    "passwd",
+    "refresh_token",
+    "secret",
+    "session",
+    "session_id",
+    "sessionid",
+    "sig",
+    "signature",
+    "token",
+]);
+const AMBIGUOUS_CREDENTIAL_ENDPOINT_PARAMETERS = new Set([
+    "api-key",
+    "api_key",
+    "apikey",
+    "auth",
+    "code",
+    "credential",
+    "key",
+    "ocp-apim-subscription-key",
+    "secret",
+    "session",
+    "session_id",
+    "sessionid",
+    "subscription-key",
+    "subscription_key",
+]);
+/** Normalize an endpoint for discovery identity without retaining credentials. */
+export function normalizeDiscoveryEndpoint(endpoint, options = {}) {
+    const callerTransient = new Set((options.transientQueryParameters ?? []).map((value) => value.toLowerCase()));
+    return normalizeEndpoint(endpoint, (key) => {
+        const normalized = key.toLowerCase();
+        return isCredentialEndpointParameter(normalized) || callerTransient.has(normalized);
+    });
+}
+/**
+ * Build the deterministic logical identity used by discovery metadata caches.
+ * The key contains no URL credentials, bearer tokens, signed-URL parameters,
+ * or raw authorization material.
+ */
+export async function createDiscoveryCacheIdentity(options) {
+    const authorizationScopeFingerprint = requiredIdentity(options.authorizationScopeFingerprint, "authorizationScopeFingerprint");
+    const adapterVersion = options.adapterVersion === undefined
+        ? HONUA_DISCOVERY_ADAPTER_VERSION
+        : requiredIdentity(options.adapterVersion, "adapterVersion");
+    const projectionVersion = options.projectionVersion === undefined
+        ? HONUA_DISCOVERY_PROJECTION_VERSION
+        : requiredIdentity(options.projectionVersion, "projectionVersion");
+    if (options.protocol !== "auto" && !PROTOCOLS.includes(options.protocol)) {
+        throw new HonuaDiscoveryError("unsupported-protocol", `Unknown discovery protocol "${String(options.protocol)}".`, {
+            protocol: options.protocol,
+        });
+    }
+    const endpoint = normalizeDiscoveryEndpoint(options.endpoint, options);
+    const callerTransient = new Set((options.transientQueryParameters ?? []).map((value) => value.toLowerCase()));
+    const identityEndpoint = normalizeEndpoint(options.endpoint, (key) => {
+        const normalized = key.toLowerCase();
+        return ((isCredentialEndpointParameter(normalized) && !AMBIGUOUS_CREDENTIAL_ENDPOINT_PARAMETERS.has(normalized)) ||
+            callerTransient.has(normalized));
+    });
+    const [endpointDigest, authorizationScopeDigest] = await Promise.all([
+        sha256(identityEndpoint),
+        sha256(`honua-discovery-scope:v1:${authorizationScopeFingerprint}`),
+    ]);
+    const dimensions = {
+        endpointDigest,
+        protocol: options.protocol,
+        authorizationScopeDigest,
+        adapterVersion,
+        projectionVersion,
+    };
+    for (const key of DISCOVERY_RESOURCE_KEYS) {
+        const value = options[key];
+        if (value !== undefined && String(value).length > 0)
+            dimensions[key] = String(value);
+    }
+    const key = `discovery:v1:${Object.keys(dimensions)
+        .sort()
+        .map((name) => `${encodeURIComponent(name)}=${encodeURIComponent(dimensions[name])}`)
+        .join("&")}`;
+    return Object.freeze({
+        version: 1,
+        endpoint,
+        protocol: options.protocol,
+        authorizationScopeDigest,
+        key,
+    });
+}
+const DISCOVERY_RESOURCE_KEYS = [
+    "tenantId",
+    "projectId",
+    "sourceId",
+    "serviceId",
+    "layerId",
+    "collectionId",
+    "typeName",
+    "tileMatrixSetId",
+    "styleId",
+    "entitySet",
+    "processId",
+    "crs",
+    "format",
+    "locale",
+    "profile",
+    "assetVariant",
+];
+function capabilitySet(values, path) {
+    const known = new Set(CAPABILITIES);
+    const out = new Set();
+    for (const value of values) {
+        if (!known.has(value)) {
+            throw new HonuaDiscoveryError("invalid-capability", `${path} contains unknown capability "${String(value)}".`, {
+                path,
+                capability: value,
+            });
+        }
+        out.add(value);
+    }
+    return out;
+}
+function normalizeEvidence(input, adapter) {
+    const values = Array.isArray(input)
+        ? input
+        : [input];
+    if (values.length === 0) {
+        throw new HonuaDiscoveryError("invalid-capability", "Discovery evidence must contain at least one record.");
+    }
+    return Object.freeze(values.map((value, index) => {
+        const path = `evidence[${index}]`;
+        const kind = discoveryEvidenceKind(value, path);
+        const observed = kind === "unavailable"
+            ? new Set()
+            : capabilitySet(value.capabilities, path);
+        const scope = value.scope
+            ? capabilitySet(value.scope, `${path}.scope`)
+            : new Set([...adapter, ...observed]);
+        for (const capability of observed) {
+            if (!scope.has(capability)) {
+                throw new HonuaDiscoveryError("invalid-capability", `${path}.capabilities contains "${capability}" outside its evaluated scope.`, { path, capability });
+            }
+        }
+        const provenance = Object.freeze((value.provenance ?? []).map((entry, provenanceIndex) => normalizeProvenance(entry, `${path}.provenance[${provenanceIndex}]`)));
+        const original = Object.freeze({
+            ...value,
+            ...(kind !== "unavailable" ? { capabilities: Object.freeze([...observed]) } : {}),
+            ...(value.scope ? { scope: Object.freeze([...scope]) } : {}),
+            ...(provenance.length > 0 ? { provenance } : {}),
+        });
+        return Object.freeze({
+            kind,
+            capabilities: observed,
+            scope,
+            ...(kind === "inferred" || kind === "unavailable"
+                ? { reason: value.reason }
+                : {}),
+            provenance,
+            original,
+        });
+    }));
+}
+function discoveryEvidenceKind(value, path) {
+    const kind = value !== null && typeof value === "object" ? value.kind : undefined;
+    if (!DISCOVERY_EVIDENCE_KINDS.includes(kind)) {
+        throw new HonuaDiscoveryError("invalid-capability", `${path}.kind must be one of ${DISCOVERY_EVIDENCE_KINDS.join(", ")}; received "${String(kind)}".`, { path: `${path}.kind`, kind });
+    }
+    return kind;
+}
+function evidenceSummary(record, capability) {
+    return Object.freeze({
+        kind: record.kind,
+        supported: record.capabilities.has(capability),
+        ...(record.reason ? { reason: record.reason } : {}),
+        provenance: record.provenance,
+    });
+}
+function discoveryState(records) {
+    const kinds = new Set(records.map((record) => record.kind));
+    return kinds.size === 1 ? (records[0]?.kind ?? "unavailable") : "mixed";
+}
+function normalizeProvenance(value, path) {
+    const source = value.source.trim();
+    if (source.length === 0) {
+        throw new HonuaDiscoveryError("invalid-capability", `${path}.source must be non-empty.`, { path });
+    }
+    return Object.freeze({
+        source,
+        ...(value.retrievedAt ? { retrievedAt: value.retrievedAt } : {}),
+        ...(value.validator ? { validator: value.validator } : {}),
+    });
+}
+function uniqueProvenance(values) {
+    const seen = new Set();
+    return values.filter((value) => {
+        const key = `${value.source}\u0000${value.retrievedAt ?? ""}\u0000${value.validator ?? ""}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function immutableCapabilities(values) {
+    return Object.freeze(new ImmutableCapabilitySet(values));
+}
+/** @internal Preserve discovery's mutation-resistant legacy set representation. */
+export function immutableDiscoveredCapabilities(values) {
+    return immutableCapabilities([...values]);
+}
+class ImmutableCapabilitySet {
+    #values;
+    constructor(values) {
+        this.#values = new Set(values);
+    }
+    get size() {
+        return this.#values.size;
+    }
+    has(value) {
+        return this.#values.has(value);
+    }
+    entries() {
+        return this.#values.entries();
+    }
+    keys() {
+        return this.#values.keys();
+    }
+    values() {
+        return this.#values.values();
+    }
+    forEach(callbackfn, thisArg) {
+        for (const value of this.#values)
+            callbackfn.call(thisArg, value, value, this);
+    }
+    [Symbol.iterator]() {
+        return this.values();
+    }
+    [Symbol.toStringTag] = "Set";
+}
+const DISCOVERY_ADAPTER_MAXIMA = new Map(PROTOCOLS.map((protocol) => [protocol, immutableCapabilities([...PROTOCOL_DEFAULT_CAPABILITIES[protocol]])]));
+function freezeDiagnostic(diagnostic) {
+    return Object.freeze({
+        ...diagnostic,
+        ...(diagnostic.capabilities ? { capabilities: Object.freeze([...diagnostic.capabilities]) } : {}),
+    });
+}
+function immutableDescriptor(descriptor, effectiveCapabilities) {
+    return Object.freeze({
+        ...descriptor,
+        locator: cloneAndDeepFreeze(descriptor.locator),
+        capabilities: immutableCapabilities([...effectiveCapabilities]),
+        ...(descriptor.schema ? { schema: cloneAndDeepFreeze(descriptor.schema) } : {}),
+        ...(descriptor.schemaV2 !== undefined ? { schemaV2: immutableSourceSchemaV2(descriptor.schemaV2) } : {}),
+        ...(descriptor.analytics ? { analytics: cloneAndDeepFreeze(descriptor.analytics) } : {}),
+    });
+}
+function immutableSourceSchemaV2(value) {
+    const cloned = cloneAndDeepFreeze(value);
+    try {
+        sourceSchemaV2EnvelopeFingerprint(cloned);
+    }
+    catch (cause) {
+        throw new HonuaDiscoveryError("invalid-capability", "Source discovery schemaV2 has an invalid discriminator or fingerprint envelope.", undefined, { cause });
+    }
+    return cloned;
+}
+function cloneAndDeepFreeze(value) {
+    try {
+        return deepFreeze(structuredClone(value));
+    }
+    catch (cause) {
+        throw new HonuaDiscoveryError("invalid-capability", "Source discovery descriptors must contain structured-clone-compatible metadata.", undefined, { cause });
+    }
+}
+function deepFreeze(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+    if (seen.has(value))
+        return value;
+    seen.add(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError("Discovery descriptor metadata must contain only arrays and plain objects.");
+    }
+    for (const child of Object.values(value))
+        deepFreeze(child, seen);
+    Object.freeze(value);
+    return value;
+}
+function capabilityDecisionReason(code, capability) {
+    switch (code) {
+        case "enabled":
+            return `${capability} is supported by the adapter, endpoint evidence, and caller policy.`;
+        case "adapter-unsupported":
+            return `${capability} is not implemented by this protocol adapter.`;
+        case "not-advertised":
+            return `${capability} was not advertised by endpoint evidence.`;
+        case "policy-denied":
+            return `${capability} was removed by caller policy.`;
+        case "inferred-not-accepted":
+            return `${capability} was inferred but the caller did not accept inferred support.`;
+        case "discovery-unavailable":
+            return `${capability} cannot be enabled because discovery evidence is unavailable.`;
+    }
+}
+function orderedCapabilities(values) {
+    return CAPABILITIES.filter((capability) => values.has(capability));
+}
+function requiredIdentity(value, name) {
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        throw new HonuaDiscoveryError("invalid-cache-identity", `${name} must be a non-empty opaque fingerprint.`, {
+            name,
+        });
+    }
+    return normalized;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isCredentialEndpointParameter(normalized) {
+    return (CREDENTIAL_ENDPOINT_PARAMETERS.has(normalized) ||
+        AMBIGUOUS_CREDENTIAL_ENDPOINT_PARAMETERS.has(normalized) ||
+        normalized.startsWith("x-amz-") ||
+        normalized.startsWith("x-goog-"));
+}
+const AZURE_SAS_PARAMETER = /^(?:rscc|rscd|rsce|rscl|rsct|saoid|scid|sdd|se|ses|sig|sip|si|ske|skoid|sks|skt|sktid|skv|sp|spr|sr|srt|ss|st|suoid|sv)$/;
+const CLOUDFRONT_SIGNED_URL_PARAMETER = /^(?:expires|key-pair-id|policy|signature)$/;
+const AWS_V2_SIGNED_URL_PARAMETER = /^(?:awsaccesskeyid|expires|securitytoken|signature)$/;
+const GCS_V2_SIGNED_URL_PARAMETER = /^(?:expires|googleaccessid|signature)$/;
+function signedUrlTransientParameter(parameters) {
+    const names = new Set([...parameters.keys()].map((name) => name.toLowerCase()));
+    const azure = names.has("sig") && [...names].some((name) => name !== "sig" && AZURE_SAS_PARAMETER.test(name));
+    const signedV2 = names.has("signature");
+    const cloudFront = signedV2 && names.has("key-pair-id");
+    const aws = signedV2 && names.has("awsaccesskeyid");
+    const gcs = signedV2 && names.has("googleaccessid");
+    return (name) => (azure && AZURE_SAS_PARAMETER.test(name)) ||
+        (cloudFront && CLOUDFRONT_SIGNED_URL_PARAMETER.test(name)) ||
+        (aws && AWS_V2_SIGNED_URL_PARAMETER.test(name)) ||
+        (gcs && GCS_V2_SIGNED_URL_PARAMETER.test(name));
+}
+function normalizeEndpoint(endpoint, omit) {
+    let parsed;
+    try {
+        parsed = new URL(endpoint.toString());
+    }
+    catch {
+        throw new HonuaDiscoveryError("invalid-endpoint", "Discovery endpoints must be absolute URLs.");
+    }
+    parsed.username = "";
+    parsed.password = "";
+    parsed.hash = "";
+    const isSignedUrlTransient = signedUrlTransientParameter(parsed.searchParams);
+    const retained = [...parsed.searchParams.entries()]
+        .filter(([key]) => !omit(key) && !isSignedUrlTransient(key.toLowerCase()))
+        .sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey === rightKey ? compareText(leftValue, rightValue) : compareText(leftKey, rightKey));
+    parsed.search = "";
+    for (const [key, value] of retained)
+        parsed.searchParams.append(key, value);
+    while (parsed.pathname.length > 1 && parsed.pathname.endsWith("/"))
+        parsed.pathname = parsed.pathname.slice(0, -1);
+    const normalized = parsed.toString();
+    return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+}
+async function sha256(value) {
+    if (!globalThis.crypto?.subtle) {
+        throw new HonuaDiscoveryError("invalid-cache-identity", "Discovery cache identity requires Web Crypto SHA-256.");
+    }
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}

package/contract/edit-sketch.d.ts

@@ -1,4 +1,5 @@
 import { type CreateEditSessionOptions, type EditAttachmentMutation, type EditWorkflowKind, type EditWorkflowMetadata, type EditWorkflowSnapshot, type EditWorkflowSubmitResult, type EditWorkflowValidationResult } from "./edit-session.js";
+import { type SnappingConfig } from "./edit-snapping.js";
 import type { CanonicalFeature, FeatureId, Protocol, Source, SourceId } from "./types.js";
 export type EditSketchTool = "point" | "line" | "polygon" | "rectangle" | "circle" | "buffer";
 export type EditSketchCapabilityState = "supported" | "unsupported";
@@ -17,6 +18,8 @@ export interface EditSketchWorkflowOptions<T = Record<string, unknown>> extends
     sketchTools?: Partial<Record<EditSketchTool, EditSketchToolCapabilityInput>>;
     optimistic?: CreateEditSessionOptions<T>["optimistic"];
     annotationPersistence?: EditAnnotationPersistenceHook<T>;
+    /** Initial snapping configuration for the sketch workflow. */
+    snapping?: Partial<SnappingConfig>;
 }
 export interface EditAnnotationPersistenceHook<T = Record<string, unknown>> {
     persist(snapshot: EditWorkflowSnapshot<T>, result: EditWorkflowSubmitResult<T>): void | Promise<void>;
@@ -44,6 +47,7 @@ export interface EditSketchWorkflowSnapshot<T = Record<string, unknown>> {
         tool?: EditSketchTool;
         tools: readonly EditSketchToolCapability[];
         geometry: Record<string, unknown> | null | undefined;
+        snapping: SnappingConfig;
     };
     dirty: boolean;
     validation: EditWorkflowValidationResult;
@@ -55,6 +59,10 @@ export declare class EditSketchWorkflowModel<T = Record<string, unknown>> {
     readonly source: Source<T>;
     readonly kind: EditWorkflowKind;
     constructor(options: EditSketchWorkflowOptions<T>);
+    /** Current snapping configuration (disabled unless configured). */
+    snappingConfig(): SnappingConfig;
+    /** Merge snapping configuration changes into the workflow. */
+    setSnapping(config: Partial<SnappingConfig>): this;
     snapshot(): EditSketchWorkflowSnapshot<T>;
     tools(): readonly EditSketchToolCapability[];
     toolCapability(tool: EditSketchTool): EditSketchToolCapability;

package/contract/edit-sketch.d.ts.map

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

package/contract/edit-sketch.js

@@ -1,4 +1,5 @@
 import { createEditSession, } from "./edit-session.js";
+import { resolveSnappingConfig } from "./edit-snapping.js";
 const EDIT_SKETCH_TOOLS = ["point", "line", "polygon", "rectangle", "circle", "buffer"];
 const DEFAULT_SKETCH_TOOL_CAPABILITIES = {
     point: { tool: "point", state: "supported" },
@@ -19,6 +20,7 @@ export class EditSketchWorkflowModel {
     #activeTool;
     #lastTool;
     #annotationState;
+    #snapping;
     constructor(options) {
         this.source = options.source;
         this.kind = options.kind ?? (options.feature?.id === undefined ? "create" : "update");
@@ -26,6 +28,18 @@ export class EditSketchWorkflowModel {
         this.#session = createEditSession(options);
         this.#base = this.#session.snapshot();
         this.#annotationState = options.annotationPersistence ? { state: "supported" } : { state: "not-configured" };
+        this.#snapping = options.snapping
+            ? resolveSnappingConfig(options.snapping)
+            : resolveSnappingConfig({ enabled: false });
+    }
+    /** Current snapping configuration (disabled unless configured). */
+    snappingConfig() {
+        return resolveSnappingConfig(this.#snapping);
+    }
+    /** Merge snapping configuration changes into the workflow. */
+    setSnapping(config) {
+        this.#snapping = resolveSnappingConfig({ ...this.#snapping, ...config });
+        return this;
     }
     snapshot() {
         const snapshot = this.#session.snapshot();
@@ -43,6 +57,7 @@ export class EditSketchWorkflowModel {
                 ...(this.#lastTool ? { tool: this.#lastTool } : {}),
                 tools: this.tools(),
                 geometry: snapshot.feature.geometry,
+                snapping: this.snappingConfig(),
             },
             dirty: this.dirty(),
             validation,