@cf-vibesdk/sdk 0.0.8 → 0.0.9

package/README.md

@@ -250,6 +250,24 @@ if (session.phases.allCompleted()) {
 
 // Get phase by ID
 const phase = session.phases.get('phase-0');
+
+// Subscribe to phase changes
+const unsubscribe = session.phases.onChange((event) => {
+  console.log(`Phase ${event.type}:`, event.phase.name);
+  console.log(`Status: ${event.phase.status}`);
+  console.log(`Total phases: ${event.allPhases.length}`);
+});
+// Later: unsubscribe();
+```
+
+The `onChange` callback receives a `PhaseTimelineEvent`:
+
+```ts
+type PhaseTimelineEvent = {
+  type: 'added' | 'updated';  // New phase vs status/file change
+  phase: PhaseInfo;           // The affected phase
+  allPhases: PhaseInfo[];     // All phases after this change
+};
 ```
 
 Each phase contains:
@@ -403,6 +421,8 @@ import type {
   PhaseStatus,
   PhaseFileStatus,
   PhaseEventType,
+  PhaseTimelineEvent,
+  PhaseTimelineChangeType,
   
   // API
   ApiResponse,

package/dist/index.d.ts

@@ -5568,6 +5568,8 @@ export type AgentEventMap = {
 	error: {
 		error: string;
 	};
+	/** Emitted when the phase timeline changes (phase added or updated). */
+	phases: PhaseTimelineEvent;
 };
 /**
  * URL provider for WebSocket connections.
@@ -5657,6 +5659,18 @@ export type SessionPhases = {
 	/** Check if all phases are completed. */
 	allCompleted: () => boolean;
 };
+/**
+ * Event emitted when the phase timeline changes.
+ */
+export type PhaseTimelineChangeType = "added" | "updated";
+export type PhaseTimelineEvent = {
+	/** Type of change: 'added' for new phase, 'updated' for status/file changes. */
+	type: PhaseTimelineChangeType;
+	/** The phase that was added or updated. */
+	phase: PhaseInfo;
+	/** All phases in the timeline after this change. */
+	allPhases: PhaseInfo[];
+};
 export type SessionDeployable = {
 	files: number;
 	reason: "generation_complete" | "phase_validated";
@@ -5759,6 +5773,11 @@ export declare class SessionStateStore {
 	private emitter;
 	get(): SessionState;
 	onChange(cb: (next: SessionState, prev: SessionState) => void): () => void;
+	/**
+	 * Subscribe to phase timeline changes.
+	 * Fires when a phase is added or when a phase's status/files change.
+	 */
+	onPhaseChange(cb: (event: PhaseTimelineEvent) => void): () => void;
 	setConnection(state: ConnectionState): void;
 	applyWsMessage(msg: AgentWsServerMessage): void;
 	/**
@@ -5770,6 +5789,14 @@ export declare class SessionStateStore {
 	 */
 	private updateOrAddPhase;
 	private setState;
+	/**
+	 * Compare old and new phases arrays and emit change events.
+	 */
+	private emitPhaseChanges;
+	/**
+	 * Check if a phase has meaningfully changed (status or file statuses).
+	 */
+	private hasPhaseChanged;
 	clear(): void;
 }
 type WorkspaceChange = {
@@ -5856,6 +5883,12 @@ export declare class BuildSession {
 		count: () => number;
 		/** Check if all phases are completed. */
 		allCompleted: () => boolean;
+		/**
+		 * Subscribe to phase timeline changes.
+		 * Fires when a phase is added or when a phase's status/files change.
+		 * @returns Unsubscribe function.
+		 */
+		onChange: (cb: (event: PhaseTimelineEvent) => void) => (() => void);
 	};
 	readonly wait: {
 		generationStarted: (options?: WaitOptions) => Promise<{

package/dist/index.js

@@ -292,6 +292,9 @@ class SessionStateStore {
   onChange(cb) {
     return this.emitter.on("change", ({ prev, next }) => cb(next, prev));
   }
+  onPhaseChange(cb) {
+    return this.emitter.on("phaseChange", cb);
+  }
   setConnection(state) {
     this.setState({ connection: state });
   }
@@ -524,7 +527,7 @@ class SessionStateStore {
     const files = (phaseFiles ?? []).map((f) => ({
       path: f.path,
       purpose: f.purpose,
-      status: status === "completed" ? "completed" : "generating"
+      status: status === "completed" ? "completed" : "pending"
     }));
     if (existingIndex >= 0) {
       phases[existingIndex] = {
@@ -549,6 +552,38 @@ class SessionStateStore {
     const next = { ...prev, ...patch };
     this.state = next;
     this.emitter.emit("change", { prev, next });
+    if (patch.phases && patch.phases !== prev.phases) {
+      this.emitPhaseChanges(prev.phases, patch.phases);
+    }
+  }
+  emitPhaseChanges(prevPhases, nextPhases) {
+    for (const phase of nextPhases) {
+      const prevPhase = prevPhases.find((p) => p.id === phase.id);
+      if (!prevPhase) {
+        this.emitter.emit("phaseChange", {
+          type: "added",
+          phase,
+          allPhases: nextPhases
+        });
+      } else if (this.hasPhaseChanged(prevPhase, phase)) {
+        this.emitter.emit("phaseChange", {
+          type: "updated",
+          phase,
+          allPhases: nextPhases
+        });
+      }
+    }
+  }
+  hasPhaseChanged(prev, next) {
+    if (prev.status !== next.status)
+      return true;
+    if (prev.files.length !== next.files.length)
+      return true;
+    for (let i = 0;i < prev.files.length; i++) {
+      if (prev.files[i].status !== next.files[i].status)
+        return true;
+    }
+    return false;
   }
   clear() {
     this.state = INITIAL_STATE;
@@ -946,7 +981,8 @@ class BuildSession {
     completed: () => this.state.get().phases.filter((p) => p.status === "completed"),
     get: (id) => this.state.get().phases.find((p) => p.id === id),
     count: () => this.state.get().phases.length,
-    allCompleted: () => this.state.get().phases.length > 0 && this.state.get().phases.every((p) => p.status === "completed")
+    allCompleted: () => this.state.get().phases.length > 0 && this.state.get().phases.every((p) => p.status === "completed"),
+    onChange: (cb) => this.state.onPhaseChange(cb)
   };
   wait = {
     generationStarted: (options = {}) => this.waitForGenerationStarted(options),

package/package.json

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