@babav/knowledge-core-client 0.22.0 → 0.22.2

package/dist/index.d.ts

@@ -107,6 +107,11 @@ export interface Visual {
         height: number;
     };
 }
+/** First event of the visual stage (streaming): generation has started. `pending` = number of
+ *  concepts about to be rendered, or null when not yet known. */
+export interface VisualsPending {
+    pending: number | null;
+}
 export interface VisualsMeta {
     count: number;
     dropped: number;
@@ -336,10 +341,14 @@ export interface StreamHandlers {
      *  (native path). Also present in `final`. May be `{}` if scoring was unavailable. */
     onGroundedness?: (g: Groundedness | Record<string, never>) => void;
     onFinal?: (d: QueryResponse) => void;
-    /** A visual, emitted (out of anchor order) during the trailing visual phase when
+    /** First event of the trailing visual stage — visual generation has STARTED (fires after
+     *  `final`/`groundedness`, before any `visual`). `pending` is how many concepts are about to be
+     *  rendered (or null when not yet known). Use it to show a "generating visual(s)" state. */
+    onVisualsPending?: (p: VisualsPending) => void;
+    /** A visual, emitted (out of anchor order) during the trailing visual stage when
      *  visual.mode="on". Place by `anchor`, not arrival order. */
     onVisual?: (v: Visual) => void;
-    /** Always emitted exactly once to close the visual phase (incl. count=0), before `done`. */
+    /** Always emitted exactly once to close the visual stage (incl. count=0), before `done`. */
     onVisualsComplete?: (m: VisualsMeta) => void;
     onError?: (d: unknown) => void;
     onDone?: () => void;

package/dist/index.js

@@ -364,6 +364,9 @@ function dispatchSse(frame, h) {
         case "final":
             h.onFinal?.(data);
             break;
+        case "visuals_pending":
+            h.onVisualsPending?.(data);
+            break;
         case "visual":
             h.onVisual?.(data);
             break;

package/dist/visual/types.d.ts

@@ -90,7 +90,7 @@ export interface VisualPayload {
     composition?: VisualComposition[];
     layout?: LayoutIntent;
 }
-/** Per-element source provenance. Present from v1; populated in Phase 2. */
+/** Per-element source provenance. Present from v1; populated later. */
 export interface VisualProvenance {
     [k: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps). Includes the babav.visual grammar TYPES at the ./visual subpath (types only; all visual rendering is server-side).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -125,6 +125,12 @@ export interface Visual {
   image?: { url: string; expires_at: number; width: number; height: number };
 }
 
+/** First event of the visual stage (streaming): generation has started. `pending` = number of
+ *  concepts about to be rendered, or null when not yet known. */
+export interface VisualsPending {
+  pending: number | null;
+}
+
 export interface VisualsMeta {
   count: number;
   dropped: number;
@@ -455,10 +461,14 @@ export interface StreamHandlers {
    *  (native path). Also present in `final`. May be `{}` if scoring was unavailable. */
   onGroundedness?: (g: Groundedness | Record<string, never>) => void;
   onFinal?: (d: QueryResponse) => void;
-  /** A visual, emitted (out of anchor order) during the trailing visual phase when
+  /** First event of the trailing visual stage — visual generation has STARTED (fires after
+   *  `final`/`groundedness`, before any `visual`). `pending` is how many concepts are about to be
+   *  rendered (or null when not yet known). Use it to show a "generating visual(s)" state. */
+  onVisualsPending?: (p: VisualsPending) => void;
+  /** A visual, emitted (out of anchor order) during the trailing visual stage when
    *  visual.mode="on". Place by `anchor`, not arrival order. */
   onVisual?: (v: Visual) => void;
-  /** Always emitted exactly once to close the visual phase (incl. count=0), before `done`. */
+  /** Always emitted exactly once to close the visual stage (incl. count=0), before `done`. */
   onVisualsComplete?: (m: VisualsMeta) => void;
   onError?: (d: unknown) => void;
   onDone?: () => void;
@@ -708,6 +718,7 @@ function dispatchSse(frame: string, h: StreamHandlers): void {
     case "citation": h.onCitation?.(data as Citation); break;
     case "groundedness": h.onGroundedness?.(data as never); break;
     case "final": h.onFinal?.(data as QueryResponse); break;
+    case "visuals_pending": h.onVisualsPending?.(data as VisualsPending); break;
     case "visual": h.onVisual?.(data as Visual); break;
     case "visuals_complete": h.onVisualsComplete?.(data as VisualsMeta); break;
     case "error": h.onError?.(data); break;

package/src/visual/types.ts

@@ -116,7 +116,7 @@ export interface VisualPayload {
   layout?: LayoutIntent;
 }
 
-/** Per-element source provenance. Present from v1; populated in Phase 2. */
+/** Per-element source provenance. Present from v1; populated later. */
 export interface VisualProvenance {
   [k: string]: unknown;
 }