@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

package/realtime/sse.js

@@ -1,3 +1,4 @@
+import { decodeDefaultRealtimeEnvelope, normalizeRealtimeErrorEvent, realtimeFailure } from "./wire.js";
 const DEFAULT_EVENT_TYPES = ["snapshot", "upsert", "delete", "delta", "heartbeat", "status", "error"];
 export function createRealtimeServerSentEventsTransport(options) {
     return {
@@ -18,20 +19,35 @@ export function createRealtimeServerSentEventsTransport(options) {
                 observer.complete();
                 return { close: () => { } };
             }
-            const url = new URL(options.url, "http://honua.local");
-            encodeDefaultRealtimeRequest(url, request);
-            options.encodeRequest?.(url, request);
-            const source = createEventSource(resolveEventSourceUrl(options.url, url), options);
+            let source;
+            try {
+                const url = new URL(options.url, "http://honua.local");
+                encodeDefaultRealtimeRequest(url, request);
+                options.encodeRequest?.(url, request);
+                source = createEventSource(resolveEventSourceUrl(options.url, url), options);
+            }
+            catch (cause) {
+                throw realtimeFailure("delivery-failed", "Unable to initialize the realtime Server-Sent Events transport.", cause);
+            }
             let closed = false;
             const listeners = [];
             const emitPayload = (payload) => {
                 if (closed || payload.trim() === "")
                     return;
+                let event;
+                try {
+                    const decoded = (options.decodeEvent ?? (decodeRealtimeServerSentEvent))(JSON.parse(payload));
+                    event = normalizeRealtimeErrorEvent(decoded);
+                }
+                catch (cause) {
+                    observer.error(realtimeFailure("invalid-event", "Realtime Server-Sent Events payload decoding failed.", cause));
+                    return;
+                }
                 try {
-                    observer.next((options.decodeEvent ?? (decodeRealtimeServerSentEvent))(JSON.parse(payload)));
+                    observer.next(event);
                 }
-                catch (error) {
-                    observer.error(error);
+                catch (cause) {
+                    observer.error(realtimeFailure("consumer-failed", "Realtime event observer rejected delivery.", cause));
                 }
             };
             const messageListener = (event) => emitPayload(event.data);
@@ -43,8 +59,9 @@ export function createRealtimeServerSentEventsTransport(options) {
             source.onerror = (event) => {
                 if (!closed)
                     observer.next({ type: "status", status: "reconnecting", reason: "sse-error", receivedAt: Date.now() });
-                if (isEventSourceClosed(source))
-                    observer.error(event);
+                if (isEventSourceClosed(source)) {
+                    observer.error(realtimeFailure("transport-gap", "Realtime Server-Sent Events transport closed unexpectedly.", event));
+                }
             };
             for (const type of options.eventTypes ?? DEFAULT_EVENT_TYPES) {
                 if (!source.addEventListener)
@@ -106,17 +123,7 @@ export function encodeDefaultRealtimeRequest(url, request) {
     return url;
 }
 export function decodeRealtimeServerSentEvent(payload) {
-    if (!isRecord(payload))
-        throw new Error("Realtime SSE payload must be a JSON object.");
-    if (typeof payload.type === "string")
-        return payload;
-    if (isRecord(payload.event) && typeof payload.event.type === "string") {
-        return payload.event;
-    }
-    if (typeof payload.kind === "string") {
-        return { ...payload, type: payload.kind };
-    }
-    throw new Error("Realtime SSE payload is missing an event type.");
+    return decodeDefaultRealtimeEnvelope(payload);
 }
 function createEventSource(url, options) {
     if (options.eventSourceFactory) {
@@ -138,6 +145,3 @@ function resolveEventSourceUrl(input, url) {
 function isEventSourceClosed(source) {
     return source.readyState === 2;
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}

package/realtime/websocket.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Raw WebSocket wire transport for `@honua/sdk-js/realtime`. Mirrors
+ * `sse.ts`'s adapter shape (subscribe params encoded onto the connection URL,
+ * default JSON event decoding, `HonuaRealtimeResumeError` failure tagging)
+ * so the two transports are interchangeable everywhere a
+ * `RealtimeFeatureTransport` is expected, including
+ * {@link "./resumable-transport.js".createResumableRealtimeTransport}.
+ *
+ * This module opens exactly one socket per `subscribe()` call and never
+ * reconnects on its own — reconnect/backoff, bounded queueing, and resume
+ * ownership live in `resumable-transport.ts` (#557), matching the resumable
+ * delivery gate's explicit non-goal ("the gate never reconnects a
+ * transport itself").
+ *
+ * @module
+ */
+import type { RealtimeFeatureEvent, RealtimeFeatureTransport, RealtimeSubscriptionRequest } from "./types.js";
+/**
+ * Minimal WebSocket surface the transport depends on. The global `WebSocket`
+ * constructor (browsers, and Node's built-in client since Node 22) already
+ * satisfies this; pass `webSocketFactory` to supply a polyfill or a mock in
+ * tests without adding a runtime dependency.
+ */
+export interface RealtimeWebSocket {
+    readonly readyState?: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent<string>) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    onclose: ((event: RealtimeWebSocketCloseEvent) => void) | null;
+    close(code?: number, reason?: string): void;
+    send(data: string): void;
+}
+/** Subset of `CloseEvent` the transport reads; avoids depending on the DOM lib for `wasClean`. */
+export interface RealtimeWebSocketCloseEvent {
+    readonly code?: number;
+    readonly reason?: string;
+    readonly wasClean?: boolean;
+}
+export type RealtimeWebSocketFactory = (url: string, protocols: string | ReadonlyArray<string> | undefined) => RealtimeWebSocket;
+export interface RealtimeWebSocketTransportOptions<TFeature = unknown> {
+    readonly url: string;
+    readonly protocols?: string | ReadonlyArray<string>;
+    readonly webSocketFactory?: RealtimeWebSocketFactory;
+    readonly encodeRequest?: (url: URL, request: RealtimeSubscriptionRequest) => void;
+    readonly decodeEvent?: (payload: unknown) => RealtimeFeatureEvent<TFeature>;
+    /**
+     * Sent as a single JSON text frame immediately after the socket opens, for
+     * servers that expect an explicit subscribe message instead of (or in
+     * addition to) URL query parameters. The default transport never sends a
+     * subscribe frame on its own.
+     */
+    readonly encodeSubscribeMessage?: (request: RealtimeSubscriptionRequest) => unknown;
+    /**
+     * WebSocket close codes treated as a normal, non-reconnectable end of the
+     * stream rather than a `transport-gap` failure. @default [1000]
+     */
+    readonly cleanCloseCodes?: ReadonlyArray<number>;
+}
+export declare function createRealtimeWebSocketTransport<TFeature = unknown>(options: RealtimeWebSocketTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+//# sourceMappingURL=websocket.d.ts.map

package/realtime/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/realtime/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EACV,oBAAoB,EAEpB,wBAAwB,EAExB,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAGpB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1D,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,kGAAkG;AAClG,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,KAClD,iBAAiB,CAAC;AAEvB,MAAM,WAAW,iCAAiC,CAAC,QAAQ,GAAG,OAAO;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACpD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC5E;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,2BAA2B,KAAK,OAAO,CAAC;IACpF;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAClD;AAID,wBAAgB,gCAAgC,CAAC,QAAQ,GAAG,OAAO,EACjE,OAAO,EAAE,iCAAiC,CAAC,QAAQ,CAAC,GACnD,wBAAwB,CAAC,QAAQ,CAAC,CAwGpC"}

package/realtime/websocket.js

@@ -0,0 +1,157 @@
+/**
+ * Raw WebSocket wire transport for `@honua/sdk-js/realtime`. Mirrors
+ * `sse.ts`'s adapter shape (subscribe params encoded onto the connection URL,
+ * default JSON event decoding, `HonuaRealtimeResumeError` failure tagging)
+ * so the two transports are interchangeable everywhere a
+ * `RealtimeFeatureTransport` is expected, including
+ * {@link "./resumable-transport.js".createResumableRealtimeTransport}.
+ *
+ * This module opens exactly one socket per `subscribe()` call and never
+ * reconnects on its own — reconnect/backoff, bounded queueing, and resume
+ * ownership live in `resumable-transport.ts` (#557), matching the resumable
+ * delivery gate's explicit non-goal ("the gate never reconnects a
+ * transport itself").
+ *
+ * @module
+ */
+import { encodeDefaultRealtimeRequest } from "./sse.js";
+import { decodeDefaultRealtimeEnvelope, normalizeRealtimeErrorEvent, realtimeFailure } from "./wire.js";
+const DEFAULT_CLEAN_CLOSE_CODES = [1000];
+export function createRealtimeWebSocketTransport(options) {
+    return {
+        capabilities: {
+            kind: "websocket",
+            resumeModes: ["cursor", "watermark", "timestamp", "sequence", "delta-token"],
+            emitsHeartbeats: true,
+            emitsWatermarks: true,
+        },
+        subscribe(request, observer) {
+            // Mirrors sse.ts: a signal already aborted at subscribe time will never
+            // fire its "abort" listener, so bail out before opening a socket that
+            // would otherwise leak.
+            if (request.signal?.aborted) {
+                observer.complete();
+                return { close: () => { } };
+            }
+            let socket;
+            try {
+                const url = new URL(options.url, "http://honua.local");
+                encodeDefaultRealtimeRequest(url, request);
+                options.encodeRequest?.(url, request);
+                socket = createSocket(resolveWebSocketUrl(options.url, url), options);
+            }
+            catch (cause) {
+                throw realtimeFailure("delivery-failed", "Unable to initialize the realtime WebSocket transport.", cause);
+            }
+            let closed = false;
+            const emitPayload = (payload) => {
+                if (closed || payload.trim() === "")
+                    return;
+                let event;
+                try {
+                    const decoded = (options.decodeEvent ?? (decodeDefaultRealtimeEnvelope))(JSON.parse(payload));
+                    event = normalizeRealtimeErrorEvent(decoded);
+                }
+                catch (cause) {
+                    observer.error(realtimeFailure("invalid-event", "Realtime WebSocket payload decoding failed.", cause));
+                    return;
+                }
+                try {
+                    observer.next(event);
+                }
+                catch (cause) {
+                    observer.error(realtimeFailure("consumer-failed", "Realtime event observer rejected delivery.", cause));
+                }
+            };
+            socket.onopen = () => {
+                if (closed)
+                    return;
+                observer.next({ type: "status", status: "live", receivedAt: Date.now() });
+                if (options.encodeSubscribeMessage) {
+                    try {
+                        socket.send(JSON.stringify(options.encodeSubscribeMessage(request)));
+                    }
+                    catch (cause) {
+                        observer.error(realtimeFailure("delivery-failed", "Unable to send the realtime WebSocket subscribe message.", cause));
+                    }
+                }
+            };
+            socket.onmessage = (event) => emitPayload(event.data);
+            socket.onerror = () => {
+                if (!closed)
+                    observer.next({ type: "status", status: "reconnecting", reason: "websocket-error", receivedAt: Date.now() });
+            };
+            socket.onclose = (event) => {
+                if (closed)
+                    return;
+                const cleanCodes = options.cleanCloseCodes ?? DEFAULT_CLEAN_CLOSE_CODES;
+                const clean = event.wasClean !== false && event.code !== undefined && cleanCodes.includes(event.code);
+                closed = true;
+                request.signal?.removeEventListener("abort", abortListener);
+                detachSocket(socket);
+                if (clean) {
+                    observer.complete();
+                    return;
+                }
+                observer.error(realtimeFailure("transport-gap", `Realtime WebSocket transport closed unexpectedly (code ${event.code ?? "unknown"}).`, event));
+            };
+            const abortListener = () => closeSocket();
+            request.signal?.addEventListener("abort", abortListener, { once: true });
+            function closeSocket() {
+                if (closed)
+                    return;
+                closed = true;
+                request.signal?.removeEventListener("abort", abortListener);
+                detachSocket(socket);
+                try {
+                    socket.close(1000, "Subscription closed by caller.");
+                }
+                catch {
+                    // Closing an already-broken socket is not itself a delivery
+                    // failure; the caller asked to stop, and stop is what happens.
+                }
+                observer.complete();
+            }
+            return {
+                close: closeSocket,
+            };
+        },
+    };
+}
+function detachSocket(socket) {
+    socket.onopen = null;
+    socket.onmessage = null;
+    socket.onerror = null;
+    socket.onclose = null;
+}
+function createSocket(url, options) {
+    if (options.webSocketFactory) {
+        return options.webSocketFactory(url, options.protocols);
+    }
+    // The global `WebSocket` is a constructor; guard rather than assume it is
+    // present so Node runtimes without a global WebSocket (or older Node) get
+    // an actionable error instead of a silent `undefined` crash, mirroring the
+    // `EventSource` guard in sse.ts. No runtime dependency is added for this:
+    // `WebSocket` is a web-standard global, optionally polyfilled by callers.
+    const WebSocketCtor = globalThis.WebSocket;
+    if (!WebSocketCtor) {
+        throw new Error("WebSocket is not available; provide webSocketFactory for this runtime.");
+    }
+    return new WebSocketCtor(url, options.protocols);
+}
+function resolveWebSocketUrl(input, url) {
+    if (input.startsWith("ws://") ||
+        input.startsWith("wss://") ||
+        input.startsWith("http://") ||
+        input.startsWith("https://")) {
+        // A WebSocket URL must use the ws(s) scheme; rewrite an http(s) origin
+        // the same way callers commonly configure REST base URLs.
+        const rewritten = new URL(url.toString());
+        if (rewritten.protocol === "http:")
+            rewritten.protocol = "ws:";
+        else if (rewritten.protocol === "https:")
+            rewritten.protocol = "wss:";
+        return rewritten.toString();
+    }
+    return `${url.pathname}${url.search}`;
+}

package/realtime/wire.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Wire-decoding and failure-tagging helpers shared by every raw realtime
+ * transport adapter (`sse.ts`, `websocket.ts`). Extracted so the two
+ * transports decode the same default JSON event vocabulary and classify
+ * failures through the exact same `HonuaRealtimeResumeError` taxonomy
+ * instead of maintaining two copies of the same parsing logic.
+ *
+ * @module
+ */
+import { HonuaRealtimeResumeError } from "./resumable.js";
+import type { RealtimeFeatureEvent } from "./types.js";
+/**
+ * Default JSON envelope decoder shared by the SSE and WebSocket transports.
+ * Accepts a bare `{ type: ... }` event, a `{ event: { type: ... } } }`
+ * wrapper, or a `{ kind: ... }` alias for `type`.
+ */
+export declare function decodeDefaultRealtimeEnvelope<TFeature = unknown>(payload: unknown): RealtimeFeatureEvent<TFeature>;
+/**
+ * Never trust a structural tag received over the wire. A server could spoof
+ * the common envelope while retaining unsanitized context and no `toJSON`.
+ * Only a locally constructed realtime error is already inside the boundary.
+ */
+export declare function normalizeRealtimeErrorEvent<TFeature>(event: RealtimeFeatureEvent<TFeature>): RealtimeFeatureEvent<TFeature>;
+export type RealtimeTransportFailureCode = "consumer-failed" | "delivery-failed" | "invalid-event" | "transport-gap";
+export declare function realtimeFailure(code: RealtimeTransportFailureCode, message: string, cause: unknown): HonuaRealtimeResumeError;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=wire.d.ts.map

package/realtime/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/realtime/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAclH;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAClD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACpC,oBAAoB,CAAC,QAAQ,CAAC,CAehC;AAED,MAAM,MAAM,4BAA4B,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,eAAe,GAAG,eAAe,CAAC;AAErH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,4BAA4B,EAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,GACb,wBAAwB,CAI1B;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE"}

package/realtime/wire.js

@@ -0,0 +1,57 @@
+/**
+ * Wire-decoding and failure-tagging helpers shared by every raw realtime
+ * transport adapter (`sse.ts`, `websocket.ts`). Extracted so the two
+ * transports decode the same default JSON event vocabulary and classify
+ * failures through the exact same `HonuaRealtimeResumeError` taxonomy
+ * instead of maintaining two copies of the same parsing logic.
+ *
+ * @module
+ */
+import { isHonuaSdkError } from "../core/error-envelope.js";
+import { HonuaRealtimeResumeError } from "./resumable.js";
+/**
+ * Default JSON envelope decoder shared by the SSE and WebSocket transports.
+ * Accepts a bare `{ type: ... }` event, a `{ event: { type: ... } } }`
+ * wrapper, or a `{ kind: ... }` alias for `type`.
+ */
+export function decodeDefaultRealtimeEnvelope(payload) {
+    if (!isRecord(payload)) {
+        throw new HonuaRealtimeResumeError("invalid-event", "Realtime payload must be a JSON object.");
+    }
+    if (typeof payload.type === "string") {
+        return normalizeRealtimeErrorEvent(payload);
+    }
+    if (isRecord(payload.event) && typeof payload.event.type === "string") {
+        return normalizeRealtimeErrorEvent(payload.event);
+    }
+    if (typeof payload.kind === "string") {
+        return normalizeRealtimeErrorEvent({ ...payload, type: payload.kind });
+    }
+    throw new HonuaRealtimeResumeError("invalid-event", "Realtime payload is missing an event type.");
+}
+/**
+ * Never trust a structural tag received over the wire. A server could spoof
+ * the common envelope while retaining unsanitized context and no `toJSON`.
+ * Only a locally constructed realtime error is already inside the boundary.
+ */
+export function normalizeRealtimeErrorEvent(event) {
+    if (event.type !== "error")
+        return event;
+    const code = event.terminal ? "invalid-event" : "transport-gap";
+    if (event.error instanceof HonuaRealtimeResumeError && isHonuaSdkError(event.error) && event.error.code === code)
+        return event;
+    return {
+        ...event,
+        error: realtimeFailure(code, event.terminal
+            ? "Realtime stream reported a terminal protocol failure."
+            : "Realtime stream reported a reconnectable transport failure.", event.error),
+    };
+}
+export function realtimeFailure(code, message, cause) {
+    return cause instanceof HonuaRealtimeResumeError && isHonuaSdkError(cause) && cause.code === code
+        ? cause
+        : new HonuaRealtimeResumeError(code, message, { cause });
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/replica-sync/errors.d.ts

@@ -7,8 +7,9 @@
  *
  * @module
  */
+import { HonuaSdkError } from "../core/error-envelope.js";
 export type ReplicaSyncErrorCode = "unsupported-sync" | "unsupported-conflict-review" | "unsupported-conflict-resolution" | "replica-not-found" | "conflict-not-found" | "replica-expired" | "conflict-already-resolved" | "merge-required" | "permission-denied" | "transport-failure";
-export declare class HonuaReplicaSyncError extends Error {
+export declare class HonuaReplicaSyncError extends HonuaSdkError {
     readonly code: ReplicaSyncErrorCode;
     readonly details: unknown;
     constructor(code: ReplicaSyncErrorCode, message: string, options?: {

package/replica-sync/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/replica-sync/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,GAClB,6BAA6B,GAC7B,iCAAiC,GACjC,mBAAmB,GACnB,oBAAoB,GACpB,iBAAiB,GACjB,2BAA2B,GAC3B,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,oBAAoB,CAAC;IAC3C,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAG/B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAOzE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAEtF;AAED,oDAAoD;AACpD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAO5F"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/replica-sync/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAuB,aAAa,EAAyC,MAAM,2BAA2B,CAAC;AAEtH,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,GAClB,6BAA6B,GAC7B,iCAAiC,GACjC,mBAAmB,GACnB,oBAAoB,GACpB,iBAAiB,GACjB,2BAA2B,GAC3B,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,SAAgB,IAAI,EAAE,oBAAoB,CAAC;IAC3C,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAG/B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAWzE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAEtF;AAED,oDAAoD;AACpD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAO5F"}

package/replica-sync/errors.js

@@ -7,11 +7,16 @@
  *
  * @module
  */
-export class HonuaReplicaSyncError extends Error {
+import { HonuaSdkError, isRetryableNetworkOrTimeoutHonuaError } from "../core/error-envelope.js";
+export class HonuaReplicaSyncError extends HonuaSdkError {
     code;
     details;
     constructor(code, message, options = {}) {
-        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        const cause = options.cause;
+        super(replicaSyncSdkCode(code, cause), message, {
+            ...(cause === undefined ? {} : { cause }),
+            context: { reasonCode: replicaSyncContextReason(code) },
+        });
         this.name = "HonuaReplicaSyncError";
         this.code = code;
         this.details = options.details;
@@ -27,3 +32,29 @@ export function isUnsupportedReplicaSyncError(error) {
             error.code === "unsupported-conflict-review" ||
             error.code === "unsupported-conflict-resolution"));
 }
+const REPLICA_SYNC_ERROR_CODES = {
+    "unsupported-sync": "offline.replica-sync.capability",
+    "unsupported-conflict-review": "offline.replica-sync.capability",
+    "unsupported-conflict-resolution": "offline.replica-sync.capability",
+    "replica-not-found": "offline.replica-sync.validation",
+    "conflict-not-found": "offline.replica-sync.validation",
+    "replica-expired": "offline.replica-sync.validation",
+    "conflict-already-resolved": "offline.replica-sync.validation",
+    "merge-required": "offline.replica-sync.validation",
+    "permission-denied": "offline.replica-sync.permission-denied",
+    "transport-failure": "offline.transport.failure",
+};
+function replicaSyncSdkCode(code, cause) {
+    if (!isReplicaSyncErrorCode(code))
+        return "offline.replica-sync.validation";
+    if (code === "transport-failure" && isRetryableNetworkOrTimeoutHonuaError(cause)) {
+        return "offline.transport.transient";
+    }
+    return REPLICA_SYNC_ERROR_CODES[code];
+}
+function replicaSyncContextReason(code) {
+    return isReplicaSyncErrorCode(code) ? code : "invalid-error-code";
+}
+function isReplicaSyncErrorCode(code) {
+    return typeof code === "string" && Object.hasOwn(REPLICA_SYNC_ERROR_CODES, code);
+}

package/runtime/edit-snapping.d.ts

@@ -0,0 +1,107 @@
+/**
+ * MapLibre runtime binding for edit-sketch snapping.
+ *
+ * Wires pointer-move on a MapLibre-shaped map to the renderer-neutral
+ * snapping engine in `contract/edit-snapping.ts`, applies snapped
+ * coordinates to an `EditSketchWorkflowModel`, surfaces snapped / unsnapped
+ * events, and maintains a default visual indicator via a lightweight GeoJSON
+ * circle layer.
+ *
+ * The map interfaces are duck-typed (same pattern as
+ * `interactions/feature-state.ts`) so the SDK carries no hard runtime
+ * dependency on `maplibre-gl`.
+ *
+ * @module
+ */
+import type { EditSketchTool, EditSketchWorkflowModel } from "../contract/edit-sketch.js";
+import { type SnapCandidate, type SnapIndex, type SnapPosition, type SnapResolution, type SnapScreenPoint, type SnappingConfig } from "../contract/edit-snapping.js";
+/** Minimal subset of a MapLibre `Map` needed for snapping. */
+export interface SnappingMap {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    project(position: readonly [number, number]): SnapScreenPoint | {
+        x: number;
+        y: number;
+    };
+    addSource?(id: string, source: Record<string, unknown>): void;
+    removeSource?(id: string): void;
+    addLayer?(layer: Record<string, unknown>, beforeId?: string): void;
+    removeLayer?(id: string): void;
+    getSource?(id: string): unknown;
+    getLayer?(id: string): unknown;
+}
+export interface EditSketchSnapIndicatorOptions {
+    /** Render the default indicator layer. @default true */
+    enabled?: boolean;
+    /** Indicator source and layer id. @default "honua-snap-indicator" */
+    id?: string;
+    /** Paint overrides merged over the default circle paint. */
+    paint?: Record<string, unknown>;
+    /** Insert the indicator layer before this layer id. */
+    beforeId?: string;
+}
+export interface EditSketchSnappingEvents {
+    /** Fired when the pointer acquires or changes a snap target. */
+    onSnap?(resolution: SnapResolution): void;
+    /** Fired when the pointer leaves a snap target; receives the lost candidate. */
+    onUnsnap?(previous: SnapCandidate): void;
+}
+export interface BindEditSketchSnappingOptions<T = Record<string, unknown>> extends EditSketchSnappingEvents {
+    /** Snap index over the loaded snap-source features. */
+    index: SnapIndex;
+    /**
+     * Sketch workflow whose snapping config drives resolution and that
+     * receives snapped geometry via {@link EditSketchSnappingHandle.applySketchGeometry}.
+     * When omitted, pass `config` and consume snaps through events / `current`.
+     */
+    model?: EditSketchWorkflowModel<T>;
+    /** Snapping configuration when no model is bound (or overrides for one-off use). */
+    config?: Partial<SnappingConfig>;
+    /** Pointer event name to listen for. @default "mousemove" */
+    pointerEvent?: string;
+    /** Default snap indicator; `false` disables it. */
+    indicator?: boolean | EditSketchSnapIndicatorOptions;
+}
+export interface EditSketchSnappingHandle {
+    /** The currently snapped candidate, if any. */
+    readonly current: SnapCandidate | undefined;
+    /** Resolve a pointer position without going through a map event. */
+    resolve(input: {
+        point: SnapScreenPoint;
+        position: SnapPosition;
+    }): SnapResolution;
+    /** Return the snapped position for `position`, or `position` unchanged. */
+    snapPosition(position: SnapPosition): SnapPosition;
+    /** Effective snapping configuration. */
+    config(): SnappingConfig;
+    /** Merge configuration changes (writes through to the bound model). */
+    setConfig(config: Partial<SnappingConfig>): void;
+    /**
+     * Apply `geometry` to the bound sketch model with its active vertex
+     * replaced by the current snap position (no-op replacement when the
+     * pointer is not snapped). Returns `true` when the model accepted the
+     * geometry.
+     */
+    applySketchGeometry(tool: EditSketchTool, geometry: Record<string, unknown> | null): boolean;
+    /** Detach event handlers and remove the indicator layer. */
+    remove(): void;
+}
+/**
+ * Bind edit-sketch snapping to a MapLibre-shaped map.
+ *
+ * @example
+ * ```ts
+ * const index = createSnapIndex();
+ * index.setSourceFeatures("parcels", parcels);
+ * const snapping = bindEditSketchSnapping(map, {
+ *   index,
+ *   model: workflow,
+ *   onSnap: ({ candidate }) => showGuide(candidate),
+ * });
+ * map.on("click", (e) => {
+ *   snapping.applySketchGeometry("point", { type: "Point", coordinates: [e.lngLat.lng, e.lngLat.lat] });
+ * });
+ * ```
+ */
+export declare function bindEditSketchSnapping<T = Record<string, unknown>>(map: SnappingMap, options: BindEditSketchSnappingOptions<T>): EditSketchSnappingHandle;
+//# sourceMappingURL=edit-snapping.d.ts.map

package/runtime/edit-snapping.d.ts.map

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