@cf-vibesdk/sdk 0.0.9 → 0.1.0

package/README.md

@@ -94,6 +94,53 @@ const session = await client.build('Build a weather dashboard', {
 });
 ```
 
+#### Blueprint Streaming
+
+The server streams blueprint chunks as the AI generates the project plan. By default, `build()` waits for all chunks before returning:
+
+```ts
+// Default behavior: waits for blueprint to complete
+const session = await client.build('Build a todo app', {
+  onBlueprintChunk: (chunk) => {
+    // Called in real-time as chunks arrive
+    blueprintText += chunk;
+  },
+});
+// Session returned after all blueprint chunks received
+```
+
+For faster startup, set `waitForBlueprint: false` to return immediately and stream chunks in the background:
+
+```ts
+const session = await client.build('Build a todo app', {
+  waitForBlueprint: false,  // Return immediately after start event
+  onBlueprintChunk: (chunk) => {
+    // Still called in real-time as chunks arrive
+    blueprintText += chunk;
+  },
+  onBlueprintError: (error) => {
+    // Called if streaming fails (session is auto-closed)
+    console.error('Blueprint streaming failed:', error);
+  },
+});
+// Session returned immediately, blueprint streams in background
+```
+
+Use the `BlueprintStreamParser` utility to convert chunks to readable Markdown:
+
+```ts
+import { BlueprintStreamParser } from '@cf-vibesdk/sdk';
+
+const parser = new BlueprintStreamParser();
+const session = await client.build('Build a todo app', {
+  waitForBlueprint: false,
+  onBlueprintChunk: (chunk) => {
+    const markdown = parser.append(chunk);
+    console.log(markdown);  // Rendered as Markdown
+  },
+});
+```
+
 ### `client.connect(agentId)`
 
 Connect to an existing app session. State is automatically restored from the agent, including:
@@ -322,14 +369,14 @@ session.workspace.onChange((change) => {
 
 ## WebSocket Reliability
 
-Connections automatically reconnect with exponential backoff.
+Connections automatically reconnect with exponential backoff. The first reconnect attempt is **immediate** (0ms delay) for fast recovery from brief network blips, followed by exponential backoff starting at 200ms.
 
 ```ts
 // Custom retry config
 await session.connect({
   retry: {
     enabled: true,        // Default: true
-    initialDelayMs: 1000, // Default: 1000
+    initialDelayMs: 200,  // Default: 200 (used from 2nd attempt onward)
     maxDelayMs: 30000,    // Default: 30000
     maxRetries: 10,       // Default: Infinity
   },
@@ -339,6 +386,35 @@ await session.connect({
 await session.connect({ retry: { enabled: false } });
 ```
 
+### Auto-Preview on Reconnect
+
+When connecting to an **existing app** (via `client.connect()`), the SDK automatically sends a `preview` message on connect and reconnect to ensure the preview deployment stays active:
+
+```ts
+// Existing app - auto-preview is enabled by default
+const session = await client.connect('agent-id');
+await session.connect();  // Sends preview message automatically
+
+// Override for new builds or disable
+await session.connect({ autoRequestPreview: false });
+
+// Force enable for new builds
+const session = await client.build('Build a todo app');
+await session.connect({ autoRequestPreview: true });
+```
+
+### Reconnect Events
+
+```ts
+session.on('ws:reconnecting', ({ attempt, delayMs, reason }) => {
+  console.log(`Reconnecting (attempt ${attempt}, delay ${delayMs}ms, reason: ${reason})`);
+});
+
+session.on('ws:reconnected', () => {
+  console.log('Reconnected successfully');
+});
+```
+
 ## HTTP Retry
 
 HTTP requests automatically retry on 5xx errors.

package/dist/index.d.ts

@@ -5453,7 +5453,21 @@ type CodeGenArgs$1 = CodeGenArgs;
 export type BuildOptions = Omit<CodeGenArgs$1, "query"> & {
 	autoConnect?: boolean;
 	autoGenerate?: boolean;
+	/**
+	 * Called for each blueprint chunk as it streams from the server.
+	 */
 	onBlueprintChunk?: (chunk: string) => void;
+	/**
+	 * Called if blueprint streaming fails. The session will be closed automatically.
+	 * Only relevant when `waitForBlueprint` is false.
+	 */
+	onBlueprintError?: (error: Error) => void;
+	/**
+	 * If true (default), `build()` waits for all blueprint chunks before returning.
+	 * If false, `build()` returns immediately after receiving the start event,
+	 * and blueprint chunks stream in the background via `onBlueprintChunk`.
+	 */
+	waitForBlueprint?: boolean;
 };
 type TemplateFiles = Record<string, string>;
 export type BuildStartEvent = {
@@ -5554,6 +5568,7 @@ export type AgentEventMap = {
 		delayMs: number;
 		reason: "close" | "error";
 	};
+	"ws:reconnected": undefined;
 	"ws:raw": {
 		raw: unknown;
 	};
@@ -5849,12 +5864,19 @@ type WaitUntilReadyOptions = WaitOptions;
 type BuildSessionConnectOptions = Omit<AgentConnectionOptions, "credentials"> & {
 	/** If true (default), send `get_conversation_state` on socket open. */
 	autoRequestConversationState?: boolean;
+	/**
+	 * If true, send `preview` message on connect and reconnect to ensure preview exists.
+	 * Defaults to true for existing apps (via `client.connect()`), false for new builds.
+	 */
+	autoRequestPreview?: boolean;
 	/** Credentials to send via session_init after connection. */
 	credentials?: Credentials;
 };
 type BuildSessionInit = {
 	httpClient: HttpClient;
 	defaultCredentials?: Credentials;
+	/** True if this session is for an existing app (via client.connect). */
+	isExistingApp?: boolean;
 };
 export declare class BuildSession {
 	private init;
@@ -5948,6 +5970,10 @@ export declare class VibeClient {
 	get baseUrl(): string;
 	/**
 	 * Creates a new agent/app from a prompt and returns a BuildSession.
+	 *
+	 * By default, waits for all blueprint chunks before returning. Set
+	 * `waitForBlueprint: false` to return immediately after the start event,
+	 * with blueprint chunks streaming in the background.
 	 */
 	build(prompt: string, options?: BuildOptions): Promise<BuildSession>;
 	/** Connect to an existing agent/app by id. */

package/dist/index.js

@@ -409,7 +409,7 @@ class SessionStateStore {
         const m = msg;
         const phaseInfo = extractPhaseInfo(m);
         const phaseFiles = extractPhaseFiles(m);
-        const phases = this.updateOrAddPhase(phaseInfo, "validating", phaseFiles);
+        const phases = this.updateOrAddPhase(phaseInfo, "completed", phaseFiles);
         this.setState({
           phase: { status: "implemented", ...phaseInfo },
           phases
@@ -431,7 +431,7 @@ class SessionStateStore {
         const m = msg;
         const phaseInfo = extractPhaseInfo(m);
         const phaseFiles = extractPhaseFiles(m);
-        const phases = this.updateOrAddPhase(phaseInfo, "completed", phaseFiles);
+        const phases = this.updateOrAddPhase(phaseInfo, "validating", phaseFiles);
         this.setState({
           phase: { status: "validated", ...phaseInfo },
           phases
@@ -618,7 +618,7 @@ async function withTimeout(promise, ms, message = "Operation timed out") {
 // src/ws.ts
 var WS_RETRY_DEFAULTS = {
   enabled: true,
-  initialDelayMs: 1000,
+  initialDelayMs: 200,
   maxDelayMs: 30000,
   maxRetries: Infinity
 };
@@ -630,6 +630,7 @@ function createAgentConnection(getUrl, options = {}) {
   let closedByUser = false;
   let reconnectAttempts = 0;
   let reconnectTimer = null;
+  let hasConnectedBefore = false;
   const pendingSends = [];
   const maxPendingSends = 1000;
   function clearReconnectTimer() {
@@ -655,22 +656,34 @@ function createAgentConnection(getUrl, options = {}) {
       return;
     if (reconnectTimer)
       return;
-    const delayMs = computeBackoffMs(reconnectAttempts, retryCfg);
+    const delayMs = reconnectAttempts === 0 ? 0 : computeBackoffMs(reconnectAttempts, retryCfg);
     emitter.emit("ws:reconnecting", {
       attempt: reconnectAttempts + 1,
       delayMs,
       reason
     });
     reconnectAttempts += 1;
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = null;
-      connectNow();
-    }, delayMs);
+    if (delayMs === 0) {
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connectNow();
+      }, 0);
+    } else {
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connectNow();
+      }, delayMs);
+    }
   }
   function onOpen() {
+    const isReconnect = hasConnectedBefore;
+    hasConnectedBefore = true;
     isOpen = true;
     reconnectAttempts = 0;
     emitter.emit("ws:open", undefined);
+    if (isReconnect) {
+      emitter.emit("ws:reconnected", undefined);
+    }
     flushPendingSends();
   }
   function onClose(e) {
@@ -1005,7 +1018,7 @@ class BuildSession {
   async connect(options = {}) {
     if (this.connection)
       return this.connection;
-    const { autoRequestConversationState, credentials, ...connectionOptions } = options;
+    const { autoRequestConversationState, autoRequestPreview, credentials, ...connectionOptions } = options;
     const getUrl = async () => {
       const { ticket } = await this.init.httpClient.getWsTicket(this.agentId);
       const base = this.websocketUrl;
@@ -1026,6 +1039,7 @@ class BuildSession {
     });
     const sessionCredentials = credentials ?? this.init.defaultCredentials;
     const shouldRequestConversationState = autoRequestConversationState ?? true;
+    const shouldRequestPreview = autoRequestPreview ?? (this.init.isExistingApp ?? false);
     this.connection.on("ws:open", () => {
       if (sessionCredentials) {
         this.connection?.send({
@@ -1036,6 +1050,14 @@ class BuildSession {
       if (shouldRequestConversationState) {
         this.connection?.send({ type: "get_conversation_state" });
       }
+      if (shouldRequestPreview) {
+        this.connection?.send({ type: "preview" });
+      }
+    });
+    this.connection.on("ws:reconnected", () => {
+      if (shouldRequestPreview) {
+        this.connection?.send({ type: "preview" });
+      }
     });
     return this.connection;
   }
@@ -1198,24 +1220,35 @@ class VibeClient {
     if (!resp.body) {
       throw new Error("Missing response body from /api/agent");
     }
-    let start = null;
-    for await (const obj of parseNdjsonStream(resp.body)) {
-      if (!start) {
-        start = obj;
-        continue;
-      }
-      const o = obj;
-      if (typeof o.chunk === "string") {
-        options.onBlueprintChunk?.(o.chunk);
-      }
-    }
-    if (!start) {
+    const iterator = parseNdjsonStream(resp.body)[Symbol.asyncIterator]();
+    const { value: start, done } = await iterator.next();
+    if (done || !start) {
       throw new Error("No start event received from /api/agent");
     }
     const session = new BuildSession(start, {
       httpClient: this.http,
       ...options.credentials ? { defaultCredentials: options.credentials } : {}
     });
+    const waitForBlueprint = options.waitForBlueprint ?? true;
+    const processChunks = async () => {
+      let result = await iterator.next();
+      while (!result.done) {
+        const obj = result.value;
+        if (typeof obj.chunk === "string") {
+          options.onBlueprintChunk?.(obj.chunk);
+        }
+        result = await iterator.next();
+      }
+    };
+    if (waitForBlueprint) {
+      await processChunks();
+    } else {
+      processChunks().catch((error) => {
+        const err = error instanceof Error ? error : new Error(String(error));
+        options.onBlueprintError?.(err);
+        session.close();
+      });
+    }
     if (options.autoConnect ?? true) {
       await session.connect();
       if (options.autoGenerate ?? true) {
@@ -1235,6 +1268,7 @@ class VibeClient {
     };
     return new BuildSession(start, {
       httpClient: this.http,
+      isExistingApp: true,
       ...options.credentials ? { defaultCredentials: options.credentials } : {}
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cf-vibesdk/sdk",
-	"version": "0.0.9",
+	"version": "0.1.0",
 	"type": "module",
 	"exports": {
 		".": {