@gp2f/client-sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,58 @@
+// WebSocket client
+export { Gp2fClient, applyOptimisticUpdate } from "./client";
+// Reconciliation UX components
+export { ReconciliationBanner } from "./ReconciliationBanner";
+export { UndoButton } from "./UndoButton";
+export { MergeModal } from "./MergeModal";
+/**
+ * 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 async function loadPolicyEngine() {
+    return _policyEngineCache ?? (_policyEngineCache = await _importPolicyEngine());
+}
+/** Cached module instance (populated after the first successful load). */
+let _policyEngineCache = null;
+/**
+ * Perform the actual dynamic import.
+ *
+ * Replace the module path with the real WASM package once it is published.
+ * The `/* webpackChunkName  magic comment tells bundlers (webpack / Vite)
+ * to emit this as a separate chunk so it is only downloaded on demand.
+ */
+async function _importPolicyEngine() {
+    // Dynamic import – bundlers will split this into a separate chunk.
+    // We use a try/catch so that the SDK remains usable even when the optional
+    // @gp2f/policy-core-wasm peer package is not installed.
+    try {
+        // @ts-expect-error: @gp2f/policy-core-wasm is an optional peer package
+        // that may not be installed.  The try/catch below handles the absence case.
+        const mod = await import(/* webpackChunkName: "policy-engine" */ "@gp2f/policy-core-wasm");
+        return mod;
+    }
+    catch {
+        // WASM package not installed – return a stub that always delegates to the
+        // server-side evaluator.  Log a warning so developers know the lazy engine
+        // is inactive.
+        if (typeof console !== "undefined") {
+            console.warn("[gp2f] WASM policy engine not found (@gp2f/policy-core-wasm). " +
+                "All policy evaluation will be performed server-side.");
+        }
+        return {
+            evaluate(_stateJson, _astJson) {
+                throw new Error("WASM policy engine is not available. Install @gp2f/policy-core-wasm to enable client-side evaluation.");
+            },
+        };
+    }
+}

package/dist/wire.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Wire-protocol types shared between the GP2F server and this SDK.
+ * These mirror the Rust structs in `server/src/wire.rs`.
+ */
+export interface ClientMessage {
+    opId: string;
+    astVersion: string;
+    action: string;
+    payload: unknown;
+    clientSnapshotHash: string;
+    tenantId?: string;
+    workflowId?: string;
+    instanceId?: string;
+    /** base64url HMAC-SHA256 over canonical op fields */
+    clientSignature?: string;
+}
+export interface AcceptResponse {
+    opId: string;
+    serverSnapshotHash: string;
+}
+export interface ThreeWayPatch {
+    baseSnapshot: unknown;
+    localDiff: unknown;
+    serverDiff: unknown;
+    conflicts: FieldConflict[];
+}
+export interface FieldConflict {
+    path: string;
+    strategy: "CRDT" | "LWW" | "TRANSACTIONAL";
+    resolvedValue: unknown;
+}
+export interface RejectResponse {
+    opId: string;
+    reason: string;
+    patch: ThreeWayPatch;
+    /**
+     * Suggested back-off interval in milliseconds (Retry-After semantics).
+     * Present when the rejection is caused by server-side backpressure; the
+     * client SHOULD pause sending new ops for at least this duration.
+     */
+    retryAfterMs?: number;
+}
+/**
+ * Sent by the server once per connection, immediately after the WebSocket
+ * handshake, for time-synchronisation purposes.
+ */
+export interface HelloMessage {
+    /** Server wall-clock time in milliseconds since the Unix epoch. */
+    serverTimeMs: number;
+    /** Server HLC timestamp at the moment of the hello. */
+    serverHlcTs: number;
+}
+/**
+ * Sent by the server when the client's AST schema version is incompatible.
+ * The client MUST fetch a fresh policy bundle before reconnecting.
+ */
+export interface ReloadRequiredMessage {
+    /** The minimum AST version the server accepts (semver). */
+    minRequiredVersion: string;
+    /** Human-readable explanation. */
+    reason: string;
+}
+export type ServerMessage = {
+    type: "ACCEPT";
+} & AcceptResponse | {
+    type: "REJECT";
+} & RejectResponse | {
+    type: "HELLO";
+} & HelloMessage | {
+    type: "RELOAD_REQUIRED";
+} & ReloadRequiredMessage;

