@gp2f/client-sdk 1.0.0 → 1.0.3

package/README.md

@@ -0,0 +1,114 @@
+# @gp2f/client-sdk
+
+GP2F client SDK – reconciliation UX components and WebSocket client.
+
+## Overview
+This SDK provides React components for opportunistic UI state reconciliation, along with a WebSocket client that directly interacts with the GP2F backend server using CRDTs. It is designed to create collaborative, real-time shared experiences seamlessly.
+
+## Installation
+```bash
+npm install @gp2f/client-sdk
+```
+
+## Usage
+
+### 1. WebSocket Client (`Gp2fClient`)
+The client provides robust sync over WebSockets with built-in Token Bucket rate-limiting and time-offset tracking.
+
+```typescript
+import { Gp2fClient } from '@gp2f/client-sdk';
+
+const client = new Gp2fClient({
+  url: 'ws://localhost:3000/ws',
+  onMessage: (msg) => {
+    console.log('Received from server:', msg);
+  },
+  onToken: (token, done) => {
+    // Helpful for streaming AI responses ("Time to First Token")
+    console.log(`Token: ${token}, Done: ${done}`);
+  },
+  onReloadRequired: (version, reason) => {
+    console.warn(`Incompatible AST schema (${version}): ${reason}`);
+    window.location.reload();
+  }
+});
+
+client.connect();
+
+// Send messages (automatically rate-limited)
+client.send({
+  type: 'SYNC',
+  payload: { /* ... */ }
+});
+```
+
+### 2. Optimistic Updates
+Visual indication for optimistic updates or LLM loading limits.
+
+```typescript
+import { applyOptimisticUpdate } from '@gp2f/client-sdk';
+
+const container = document.getElementById('my-loader-div');
+
+// Shows a shimmering skeleton loader
+const cleanup = applyOptimisticUpdate({
+  container,
+  confidence: 0.8, // >= 0.7 triggers high-confidence skeleton loader
+  thinkingText: "Vibe checking..."
+});
+
+// Later, when the update completes:
+cleanup();
+```
+
+### 3. React Components
+The SDK ships with React components to handle state conflicts and reconciliation UX:
+
+```tsx
+import React from 'react';
+import { ReconciliationBanner, UndoButton, MergeModal } from '@gp2f/client-sdk';
+
+export function EditorHeader() {
+  return (
+    <header>
+      {/* Banner handles showing connection states and sync issues */}
+      <ReconciliationBanner 
+        status="conflict" 
+        onResolve={() => console.log('Resolve clicked')} 
+      />
+      
+      {/* Undo integration */}
+      <UndoButton 
+        canUndo={true} 
+        onUndo={() => console.log('Undo triggered!')} 
+      />
+    </header>
+  );
+}
+```
+
+### 4. Lazy Policy Evaluation (WASM Engine)
+Load the fast WASM policy engine dynamically when needed without blocking the main thread.
+
+```typescript
+import { loadPolicyEngine } from '@gp2f/client-sdk';
+
+async function checkPolicy(state: any, ast: any) {
+  const engine = await loadPolicyEngine();
+  const { result } = engine.evaluate(
+    JSON.stringify(state),
+    JSON.stringify(ast)
+  );
+  return result;
+}
+```
+
+## Peer Dependencies
+Please note that you'll need `react` and `react-dom` version `>=18.0.0` installed in your host project.
+
+## Scripts
+- **Build**: `npm run build`
+- **Test**: `npm run test`
+
+## License
+MIT

package/dist/index.js

@@ -32,13 +32,17 @@ let _policyEngineCache = null;
  * 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.
+    // We intentionally defeat static import analysis by building the specifier
+    // at runtime.  Vite / Rollup / webpack resolve bare string literals in
+    // dynamic imports at *build time*, before any try/catch can help.  A computed
+    // expression is invisible to those static passes, so the try/catch below
+    // actually runs at runtime when the package is absent.
+    //
+    // If @gp2f/policy-core-wasm IS installed, this resolves normally.
+    // If it is NOT installed, the runtime import() throws and we return the stub.
+    const specifier = /* @vite-ignore */ "@gp2f/" + "policy-core-wasm";
     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");
+        const mod = await import(/* @vite-ignore */ specifier);
         return mod;
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gp2f/client-sdk",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "GP2F client SDK – reconciliation UX components and WebSocket client",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,13 @@
   "license": "MIT",
   "peerDependencies": {
     "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
+    "react-dom": ">=18.0.0",
+    "@gp2f/policy-core-wasm": "*"
+  },
+  "peerDependenciesMeta": {
+    "@gp2f/policy-core-wasm": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/react": "^18.0.0",

package/src/index.ts

@@ -69,13 +69,17 @@ let _policyEngineCache: PolicyEngineModule | null = null;
  * to emit this as a separate chunk so it is only downloaded on demand.
  */
 async function _importPolicyEngine(): Promise<PolicyEngineModule> {
-  // 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.
+  // We intentionally defeat static import analysis by building the specifier
+  // at runtime.  Vite / Rollup / webpack resolve bare string literals in
+  // dynamic imports at *build time*, before any try/catch can help.  A computed
+  // expression is invisible to those static passes, so the try/catch below
+  // actually runs at runtime when the package is absent.
+  //
+  // If @gp2f/policy-core-wasm IS installed, this resolves normally.
+  // If it is NOT installed, the runtime import() throws and we return the stub.
+  const specifier = /* @vite-ignore */ "@gp2f/" + "policy-core-wasm";
   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");
+    const mod = await import(/* @vite-ignore */ specifier);
     return mod as PolicyEngineModule;
   } catch {
     // WASM package not installed – return a stub that always delegates to the