@gp2f/client-sdk 1.0.0

package/dist/MergeModal.d.ts

@@ -0,0 +1,21 @@
+import React from "react";
+import type { FieldConflict } from "./wire";
+/**
+ * Side-by-side modal shown when a REJECT contains non-CRDT field conflicts.
+ *
+ * For each conflicting field the user can choose:
+ * - **Keep mine** – use the local optimistic value
+ * - **Use server** – accept the server's authoritative value (from `resolvedValue`)
+ */
+export interface MergeModalProps {
+    conflicts: FieldConflict[];
+    /** JSON snapshot of the state *before* the rejected op was applied. */
+    baseSnapshot: unknown;
+    /** JSON diff representing the local (client) changes. */
+    localDiff: unknown;
+    /** Called with the user's resolution choices (path → chosen value). */
+    onResolve: (resolutions: Record<string, unknown>) => void;
+    /** Called when the user cancels without resolving. */
+    onCancel: () => void;
+}
+export declare function MergeModal({ conflicts, localDiff, onResolve, onCancel, }: MergeModalProps): React.ReactElement;

package/dist/MergeModal.js

@@ -0,0 +1,136 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from "react";
+export function MergeModal({ conflicts, localDiff, onResolve, onCancel, }) {
+    const [choices, setChoices] = useState(() => Object.fromEntries(conflicts.map((c) => [c.path, "server"])));
+    function handleChoice(path, choice) {
+        setChoices((prev) => ({ ...prev, [path]: choice }));
+    }
+    function handleResolve() {
+        const resolutions = {};
+        for (const conflict of conflicts) {
+            if (choices[conflict.path] === "server") {
+                resolutions[conflict.path] = conflict.resolvedValue;
+            }
+            else {
+                // "mine": extract value from localDiff
+                resolutions[conflict.path] = getFieldValue(localDiff, conflict.path);
+            }
+        }
+        onResolve(resolutions);
+    }
+    return (_jsx("div", { role: "dialog", "aria-modal": "true", "aria-labelledby": "merge-modal-title", style: {
+            position: "fixed",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            backgroundColor: "rgba(0,0,0,0.45)",
+            zIndex: 1000,
+        }, children: _jsxs("div", { style: {
+                backgroundColor: "#ffffff",
+                borderRadius: "0.5rem",
+                boxShadow: "0 20px 60px rgba(0,0,0,0.3)",
+                width: "min(90vw, 640px)",
+                maxHeight: "80vh",
+                display: "flex",
+                flexDirection: "column",
+                overflow: "hidden",
+            }, children: [_jsxs("div", { style: {
+                        padding: "1rem 1.25rem",
+                        borderBottom: "1px solid #e5e7eb",
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "space-between",
+                    }, children: [_jsxs("h2", { id: "merge-modal-title", style: { margin: 0, fontSize: "1rem", fontWeight: 600 }, children: ["Resolve Conflicts (", conflicts.length, ")"] }), _jsx("button", { type: "button", "aria-label": "Close", onClick: onCancel, style: {
+                                background: "none",
+                                border: "none",
+                                cursor: "pointer",
+                                fontSize: "1.25rem",
+                            }, children: "\u2715" })] }), _jsx("div", { style: { overflowY: "auto", flex: 1, padding: "0.75rem 1.25rem" }, children: conflicts.map((conflict) => (_jsx(ConflictRow, { conflict: conflict, localValue: getFieldValue(localDiff, conflict.path), choice: choices[conflict.path] ?? "server", onChoose: (c) => handleChoice(conflict.path, c) }, conflict.path))) }), _jsxs("div", { style: {
+                        padding: "0.75rem 1.25rem",
+                        borderTop: "1px solid #e5e7eb",
+                        display: "flex",
+                        justifyContent: "flex-end",
+                        gap: "0.5rem",
+                    }, children: [_jsx("button", { type: "button", onClick: onCancel, style: {
+                                padding: "0.5rem 1rem",
+                                borderRadius: "0.375rem",
+                                border: "1px solid #d1d5db",
+                                background: "#ffffff",
+                                cursor: "pointer",
+                            }, children: "Cancel" }), _jsx("button", { type: "button", onClick: handleResolve, style: {
+                                padding: "0.5rem 1rem",
+                                borderRadius: "0.375rem",
+                                border: "none",
+                                backgroundColor: "#2563eb",
+                                color: "#ffffff",
+                                cursor: "pointer",
+                                fontWeight: 500,
+                            }, children: "Apply Resolutions" })] })] }) }));
+}
+function ConflictRow({ conflict, localValue, choice, onChoose, }) {
+    return (_jsxs("div", { style: {
+            marginBottom: "1rem",
+            borderRadius: "0.375rem",
+            border: "1px solid #e5e7eb",
+            overflow: "hidden",
+        }, children: [_jsxs("div", { style: {
+                    padding: "0.5rem 0.75rem",
+                    backgroundColor: "#f9fafb",
+                    borderBottom: "1px solid #e5e7eb",
+                    display: "flex",
+                    alignItems: "center",
+                    gap: "0.5rem",
+                }, children: [_jsx("code", { style: { fontSize: "0.8125rem", flex: 1 }, children: conflict.path }), _jsx("span", { style: {
+                            fontSize: "0.75rem",
+                            padding: "0.125rem 0.375rem",
+                            borderRadius: "0.25rem",
+                            backgroundColor: conflict.strategy === "TRANSACTIONAL" ? "#fde8e8" : "#e0f2fe",
+                            color: conflict.strategy === "TRANSACTIONAL" ? "#991b1b" : "#0369a1",
+                        }, children: conflict.strategy })] }), _jsxs("div", { style: {
+                    display: "grid",
+                    gridTemplateColumns: "1fr 1fr",
+                    gap: 0,
+                }, children: [_jsx(OptionPanel, { label: "My change", value: localValue, selected: choice === "mine", onClick: () => onChoose("mine"), accentColor: "#2563eb" }), _jsx(OptionPanel, { label: "Server (authoritative)", value: conflict.resolvedValue, selected: choice === "server", onClick: () => onChoose("server"), accentColor: "#16a34a", bordered: true })] })] }));
+}
+function OptionPanel({ label, value, selected, onClick, accentColor, bordered, }) {
+    return (_jsxs("button", { type: "button", onClick: onClick, style: {
+            padding: "0.75rem",
+            textAlign: "left",
+            cursor: "pointer",
+            border: "none",
+            borderLeft: bordered ? "1px solid #e5e7eb" : undefined,
+            backgroundColor: selected ? `${accentColor}10` : "#ffffff",
+            outline: selected ? `2px solid ${accentColor}` : "none",
+            outlineOffset: "-2px",
+            transition: "background-color 100ms",
+            width: "100%",
+        }, children: [_jsxs("div", { style: {
+                    fontSize: "0.75rem",
+                    fontWeight: 600,
+                    color: selected ? accentColor : "#6b7280",
+                    marginBottom: "0.25rem",
+                }, children: [selected && "✔ ", label] }), _jsx("pre", { style: {
+                    margin: 0,
+                    fontSize: "0.75rem",
+                    fontFamily: "monospace",
+                    whiteSpace: "pre-wrap",
+                    wordBreak: "break-all",
+                    color: "#1f2937",
+                }, children: JSON.stringify(value, null, 2) })] }));
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+/** Extract the value at a JSON-pointer path (e.g. `/amount`) from an object. */
+function getFieldValue(obj, pointer) {
+    if (typeof obj !== "object" || obj === null)
+        return undefined;
+    // Strip leading `/` and split on `/`
+    const segments = pointer.replace(/^\//, "").split("/");
+    let current = obj;
+    for (const seg of segments) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[seg];
+    }
+    return current;
+}

package/dist/ReconciliationBanner.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+import type { RejectResponse } from "./wire";
+/**
+ * Displayed as a dismissible banner at the top of the form whenever the server
+ * REJECTs an operation.  Shows the rejection reason and provides a "Undo" and
+ * "Resolve conflicts" action.
+ */
+export interface ReconciliationBannerProps {
+    /** The full server REJECT response. */
+    rejection: RejectResponse;
+    /** Called when the user clicks "Undo". */
+    onUndo: () => void;
+    /** Called when the user clicks "Resolve conflicts". */
+    onResolve: () => void;
+    /** Called when the user dismisses the banner. */
+    onDismiss: () => void;
+}
+export declare function ReconciliationBanner({ rejection, onUndo, onResolve, onDismiss, }: ReconciliationBannerProps): React.ReactElement;

package/dist/ReconciliationBanner.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { UndoButton } from "./UndoButton";
+export function ReconciliationBanner({ rejection, onUndo, onResolve, onDismiss, }) {
+    const hasConflicts = rejection.patch.conflicts.length > 0;
+    return (_jsxs("div", { role: "alert", "aria-live": "assertive", style: {
+            display: "flex",
+            alignItems: "center",
+            gap: "0.75rem",
+            padding: "0.75rem 1rem",
+            borderRadius: "0.375rem",
+            backgroundColor: "#fef3c7",
+            borderLeft: "4px solid #f59e0b",
+            color: "#92400e",
+            fontSize: "0.875rem",
+        }, children: [_jsxs("span", { style: { flex: 1 }, children: [_jsx("strong", { children: "Sync conflict:" }), " ", rejection.reason] }), _jsx(UndoButton, { onUndo: onUndo }), hasConflicts && (_jsxs("button", { type: "button", onClick: onResolve, style: {
+                    padding: "0.25rem 0.75rem",
+                    borderRadius: "0.25rem",
+                    border: "1px solid #b45309",
+                    backgroundColor: "transparent",
+                    color: "#92400e",
+                    cursor: "pointer",
+                    fontSize: "0.875rem",
+                }, children: ["Resolve conflicts (", rejection.patch.conflicts.length, ")"] })), _jsx("button", { type: "button", "aria-label": "Dismiss", onClick: onDismiss, style: {
+                    background: "none",
+                    border: "none",
+                    cursor: "pointer",
+                    color: "#92400e",
+                    fontSize: "1rem",
+                    lineHeight: 1,
+                    padding: "0.125rem",
+                }, children: "\u2715" })] }));
+}

package/dist/UndoButton.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+/**
+ * A small undo button shown inline (e.g. in the {@link ReconciliationBanner}).
+ * Reverts the optimistic local change that was rejected by the server.
+ */
+export interface UndoButtonProps {
+    /** Callback invoked when the user clicks the undo button. */
+    onUndo: () => void;
+    /** Optional label (defaults to "Undo"). */
+    label?: string;
+    /** Whether the undo action is currently available. */
+    disabled?: boolean;
+}
+export declare function UndoButton({ onUndo, label, disabled, }: UndoButtonProps): React.ReactElement;

package/dist/UndoButton.js

@@ -0,0 +1,17 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+export function UndoButton({ onUndo, label = "Undo", disabled = false, }) {
+    return (_jsxs("button", { type: "button", onClick: onUndo, disabled: disabled, "aria-label": "Undo last change", style: {
+            display: "inline-flex",
+            alignItems: "center",
+            gap: "0.25rem",
+            padding: "0.25rem 0.75rem",
+            borderRadius: "0.25rem",
+            border: "1px solid #b45309",
+            backgroundColor: "#ffffff",
+            color: "#92400e",
+            cursor: disabled ? "not-allowed" : "pointer",
+            fontSize: "0.875rem",
+            opacity: disabled ? 0.5 : 1,
+            transition: "background-color 150ms",
+        }, children: ["\u21A9 ", label] }));
+}

package/dist/client.d.ts

@@ -0,0 +1,134 @@
+import type { ClientMessage, ServerMessage } from "./wire";
+export type MessageHandler = (msg: ServerMessage) => void;
+export type ErrorHandler = (err: Event) => void;
+/**
+ * Called for each incremental text token received from the server during a
+ * streaming AI response.  The `done` flag is `true` on the final token.
+ */
+export type TokenHandler = (token: string, done: boolean) => void;
+/**
+ * Called when the server sends a RELOAD_REQUIRED message indicating the
+ * client's AST schema version is incompatible.  The application should
+ * reload its policy bundle and reconnect.
+ */
+export type ReloadRequiredHandler = (minRequiredVersion: string, reason: string) => void;
+export interface Gp2fClientOptions {
+    url: string;
+    /** Called with every inbound {@link ServerMessage}. */
+    onMessage: MessageHandler;
+    /** Called on WebSocket error. */
+    onError?: ErrorHandler;
+    /** Called when the connection is established. */
+    onOpen?: () => void;
+    /** Called when the connection is closed. */
+    onClose?: () => void;
+    /**
+     * Called with each incremental text token during a streaming AI response.
+     * Enables token-by-token UI updates ("Time to First Token" UX pattern).
+     */
+    onToken?: TokenHandler;
+    /**
+     * Called when the server signals that the client's AST schema version is
+     * incompatible.  The client MUST reload its policy bundle before reconnecting.
+     * Defaults to a no-op if not provided.
+     */
+    onReloadRequired?: ReloadRequiredHandler;
+    /**
+     * Token-bucket capacity: maximum number of ops that may be sent in a burst.
+     * Defaults to 10.
+     */
+    tokenBucketCapacity?: number;
+    /**
+     * Token-bucket refill rate in tokens per second.
+     * Defaults to 5 (one token every 200 ms).
+     */
+    tokenBucketRefillRate?: number;
+    /**
+     * How long (ms) to pause optimistic updates after a conflict is detected.
+     * Defaults to 500 ms ("Settle Duration").
+     */
+    conflictSettleMs?: number;
+}
+/**
+ * Options for {@link applyOptimisticUpdate}.
+ */
+export interface OptimisticUpdateOptions {
+    /** The DOM element in which to render the loading indicator. */
+    container: HTMLElement;
+    /**
+     * Vibe engine confidence in [0, 1].  When ≥ 0.7 a full skeleton loader is
+     * shown; below that threshold a lighter "Thinking…" text badge is used.
+     * Defaults to 0 (text badge).
+     */
+    confidence?: number;
+    /**
+     * Override the default "Thinking…" label shown in low-confidence mode.
+     */
+    thinkingText?: string;
+}
+/**
+ * Show an optimistic UI loading indicator while waiting for an LLM response.
+ *
+ * Renders a skeleton loader (high-confidence path) or a "Thinking…" badge
+ * (low-confidence path) inside `container`, then returns a cleanup function
+ * that removes the indicator when the response arrives.
+ *
+ * @example
+ * ```ts
+ * const cleanup = applyOptimisticUpdate({ container: myDiv, confidence: 0.9 });
+ * const response = await fetchAiSuggestion();
+ * cleanup();
+ * renderResponse(response);
+ * ```
+ */
+export declare function applyOptimisticUpdate(options: OptimisticUpdateOptions): () => void;
+/**
+ * GP2F WebSocket client with:
+ * - Token-bucket rate limiting to prevent thundering-herd on reconnect.
+ * - Settle-Duration: optimistic updates are paused for
+ *   {@link Gp2fClientOptions.conflictSettleMs} after a conflict is detected.
+ * - Retry-After: the client respects the server's backpressure hint.
+ * - Time-offset tracking: the client records the delta between its clock and
+ *   the server's clock reported in the `HELLO` message.
+ */
+export declare class Gp2fClient {
+    private ws;
+    private readonly options;
+    private readonly bucket;
+    /** Timestamp (Date.now()) until which sends are paused. */
+    private pauseUntil;
+    /** Pending messages queued while the rate limiter or pause is active. */
+    private readonly pendingQueue;
+    /** Drain timer handle (if set). */
+    private drainTimer;
+    /**
+     * Difference `serverTimeMs - Date.now()` captured on the last HELLO.
+     * Add this to `Date.now()` to get an estimate of the server's current time.
+     */
+    serverTimeOffsetMs: number;
+    constructor(options: Gp2fClientOptions);
+    /** Open the WebSocket connection. */
+    connect(): void;
+    /** Close the WebSocket connection. */
+    disconnect(): void;
+    /**
+     * Send a {@link ClientMessage} to the server.
+     *
+     * If the rate limiter or a settle/retry-after pause is active the message
+     * is queued and drained automatically once the pause expires.
+     */
+    send(msg: ClientMessage): void;
+    /** Whether the connection is currently open. */
+    get connected(): boolean;
+    /** Handle an inbound server message, updating internal rate-limit state. */
+    private handleInbound;
+    /**
+     * Returns the number of milliseconds to wait before the next send.
+     * 0 means "send immediately".
+     */
+    private nextSendDelay;
+    /** Schedule a drain of the pending queue after `delayMs` ms. */
+    private scheduleDrain;
+    /** Attempt to flush as many pending messages as the rate limiter allows. */
+    private drainQueue;
+}

package/dist/client.js

@@ -0,0 +1,244 @@
+/**
+ * Show an optimistic UI loading indicator while waiting for an LLM response.
+ *
+ * Renders a skeleton loader (high-confidence path) or a "Thinking…" badge
+ * (low-confidence path) inside `container`, then returns a cleanup function
+ * that removes the indicator when the response arrives.
+ *
+ * @example
+ * ```ts
+ * const cleanup = applyOptimisticUpdate({ container: myDiv, confidence: 0.9 });
+ * const response = await fetchAiSuggestion();
+ * cleanup();
+ * renderResponse(response);
+ * ```
+ */
+export function applyOptimisticUpdate(options) {
+    const { container, confidence = 0, thinkingText = "Thinking\u2026" } = options;
+    const indicator = document.createElement("div");
+    indicator.setAttribute("aria-live", "polite");
+    indicator.setAttribute("aria-label", thinkingText);
+    if (confidence >= 0.7) {
+        // High-confidence: render a skeleton loader so the layout shift is minimal.
+        indicator.setAttribute("data-gp2f-skeleton", "true");
+        indicator.style.cssText = [
+            "display:block",
+            "background:linear-gradient(90deg,#e0e0e0 25%,#f5f5f5 50%,#e0e0e0 75%)",
+            "background-size:200% 100%",
+            "animation:gp2f-shimmer 1.4s infinite",
+            "border-radius:4px",
+            "height:1.2em",
+            "width:80%",
+            "margin:4px 0",
+        ].join(";");
+    }
+    else {
+        // Low-confidence: show a simple "Thinking…" text badge.
+        indicator.setAttribute("data-gp2f-thinking", "true");
+        indicator.textContent = thinkingText;
+        indicator.style.cssText = "opacity:0.6;font-style:italic;font-size:0.9em";
+    }
+    // Inject the shimmer keyframes once per document.
+    if (typeof document !== "undefined" &&
+        !document.getElementById("gp2f-shimmer-style")) {
+        const style = document.createElement("style");
+        style.id = "gp2f-shimmer-style";
+        style.textContent =
+            "@keyframes gp2f-shimmer{0%{background-position:200% 0}100%{background-position:-200% 0}}";
+        document.head.appendChild(style);
+    }
+    container.appendChild(indicator);
+    return () => {
+        if (indicator.parentNode === container) {
+            container.removeChild(indicator);
+        }
+    };
+}
+// ── Token Bucket ──────────────────────────────────────────────────────────────
+/**
+ * A simple Token Bucket rate limiter.
+ *
+ * Tokens refill continuously at `refillRate` tokens/second up to `capacity`.
+ * Each `consume()` call removes one token.  If no token is available,
+ * `consume()` returns the number of milliseconds to wait before retrying.
+ */
+class TokenBucket {
+    constructor(capacity, refillRate) {
+        this.capacity = capacity;
+        this.refillRate = refillRate;
+        this.tokens = capacity;
+        this.lastRefill = Date.now();
+    }
+    /** Attempt to consume one token.  Returns 0 if successful or wait-ms > 0. */
+    consume() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return 0;
+        }
+        // Calculate how long until the next token is available.
+        // `1 - this.tokens` is the fractional deficit; convert to milliseconds.
+        return Math.ceil(((1 - this.tokens) / this.refillRate) * 1000);
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000; // seconds
+        this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
+        this.lastRefill = now;
+    }
+}
+// ── Gp2fClient ────────────────────────────────────────────────────────────────
+/**
+ * GP2F WebSocket client with:
+ * - Token-bucket rate limiting to prevent thundering-herd on reconnect.
+ * - Settle-Duration: optimistic updates are paused for
+ *   {@link Gp2fClientOptions.conflictSettleMs} after a conflict is detected.
+ * - Retry-After: the client respects the server's backpressure hint.
+ * - Time-offset tracking: the client records the delta between its clock and
+ *   the server's clock reported in the `HELLO` message.
+ */
+export class Gp2fClient {
+    constructor(options) {
+        this.ws = null;
+        /** Timestamp (Date.now()) until which sends are paused. */
+        this.pauseUntil = 0;
+        /** Pending messages queued while the rate limiter or pause is active. */
+        this.pendingQueue = [];
+        /** Drain timer handle (if set). */
+        this.drainTimer = null;
+        /**
+         * Difference `serverTimeMs - Date.now()` captured on the last HELLO.
+         * Add this to `Date.now()` to get an estimate of the server's current time.
+         */
+        this.serverTimeOffsetMs = 0;
+        this.options = options;
+        this.bucket = new TokenBucket(options.tokenBucketCapacity ?? 10, options.tokenBucketRefillRate ?? 5);
+    }
+    /** Open the WebSocket connection. */
+    connect() {
+        if (this.ws)
+            return;
+        const ws = new WebSocket(this.options.url);
+        this.ws = ws;
+        ws.addEventListener("open", () => this.options.onOpen?.());
+        ws.addEventListener("close", () => {
+            this.ws = null;
+            this.options.onClose?.();
+        });
+        ws.addEventListener("error", (e) => this.options.onError?.(e));
+        ws.addEventListener("message", (e) => {
+            // ── Streaming token path ───────────────────────────────────────────
+            // The server may send incremental token frames before the final JSON
+            // message to enable token-by-token UI updates (Time to First Token).
+            // Streaming frames are plain-text lines of the form:
+            //   data: <token>\n   (SSE-style, done=false)
+            //   data: [DONE]\n    (final frame, done=true)
+            if (this.options.onToken && e.data.startsWith("data: ")) {
+                const payload = e.data.slice(6).trim();
+                if (payload === "[DONE]") {
+                    this.options.onToken("", true);
+                }
+                else {
+                    this.options.onToken(payload, false);
+                }
+                return;
+            }
+            try {
+                const msg = JSON.parse(e.data);
+                this.handleInbound(msg);
+            }
+            catch {
+                // Ignore unparseable messages
+            }
+        });
+    }
+    /** Close the WebSocket connection. */
+    disconnect() {
+        this.ws?.close();
+        this.ws = null;
+    }
+    /**
+     * Send a {@link ClientMessage} to the server.
+     *
+     * If the rate limiter or a settle/retry-after pause is active the message
+     * is queued and drained automatically once the pause expires.
+     */
+    send(msg) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("GP2F WebSocket is not connected");
+        }
+        const delay = this.nextSendDelay();
+        if (delay > 0) {
+            this.pendingQueue.push(msg);
+            this.scheduleDrain(delay);
+            return;
+        }
+        this.ws.send(JSON.stringify(msg));
+    }
+    /** Whether the connection is currently open. */
+    get connected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    // ── private ─────────────────────────────────────────────────────────────────
+    /** Handle an inbound server message, updating internal rate-limit state. */
+    handleInbound(msg) {
+        if (msg.type === "HELLO") {
+            // Record the server-client time offset for HLC-aware scheduling.
+            this.serverTimeOffsetMs = msg.serverTimeMs - Date.now();
+        }
+        else if (msg.type === "REJECT") {
+            const settleMs = this.options.conflictSettleMs ?? 500;
+            if (msg.retryAfterMs !== undefined) {
+                // Server-side backpressure: respect the Retry-After hint.
+                this.pauseUntil = Math.max(this.pauseUntil, Date.now() + msg.retryAfterMs);
+            }
+            else {
+                // Conflict detected: apply the Settle Duration.
+                this.pauseUntil = Math.max(this.pauseUntil, Date.now() + settleMs);
+            }
+            this.scheduleDrain(this.pauseUntil - Date.now());
+        }
+        else if (msg.type === "RELOAD_REQUIRED") {
+            // Server signals that our AST schema version is incompatible.
+            // Notify the application so it can reload the policy bundle.
+            this.options.onReloadRequired?.(msg.minRequiredVersion, msg.reason);
+            // Close the connection — we cannot continue with an incompatible schema.
+            this.disconnect();
+        }
+        this.options.onMessage(msg);
+    }
+    /**
+     * Returns the number of milliseconds to wait before the next send.
+     * 0 means "send immediately".
+     */
+    nextSendDelay() {
+        const pauseRemaining = Math.max(0, this.pauseUntil - Date.now());
+        if (pauseRemaining > 0)
+            return pauseRemaining;
+        const bucketWait = this.bucket.consume();
+        return bucketWait;
+    }
+    /** Schedule a drain of the pending queue after `delayMs` ms. */
+    scheduleDrain(delayMs) {
+        if (this.drainTimer !== null)
+            return; // already scheduled
+        this.drainTimer = setTimeout(() => {
+            this.drainTimer = null;
+            this.drainQueue();
+        }, Math.max(0, delayMs));
+    }
+    /** Attempt to flush as many pending messages as the rate limiter allows. */
+    drainQueue() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        while (this.pendingQueue.length > 0) {
+            const delay = this.nextSendDelay();
+            if (delay > 0) {
+                this.scheduleDrain(delay);
+                return;
+            }
+            const msg = this.pendingQueue.shift();
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export type { ClientMessage, ServerMessage, AcceptResponse, RejectResponse, ThreeWayPatch, FieldConflict, HelloMessage, ReloadRequiredMessage, } from "./wire";
+export { Gp2fClient, applyOptimisticUpdate } from "./client";
+export type { Gp2fClientOptions, MessageHandler, ErrorHandler, TokenHandler, OptimisticUpdateOptions, ReloadRequiredHandler } from "./client";
+export { ReconciliationBanner } from "./ReconciliationBanner";
+export type { ReconciliationBannerProps } from "./ReconciliationBanner";
+export { UndoButton } from "./UndoButton";
+export type { UndoButtonProps } from "./UndoButton";
+export { MergeModal } from "./MergeModal";
+export type { MergeModalProps } from "./MergeModal";
+/**
+ * The shape of the lazily-loaded policy engine module.
+ *
+ * When the WASM build of `policy-core` is published as an npm package
+ * (e.g. `@gp2f/policy-core-wasm`), this interface describes its public API.
+ * The lazy loader below imports it on-demand so that the WASM binary is NOT
+ * included in the initial JS bundle, reducing Time-To-Interactive.
+ */
+export interface PolicyEngineModule {
+    /** Evaluate a policy AST against a JSON state document. */
+    evaluate(stateJson: string, astJson: string): {
+        result: boolean;
+        trace: string[];
+    };
+}
+/**
+ * Lazily load the GP2F WASM policy engine.
+ *
+ * The module is fetched and instantiated on the **first call** only; subsequent
+ * calls return the cached instance with no additional network cost.
+ *
+ * This pattern ("lazy loading") keeps the initial JS bundle small and defers
+ * the WASM download until the moment the policy engine is actually needed.
+ *
+ * @example
+ * ```ts
+ * const engine = await loadPolicyEngine();
+ * const { result } = engine.evaluate(JSON.stringify(state), JSON.stringify(ast));
+ * ```
+ */
+export declare function loadPolicyEngine(): Promise<PolicyEngineModule>;