package/dist/wire.js

@@ -0,0 +1,5 @@
+/**
+ * Wire-protocol types shared between the GP2F server and this SDK.
+ * These mirror the Rust structs in `server/src/wire.rs`.
+ */
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gp2f/client-sdk",
+  "version": "1.0.0",
+  "description": "GP2F client SDK – reconciliation UX components and WebSocket client",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --passWithNoTests"
+  },
+  "keywords": [
+    "gp2f",
+    "crdt",
+    "reconciliation",
+    "optimistic-ui"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/MergeModal.tsx

@@ -0,0 +1,321 @@
+import React, { useState } 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;
+}
+
+type Resolution = "mine" | "server";
+
+export function MergeModal({
+  conflicts,
+  localDiff,
+  onResolve,
+  onCancel,
+}: MergeModalProps): React.ReactElement {
+  const [choices, setChoices] = useState<Record<string, Resolution>>(
+    () =>
+      Object.fromEntries(conflicts.map((c) => [c.path, "server" as Resolution]))
+  );
+
+  function handleChoice(path: string, choice: Resolution) {
+    setChoices((prev) => ({ ...prev, [path]: choice }));
+  }
+
+  function handleResolve() {
+    const resolutions: Record<string, unknown> = {};
+    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 (
+    <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,
+      }}
+    >
+      <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",
+        }}
+      >
+        {/* Header */}
+        <div
+          style={{
+            padding: "1rem 1.25rem",
+            borderBottom: "1px solid #e5e7eb",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+          }}
+        >
+          <h2
+            id="merge-modal-title"
+            style={{ margin: 0, fontSize: "1rem", fontWeight: 600 }}
+          >
+            Resolve Conflicts ({conflicts.length})
+          </h2>
+          <button
+            type="button"
+            aria-label="Close"
+            onClick={onCancel}
+            style={{
+              background: "none",
+              border: "none",
+              cursor: "pointer",
+              fontSize: "1.25rem",
+            }}
+          >
+            ✕
+          </button>
+        </div>
+
+        {/* Conflict list */}
+        <div style={{ overflowY: "auto", flex: 1, padding: "0.75rem 1.25rem" }}>
+          {conflicts.map((conflict) => (
+            <ConflictRow
+              key={conflict.path}
+              conflict={conflict}
+              localValue={getFieldValue(localDiff, conflict.path)}
+              choice={choices[conflict.path] ?? "server"}
+              onChoose={(c) => handleChoice(conflict.path, c)}
+            />
+          ))}
+        </div>
+
+        {/* Footer */}
+        <div
+          style={{
+            padding: "0.75rem 1.25rem",
+            borderTop: "1px solid #e5e7eb",
+            display: "flex",
+            justifyContent: "flex-end",
+            gap: "0.5rem",
+          }}
+        >
+          <button
+            type="button"
+            onClick={onCancel}
+            style={{
+              padding: "0.5rem 1rem",
+              borderRadius: "0.375rem",
+              border: "1px solid #d1d5db",
+              background: "#ffffff",
+              cursor: "pointer",
+            }}
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={handleResolve}
+            style={{
+              padding: "0.5rem 1rem",
+              borderRadius: "0.375rem",
+              border: "none",
+              backgroundColor: "#2563eb",
+              color: "#ffffff",
+              cursor: "pointer",
+              fontWeight: 500,
+            }}
+          >
+            Apply Resolutions
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ── internal components ───────────────────────────────────────────────────────
+
+interface ConflictRowProps {
+  conflict: FieldConflict;
+  localValue: unknown;
+  choice: Resolution;
+  onChoose: (c: Resolution) => void;
+}
+
+function ConflictRow({
+  conflict,
+  localValue,
+  choice,
+  onChoose,
+}: ConflictRowProps): React.ReactElement {
+  return (
+    <div
+      style={{
+        marginBottom: "1rem",
+        borderRadius: "0.375rem",
+        border: "1px solid #e5e7eb",
+        overflow: "hidden",
+      }}
+    >
+      <div
+        style={{
+          padding: "0.5rem 0.75rem",
+          backgroundColor: "#f9fafb",
+          borderBottom: "1px solid #e5e7eb",
+          display: "flex",
+          alignItems: "center",
+          gap: "0.5rem",
+        }}
+      >
+        <code style={{ fontSize: "0.8125rem", flex: 1 }}>{conflict.path}</code>
+        <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",
+          }}
+        >
+          {conflict.strategy}
+        </span>
+      </div>
+
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "1fr 1fr",
+          gap: 0,
+        }}
+      >
+        {/* Mine */}
+        <OptionPanel
+          label="My change"
+          value={localValue}
+          selected={choice === "mine"}
+          onClick={() => onChoose("mine")}
+          accentColor="#2563eb"
+        />
+        {/* Server */}
+        <OptionPanel
+          label="Server (authoritative)"
+          value={conflict.resolvedValue}
+          selected={choice === "server"}
+          onClick={() => onChoose("server")}
+          accentColor="#16a34a"
+          bordered
+        />
+      </div>
+    </div>
+  );
+}
+
+interface OptionPanelProps {
+  label: string;
+  value: unknown;
+  selected: boolean;
+  onClick: () => void;
+  accentColor: string;
+  bordered?: boolean;
+}
+
+function OptionPanel({
+  label,
+  value,
+  selected,
+  onClick,
+  accentColor,
+  bordered,
+}: OptionPanelProps): React.ReactElement {
+  return (
+    <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%",
+      }}
+    >
+      <div
+        style={{
+          fontSize: "0.75rem",
+          fontWeight: 600,
+          color: selected ? accentColor : "#6b7280",
+          marginBottom: "0.25rem",
+        }}
+      >
+        {selected && "✔ "}
+        {label}
+      </div>
+      <pre
+        style={{
+          margin: 0,
+          fontSize: "0.75rem",
+          fontFamily: "monospace",
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-all",
+          color: "#1f2937",
+        }}
+      >
+        {JSON.stringify(value, null, 2)}
+      </pre>
+    </button>
+  );
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/** Extract the value at a JSON-pointer path (e.g. `/amount`) from an object. */
+function getFieldValue(obj: unknown, pointer: string): unknown {
+  if (typeof obj !== "object" || obj === null) return undefined;
+  // Strip leading `/` and split on `/`
+  const segments = pointer.replace(/^\//, "").split("/");
+  let current: unknown = obj;
+  for (const seg of segments) {
+    if (typeof current !== "object" || current === null) return undefined;
+    current = (current as Record<string, unknown>)[seg];
+  }
+  return current;
+}

package/src/ReconciliationBanner.tsx

@@ -0,0 +1,87 @@
+import React from "react";
+import type { RejectResponse } from "./wire";
+import { UndoButton } from "./UndoButton";
+
+/**
+ * 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 function ReconciliationBanner({
+  rejection,
+  onUndo,
+  onResolve,
+  onDismiss,
+}: ReconciliationBannerProps): React.ReactElement {
+  const hasConflicts = rejection.patch.conflicts.length > 0;
+
+  return (
+    <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",
+      }}
+    >
+      <span style={{ flex: 1 }}>
+        <strong>Sync conflict:</strong> {rejection.reason}
+      </span>
+
+      <UndoButton onUndo={onUndo} />
+
+      {hasConflicts && (
+        <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",
+          }}
+        >
+          Resolve conflicts ({rejection.patch.conflicts.length})
+        </button>
+      )}
+
+      <button
+        type="button"
+        aria-label="Dismiss"
+        onClick={onDismiss}
+        style={{
+          background: "none",
+          border: "none",
+          cursor: "pointer",
+          color: "#92400e",
+          fontSize: "1rem",
+          lineHeight: 1,
+          padding: "0.125rem",
+        }}
+      >
+        ✕
+      </button>
+    </div>
+  );
+}

package/src/UndoButton.tsx

@@ -0,0 +1,45 @@
+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 function UndoButton({
+  onUndo,
+  label = "Undo",
+  disabled = false,
+}: UndoButtonProps): React.ReactElement {
+  return (
+    <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",
+      }}
+    >
+      ↩ {label}
+    </button>
+  );
+}